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
  • For normal text that will be read by humans, 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.
  • Use the Unix standard of the newline character ("\n") to terminate lines.
  • 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 $snake_case for variable names.
  • Use snake_case for function names.
  • Use CamelCase for package names.
  • Use short variable names for hash references, particularly those created from database lookups.
  • Use tabs for indentation.
  • 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 space after negation: if ( ! $variable ) {
  • Do not leave a blank line after if, else, while, foreach, etc.
  • Do not leave a blank line before solitary closing curly brackets.
  • Do not leave multiple consecutive blank lines.
  • Use " => " between hash array keys and values, and ", " between values and keys.
  • 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: scalar( @variable )
  • Use @EXPORT for library functions that are intended to be public.
  • Use @EXPORT_OK for library variables that are intended to be public.
  • '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 the "<condition> ? <if true> : <if false>" construct if thought appropriate.
  • For Enswitch versions 4.2 and newer prefer the array style syntax for SQL queries even for data with a single parameter, e.g. data => [ $a->{ 'uniqueid' } ].

• Databases
  • Use snake_case for column names.

• Configuration files
  • Use .ini format.
  • Use single word lower-case section and key names were possible, or snake_case if multiple words are required.
  • Use "true" and "false" for boolean values.