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 Joe’s 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)

Joe’s 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

Ambler’s 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 don’t waste time creating something that you won’t 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 needn’t 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