Development standards

``## Basics

• Fix warnings whenever possible. Only unavoidable warnings are acceptable.
• Do not use deprecated APIs. Calls to deprecated methods must be reduced over time, never increased.
• Always chain exceptions, i.e. pass the original exception to the constructor of the new exception. Never discard a caught exception.
• No console output. Do not use System.out.println(...), e.printStackTrace() etc.
• Follow established patterns and conventions. For example: Java package and Maven module names are lower case; Methods that return collection types never return null; etc.
• Maintain consistent ordering of declarations. For example: Error code enum constants are ordered by code; Dependencies in pom.xml files are ordered alphabetically within groups; etc.

Question and Answers

General

Q: I am adding a constant to a class. What are the considerations ?

A: First, if the content is text intended to be shown to users then do not create a constant. Instead add a message to a properties file.

Otherwise, in most cases an enum type is preferred.

1. Check for an existing enum that meets your needs.
2. If no enum exists, and you expect the constant to be required outside your class(i.e: it is public), then create a new enum.
3. Otherwise, declare a nested enum within the class.
4. In simple cases, declare a private static final field instead of an enum.

Q: I am adding a field to a class. Where should it go ?

A: Do not simply append the new field without consideration. Assess the existing fields and then insert the new field in a well position.

• Are the fields categorised into groups ?
• Is there a logical sequence? For example firstname, middle name and last name ?
• Are the fields in alphabetical order ? Are they in alphabetical order within groups ?

Remember to insert getters and setters in the same sequence as field declarations.

Q: I am injecting an EJB into a class. What annotation should be used ?

A: Use @Inject. Do not use @EJB.

Q: I am injecting a bean into a class. WHat access modifier should be used ?

A: Declare the field with package scope, i.e. no access modifier:

• It is better for testing. A private field without a setter can be problematic when setting up test cases.
• Readability is improved. The declaration reads cleanly without an access modifier, and the line is shorter.

Q: I am adding serialVersionUID to a class. What value should i assign?

A: private static final long serialVersionUID = 1L;

Q: Should package names be plural?

A: No, Package names are singular. For example a.b.c.mapper is a package name for mapper classes. Do not use a.b.c.mappers.

Q: Should class names be plural ?

A: No. Class names are singular. Plural class names lead to difficulty when naming collections.

Q: How do i capitalize all uppercase brandnames or acronyms in class/method/variable names?

A: Treat them as a word and capitalize appropriately. No exceptions.

Q: I am declaring a list of widgets. Do i name the field/variable widgets or widgetList ?

A: Name it widgets. Collections should have plural names. Avoid using the collection type as a prefix or suffix.

Q: Should i use prefixes such as 'm' for a member field, 'p' for a parameter, and 's' for static ?

A: No. They are detrimental to readability.

Q: Can i use an automatic code formatting tool ?

A: Generally not. Do not reformat existing code without a compelling reason. Formatting tools may only be ised with the greatest of care. Their default configurations are universally unsuitable. Do not destroy the effort your colleagues put into laying out their code. Do not pollute the diffs.

Q: Can i use an IDE to generate equals and hashcode methods ?

A: No. The generated code is too far inferior to a hand written implementation. Use java.util.Objects.hash(Objects....) and java.util.Object.equals(Object, Object) to create readable and null-safe implementations.

Q: Can i use IDE to generate getters and setters ?

A: Yes, but you are still responsible for the results. Make sure that

• The setters is declared immediately after the getter.
• There is one blank line between methods.
• Getters appear in the same order as the field declarations.
• Getters that return collections must never return null.

Q: Should i generate Javadoc for getter and setter ?

A: No. Geterated Javadoc detracts from readability and add zero useful information. Getters and setters are self documenting.

Hard Coading Messages

User displayable messages must be stored in a properties files. The "message" framework component provides lookup and formatting capabilities. Hard coading messages is a bad practise because:

• It promotes duplication.
• It prevents localization.
• It clutters the code.

Code Review

Checklist

1. Is there 85% unit test coverage against the TSL ? Disabling unit tests is strongly discouraged. Commenting-out, adding an @Ignore annotation, and removing the @Test annotation are all examples of disabling.
2. Any instances of the common mistakes ?

• Throwing BusinessExceptions
• Instantiating a BusinessException without any Error codes
• Throwing Non Business Exception
• Catching java.lang.Exception
• Hard Coding Messages
• Returning null collections
• Constructing a BigDecimal from a Floating-Point Literal
• Duplication
• Weak Types
• Verbose Logging
• Mapping Boolean Database Columns to java.lang.String
• Needlessly calling Hibernate Session.Update()
• Indirectly accessing fields from Unit Tests
• Indenting to the wrong level

3. Adding references to deprecated fields, methods, classes etc is not allowed.
4. String literals should be avoided in services, delegates, and data access objects. Instead use enum, configuration properties and message properties. Places where string literals should be used:

• Log messages
• Exception messages that are not used displayable
• Enum definations
• Persistence Entities

5. Check for spelling mistakes
6. Verify declaration order in bean classes. Getter and setters must be together with the getter method first. Also the declaration order of getter methods must match the declaration order of fields.
7. Commented out code is almost always better off removed. It is likely to be problematic when merging.
8. Exceptions must always be chained, Also look for exception logging that logs the messages only. Stack trace must be logged.