OSMIS Technical Specification
6. Coding Policy
Since this project will have multiple developers working on the codebase at
the same time, the following must be kept in mind:
- Before checking any piece of code in, it must be tested so as not to
damage the integrity of the system. This means that checked in code consists
of two types:
- Bug fixes: All developers whose code interacts with
the bug-fixed code should be alerted.
- New functionality: All developers should be notified
so that they may now write code which makes use of the new
functionality.
- A developer who checked in a piece of code is the only
developer allowed to check in modifications to that code. This
allows orderly tracking of enhancements, bug fixes, and the like.
- All code checked in to the CVS must have a descriptive comment
attached to it. A comment such as "bugfixes" is not
considered descriptive. Comments such as "Stopped widget XYZ from
doing foobar by changing the frobnik function to return false on
input 123" is.
- Code review meetings should happen for 1 hour at least every 2
days.
- If a bug is found, it must be fixed before new
functionality is added.
- Code must be well commented. Apart from standard commenting
techniques, each method must have the following:
- The preconditions that must hold before the method may be
invoked.
- The postconditions that exist when the method returns
- A detailed explanation of the parameters passed to the method
- A detailed explanation of the return values given by the method
- An explanation of the method's functioning
- It is highly recommended that assertions be used to test
preconditions
- It is very highly recommended that, at the very
least, each class have a method that can be called to test other
methods in the class
- An example method comment would thus be (using Javadoc style comments):
/**
* This method computes the number of widgets handed to it by the pinky.
* It does this by asking pinky for the widget list, iterating through
* the widgets, and counting them.
* @pre Pinky must have a non-empty widget list
* @post Pinky knows how many widgets it has
* @return The number of widgets given by pinky
* @param pinky the pinky object wanting to be told how many widgets it
* has.
*/
public int countNumberOfWidgets(Pinky pinky)
...
Please see the Joel on Software article on
12 Steps to Better Code for a very good introduction to these
software development principles.