From Open Babel
Revision as of 14:49, 12 April 2006 by Ghutchis (Talk | contribs) (Added comment about indentation.)

Jump to: navigation, search

In any large software project, some parts of the code are revised and kept up-to-date more than others.

Conversely, some parts of the code begin to fall behind -- the code may be poorly tested, poorly documented, and not always up to best practices.

With that in mind, here are some very important tasks of software archeology -- diving in to older parts of code and bringing them up to date. Whenever editing a file, please keep these in mind and consider these simple tasks:

  • Add clear documentation for every public function.
  • Add clear comments on the internal operation of functions -- so anyone can read through the code quickly.
  • Improve code indentation -- different contributions have often had different indentation styles. Simply making the code indentation consistent across an entire file makes the code easier to read.
  • Delete code which is commented out. The CVS version control system maintains history, so if we need it later, we can go back and get that code. Dead code like this simply makes it harder to read the important code!
  • Minimize #if/#endif conditional compilation. Some is required for portability, but these should be minimized where possible. If there seems to be some magic #define which accesses parts of the file, it's probably dead code. As above, dead code makes it harder to maintain and read everything else.
  • Mark functions which should be publicly visible and functions which are only useful internally. Many methods are not particularly useful except inside the library itself.
  • Removing calls to cout, cerr, STDOUT, perror etc. These should use the global error reporting code.
  • Minimize warnings from compilers (e.g., GCC flags -Wextra -Wall). Sometimes these are innocuous, but it's usually better to fix the problems before they become bugs.
  • Use static code analysis tools to find potential bugs in the code and remove them.