Lecture 20

Coding Standards
Tools for Debugging 1

Coding Standards
Or
How to Pound all of your odd-shaped
programmers into a one size fits all
hole

I think there may be a bug in Joes Code - Please Fix

func GreenEggsNHam(Not SamIAm, Green EggsNHam)
foreach Green TryThem in SamIAm
do EatThem(TryThem) = false
NotInACarNotOnABus(EggsNHam)
func NotInACarNotOnABus(Green EggsNHam)
EatThem(EggsNHam) = true
NotOnAPlane(EggsNHam)
foreach NotLikeThem SamIAm of EggsNHam do
if not EatThem(SamIAm) then
NotInACarNotOnABus(SamIAm)
IDoNotLikeThem(EggsNHam)

Joes Code Following a Sane Coding Standard . . .

func DepthFirstSearch(graph G, vertex v)
foreach vertex w in G
do Encountered(w) = false
RecursiveDFS(v)
func RecursiveDFS(vertex v)
Encountered(v) = true
PreVisit(v)
foreach neighbor w of v do
if not Encountered(w) then
RecursiveDFS(w)
PostVisit(v)

What are Coding Standards

Coding standards are guidelines for code style
and documentation.
The dream is that any developer familiar with the
guidelines can work on any code that followed
them.
Standards range from a simple series of statements
to involved documents.

Areas Typically Covered

Program Design
Naming Conventions
Formatting Conventions
Documentation
Possibly Even Licensing

Why Have Coding Standards

Greater consistency between developers
Easier to develop and maintain
Saves time and money

Prime Directive
Document every time you violate a
standard.
No standard is perfect for every application,
but failure to comply with your standards
requires a comment

Amblers Law of Standards

Industry Standards > organizational standards > project
standards > no standards
The more commonly accepted a standard the easier it is for team
members to communicate
Invent standards when necessary, but dont waste time creating
something that you wont be able to use later.
All languages have recommended coding standards available. It
is well worth your effort to find and use industry standards
Push for organizational standards whenever possible

Good Coding Style

Names

Use full English descriptors

Use mixed case to make names readable
Use abbreviations sparingly and consistently
Avoid long names
Avoid leading/trailing underscores

Documentation
Document the purpose of every variable
Document why something is done not just what

 Accessors
use getVar() and setVar() functions on all class variable unless
class is being used solely as a data structure (OOP)

Member Functions Documentation

What and why member function does what it does

Parameters / return value
How function modifies object
Preconditions /Postconditions
Concurrency issues
Restrictions

Internal Documentation

Control Structures
Why as well as what the code does
Difficult or complex code
Processing order

Three Rules
Coding standards neednt be onerous - find
a standard that works for your team.
Standardize early - the effort to bring your
old work into the standard will be too great
otherwise.
Encourage a culture where standards are
followed.

Examples of Coding Standards

http://www.ambysoft.com/javaCodingStandards.html
http://www.swtech.com/java/codestd/
http://ccs.hst.nasa.gov/ccspages
/policies/standards/coding_standards.html
http://www.scriptics.com/doc/styleGuide.pdf