Tonto | ||
---|---|---|
<< Previous | Next >> |
Here are some golden rules for designing a module in the TONTO style.
Document before writing. It is highly recommended that you fully document the functions and routines that you want to include in your module, including their arguments, before you start any coding. Often, if the plan of attack is clearly specified before any coding proper is completed, bugs are less prevalent.
Insert the type definition (commented out) at the start of the module. This is required for documentation purposes. The reason the type does not appear in the module itself is because we wish all modules to have access to the internals of a type. In C++ parlance, all TONTO modules are friendly.
Use long decriptive names. Most of the effort in documentation can be made easier if you use descriptive names for routines and variables. Please, spend some time on this.
Ensure routines have few arguments. Routines that have few, if any, arguments are easier to remember and easier to use.
Write simple routines. Is there more to be said?
Write short routines. There isn't really any reason to write a long routine; a long routine can be separated into separate tasks for the current module, or farmed out to tasks belonging to other modules.
Use preconditions liberally. When developing, it is highly recomended that you use the -DUSE_PER_AND_POST_CONDITIONS switch and the -DUSE_CALL_STACK_MANAGEMENT switch. By the same token, make sure you include before the start of a routine a a set of ENSURE commands which will detect any missing data or incorrect conditions required for the routine to perform its task. Remember, these can eventually be switched off and you will pay no performance penalty, but you will get the productivity gain in fewer bugs.
Mark routines [leaky]. It is useful to keep track of where your memory is going. Spend some time to reduce the number of routines which deliberately have memory leaks, and for those where leaks are unavoidable, mark them as [leaky].
Add functionality to low-level modules where possible. Try not to make your top-level routines too heavy. The more you can place in lower level modules which are well decoupled, the faster will be your compile times, and the quicker will your program be debugged, since lower level routines are more exhaustively used.
Do not remove your initial code; provide redundancy. Often your initial code is very sinmple and clear. Then it becomes wrecked asyou make it more efficient. Please do not delete your initial simple code. Routine names can be overloaded, and when bugs are detected your simple code will be invaulable in testing.
Provide all the conventional routines. They will usually be needed at some stage.
When using string case statements, use alphabetical order. You should also use the UNKNOWN(word) so that when there is an error, and alphabetical list of allowed options is echoed to the user.