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: This is a sample.
  • A naming convention of <noun>_<verb> is preferred for exported library functions: email_send()
  • 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 brackets: if ( $variable ) {
  • Leave a space before close brackets: if ( $variable ) {
  • Leave a space after commas: function( $a, $b, $c );
  • Leave a blank line before if and else.
  • 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, spread it across multiple lines. The last line before the closing round bracket should have a trailing comma.
  • Use brackets on built-in Perl functions which can optionally have brackets, such as scalar(): scalar( @variable )
  • Use @EXPORT_OK rather than @EXPORT.
  • '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.
  • Use " => " between hash array keys and values, and ", " between values and keys.
  • Use short variable names for hash references, particularly those created from database lookups.
  • Use the Perl "<condition> ? <if true> : <if false>" construct if thought appropriate.