# Code Quality

Bart Massey 2013-11-12

## Overview

• Misc notes
• Code Formatting
• Code Quality

## Code Formatting

• Three main areas:

• Semantic structuring

• Syntactic formatting

## Semantic Structuring

• Idea: Break code into "chapters" (modules), "sections" (routines), "paragraphs" (blocks of related code), "sentences" (statements)

• Make sure semantic units are clearly delineated

• Comment semantic units at the top if they are unclear

• Pay attention to data declarations: often source of ugliness and confusion

## Important Principles

• The Overhead Principle: Time and effort spent on an SE practice should be rewarded by a greater lifetime reduction of time and effort in development and maintenance

• Many syntactic practices fail the Overhead Principle
• The Invisibility Principle: When changing existing code, changes should be invisibly different from surrounding code

• The Consistency Principle: Whatever syntactic formatting rules are adopted should always be followed in a given codebase

## Brace Style: The Real Rules

• Opening brace should be on the next line

• Exception: the opening brace may be endline (OTBS). Treat it as if it is unindented
• Closing brace should be on its own line after the last line of the block

• Braces should be indented the same amount

• Braces should be indented somewhere between unindented and indented to the block, inclusive

• Brace style must be consistent throughout the program

## Expression Formatting: The Real Rules

• Extra parentheses must not be used where anyone with passing familiarity with programming would find them obvious

y = ( 3 + ( 2 * b ) )

• Whitespace should not be used just inside expr parentheses

• It is acceptable to use whitespace just inside array brackets or function call parentheses, but by no means required (be consistent)

## Character Encodings

• Why I advocate TAB-free source files: invisible differences between lines are bad

• Watch out for host line endings: there are three conventions (LF, CRLF, CR) and two are common

## Idiomatic Programming

• Always follow the idioms of your language, environment, programming in general

for (index = 0; index <= limit - 1; ++index)

• Idioms may be syntactic, semantic, or both

• Stacks in C:

int stack[5];
int sp = 0;
/* push */
stack[sp++] = 3;
/* pop */
result = stack[--sp]


## Principle Of No Comment

• If it is possible to make a comment unnecessary, do so

• Top-data comments: give intent of data structure

• Top-routine comment

• Nothing for small, simple, "obvious" routines
• One or two sentences for more complex routines
• If you need more, consider breaking up the routine
• Top-paragraph comment

• Extra important, neglected
• Should provide intent

• As needed for intent: should be rare

## Why Care About Code Quality?

• The more clear the code, the more it is ready for review

• Code that is not adequately clear should not be reviewed until that problem is fixed
• The more clear the code, the better you look

• You will not get hired, raises, promotions if you turn out unclear code; regardless of how "good" it is otherwise
• Clear code should be a vocation, not a religion

• Save proselytizing for where it matters