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 lead to a confusion in the calculations, losing $320 million.
• The Ariane 5 rocket explosion by ESA was caused by bad code 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 to 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 understandable variables name helps anyone to understand the reason for using them.
• General variables should be named in camelCase for Javascript, Node, Java, Ruby, etc., in snake_case for python, 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 names of the function should be written in camel case starting with small letters.
• The name of the 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 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 a prettier or more automatic indentation tool. If that is not possible (because of some weird reason), make sure to manually indent every single:

• Pick how many spaces you will use (2 or 4 spaces per single indent).
• 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 code, some of the errors are hidden to developers unless exceptions are actively handled, for this reason, we decided to include this guideline into 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:

1def calculate_discount(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  elif item.category == 'electronics':
8    if quantity >= 5:
9      return item.price * 0.8
10    else:
11      return item.price * 0.9
12  else:
13    return item.price

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:

1def calculate_discount(item, quantity):
2  if item.category != 'clothing' and item.category != 'electronics':
3    return item.price
4  
5  discount = 1.0
6  if item.category == 'clothing':
7    discount = 0.9 if quantity >= 10 else 0.95
8  else:
9    discount = 0.8 if quantity >= 5 else 0.9
10  
11  return item.price * discount