Coding style

The sole purpose for a coding style, it to get better maintainable code. It spoils energy of the reader of code when (s)he has to work though inconsistent layout and naming conversions. Valuable energy which is need to focus on the issue to be resolved. Therefore, please try to stick to the simple rules described here.

In case of doubt, Perl Best Practices (PBP by Damian Conway) may give you good advice.

Taranis 3 does not always follow these rules yet, but we are working towards it.

Code

Layout:

• One blank line before and after each sub.
• The tabstop is 4. Do not use blanks to adjust code.
• Each nesting adds one tab.
• No trailing blanks.

Syntax:

• Curly open braces '{' on the same line as their if()/while()
• Cuddled else: '} else {'
• Avoid superfluous symbols, like parenthesis in expressions, when the priority of the operator is well known.

Use of modules:

• Each perl module in a separate file
• All modules in the Taranis:: namespace when they are (to be) merged with main-stream Taranis, and must be different when in a local extension.
• Explicitly import functions from external modules, preferably not via an export tag but each named separately.
• Do always cleanly import functions: no '::' when calling them.
• Do not provide global variables: use functions or methods to get their value.

Exceptions:

• Use real exceptions (croak) on errors
• Use Try::Tiny::try() to catch errors

Naming:

• Use camelCase for methods and Packages, but lower_cased for anything else
• Subs which are not to be used outside a package start with an '_', and are usually not documented in pod
• Use prototypes on functions, which adds compile-time errors (not checked in methods)

Other:

• Don't be afraid to refactor silly code (there is enough of it)

Each perl module should use this order of statements:

0. copyright
1. package statement
2. use parent (modern version of 'use base' or '@ISA')
3. pragmas; always use strict and warnings.
4. use external modules
5. use Taranis modules
6. constants
7. @EXPORT
8. object constructors, new/init()
9. attribute handlers, getters/setters
10. more subs

Documentation

There are various kinds of documentation:

• Use American English
• Code documention (#), to make code understandable
  • Use better (variable) names to reduce the need for code comments
  • On one or more lines before the described code, indented as the code with a leading blank line.
  • Full sentences (start with a capital and close with a dot)
  • After a statement on the same line, with at least to blanks before the '#' (no capital, no trailing dot)
• Interface documentation (pod), to describe that a function does
  • Interleaved with the functions which it describes; both to lower the chance that it is not maintained, and as additional information to fulfill the interface promises by the coder.
  • each sub which is exported (used outside the file where it is implemented) should have pod
  • Long explanations in 'DETAILS' head1 after __END__
• The Administration Guide describes the interface, from the point of the user of the Taranis application.
• The Installation guide should be as small as possible: installation should be automatic when possible. You can add your own install scripts.

Programming is a Dark Art, and it will always be. The programmer is fighting against the two most destructive forces in the universe: entropy and human stupidity. They're not things you can always overcome with a "methodology" or on a schedule. -- Damian Conway