Skip to end of metadata
Go to start of metadata

TRC Standards Document

Icon

Also See Kuali Development Standards

Why are coding conventions important?

Poor code quality and lack of standards lead to more defects

Icon
 

Coding conventions make future maintenance easier

Icon
 

Conventions help new developers get up to speed more quickly

Icon
 

Good code aesthetics lead to more confidence and appreciation from customers

Icon
 

Team Commitment

  1. 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)
  2. 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
  3. 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

1 - Adhere to the style of the original.

Icon
 

2 - Adhere to the style of Least Astonishment.

Icon
 

3 - Do it right the first time!

Icon
 

General Standards and Conventions

General Coding Standards

Follow patterns that have been established (for instance naming, conventions of how to do certain functions, documentation, ...)

Icon
 

Write meaningful and correctly formatted Javadocs for all code - see Javadocs section

Icon
 

Be consistent with how things are coded

Icon
 

Favor object oriented solutions over linear programming

Icon
 

Format your code - within IntelliJ, select Code > Reformat Code (or Ctrl-Alt-L)

Icon
 

Maintain conceptual integrity for the system

Icon
 

Don't go with the first solution but the best solution

Icon
 

Strive to make the code easy to follow and understand

Icon
 

Avoid long chunks of code - a single method should be completely visible on your screen without needing to scroll - if a method goes beyond this, consider using helper methods to reduce its size

Icon
 

Construct good class and variable names - see Naming Conventions section

Icon
 

Follow SRP ('Single Responsibility Principle') and DRY ('Don't Repeat Yourself')

Icon
 

Use Generics where possible

Icon
 

Organize logical groupings of methods and properties (avoid just adding methods to the end of a class) - see Class Organization section

Icon
 

Avoid hard coding strings (use instead constants or external resources) with the exception of log or exception stringss

Icon
 

Avoid deeply nested control statements

Icon
 

Avoid the ternary operator ('?') except in very simple cases. One rule of thumb is that it should all fit on one line.

Icon
 

Avoid giant expressions; instead, break complex expressions down into smaller, simpler pieces

Icon
 

Remove unused code (not comment out), if commenting out code temporally or for reference, place a TODO item before the block

Icon
 

Keep it Simple!

Icon
 

Reevaluate often (Switch frequently between 'create' and 'maintain' mode) - look for duplicate code and refactor to prevent duplicates, larger methods, nesting, etc.

Icon
 

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

Use names that have meaning (not i, j, .. with the exception possibly of loop counters)

Icon
Good
Bad

Follow naming patterns that have been established for similar types of classes, variables, and methods

Icon
 

In general avoid abbreviations, with the exception of very well known abbreviations or to prevent excessively long names

Icon
Good
Good
Bad

Names use camel casing with first letter upper-cased for class names and lower cased for method and variable names

Icon
Good
Good
Bad

Use nouns when naming classes and fields, verbs when naming methods - avoid words that can be both, such as Group

Icon
 

Pluralize the names of collection references

Icon
Good
Bad

Avoid negated terms in a name

Icon
Good
Bad

Does the name fully and accurately describe what the class, variable or method represents?

Icon
 

Does the name refer to the real world problem rather than to the programming language solution?

Icon
 

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.

Good
Good
Good
Bad
Bad
Bad

Class Organization

Every class should generally be written in the following order:

  1. Class members
  2. Constructor (always create the default constructor)
  3. Public methods (methods that implement an interface or are public)
  4. Protected methods with logic
  5. General getters/setters (in the order of the member declaration)
  6. 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.

Example
Good
Bad

Multiple Casts

Rather than casting a variable multiple times, create a temp variable for reuse.

Bad
Good

Line Breaks

  • Place concat operators (+) and dot operators (.) on the new line.
Bad
Good

Blank Line Usage

See: https://wiki.kuali.org/display/KULRICE/Blank+Line+Usage

Code Cleanup (on new/changed code)

  1. Perform formatting (before check-in)
  2. Organize imports - IntelliJ has a command for this under Code > Optimize Imports... (or shortcut Ctrl+Alt+O)

Deprecating Code

  1. 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.
  2. 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

Only one indentation level per method

Icon
 

Keep your classes small

Icon
 

Use accessors (getters/setters)

Icon
 

Martin Fowler Refactoring

Joshua Bloch Effective Java

Rice-Specific Conventions

UIF Specific

  1. Group together lifecycle methods in order (initialize, applyModel, finalize)
  2. Make methods public/protected to allow for overriding any behavior
  3. Strive to provide declarative options (via XML) where possible
  4. 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: