Guidelines - my-accounts/accounts GitHub Wiki

Code Readability

General: Remember that you are not writing your code for you. You are writing it for everyone else who will ever work on it. Make them like you!

Layout: Use consistent indentation and spacing (Tab and Indentation Size should be 4 whitespace characters). Code layout should be neat, clean and tidy. If it is abundantly obvious that you care about your code then future developers will be much less likely to add hacks to it.

Naming: Name classes, methods and variables using the common language of the domain model, so it becomes the domain model.

Naming: Use concise, properly descriptive names (i.e. don't call anything a name that includes the following: 'Helper', 'Manager', 'Utils', 'Utility'). If a method has a long name then check that it isn't doing more than one thing - and if it is, then refactor it into two methods. Naming is difficult: if you can't think of the correct name for something then pair with someone.

Naming: Don't use Hungarian notation. Don't use the variable type in variable names. Don't repeat the class name in properties or getters and setters.

Boolean Naming: Prefix methods that return booleans with "is/has/can" to signify the boolean response.

Intent and Flow: Design your method names so that your code flows as closely to natural language as possible. Good code is so clear, it is self-documenting.

Comments: Use as required. For each comment, then look at why you need it. A comment is a sign that your code is not clear enough, so refactor it to the point where it is so clear that you no longer need the comment (e.g. extract the commented code into a new method named after the comment text). Delete the comment.

Code StructureNesting: No method should have more than three levels of nesting. Refactor deeper levels into separate methods. Test all paths through conditionals, and use sparing (i.e. refactor to polymorphism).

Duplication: Be ruthless about removing code duplication: it makes code hard to maintain, more likely to break when changed and less reliable to test.

Error Handling: Keep error handling at tier boundaries, not scattered throughout the codebase. The meaning of exceptions should be scoped to the tier within which they are raised, and then wrapped in outer exceptions if they are bubbled up to higher tiers. Do not use try/catch exception handling to control program flow!

Inheritance: Use sparingly and beware of breaking encapsulation via subclassing (reread the first chapter of Gang of Four if you can't remember why this is important)

Observe SOLID principles: Single Responsibility Principle, Open-Closed Principle, Liskov Substitution Principle, Interface Segregation Principle, Dependency Inversion Principle

Observe Law of Demeter (aka. only talk to your neighbours): Method M of object O should only call other methods on O, methods on objects passed to O or methods on objects created by O

Observe "Tell Don't Ask" programming style: Tell objects to do things for you - don't ask them for their data and then perform manipulations externally. This ensures state and behaviour are managed in one place, where they belong in the relevant domain model entity. It also highlights the importance of messages between objects, i.e. the "tell" method calls.

Version Control

Check-in Comments: Every commit should include a comment with a brief overview of the change and an explanation of why the change was made.

Code Coverage: A commit should not reduce test coverage. It should only maintain or increase coverage. Branching: Don't do it unless you are really clear why you need it. Ensuring trunk is always remains in a fully deployable state is the safe and simple option.