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

  • In general - try to make your new code look like the old code.
  • 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 #define DEBUG. * 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 user_trace versus 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).
coding_standards.txt · Last modified: Y/m/d H:i:s O (T) by wsy
Recent changes RSS feed Creative Commons License Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki