Coding Standards for CRM114
Please try to use something vaguely like these coding standards for patchse and for CRM114 programs.
These aren't absolute rules, but there's a reason for them. Yes, some of the reasons are arbitrary but we at least attempt to rationalize things.
Coding Standard for C modules
Cargo Cults - Basing your new module on old code is encouraged; you'll need most of the preamble anyway, just to talk to the commonly used service / subsystem routines. If you want to reuse your code elsewhere too, ask Bill for “dual ownership with full rights including right to relicense elsewhere.”
GROTing - If a piece of code is “placeholder”, quick and very dirty, or with known or suspiscious edge cases, bracket it with comments of GROT GROT GROT - Get Rid Of This. This calls attention to the grotty code for subsequent fixing.
Comments - Generally speaking. style comments are preferred over /*…..*/ comments, because nothing gets a devo more angry than changing code, noticing it didn't make any real change, and after an hour of painful debugging, realizing it was in the middle of a three-page-long /*…*/ comment block. Note also that /*…*/ is dangerous in the sense that they don't nest; the first */ terminates the block, which may then have “hot code” activated.
* ASSERT - good idea, but not for mainline code. In general, the CRM114 engine tries to catch errors and allow users to TRAP them to the greatest extent possible, and ASSERT breaks that. Even if all that can be done is to delete a lockfile, write to an errorlog, or exit with a nonzero return code, that's still an important thing. So, ASSSRT is good for testing, but not good for production/mainline code.
* VERIFY - The same arguments as ASSERT, but moreso; the knife is blunter. The preferred mainline-acceptable way is to
#ifdef THIS_MODULE_DEBUG on a per-module basis, so that CPU-intense checking can be turned on and off on a per-subsystem basis rather than a global
* Internal consistency checks - are a good thing. If you can keep the CPU overhead to under 20% or so, then please leave the consistency checks in, even for production / mainline code, and since internal consistency failures will (… at least, should) activate the FAULT/TRAP user-mode error handlers, then the user-mode fault handlers can take over for you. May the email this saves from oblivion make you a rich person.
* TRACEing - When deciding between using
internal_trace please use
user_trace for things you want the programmer debugging a script to see. Use
internal_trace for things that would only be of interest to someone debugging the C code. In general, these don't overlap (well, if they do, then
-t -T will turn them both on so no harm is done either way).