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.


elijah 2009-01-02	I propose the text above as a draft for crabgrass coding standards. If a commit or patch does not follow these, then the commit is rolled back or the patch rejected. Comments? Modifications?


mcnair 2011-04-12 2011-04-12	we need to add cross browser compatablity to this. any new code has to have had acceptance testing in firefox 3.x and 4.x, ie 7 – current, chrome, and safari. we need to create some sort of check list that people check off when submitting code. I do not think we should work to make cg ie6 compatable anymore. translation keys and UI changes.