code passion

Coding best practices – Part 1

The aim of this article is to present some good practices that every developer should use in his code.

The audience could be data scientist or people coming to code without all the academical knowledge that every profesional developer has to master.

These practices are applicable to almost all procedural or object languages.

The first statement and the most important is that your code must be readable as a book.

To write this book, we must follow some rules I detail below.

Naming conventions

If you want your code to be readable, naming conventions are essentials. These conventions are to use for: your variables, your functions, your classes. All the entities that you define must be understandable when you read their name.

For the class name, you must explicitly give a full name, not an abbreviation like ‘acc‘ but ‘account‘.

For the variable name, you should avoid ‘i’ for an iterator, also choose an explicit word like ‘account_id‘ for the iterator on a list of account ids.

For functions, use something like a sentence beginning with a verb and a word or group of words designing the data manipulated inside the function. If you want to save an account to a database, write ‘save_account_to_db‘. ‘db’ means of course ‘database’.

The way you write a sentence could be specific depending from the language you use, sometimes camel case like ‘SaveAccountToDb‘ or with underscores. Refer to the documentation of your language.

Comments

Comments in your code are not here to transform you code in natural language, your code is the comment !

Comments in the code are only there to explain some syntax trick or a business rule, or to add a reference to a mathematical formula, or to an external definition with a link to a website.

No more, don’t repeat your code in comment !

It’s better to add an header for the function, it could be useful if you want to use a tool to generate documentation.

Single Responsability Principle

I don’t want to explain ‘SOLID’ principles, they are dedicated to Object Oriented Programming and are not very easy to understand for beginners. You can find plenty of good articles about this acronym.

However, I want to introduce the ‘S’ letter, which means ‘Single Responsability Principle’

This is essential for your function (or class) to do only what is defined in the sentence you gave as a name.

With this principle, your function remains small in term of number of lines. And, in consequence, the number of parameters is small too.

Usually, a function could be about 20-30 lines maximum and number of parameters about 5-7.

The most important is that every line should respect what the function is defined for.

For exemple, the ‘SaveAccountToDb’ could be written like this in C#:

void SaveAccountToDb(Account accountItem)
{
	using (var context = new BankContext())
	{   
    		context.Accounts.Add(accountItem);
    		context.SaveChanges();
	}
}

Furthermore, in Test Driven Development, it is easy to test a feature if it is isolated in a function.

Don’t Repeat Yourself

Another very important principle is ‘DRY’ meaning ‘Don’t Repeat Yourself’.

This statement explains that every code which is repeated must be isolated in a function. Factorisation is a basis task when you write code, and I give you the advice to do it as soon as you write new lines and you identify repetition.

Similarly, any literal or numeric value that repeats more than once without being modified must be defined as a constant, usually in uppercase.

Pretty code

At last, if you follow all these principles, you want to have a good looking code, so use a beautifier. It’s nice to have a beautiful indentation, to delete extra empty lines.

With some languages, you can define regions of code, and these regions can be folded to have a shorter view of your code.

I can summarise these advices in a checklist:

• Be explicit.
• Comment when needed.
• Single Responsability Principle.
• Don’t Repeat Yourself.
• Beautify.

I hope you liked this article and all these advices about good coding. This is the minimum you can use to write clean code.

In a next article, i will write about usage of exception and logging.

I can recommend this book to complete your knowledge Amazon.fr – Clean Code: A Handbook of Agile Software Craftsmanship – Martin, Robert – Livres

Have fun coding !