Six Ways To Write More Comprehensible Code

Courtesy: Jeff Vogel
I read this article and thought I would just jot down the major points. I liked it.

• Comment Like A Smart Person
• A few sentences before the procedure/function saying what it does.
• A description of the values being passed into it.
• If a function, a description of what it returns.
• Inside the procedure/function, comments that split the code up into shorter tasks.
• For chunks of code that seem thorny, a quick explanation of what is happening.
• Use #define (or Static Constant Variables) a lot
• Use proper variable names
• Do proper error checking in the code - Other than the actual code find extreme conditions and handle them properly
• "Premature optimization is the root of all evil." - Donald Knuth
• Don't be too clever by half - Never write a code which is cryptic. Code must be simple and understandable