Any code when written in a clean, easy to understand and formatted way is easily readable and accepted by everyone.
It is essential for everyone to easily understand the code one writes as same projects can involve participation of multiple programmers. For easy identification and understanding of the code and code flow by everyone involved, it is essential that the code is structured, clean, and easily maintainable.
Explained below are some of the practices to write clean and understandable code.
Commenting and Documentation
For any software project reliable documentation is crucial. Commenting and documentation helps one analyze what’s happening inside the code. This is very crucial for the one who is examining the code for the very first time. Writing comments for methods or functions is good for understanding its purpose. They can quickly show what a complex function is doing.
However, don’t write unnecessary comments as it would make your code messy. Obvious commenting does more harm than good. Comment should describe only what the method is doing or why it’s written. It can also describe the purpose of writing the program in a nutshell at the beginning of a class or module.
Adopting a consistent naming convention in your program is always a sensible and thoughtful practice. It’s a set of rules for picking the character flow to be used for identifier, which signify variables, functions & methods. It makes it easier to understand the purpose of using that variable / function / method. If one’s a beginner, it’s a good practice to give meaningful names to your variables, methods, functions etc. instead of vague combinations of alphabets and numbers. Using camelCase and underscores is a widely popular approach. Use of camel case is to be preferred as this does not create confusion between salesforce api names and variable names in case of apex code.
There’s nothing worse than reading a piece of code that is poorly formatted. Indenting makes your code looks neat and clean. It is easy to understand the flow of program, the link between control flow constructs such as loops and codes written inside and outside of them.
Keeping it simple
One should keep their code as simple as possible. Avoid writing complex code for simple logic. Try breaking down your code in multiple methods if the logic is getting too complicated for a single module.
Ideally a method or a function should not have more than 40-50 lines of code, excluding comments.
Modules like servlets, triggers and callouts should not have any logic written in them. All the logical operations should be performed in a helper lass.
It is not advisable to use “hard-coded” values referring to environmental parameters, such as absolute file paths, file name, user name, host name, URLs etc. Else, the application might not run on a host with a different design. An efficient programmer should parametrize such variables and configure them as per the hosting environment outside of the application.
The best way to do it would be to maintain all the required constants in a single file which is easily configurable without making any code changes.
Loops and conditional statements
Beware of using loops and conditional statements in your code! Choose right loops at the right place in order to save code’s execution time.
Too many nested blocks of code can reduce code efficiency and readability drastically.
Omit unwanted code
It’s very common to find a block of code commented inside the program. It’s not going to do any harm to your program but bloats the code unnecessarily, so try not to keep such code. In addition, since this code is not going to be executed or compiled there is no difference between commenting out and deleting that code. Deleting commented codes makes your entire program looks cleaner.
In case of future necessity of the commented blocks, maintain additional backup along with the code repositories.
Do not just copy and paste code
If you have a snippet of, say, seven lines of code that do one thing, and you want to do it again for another module, don’t just copy and paste the code. Instead, make a function and to make it reusable. It’ll keep your code simple.
Code Versioning, popularly known as version control, is the management of the changes made to computer programs, documents and other collection of information.
In computer programming, it refers to the process of tracking & controlling the changes made to the source code.
Version control becomes very important especially when working in a big team as this saves additional time that one might require for code merging and also one can easily backtrack in case of errors.
Code versioning is to be done for every project using available resources like Gitlab, Github, Assembla, etc.