Making programs more readable

Programs are read more often than they are written, so readability makes maintenance and debugging easier. A program can be made more readable by:

1. Meaningful names: use descriptive names (motor_speed, not x) for variables, functions and constants; follow one naming convention.
2. Comments: a header block at the start of each module and function (purpose, inputs, outputs, author, date, revision), plus brief comments for complex logic, explaining why. Avoid obvious comments and keep comments updated.
3. Consistent layout: proper indentation, one statement per line, blank lines between logical blocks, limited line length, uniform brace style.
4. Modular structure: small functions with one task and few parameters; top-down design and clear interfaces; limit nesting depth.
5. Structured control flow: use if/else, for, while and switch; avoid goto and tricky constructs.
6. Named constants: replace magic numbers with #define or const; define hardware addresses in one header file.
7. Avoid global variables and side effects; declare variables near their use.
8. Simple expressions: break complex expressions with parentheses and temporary variables; prefer clarity to cleverness.
9. Documentation such as flowcharts, a design document and version history; use version control.
10. Coding standards and peer reviews to maintain uniformity.