There are numerous ways in which you can affect the correctness of the code you write as well as the capabilities of changing that code in the future. Unit testing, design patterns, and code reviews are all methodologies that have a decisive impact in how your software works.

However, very few things have such a great impact in you as a programmer as the way your code looks. This might be surprising to some people, since it is well-known that the compiler doesn’t care about the organization and cleanliness of a source file. Compilers just care about translating a stream of symbols into a binary file.

The big insight, however, is that source files are not just an input for a compiler. As important as it is to give correct instructions, the far more important role of a source file is to present the solution of a programming problem to other professionals. As such, sources files should be formatted as any other documentation: in a clean and tide way.

Software engineers are required, by profession, to create source code that solves problems. But more often than not, source code is the only form of formal documentation that tells how a program works.

The readers of program code vary in number. If you work in a large company, dozens of other programmers will, at one time or another, need to read your code. However, it pays to write clean code even if you are the only developer in a project.

The main reason is that it is very frequent that you have to revisit a decision made previously. When this happens, you need to consult source files again, and going through a disorganized program can make life miserable. Remember, to start with, that source code is by nature a difficult document to comprehend.

The other reason is that, these days, it is very rare that you will be the only person to see a source file. First, the project that you are now working on can become something of interest for other people in the future. For example, you can open source it and distribute the software to a small community. Or you may even start a business based on that application, a business that will end up having other developers.

What all this says is that it pays to be clean and thorough when writing software. Even if nobody ever see your source file again, not even yourself, think of it as training. In a future job you can expect that other people will be able to observe and understand what you’re doing.

Things to Consider

Spelling: It may seem unimportant at first, but using the right spelling has great impact on the resulting quality of source code. For example, making sure that variables are named with the correct spelling may be the difference between finding that variable or not, when using search tools such as grep. Moreover, it shows that you can communicate well and work in a professional way.

Commenting: there are many opinions about the right amount of commenting in source files. Some people think it is not necessary, while others believe you should write as much as possible. Whatever your opinion of commenting, do it consistently. Make a point of adding as much information as you feel necessary. Also, get in the habit of doing so while actually writing the code. It is too much a temptation to leave such things until after the code is done, when you will probably have forgotten a lot of the original context of the comments.

Empty Spaces: Be consistent with empty spaces, both vertical and horizontal. The most important goal is to have equal spacing everywhere in the source file. Languages such as C++ have different standards for this, for example the location of braces. Pick the method you like most, but make sure that it is applied everywhere in your project. If you’re using external libraries, however, don’t make changes to the file just for the sake of formatting: it is Ok to have external code that looks different.

Conclusion

Writing correct software is a good starting point, but is not enough. Good software is also a communications tool, and must be treated as such.

Also, writing clean code is a matter of professionalism. You cannot write sloppy code and expect be considered seriously by others. They will see a lack in cleanliness as a consequence of a lack of care — which usually is the case.

Similar Posts:

• How much code should you write?
• Day 25: Learning to Document Properly
• Isolating Dependencies in C++ Code
• Using Vim with NERD Tree
• Editing multiple files in a single buffer