Coding Guidelines

When working on Integrics code, developers are encouraged to bear these guidelines in mind. They are guidelines rather than rules, and developers should use their own judgement as to when to break them.

• All development
  • Use sentence case, without capital letters in the middle of sentences unless specifically required.
  • Libraries should, where reasonable, keep their functions sorted alphabetically.
  • Comments should be limited to the following, unless there's a specific reason otherwise. Overuse of comments is discouraged.
    • A brief description at the top of files.
    • A copyright notice at the top of files.
    • A brief description of each 'paragraph' in long functions.
    • An explanation any section of code that may be counter-intuitive to someone reading the source.

• Go specific
  • Run "go fmt" before checking into the repository.
  • Strip executables before distribution unless symbols are specifically required for debugging.

• Perl specific
  • Use tabs instead of spaces for indentation.
  • Leave a space after negation: if ( ! $variable ) {
  • Leave a space after open bracket: if ( $variable ) {
  • Leave a space before close bracket: if ( $variable ) {
  • Do not leave a blank line after if, while, foreach, else, etc.
  • Do not leave a blank line before closing curly brackets of blocks.
  • Do not leave multiple consecutive blank lines.
  • If a list is very long, it should be spread across multiple lines. The last line before the closing round bracket should have a trailing comma.
  • Built-in Perl functions which can optionally have brackets, such as scalar(), should normally have brackets: scalar( @variable )
  • 'use' statements should be listed at the top of each file, in case-insensitive alphabetical order, unless otherwise necessary.
  • 'require' statements may be embedded within functions.
  • Hash references are normally given very short names, typically one letter, or two if necessary to be unambiguous.
  • Enumerated hash arrays should use " => " between keys and values, and ", " between values and keys.
  • Use of the Perl "<condition> ? <if true> : <if false>" construct is encouraged where thought appropriate.
  • Perl libraries should normally use @EXPORT_OK rather than @EXPORT.
  • Libraries should where possible name their functions starting with <library>_.