Coding Standards - IntegratedBreedingPlatform/Documentation GitHub Wiki

General

  • All files must be formatted using hard tabs set to 4 spaces
  • All unnecessary code must be removed, i.e. empty blocks, commented out code, unused variables, unused functions etc.
  • All user facing text must be internationalized
  • All trailing whitespace must be removed

Front End

HTML

  • Use lowercase for all element names, attributes, attribute values, CSS selectors, properties and property values
  • Use the HTML5 doctype: <!DOCTYPE html>
  • HTML must be valid
  • Use HTML semantically, each element should be used for what it has been created for, i.e. use p for paragraphs, a for anchors etc.
  • Do not write CSS styles inline in HTML. They should be written in a CSS file and included in the head
  • Do not write JavaScript inline in HTML. It should be written in a JavaScript file and included at the bottom of the body
  • Use a new line for every block, list or table element and indent every such child element
  • Declare classes and ids using hyphenated-lower-case
  • Only use an id on an element if you can guarantee that it will be the only element with that id on the page, otherwise use a class

JavaScript

Follow the JavaScript standards outlined here.

Use JSHint and JSCS to ensure that you are adhering to the standards.

Ensure you are using an editor that will support the JSHint and JSCS standards provided. Sublime Text or WebStorm are our recommended editors. For instructions on setting up Sublime, see Setting Up Development Environment. WebStorm applies JSHint and JSCS validation automatically if config files put in the project directory.

JSHint and JSCS validation could also be used in Eclipse using plugins (jshint-eclipse or Tern IDE + Tern Linters), although their support is not ideal.

  • jshint-eclipse should be configured both on IDE level (Enable JS Hint errors) and on project level (Enable JSHint for these files and folders and add js folders). And it runs on project build.
  • Tern jshint needs a path in project to the .jshintrc file to be configured on project properties. It runs when you are making changes to the file.
  • (please, add your instructions of how to configure jscs in eclipse if you've managed to do that)
  • We have JavaScript formatter and clean up profiles that must be used if you are editing JavaScript in Eclipse.

Recommended Reading

Raising the bar

The good example is Ontology. It is written in angular, uses gulp for the build and jasmine for tests. It has 100% test coverage (and you can see the happy kitty when they pass ^_^) hundredPercentTestCoverage

CSS

  • CSS must be valid
  • Use meaningful class names. Don't use cryptic names that someone couldn't understand without an explanation.
  • Avoid qualifying id and class names with type selectors, i.e. don't use div.error {} instead use .error
  • Prefix classes with a short, meaningful prefix related to the module or feature that this class is for, e.g. om-title is for styling the title of the Ontology Manager.
  • Omit units after "0" values, e.g. margin: 0;
  • Avoid user agent detection and CSS "hacks" such as !important
  • Order declarations with this ordering
  • Use a semicolon after each declaration
  • Put each selector and declaration on a new line

Back End

Follow Google's Java standards.

Import the following formatter and code clean up settings into Eclipse. These settings follow Google's Java standards.

These can be run in Eclipse via Eclipse Code Window > Right Click > Source > Format and Eclipse Code Window > Right Click > Source > Cleanup.

For IntelliJ Idea the Formatter settings can be imported from the [same eclipse settings file] (https://github.com/IntegratedBreedingPlatform/Documentation/blob/master/eclipseSettings/leafnode-google-formatting.xml) using Preferences > Editor > Code Style > Java > Scheme > Manage > Import > Eclipse XML Profile.

You will also need to setup Indent = 4 manually in Editor > Code Style > Java And in Settings -> Java -> Code Style -> Imports -> Class count to use import with '*'; Set it to 99, which is the same as Eclipse.

For Clean Up use Code > Reformat Code, Auto-Indent Lines and Optimise Imports commands before committing. If you commit from Idea alternatively you could set on Commit Changes window Before Commits flags - Reformat code, Rearrange code and Optimize imports

Recommended Reading