Difference between revisions of "Developer:Archeology"

From Open Babel
Jump to: navigation, search
m (Added comment about indentation.)
Line 4: Line 4:
  
 
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:
 
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:
 +
==Documentation and Code Readability==
 
* Add clear [[Developer:Documentation|documentation]] for '''every''' public function.
 
* Add clear [[Developer:Documentation|documentation]] for '''every''' public function.
 
* Add clear comments on the internal operation of functions -- so anyone can read through the code quickly.
 
* Add clear comments on the internal operation of functions -- so anyone can read through the code quickly.
 +
** If you're not sure what a function does, e-mail the [mailto:[email protected]|openbabel-devel] list and it can be worked out.
 +
* 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.
 
* 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.
 
* 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!
+
** The current accepted scheme for Open Babel is a default indent of two spaces, and use of spaces instead of tabs.
 +
** For tips on changing your editor to use this indentation style, please e-mail the [mailto:[email protected]|openbabel-devel] list.
 +
* Delete code which is commented out. The SVN 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!
 +
 
 +
==Code Maintenance==
 
* 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.
 
* 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 <code>cout</code>, <code>cerr</code>, <code>STDOUT</code>, <code>perror</code> etc. These should use the global [[Errors|error reporting]] code.
 
* Removing calls to <code>cout</code>, <code>cerr</code>, <code>STDOUT</code>, <code>perror</code> etc. These should use the global [[Errors|error reporting]] code.
 
* Minimize warnings from compilers (e.g., GCC flags <code>-Wextra -Wall</code>). Sometimes these are innocuous, but it's usually better to fix the problems before they become bugs.
 
* Minimize warnings from compilers (e.g., GCC flags <code>-Wextra -Wall</code>). Sometimes these are innocuous, but it's usually better to fix the problems before they become bugs.
 
* Use [http://en.wikipedia.org/wiki/Static_analysis static code analysis] tools to find potential bugs in the code and remove them.
 
* Use [http://en.wikipedia.org/wiki/Static_analysis static code analysis] tools to find potential bugs in the code and remove them.
 +
 +
Patches and contributions towards any of these tasks will be greatly appreciated.
  
 
[[Category:Developer]]
 
[[Category:Developer]]

Revision as of 07:25, 24 June 2006

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:

Documentation and Code Readability

  • Add clear documentation for every public function.
  • Add clear comments on the internal operation of functions -- so anyone can read through the code quickly.
    • If you're not sure what a function does, e-mail the [1] list and it can be worked out.
  • 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.
  • 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.
    • The current accepted scheme for Open Babel is a default indent of two spaces, and use of spaces instead of tabs.
    • For tips on changing your editor to use this indentation style, please e-mail the [2] list.
  • Delete code which is commented out. The SVN 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!

Code Maintenance

  • 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.
  • 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.

Patches and contributions towards any of these tasks will be greatly appreciated.