Coding Standards¶

There are many people who contribute to the Crabgrass code, often for short periods of time. Few of these contributors have enough time to understand all of Crabgrass. The top priority in writing code for Crabgrass is to make something that someone else will be able to understand, maintain, and debug long after you are gone.For this reason, it is absolutely imperative that all contributions to the source code include the following:

Imperatives

• Complete unit and functional tests. At minimum a test for every controller action, and tests for the main behavior of all the models.
• Inline RDoc comments for every method and class that another programmer might need to call from somewhere else in crabgrass. (more on documentation →https://we.riseup.net/cgdev/new-crabgrass-documentation]
• Any big changes must be flagged at least in the file CHANGES, with a reference to which document in doc/ to read more.
• Any big changes need to be reflected in the appropriate doc/ file
• Any changes that alter the install process (new modules, new configuration) need to be reflected in INSTALL and doc/CONFIGURATION
• mods and libs need to have README files, i.e.

  mods/*/README, lib/*/README

• other doc files to consider:

  doc/SITES, vendor/plugins/*/README

Coding Practices: Additionally, all Crabgrass contributions should follow these generally accepted coding practices:

• Variable names should be descriptive and verbose. Don‘t save on typing at the expense of readility and maintainability.
• Don‘t be too clever: don‘t write something compact and tricky if it is going to be difficult for the next person to figure out.
• In ruby, we use two spaces instead of tabs for indents. Get used to it.
• Indent protected/public keywords on the same level as ‘def methodname’
• Ruby source files should be kept small and managable.
• Class methods should be kept small and managable, ideally under 20 lines.
• Thin controllers, fat models: as much logic as possible should be put in the models. The controllers should be light weight.
• More controllers is more better: it is better to have more controllers than more lengthy controllers. As with a strict REST strategy, try to think of ways to have at least one controller for every table.

How would coding standards be applied?

• group consensus/dialog on what is expected
• a measure by which to live up to
• a basis by which to ask someone to improve their code/tests/doc and recommit.

IE¶

The enemy of all, but currently we need to be compatible with ie 6 and 7. Devs need to have a test bed ready and test against ie6 and 7 as they go. One setup: 1) virtualbox (2) xp performance edition (3) tredosoft.com/Multiple_IE multiple ies hack.