In continuation with the clean code series, here I am covering Comments, Formatting, and Objects and data structures.
- Code should be self-explanatory, the purpose of the code is that humans should be able to understand and not that computer is able to execute it
- Comment only where logic is complex
- Private API should not have comments
- Use comments when you want to caution other developers, for example, why List instead of Queue was chosen and should not be modified
- Comments should answer why (was a decision made) and not how the code works
- Formatting is a way to communicate with fellow developers
- Readability = Maintainability = Extensibility
- Verticle Alignment: Keep connected functions together for better readability
- Horizontal Alignment: one should never need to scroll right
- Team Formatting Rules: everyone should follow the same rules, braces, ident size, spaces/tabs
Objects and Data Structures
- Follow OOPS Principles, e.g. parameters and behavior should be encapsulated
- Law of Demeter: M method of an object O can only consume services of the following types of objects:
- The object itself, O.
- The M parameters.
- Any object created or instantiated by M.
- Direct components of O.
- Avoid Static methods wherever possible