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/c
oding_standards.html
• http://www.scriptics.com/doc/styleGuide.pdf