1. Comment: a good programming paractice...

• Each function needs a sentence or two that clarifies the following:

  • What it does

  • What input parameters are expected to contain

  • What output parameter is expected to contain

  • What would indicate success or failure

  • What exception could be thrown by the function

  • Each part of code that isn't immediately obvious needs a sentence of explaination

  • Any interesting algorithm deserves a complete description.

• Consider using doxygen - an open source documentation generator tool.