Krang Coding Standards

The Krang project will require coding standards above and beyond those used in other PIRT projects. Krang will be a large project with high levels of interaction between developers. Due to scheduling issues developers may enter and exit the project through-out it's life-span. To arrive at a maintainable code-base we must develop and adhere to a strict set of coding guidelines.

Code Formating

• Indentation
  
Code must be indented using 4 spaces, and never with hard tabs. A 2 space indent for continued lines is recommended, but not mandatory. Similarly, breaking lines at 80 columns is generally prefered but not a requirement.

Using Emacs cperl-mode, automatic indenting should be setup using:

  (custom-set-variables
   '(cperl-indent-level 4)
   '(cperl-continued-statement-offset 2)
   '(cperl-tab-always-indent t)
   '(indent-tabs-mode nil))

Using VIM, these settings will accomplish similar goals:

   source $VIMRUNTIME/indent.vim
   set tabstop=8
   set softtabstop=4
   set shiftwidth=4
   set expandtab

Testing

• Module Test Suites
  
All modules will have a dedicated test suite built using Test::More. This test suite must be created as the module is written. Every significant addition to the module must be accompanied by additional tests in the test suite.

Documentation

• Module Documentation
  
All modules must have full POD documentation containing the following sections:
• NAME
  
Name and short description of the module.
• SYNOPSIS
  
This section must contain a working example of every method or function in the interface offered by the module.
• DESCRIPTION
  
A general description of the purpose of the module.
• INTERFACE
  
A listing of each method or function in the public interface. Must include parameter descriptions, return values and side-effects if any.

If appropriate, modules should include:

• TODO
  
A list of known issues in the module. If you put a FIXME comment in the code then you should list the issue here.
• SEE ALSO
  
A list of modules related to this module.

• Script Documentation
  
All command-line scripts will have full POD documentation describing their usage. Scripts should use Pod::Usage and GetOpt::Long. Scripts must support --man and --help options as shown in the Pod::Usage documentation.
• Configuration Documentation
  
New configuration directives for krang.conf need two pieces of documentation. First, they need a comment in the default krang.conf explaining their usage along with a reasonable default setting. Second, they need an entry in docs/configuration.pod.

CVS

• Commit Comments
  
All CVS commits must come with a fully descriptive comment. These comments will be sent to the CVS commit mailing-list and will allow developers to stay up-to-date with code changes.
• Commit Requirements
  
All commited code must pass the full application test suite. This is defined as running ``make test'' at the project root and finding no failures.

Database Conventions

• Table Names
  
Tables should be named with singluar nouns. For example, the table containing data managed by Krang::Story is called ``story'' not ``stories''.
• Join Table Names
  
Tables that establish relationships between two tables should be named by combining the two table names. For example, the story table is joined to the contributor table using the ``story_contributor'' table. Consider choosing the first member based on which module ``owns'' the data in the table. For example, ``story_contributor'' is better than ``contributor_story'' because Krang::Story is responsible for maintaining this relationship.
• Primary Keys
  
When an auto-incrementing integer is used for the primary key of a table, it should be named using the table name and ``_id''. For example, the primary key of the story table is ``story_id''. Using just ``id'' is not acceptable.
• VARCHAR columns
  
All VARCHAR columns must be of the maximum allowed width (255 in MySQL 3.23) unless there is a compelling reason to do otherwise. VARCHARs should be used when users will access the data in a text input through the UI.
• TEXT columns
  
When a textarea is used in the UI, the column recieving the data should be of the TEXT type. This will avoid unnecessary restrictions on the length of the data entered.
• SQL comments
  
An SQL comment at the beginning of each table definition is required. It should identify the code module responsible for the table as well as any other modules which access the table. This will be helpful when changes are required and all table accesses must be examined. For example:

  /* The users table holds data managed by Krang::User and 
     accessed by Krang::CGI::Login */