Blog

Coding guidelines are extremely important part of a professional developer’s day to day practices. Following these guidelines differentiate between an experienced developer and a rookie.

It surprises me that so many companies still ignore them and produce poor quality code that results in very expensive maintenance over the period and is so fragile that every time you add a new feature immediately bugs creeps in.

I am sharing some of these guidelines which are far from exhaustive but are most important for me. Some things people might not agree with but these are my experiences and many of them are borrowed from classic tests.

GENERAL CODING STANDARDS

These are general predefined standards for developing a code. This reduces

1. Naming Conventions should be descriptive (Variable as well as functions).
2. Your application must have separate static and dynamic parts.
3. No Hard Coding. Find an appropriate place where you can define constants or enums.
4. Prefer simplicity over complexity. If your code is turning out to be very complex most likely you are doing something wrong. As the saying goes its “hard to build simple things”
5. Avoid premature optimization. Define premature optimization for your own use case. Well sounds awkward. Trust me it is. Only experience can tell you what does this really mean
6. Always look for the possibility of following a standard Design Pattern. Tweak it for your own use case
7. Strictly prohibit repetitive code. If the code is repeating it’s a candidate for refactoring.

CLASS DESIGN

1. Class should not be more than 600 lines.
2. Constructor should not have any complex logic and has to be exception safe.
3. Prefer composition over inheritance.
4. Follow one responsibility rule everywhere.
5. Design for extensibility.
6. If in Object Oriented language always define an interface.
7. Avoid circular dependency.

COMMENTS AND ERROR MESSAGES

1. Write comments at all critical places in your code including variable name, their usage, function signature (input/output/parameters).
2. Work with error messages framework. Using error codes for displaying error messages is confusing as it’s hard to figure out which error code is coming from which place. To avoid this chaos, it is recommended to use error message framework.

IF ELSE STATEMENTS

1. Do not write deep nested if else statements.
2. Operator precedence for your language can introduce nasty bugs in your code which are extremely hard to debug. Follow a policy of using parenthesis while writing long if else conditions.

IMPLEMENT OOPS

It is recommended to implement OOPS in your code as much as possible. Program to an interface (contract), not class. Try to make an abstract class for a business service (in case of python/C++, interface in case of Java).

FUNCTIONS

1. Function should not be more than 25 lines.
2. Always check for valid parameters inside public functions. Throw an exception to report an error in params
3. To group the statements logically, try to divide different sections of a function into other smaller functions. E.g. Separate function for initializing values for every possible activity.
4. Use functional programming capabilities if your stack supports it. I.e. pass around functions to write reusable code.
5. Follow Single Responsibility Rule as closely as possible.
6. Functions have to be testable (I should be able to write unit test case for this function). In other words promote loose coupling via Dependency Injection or otherwise.
7. To continue with loose coupling follow the rule “Prefer composition over inheritance”.
8. If you are working with Java8 Never return null. Consider returning Optional
9. Try to avoid multiple return statements. This can put nasty bugs inside programs so it’s best to avoid them as much as possible.
10. Check Big O Complexity of algorithm you are writing. Especially for the case, where you are writing a lot of lines of code or for functions which are on a critical path.

LAYERED ARCHITECTURE

Follow layered architecture in true spirit. Upper Layer should call into lower layers and each layer has to be designed for specific purpose. E.g. while following MVC, Logic in views has to be related to view and all heavy lifting shall be done by the service layer.

PACKAGES

1. All Java Packages should start with com.yourcompany. Check for specific naming convention in your stack but the topmost package has to be your company.
2. Define functions in packages instead of utility. It’s a common malpractice to put every seemingly useful function inside utility classes. And while writing code it becomes difficult to look into these packages. If it’s a business utility function then try to find a proper package for it rather than putting function inside utility classes. Utility classes generally shall have function related to common tasks like String Reverse or some Math functions or may be emailed format checking utility.

LOGGING/TRACING

1. It is recommended to use logging, wherever possible. Purpose of the logging is to diagnose any potential issues in production. Logging is useful but it incurs significant overhead on the application so it must be used wisely and only information required shall be logged.
2. Logging should not be cluttered, it must follow same consistent pattern across the application. Identify a pattern for logging for your specific use case.
3. Logging libraries are incredibly useful. Use their package level capabilities to switch on/off selective logging at different levels.

EXCEPTION HANDLING

1. Do not suppress exceptions.
2. If an exception is explicitly raised in a function then it should not be handled in that same function. Create a separate function to handle exception and process.
3. Do not suppress original exception even if you have to create a new exception.
4. Try to use already available functions in logging libraries.
5. Comment on bypassing function i.e if we are passing any exception then mention in a comment why we are doing this.
6. Try following naming convention for exceptions as per your language e.g. Exception suffix in Java.
7. Do not write complex code in handler. Lot of times this code block throws an exception and hides original exception.
8. Read about exception handling best practices for your respective language and follow same.