How to write clean or high quality code?09/30/2019
If you look any of the printed or online material that is dedicated to writing code these days you will see the term "clean code" bantered about quite a bit. The problem is that while many of these articles tout the virtues of clean code, they do very little to tell the reader what clean code actually is.
Clean code is definitely something that does not happen by accident. It is something that the serious coder does very carefully and purposefully. Although clean code may look better then crappy code, "looking pretty" is not why the coder does it. The coder does it to make the code flow easier to understand and follow.
Most modern programming languages like C, and Golang allow for the decomposition of larger programming tasks into smaller ones called functions, or subroutines. Object oriented languages like C#, C++, java, python, and even PHP (this is fairly advanced PHP, for examples see the latest and best PHP books) allow decomposition into objects that interact using function-like entities called methods. Even large and complex websites written in HTML with CSS running on any number of frameworks can be cleanly written if those coding know what they are doing.
The first rule to writing clean code is the K.I.S.S principle the we all know and love. If you have been living on a different planet and have not been clued-in on this one, K.I.S.S stands for Keep It Simple Stupid. Try to break the program up into small easy to under stand pieces. As a matter of principle, try to keep functions short and sweet. If they are getting longer than 50 or 75 lines of code, it might be time to consider refactoring the code and breaking the function up into two or more smaller functions. Another case for refactoring is when code gets too complicated or "nested" with multiple levels of conditional and looping statements. Code that is organized this way can be hard to follow, but when refactored and split into smaller bite-sized chunks it can be easier to visualize and comprehend.
The second rule to writing clean code is to make sure that your functions and your variables have meaningful names. These names should indicate something about what they are or what they do. Nothing is more worrisome than trying to debug code where all of the variables are named "x", "y", "i", and "j", and the functions are named "doit" or "run". Names like these do not convey any meaning about what the variables represent or what the functions do. A variable named "PartNumber" and a function named "FindItemInCatalog" are much more helpful in trying to understand how the program works.
The third rule to writing clean code is to make sure that your code is commented well. This does not mean that every single line needs to have a comment about it. However, comment blocks at the beginning of functions explaining what the inputs and outputs of the function are very helpful. In addition, in-line comments describing the overall objective of a series of lines of code that may not be openly obvious is also a good idea. Basically, your objective should be to be able to come back to this code a few years down the road and be able to work on it just by reading the comments that you have left behind.
The fourth rule to writing clean code is to verify that all code paths have been covered. That there are no "corner-cases" that you have left uncovered. For example, if you are expecting the user to type in their phone number and they enter a letter ... what happens? Or, if you are reading data from a database and you get an error opening the database ... what does the program do?
Most of these rules may seem like common sense, and all of them will serve to improve code quality. However, you would be surprised by the amount of poorly written code there is out there. All it takes is having to debug poorly written code one time before you will become a devout fan of clean coding.
In an effort to combat poor coding most companies that do any level of coding have developed coding style guides and practices of their own. Some require peer code reviews. Some even resort to automated tools to enforce their standards. All of this is in effort to have their coders do what they should have been doing all along, coding cleanly. It is as much for the coder's sanity as it is for their employer. In the end, which would you want to put your name on ... clean code? or shit code?