General Coding Guidelines: Clean Code From Day 1

Help your teammates understand, reuse and extend your code easily, and help them not to introduce bugs while they are at it.

Make people happy with your code

Good coding habits make working with your team a piece of cake

The life of a programmer is beautiful when the code they work with is beautiful. Through your code, you have the power to affect the life of your fellow programmers:

  • They will spend 10 minutes/1 hour understanding the code you wrote.
  • They will introduce 0 bugs/2 bugs when they edit the code you wrote.
Every time you code like this you make a programmer cry

Make Your Code Readable

Your teammates and your future self should be able to understand, reuse and extend your code seamlessly whenever they need to.

1. Use Meaningful Names and Avoid Made-Up Acronyms

// Avoid this
label1.text = dog.name
label2.text = dog.breed
label3.text = dog.int_temp
label4.text = dog.breed.int_fact
// Do this
name_label.text = dog.name
breed_label.text = dog.breed
internal_temperature_label.text = dog.internal_temperature
interesting_fact_label.text = dog.breed.interesting_fact

2. Follow the Conventions

I cannot tell you exactly how to name your variables, functions and other stuff because I don’t know what programming language you are using. Each language, and sometimes each project, has a specific coding convention.

Each language has a specific coding style

3. Keep Functions Short and to the Point

How short? around 20 lines of code or less. And yes, nobody likes to count lines of code while coding. Thankfully, you don’t have to do that, you can use the old recommendation: the function should fit entirely on your screen so that you don’t have to scroll to read it completely.

If your function occupies a huge screen entirely, it doesn’t count as a short function

4. Update Member Variables Explicitly

Other guides explain this more broadly by saying:

5. Use Comments Wisely

Your comments should not explain step by step what the code is doing. Your excellent variable/method/class naming skills will take care of that.

Make Your Code Robust

Your teammates and your future self should be able to edit your code without introducing bugs in the process.

1. Avoid Duplication

The famous DRY (Don’t Repeat Yourself).

// Written by Tommy two weeks ago
setHourlyAlarm() {
/**
* Very cool code for setting an alarm <- DUPLICATED
*/
/**
* Very cool code to do it hourly
*/
}
// Written by you just now because you didn't see Tommy's code
setDailyAlarm() {
/**
* Very cool code for setting an alarm <- DUPLICATED
*/
/**
* Very cool code to do it daily
*/
}

2. Avoid Hard-Coded Strings and Magic Numbers

Every string should be a reference to a string resource, an enum or a constant. Why? because you think that you’ll only use that string this one time. What you don’t know is that there will come a fateful day when that string is used in another place too. And after that, will come an even worse day when someone edits that string, and they only edit it in one place because they have no idea it exists somewhere else. Only very careful people do a “Find in project” for every hard-coded string they update.

Hard-coded strings are death bringers
// Avoid this
switch(status) {
case 1:
do_this();
break;
case 2:
do_that();
break;
default:
do_something_else();
}
// Do this
switch(status) {
case STATUS_ENABLED:
do_this();
break;
case STATUS_DISABLED:
do_that();
break;
default:
do_something_else();
}

3. Check Values From Unreliable Sources

Or, in the words of my friend Gabriel Aguirre:

// Avoid this
// This code throws a null exception
// if the JSON doesn't have the 'name' or 'breed' properties
dogName = dogDataJSON.get("name").getAsString();
dogBreed = dogDataJSON.get("breed").getAsString();
// Do this
// Do a null check before working with data obtained from the server
dogName = dogDataJSON.get("name") != null?
dogDataJSON.get("name").getAsString() : "";
dogBreed = dogDataJSON.get("breed") != null?
dogDataJSON.get("breed").getAsString() : "";

4. Always Write the Braces Around Single Line Blocks

We all know that when you have an if statement with just one line, you can omit the braces. Please don’t do this. This is extremely error prone, and I’ll tell you why:

Single-line blocks without braces are the true death bringers

Write Everything Code-Related in English

This may seem obvious for native English speakers, but I have seen code from Spanish speaking programmers with comments, variable names and function names written in Spanish. This is not a good practice.

  • It’s easier to ask a question in Stack Overflow and copy/paste your code without translating the comments or variable/function names for people around the world to answer your question.
  • It allows you to seamlessly add a new team member from another country to your project, because every programmer knows English.
  • Getters and setters: it’s weird to have getters and setters that don’t start with get and set. So some people mix the get/set word with the Spanish word for the object they are getting/setting. That’s kind of weird.

Final Words

I know it’s difficult to apply all these guidelines while you are coding because you are focused on the functionality you are writing and you probably are short on time and that’s OK. But once you finish writing a piece of functionality or you are ready to push some code… STOP! and read the code. Read it and and you’ll realize if your teammates will be able to understand your code easily or if they’ll have a hard time modifying it.

Maria Luisa Carrion D.

Written by

Software engineer and hobbyist 3d modeler. Sketchfab: https://sketchfab.com/marilu597