NetDB Programming Guidelines
- Output
- The natural order of data is hardly ever random, therefore virtually all output should be sorted. Programmers need to make sure they understand the desired output order and make sure it comes out that way.
Errors, warnings, and informational messages should have a consistent format that includes the severity of the error. Error reporting systems should have switches to increase or decrease the level of error reporting. It's probably best to integrate all that into the debugging system as well.
- Testing
- Where possible, programmers will write tests and/or test plans as the code is written.
These tests will be automated as much as possible.
Programmers will run these tests after any changes to the code and the code won't be released for wider testing until it passes these tests (unless bugs in the released code are clearly documented in the release announcement).
- Code
- Line lengths shouldn't normally exceed 80 to 85 characters. However, the goal is readable code, not strict adherence to silly rules, so no one is going to kill you if your lines are occasionally (<10%) in the 90 to 95 character range. Your safety is not guaranteed if you go beyond that limit.
Unless there's a really good reason, indentations will be at 4 spaces per level, and only spaces should be used for indentation (i.e., no tabs).
Only the standards-compliant double dash, '--', comment delimiter should be used in SQL source, and a space must follow the double dash before the comment text.
Source files must include following header with appropriate comment delimiters. (Shown here with the SQL style comment delimiter.)
-- <module name> --- <one-line definition> -- <extended definition, if necessary>Be sure to include the three dashes surrounded by spaces, ' --- '. Summary documentation is created by automated tools that look for that pattern.
That's the minimum header. If more documentation is warranted, use any or all of the following template. (Shown here with a shell/perl style comment delimiter.)
############################################################################# # # <module name> --- <one-line definition> # <extended definition, if necessary> # # $Id$ # # Usage: # Options: # Input: (arguments, command line, files, environment ...) # Output: (return value, arguments, files ...) # # Algorithm: # # Subordinate modules: (<module name> ...) # #---------------------------------------------------------------------------- # Copyright (c) <year> Board of Trustees, Leland Stanford Jr. University #############################################################################We'd all really like to see nice readable code. The Perl style guide, while somewhat perl-specific, contains some good recommendations that work perfectly well in Perl, C, C++, and Java. It's worth a read. Find it at:
http://search.cpan.org/dist/perl/pod/perlstyle.pod