Over the last five years, I have been constantly attempting to improve my coding skills, and one of them was learning and following the most recommended coding styles.
This guide aims to help you write consistent and elegant code and includes some advice to improve the code readability and maintainability. It is inspired by the most accepted popular guidelines within the community but has some modifications to fit more suitably to my preferences.
It is worth mentioning that I am a full-stack JavaScript developer, and all my notes are specific to my tech stack (MEVN) and may not be applicable to other stacks.
If there is a need to write the same code block (or with some manageable differences) in more than one place, it is essential to merge them into a function and, hereafter, call the function whenever needed.
Functions should work independently, meaning that editing one should have absolutely no effect on the others as long as the input and outputs remain the same. Each function should have no knowledge of definitions of the others and work as a separate component. In this situation, all it knows is its parameters, and no matter who calls the function, the same inputs always return the same results.
First and foremost, remember to declare the variables all the time.
Use the const keyword when a variable is not going to be reassigned. However, you can still use const for variables that are objects or arrays, even if you plan to reassign their nested elements.
Please note to require modules and define constant variables always using const keyword.
Use the let keyword when you can not use const, and only use the var keyword if you need to support older browsers.
Functions should be limited to the following:
Code lines should be limited to 100 characters, and in order to group/organize the functions, it is better to keep the related functions close to each other as much as possible.
Privilege the arrow function syntax to the traditional alternative whenever it's possible.
Use single quotes ' (rather than double quotes ") for the ordinary string literals, but for strings with embedded variables/expressions, multiple line strings, and strings that contain single quote characters, use template literals.
It's essential to maintain consistency when naming variables. It means that if variables on different pages are responsible for the same data, they should have the same name.
The names of variables, functions, methods, and parameters should be self-descriptive, meaning anyone should be able to know (or at least make a fair guess) about the contained data just by looking at their names.
Constant variables should be in uppercase, with words separated by underscores. Functions, variables, and methods should follow the camelCase syntax, while CSS classes and ids should follow the kebab-case syntax.
Comments should always start with an uppercase letter and be limited to 100 characters. You might remember that the code lines would follow the same rule, but note that if lines include both, they can only exceed up to 150 characters.
Comments describing the functions should not be written where they are called but where they are defined.
Place the comments after the one-line codes unless the line's length exceeds 150 characters. In such cases, and for multi-line codes, put the comments at the top.
Regarding the if statements, the comments should be placed after the conditional statements.
if (conditionIsTrue) { // Put your comment here doSomeThing(); } else { // Put your comment here doSomethingElse(); }
Remember to use double slashes // for one-line comments and /* */ for multi-line ones. When adding multi-line comments to one-line code or conditional statements, place them within /* */ so that /* is written in front of the code, the comment starts on the following line, and */ is written on a new line.
if (conditionIsTrue) { /* Put your comment here Put your comment here */ doSomeThing(); } functionName(parameter), /* Put your comment here Put your comment here */
Place the comments on top of the functions wrapped by /** */.
/** * Describing the function here * @param {type} normalVariable A normal variable * @param {type1 | type2} multiTypeVariable A variable with multiple expected types * @param {type} [variableWithDefaultValue="value"] An optional variable that has a default value in case of being absent when calling the function * @param {type} [optionalVariable] An optional variable * @returns {type} description */ const functionName = (normalVariable, multiTypeVariable, variableWithDefaultValue, optionalVariable) => { doSomeThing(); }
Regarding server functions with req and res parameters, there is no need to describe request parameters; only describe the response using @returns description.
/** * Describing the function here * @returns description */ functionName = (req, res) => { doSomeThing(); }
Generally, there is no need to describe the req, res, next, to, and from parameters.
In HTML files, use to separate different parts of the code; hence the user could identify each part easily.
In case you write comments in the middle of a line of code, use /* */.
const calc_result = (firstNumber * secondNumber)/* Explain the reason for the multiplication */ thirdNumber;
Trailing whitespace is forbidden.
Remember to always put spaces around expressions, operators, and symbols, and also after commas and curly braces, if they are not the last characters of the line.
Empty lines are only allowed (and required) at the end of the file (all files should end in an empty line), after the last imported module, separating Template, Script, and Style tags, and between CSS rule sets.
Remember to use Tab for indentation and Space for alignment.
While obviously, these are not the best advice ever, I believe they offer a solid starting point for anyone interested in learning clean code principles.
Moreover, although strictly adhering to these rules might initially seem challenging, it becomes much more straightforward with practice.
It is essential to emphasize the necessity of sticking to the current project's guidelines when working on a long-term codebase, even if they are insufficient. If you are serious about revisiting the project's guidelines, consider the most beneficial modifications and let them be injected into the project gradually.
Cover image credit: Photo by luis gomes from Pexels
Disclaimer: All resources provided are partly from the Internet. If there is any infringement of your copyright or other rights and interests, please explain the detailed reasons and provide proof of copyright or rights and interests and then send it to the email: [email protected] We will handle it for you as soon as possible.
Copyright© 2022 湘ICP备2022001581号-3