“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” - Martin Fowler
One should always try to build good software. Good software can be judged by reading some code written in the project. If the code is easy to understand and easy to change, then definitely it’s good software.
Following are some tips (that I learned from the book - “The Clean Code” - Robert C. Martin)
Naming
In a software product, we name our variables, functions, classes, packages, etc. We name our directories, the source files, etc. Since names are everywhere, one should use meaningful names, easily making the reader understand their intention. Try to follow camelCaseNaming wherever possible.
As an example, consider the following code snippet.
In the above code, both line 1 and line 3 have a variable declared. As a reader, one can easily infer the meaning of distanceBetweenXY rather than dxy. If dxy had been used, you'd probably have to read the entire chunk of code to reverse engineer its meaning. Hence, one should always use meaningful names.
Functions
Break a big code into functions. Try to keep small functions. Understanding functions with hundreds of lines of code is complicated. In such a case, comments do help but only to a limited extent. Using multiple functions makes the code organized and easier to understand.
Every function should aim to do one thing, and every class should represent one particular concept. As an example, consider the following code snippet.
In the above code snippet, the calculate function is further broken down into 4 functions - add, subtract, multiply and divide.
Unnecessary Code
Rather than commenting on the unnecessary/old/unoptimized code, remove it. To save the code as a backup, it is better to use source control. Also, avoid repetitive code; otherwise, it will look messy and unnecessarily long.
This increases the readability of the code.
Comments
Comment every function, every variable, etc. Comments help you to explain the code to others. Comments will help you and others understand why you did what you did. When you write it, it may seem obvious to you, but will others who work on the code understand it? Will you remember what you did after a month or a year?
Writing good comments is important. Comments are really helpful in explaining the code what it does, but it also requires more maintenance of your code. One should avoid writing unnecessary comments. In the above code snippet, check out the comments.
Indentation
One should properly consistently indent the code. Style is important, not to make code look pretty, but because it helps with reading, editing, and understanding. In the above code snippet, check out how the code has been indented.
Exception Handling
Always use the exception handling feature in your code. Surround the code statements with try-catch-finally statements.
Exception handling ensures that the flow of the program doesn't break when an exception occurs. It would also help debug the code in case of any error.
Clever Code
If using some tricks, try to explain the same using comments in the code. Else prefer an easily readable and understandable approach.
Always remember: Readability > Cleverness
Lastly, always try to maintain consistency, simplicity, and readability.