Clean coding (Part 1)

Chapter 1: Before starting

As Robert Martin explains in his book “Clean Code”, the only valid measurement of code quality is the number of WTFs per minute.

If you want to generate a good code, the very first things you need is to structure your project and name your files in a way that anybody, including you, may understand in the future without going deep into the code.

There is nothing worst in a project than having to read the code to know whats going on, especially when you need to change something and you struggle to find out where the actual code is. It's an exponential waste of time increased by the number of teammates you have to ask, and worst of all, the catastrophic scenario where you need to figure it out by yourself.
Even when you're working solo in a project, it really doesn't matter, because after the third month you will have to refresh your mind, and after the sixth month you will become a team member of your own project, you won’t remember anything you did and why you did it.

Simple structure

There are three big areas that any project should cover:

These areas are separated by a reason, you may want to bundle your product without documentation or testing to keep things light.

1. Documentation.
Important for the development process and especially for final users. Never wait to finish a project to document it, it MUST be done during the developing process. You explain something better when you are working on it, also another team member may need to use your stuff and he won’t consume your time asking you if he can just read it.

A good documentation consists of:

• API: It's a reference manual containing all the information required to work with the program: functions, classes, return types, arguments and more.
• Examples: Usage demonstration of the final product.
• Manuals/Tutorials: Instructions on how to install, integrate and use the software.

2. Source.
The application code. Code written by you, frameworks used and each resource that the application needs to run.

The image above is taken from a node project I’m working at Vimlet

• lib - I personally don’t like to work with huge files so I tend to split the code into several files and require them where needed. This directory is used to store those files.
• server - In this particular case, we have a server to run our web application. server code goes here.
• webapp - The web application itself, where the server will find the "index.html".

3. Tests.
Tests are fundamental to write clean code. Same as doc, tests need to be done while developing and of course before working on the release version.

Tests should be independent of each other, It's a good practice to create a self-contained directory for each one.

There are more complex scenarios but the basics are the same:

In this example, I split my directories in scenes. I do that for everything in the game, it is easier to find a song, an image, a script if you keep it tidy.

Naming

It's the last step of finding something, it's very important to name directories and files in a consistent and clear way.

There are many rules to follow naming files, like not use verbs as suffixes or prefixes, not use redundant words like (the, a, object, info…). I personally don’t follow too many rules apart from being consistent and descriptive.

The same pattern applies to directories, I rather prefer a directory containing a single file than a directory called "misc" or "resources", full of trash, because in the future it will become hard to find anything in it.

Conclusion

A good documentation saves time. First, to your teammates and your colleagues, that will be able to work along with you understanding your code. Finally to your end user, that will know how to use it and might get involved in the development process.

Tests have become my favorite time-saving tool. Having strong tests won’t let bugs live long before you notice them, they also help to find where they are if you keep making tests while working.