Coding standards that everyone must follow

Introduction

• First rule of coding - write clean, beautiful and elegant code
• Second rule of coding - write clean, beautiful and elegant code
• Take time and effort to keep our code clean and pleasing for everyone to read
• Follow these basic coding principles:
• KISS – Keep It Simple, Stupid
• SOLID Principles
• Inversion of Control
• DRY – Don’t Repeat Yourself.
• YAGNI – You Ain’t Gonna Need It.
• Law of Demeter.
• Follow Boy’s Scout rule – leave code better than you found it.
• Use “Design Patterns” whenever it makes sense to do it.
• Avoid Premature Optimization – Premature Optimization is the root of all evil (or at least most of it) in programming. It adds unnecessary complexity in code and makes it hard to maintain in the long run. Always measure, analyze and then optimize.
• Pay attention to all IDE generated warnings/suggestions

General

• Favor composition over inheritance.
• Create abstraction that separate higher level concepts from lower level details.
• Variables and functions should be defined close to where they are used.
• When a method uses getter/setter excessively from other class, consider moving that logic to that class.
• Make sure all DTOs and Value Objects are immutable.
• Avoid magic numbers, Hungarian notations in code. Use named constant instead of magic numbers

Core Java

• Leverage Java 8’s stream API as much as you can instead of processing collection/array explicitly. For simple operations see if makes sense to process the collection without using stream API.
• Use Lombok to generate boilerplate code. But do not overuse it to generate code that you don’t need
• Avoid annotations like @SneakyThrow, @data, @synchronized from Lombok
• Before using @Value annotation make sure you really need all functionality provided by @Value
• Create new type instead of passing around complex collection types around e.g. instead of using List> create a type that represents that collection at higher abstraction
• Use enums instead of constants
• Investigate if there’s a reliable third-party library available before writing your own utility methods. Apache commons, Google Guava and Spring Utils are good example of third-party libraries that provides tons of useful functionality
• Use meaningful and explanatory name that reveals the intention of variable/class/method
• If name requires comment, it doesn’t reveal its intention. Consider re-naming such variables
• Use long and descriptive name but do not use very long variable name that it starting to look like sentence
• Avoid unnecessarily acronymization of variable name. A variable called “timeSheet” is much more descriptive and meaningful than “ts”
• Class Names – Classes and Objects should have noun or noun phrase names. E.g. TimeSheet, WorkEntry. It should not be a verb.
• Method Names – Method should have verb or verb phrase names. E.g. approveTimeSheet, submitWorkEntry
• Event Class Names - Should be verb in past tense E.g.TimeSheetSubmitted

Comments

• Avoid comments. We should strive at writing self-explanatory code that requires minimum to no comments. Ideally, our code should not have any comments. If your code needs commenting, you might be doing something wrong
• Do not comment change history, user story in source code – it should go as part of your commit message. All meta-data about code like author, last modified time, US number, Defect Numbers should not be part of code
• Do not use Javadoc comment that says nothing more than function signature
• Javadoc style comments which are mainly used for documentation should be limited for library functionality
• Never ever comment out code. Just delete it.
• Comment should be used only when code cannot say for itself clearly

Functions

• Functions should be small. This applies to code blocks like if, while, switch blocks etc.
• Function should do one thing only
• If your function has more than a few arguments, see if your method has tight coupling with other classes. If you do need those arguments, try to wrap them in separate class
• Avoid Boolean flag as method parameter that is used as a flag to choose behavior in method
• Return java.util.Optional instead of "return null" from method

Tests

• Make sure your tests cover all scenarios specified.
• Write unit test for everything that could possibly break
• Use IDE coverage tool to make sure you are covering all critical code path and branches
• Test all boundary conditions
• Write test (or tests) for each reported bug