prg_style.txt
version 0.02

This file briefly describes the style I employ in writing my source files, and designing my programs.

Editing:
* Tab length is always four (4), and never-ever eight (8) or anything else
* Tabs never-ever inserted as spaces
* I use a variation of the Allman indentation style (matching brackets are at same level, vertically)
* curly braces missing where they're not needed, except for when they improve readability
* I comment as little as possible, but as much as needed
* functions always have ABOUT: comment, briefly describing what they do
* all header files must be included directly where they're needed, and not indirectly via other headers (with exception for compiler's inner workings of course)
* I avoid using extra parentheses; in this regard, I favour readability over understandability; and I consult an operator precendence chart when in doubt
* if a function doesn't directly or indirectly change the value of a variable aside from initializing it, then the variable should be `const'

Design (these may change from project to project):
* robustness, security, performance and efficiency must all be maximized
* robustness >= security > performance >= efficiency
* the source code must be easy to understand by a developer, and the program must be easy to use by a user
* both the source code and program should be as self-sufficient as possible

DON'Ts (this list is the result of me learning from my mistakes):
* don't add unnecessary `else's to `if's which `continue', `break', `return' or `exit()' (decreases readability and harasses with indentation)
* don't cast except where absolutely necessary (casting prevents the compiler to warn you of data type inconsistency)
* don't "fix" data type warnings by casting (because the compatible types you can safely cast on your machine may be incompatible on someone else's)
* don't use dynamic allocation where static allocation is good enough (increases code complexity; got carried away with this, once)
* don't treat multi-instruction macros as being one instruction (compile-time error, for example if you omit curly braces for an `if')

Fun facts (this list is the result of me learning):
* did you know that `array[position]' is the same as `position[array]'?
 (they evaluate to `*(array + position)' and `*(position + array)', which are equal)

Personal definitions (these may change from project to project):
* robustness: the ability to fail gracefully and cleanly, with a meaningful error message
 ("real" robustness is different from this as it involves attempting to recover from errors, and continued operation under abnormal conditions)
* security: having no code quality -induced flaws, which can be used for malicious purposes
* performance: completing the task as quickly as possible
* efficiency: completing the task while consuming as few resources as possible
* self-sufficiency: not being dependent on third-party, non-standard components
 (e.g. other programs, and libraries that basic users don't usually have installed -- or even need to have them installed, other than for compiling/running strictly your program)

-RF
