Coding Standards
The document gives the summary of general coding standards that will be used for this project.
In addition, it drills deep to the front-end language Angular 6 and the backend language Java 8 and provide specific instructions and directs to the formatters, lints that can be used to ensure that the coding principles are followed.
The rule of thumb
Follow the generic principles outlined here when writing each line of code, which ever language it may be. Make use of the formatter and lint where ever possible to ensure the standards.
It is the responsibility of the developer to make sure that the coding standard is met. Also it is the responsibility of the reviewers to ensure that any code that does not meet the coding standards is blocked from getting into the master.
Clean Code Principles Summary
- Credits: Clean Code - A Handbook of Agile Software Craftsmanship by Robert C. Martin
- Credits for Summary: https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988cf8d29
Code is clean if it can be understood easily – by everyone on the team. Clean code can be read and enhanced by a developer other than its original author. With understandability comes readability, changeability, extensibility and maintainability.
General rules
- Follow standard conventions.
- Keep it simple stupid. Simpler is always better. Reduce complexity as much as possible.
- Boy scout rule. Leave the campground cleaner than you found it.
- Always find root cause. Always look for the root cause of a problem.
Design rules
- Keep configurable data at high levels.
- Prefer polymorphism to if/else or switch/case.
- Separate multi-threading code.
- Prevent over-configurability.
- Use dependency injection.
- Follow Law of Demeter. A class should know only its direct dependencies.
Understandability tips
- Be consistent. If you do something a certain way, do all similar things in the same way.
- Use explanatory variables.
- Encapsulate boundary conditions. Boundary conditions are hard to keep track of. Put the processing for them in one place.
- Prefer dedicated value objects to primitive type.
- Avoid logical dependency. Don’t write methods which works correctly depending on something else in the same class.
- Avoid negative conditionals.
Names rules
- Choose descriptive and unambiguous names.
- Make meaningful distinction.
- Use pronounceable names.
- Use searchable names.
- Replace magic numbers with named constants.
- Avoid encodings. Don’t append prefixes or type information.
Functions rules
- Small.
- Do one thing.
- Use descriptive names.
- Prefer fewer arguments.
- Have no side effects.
- Don’t use flag arguments. Split method into several independent methods that can be called from the client without the flag.
Comments rules
- Always try to explain yourself in code.
- Don’t be redundant.
- Don’t add obvious noise.
- Don’t use closing brace comments.
- Don’t comment out code. Just remove.
- Use as explanation of intent.
- Use as clarification of code.
- Use as warning of consequences.
Source code structure
- Separate concepts vertically.
- Related code should appear vertically dense.
- Declare variables close to their usage.
- Dependent functions should be close.
- Similar functions should be close.
- Place functions in the downward direction.
- Keep lines short.
- Don’t use horizontal alignment.
- Use white space to associate related things and disassociate weakly related.
- Don’t break indentation.
Objects and data structures
- Hide internal structure.
- Prefer data structures.
- Avoid hybrids structures (half object and half data).
- Should be small.
- Do one thing.
- Small number of instance variables.
- Base class should know nothing about their derivatives.
- Better to have many functions than to pass some code into a function to select a behavior.
- Prefer non-static methods to static methods.
Tests
- One assert per test.
- Readable.
- Fast.
- Independent.
- Repeatable.
- The Unit Tests should not have dependencies of network or static assets. Mock then as required.
Code smells
- Rigidity. The software is difficult to change. A small change causes a cascade of subsequent changes.
- Fragility. The software breaks in many places due to a single change.
- Immobility. You cannot reuse parts of the code in other projects because of involved risks and high effort.
- Needless Complexity.
- Needless Repetition.
- Opacity. The code is hard to understand.
JAVA
- Use the formatter available in the location here. Please refer to the following link to import the formatter into eclipse and use Ctrl + Shift + F to autoformat your code.
- Also make sure to import the clean-up profile available in the location
. Please refer to the following [link](https://raw.githubusercontent.com/trinitywayfinders/WayFinder/master/Documentation/Coding_Standards/eclipse/wayfinder-clean-up-profile.xml). Once the code implementation is done, use Source --> Cleanup to run the cleanup wizard with the imported cleanup profile. - Make sure to submit your code to SonarQube and ensure that there are no critical warning and no/very less major issues. The documentation for submitting your code to SonarQube. The instruction for SonarQube submission are available in the wiki.
Angular 6
- Use ATOM beautify plugin and enable the beautify on save option. Please use the instruction available here