SEARCH: NAVIGATION:

Coding Guidelines

Students achieving Oneness will move on to Twoness.
Woody Allen

Writing clean code is a fine art, while at the same time, exacting in its nature. These rules will help with some of the latter, freeing you to focus on the former.

Names

Consistent and appropriate naming of directories, files, modules, classes, functions, and variables provide several advantages:

It is easier for someone else to read your code.
It is easier for you to read your code in six months. Poorly written code sometimes cannot be read by the author the following week, let alone six months later!
It is easier for you to document your code; if you reuse a parameter name appropriately among functions, once you document it for one, then you've got it available to paste into documentation for other functions.

Namespaces (NM1): Use namespaces to improve maintainability.

Namespaces (NM2): Add clarity with consistent naming conventions

Namespaces (NM3): Add clarity with consistent naming.

Avoid repetition like the plague

Repetition in code is the vampiric garlic of the software world. It appears innocuous yet can cause great harm. And, it stinks. There are many avenues of condensing code; we explore a few of them here.

Memory impact may be positive or negative. Obviously less memory will be used if you have one copy of a complete function instead of two or more copies. But if you consolidate a code fragment as described above, you incur the overhead of additional function calls, using more memory when running. With well-written function declarations, however, function calls should not incur high overhead (TBD: see "clean function calls").

Repetitive Code (RP1): Do not repeat whole functions.

Repetitive Code (RP2): Do not repeat identical code fragments.

Repetitive Code (RP3): Do not repeat isomorphic code fragments.

Repetitive Code (RP4): Do not repeat effectively isomorphic code fragments.

Repetitive Code (RP5): Condense code for clarity.

Repetitive Code (RP6): Do not hardcode repetitive entities.

Repetitive Code (RP7): Reorganize loops to consolidate and reduce code.

Branching

Conditional branching involves more than meets the eye, when it comes to design consideration. From the single if statement to the multiple if and the switch statements, there are issues with code clarity, performance, and maintainability to consider.

Branches (IF1): Avoid multiple if-then-else constructs with jump tables.

Branches (IF2): Avoid multiple if-then-else constructs with dynamic lookup switching.

Branches (IF3): Keep if-then-else statements structured.

Variables

Proper handling of variables.

Variables (VR1): Program without using global variables.

Variables (VR2): Watch out for variable forgiveness: the scoop on declaration, definition, and initialization.

Variables (VR3): Eschew weak typing; strong typing aids robustness.

Variables (VR4): Strive for assumption-less programming.

Functions

Functions are our friends.

Function Calls (FN1): Minimize the number of function calls.

Other Resources

Code Refinement (CD1): As in literature, the secret to writing is rewriting.

CleanCode -- The Website for Clean DesignRevised 2013.06.30