Why are coding conventions important?
Team Commitment
- All team members must commit to following the established standards and not deviate (for instance in cases where the standard is
felt to be incorrect, in these cases the developer should bring it up for discussion with the team) - Take time before development to look for existing code that is performing similar functions and has an established standard, and take
time after developing to review the code for aesthetics and possible cleaner solutions - All team members should participate in reviewing other developer's code and point out places where standards have not been followed
Elements of Style 1-3
General Standards and Conventions
General Coding Standards
IntelliJ Automatic Code Review
IntelliJ automatically reviews all code. In the right margin, it lists warnings (in yellow) along with syntactical mistakes (in red) and other information (in green). Our goal as a team is to keep every file in green. That is, there shouldn't be warnings within a file except in rare cases. We have the ability to customize what IntelliJ checks, so if there are warnings that seem inapproriate for our team, we can remove them. Conversely, we can add new warnings that IntelliJ does not mark by default.
JSHint Code Review
JSHint is a tool to detect errors and potential problems in JavaScript code and can be used to enforce coding conventions. JSHint is integrated into Intellij so that JavaScript warnings, mistakes and other information are displayed as part of the Intellij automatic code review. Intellij is configured (in project settings) to read the JSHint rules from a configuration file. The JSHint configuration file (called .jshintrc) is located in the project root directory. Eclipse also supports JSHint with configuration files. Additional information on JSHint can be found at http://www.jshint.com.
Javadocs
See: https://wiki.kuali.org/display/KULRICE/Javadocs#
Naming Conventions
Braces
Always add braces around blocks of code, such as conditionals, unless that code is short enough to perform on a single line. If a conditional has an if and else, always add braces.
Class Organization
Every class should generally be written in the following order:
- Class members
- Constructor (always create the default constructor)
- Public methods (methods that implement an interface or are public)
- Protected methods with logic
- General getters/setters (in the order of the member declaration)
- Dependency getters/setters
Implement the methods in the order defined by the interface. If more than one interface is implemented, implement each in order.
Dependencies
If a class has service dependencies, use a private class member. Create a public getter; if the private member is null, the getter will retrieve the service from the module service locator. The private member should never be accessed directly; all calls should be made through the getter. Also, create a public setter to allow for overrides.
Multiple Casts
Rather than casting a variable multiple times, create a temp variable for reuse.
Line Breaks
- Place concat operators (+) and dot operators (.) on the new line.
Blank Line Usage
See: https://wiki.kuali.org/display/KULRICE/Blank+Line+Usage
Code Cleanup (on new/changed code)
- Perform formatting (before check-in)
- Organize imports - IntelliJ has a command for this under Code > Optimize Imports... (or shortcut Ctrl+Alt+O)
Deprecating Code
- Mark the method/class/package/etc. with @Deprecated annotation. This compiles the object's deprecated status in the .class file (and can even be accessed with reflection). When a client compiles against the class file, the compiler will issue a warning regardless of whether source/javadoc is present.
- Mark the method/class/package/etc. with @deprecated javadoc tag. Unlike, the annotation this tag allows us to put a description what why the thing is deprecated and what to do.
Object Calisthenics
Martin Fowler Refactoring
Joshua Bloch Effective Java
Rice-Specific Conventions
UIF Specific
- Group together lifecycle methods in order (initialize, applyModel, finalize)
- Make methods public/protected to allow for overriding any behavior
- Strive to provide declarative options (via XML) where possible
- Put all standard getter/setters in the order the members are listed after the lifecycle methods and before the complete validation method. The complete validation method should be last.
JAXB and JAXWS Annotation Standards
See: