General Coding Standards and Guidelines

I'm not a great programmer; I'm just a good programmer with great habits. - Kent Beck"

--

Studies have shown that developers who use best practices when coding are up to 40% more productive than those who do not, and that code with good practices is up to 50% cheaper to maintain than code with poor practices.

Also, companies and governments lose a lot of money every day because developers don't follow the best practices and guidelines. Here are some examples you can read more about:

• NASA's Mars Climate Orbiter was lost because the team was not using consistent metric system in the codebase, which led to confusion in the calculations, losing $320 million.
• The Ariane 5 rocket explosion by ESA was caused by bad code that was very difficult to read, and $370 million was lost
• The US stock market Flash Crash in 2010, with undisclosed significant financial losses.

This lesson is a compilation of best practices that we promote at 4Geeks, it has been created and grown with contributions from all the community mentors.

Global variables

It's best to avoid using global variables whenever possible, use more function arguments and return values to share data between different parts of a program. This can help you make code more maintainable, testable, and reliable.

1. Global variables can be accessed from anywhere in the code, making it more difficult to track down bugs and understand how the code is working.
2. It's harder to isolate problems when multiple parts of the code are interacting with the same global variables.
3. Changes to a global variable can have unintended consequences in other parts of the code.

Variable Names

Some of the naming conventions are given below:

• Meaningful and clear variable names help everyone understanding what goes in said variable.
• General variables should be named in camelCase for JavaScript, Node, Java, etc. And in snake_case for Python, Ruby, etc. Here you can read more about variable naming conventions.
• Constant variables are named in CAPITAL LETTERS.
• It is better to avoid the use of digits in variable names.
• The name of a function should be written in camelCase starting with lower case.
• The name of a function must describe the reason of using the function clearly and briefly.

1Descriptive variable names:
2✅ GOOD: "customer_name" (describes the contents of the variable)
3❌ BAD: "x" (not descriptive or meaningful)
4
5Use naming conventions:
6✅ GOOD: "number_of_items" (full words and snake_case are used)
7❌ BAD: "n_items" (abbreviation is used)
8
9✅ GOOD: "customerName" (camelCase is used)
10❌ BAD: "customername" (no naming convention is used)
11
12Avoid using single-letter names:
13✅ GOOD: "customer_name" (descriptive and meaningful)
14❌ BAD: "x" (single-letter and not descriptive)
15
16Keep names short, but not too short:
17✅ GOOD: "product_price" (short and descriptive)
18❌ BAD: "p" (too short and not descriptive)

Indentation

Use Prettier or any automatic indentation tool. If that is not possible (for some weird reason), make sure to manually indent every single line:

• Pick how many spaces you will use (2 or 4 spaces per single indent).
• In Python it is recommended to use 4 spaces for each indentation PEP8.
• Use a consistent indentation style.
• Indent code blocks: Code blocks, such as those inside of a function or loop, should be indented to visually distinguish them from the surrounding code.

1if (condition) {
2  // code block 1
3} else if (condition) {
4  // code block 2
5} else {
6  // code block 3
7}

Errors and exceptions

When coding, some of the errors are hidden from developers unless exceptions are actively handled. For this reason, we decided to include this guideline in the list.

• Use try-except and try-catch blocks to handle exceptions.
• When fetching data in JavaScript, always include the .catch() function or try-catch block (if using promises) and show the error on the console.
• Log errors and exceptions in the console and log file if possible.
• Avoid suppressing exceptions.

Readability

Creating code that is easy to read is essential for producing high-quality software that is reliable, maintainable, and easy to modify or update. We have a whole article in code readability but here is a very short summary of the best practices:

• Choose variable names wisely.
• Split your code into smaller functions.
• Avoid using else statements.
• Pay good attention to indentation.
• Don't over-comment your code.
• Avoid long lines of code.

Avoid nesting

When possible avoid using nested functions like:

1function calculateDiscount(item, quantity) {
2    if (item.category === 'clothing') {
3        if (quantity >= 10) {
4            return item.price * 0.9;
5        } else {
6            return item.price * 0.95;
7        }
8    } else if (item.category === 'electronics') {
9        if (quantity >= 5) {
10            return item.price * 0.8;
11        } else {
12            return item.price * 0.9;
13        }
14    } else {
15        return item.price;
16    }
17}

The code is nested too deeply and has a complex structure that can be difficult to follow. This can be improved by refactoring the code to use fewer levels of nesting, or by using early returns or refactoring the conditional statements to simplify the structure. Here is an example:

1function calculateDiscount(item, quantity) {
2    if (item.category !== 'clothing' && item.category !== 'electronics') {
3        return item.price;
4    }
5
6    let discount = 1.0;
7    if (item.category === 'clothing') {
8        discount = quantity >= 10 ? 0.9 : 0.95;
9    } else {
10        discount = quantity >= 5 ? 0.8 : 0.9;
11    }
12
13    return item.price * discount;
14}