5 tips for have readable code

I attend a class in my masters that requires that the students be able to code, and some of my classmates haven't experienced this world, so I been watching them going from one tutorial to another giving all of them to learn, so I wanted to give 5 quick tips to help them to improve the readability of their code.

But, what is a readable code? some can define it as the basic conscious that someone, someday, will heredity your code and for that person will be a dream or a living hell to modified or add new functions, so you want that people can understand what you code and in an easier manner, so the tips:

1. Define what will be your naming scheme

There are different naming schemes for your variables, constants and methods, and it doesn't matter which you choose but you need to stick to it through all the code, the 2 schemes that I recommend the most because are the most used are:

• camelCase: The first letter of each word is capitalized, except the first word, like getUserInformation().
• underscores: Underscores between words, like get_user_information().

2. Every time you can, use objects

If you see the opportunity choose objects over variables, always choose the object route and I'm gonna give you an example, maybe the first time you are approaching your functionality you only need to receive the name and Lastname of a person because is the only thing you are going to save, but what if now you need to save the birth date too?? if you chose the object route you only need to add the new variable in the object that you created, but if you didn't in each part of your code where you need the information of that person, now you have to add the variable.

////BAD
void savePerson(string namePerson, string lastNamePerson , dateTime birthDate){
  ...
}

////GOOD
void savePerson(Person person){
  ...
}

3. Always Always format !!

It doesn't matter if you used tabs or spaces but always format in a really consisting manner, personally, I recommend to use the formatting available in your code sniffers and IDEs, because depending on the language could be different.

4. Functions should only do one thing

I know that maybe you have heard about the rule of never have more than 500 lines in your function, but I don't think is a practical rule especially in the backend, the rule that I like to apply is that each function should only do one thing, maybe for achieving it will need to call other functions, but never should do it himself, apply this has many advantages like, is easier to avoid duplicate code and test, compose and reason the function.

////BAD
function notifyGroups(groups) {
  groups.forEach(group=> {
    const listenerRecord = database.lookup(group);
    if (listenerRecord.isActive()) {
      notify(group);
    }
  });
}
////GOOD
function notifyActiveGroups(groups) {
  groups.filter(isListenerActive).forEach(notify);
}

function isListenerActive(group) {
  const listenerRecord = database.lookup(group);
  return listenerRecord.isActive();
}

5. Better names fewer comments

In our community there is a saying "the best comment is the one you never write", but I don't really like that approach, so I incline with the Jason McCreary philosophy that you could resume in 3 phrases:

1. Is better no comment than a badly written or unnecessary comment
2. Code that needs to be explained needs to be improved, so first, try to refactor your code and give better names.
3. Comments are not the devil, they are sometimes justified; for example, when they explain a business rule.

Thank you for reading!