Software Craftsmanship

1
Software Craftsmanship
Right Making sundials. From website
www.davidharbersundials.co.uk/craftsmanship.htm .

• Steve Chenoweth
• CSSE 375, Rose-Hulman
• Based on Don Bagerts 2006 Lecture

2
Today

• Review SPE HW.
• Software craftsmanship this.
• Tonight Turn in HW 6.
• Tomorrow Review for Wed night Exam 2.

3
Outline

• Elegant / beautiful code?
• Program Layout Issues
• Self-Documenting Code

4
Elegant / beautiful code?

• Whats elegant?
• http//en.wikipedia.org/wiki/Elegance

5
Elegant language, maybe?

• Towers of Hanoi, in Lisp
• (defun Towers (Number-of-Discs Start-Peg
  Goal-Peg)
• (cond
• (( 1 Number-of-Discs) (format t "Move Top
  Disc from peg D to peg D."
• Start-Peg Goal-Peg))
• (t (Towers (1-
  Number-of-Discs)
• Start-Peg
• (Remaining-Peg Start-Peg Goal-Peg))
• (Towers 1 Start-Peg Goal-Peg)
• (Towers (1- Number-of-Discs)
• (Remaining-Peg Start-Peg Goal-Peg)
• Goal-Peg))))
• 
  
• Given two peg numbers, what is the peg number
  of the third peg?
• (defun Remaining-Peg (Peg1 Peg2)
• (- 6 Peg1 Peg2))

6
Beautiful code layout?

• Examples from Karen Bob Hanmers Beautiful
  software project
• Ugly
• Good
• Ref http//www.bookarts.uwe.ac.uk/khanmer.htm.

7
Program Layout Issues
8
Overview

• Layout of source code refers to how spacing and
  indentation is used to enhance program
  readability and understandability
• The term prettyprinting is sometimes used in
  relation to good program layout

9
Objectives of good layout

• Accurately represent the codes logical structure
• Consistently represent the codes logical
  structure
• Improve readability (and understandability)
• Withstand modifications

10
White Space 1/2

• Term first popularized by Kernighan and Ritchie
  in their development of the C programming
  language
• Refers to any characters within the source
  program which cannot be seen when printed like

11
White Space 2/2

• Examples of white space include spaces, line
  breaks/blank lines, tabs, and form feeds
• White space can be used for grouping of
  statements (chunking) or separating groups
  through blank lines.
• Warning blank lines can be overused!

12
Indentation

• Should be used for alignment of related elements
  (e.g. within an expression)
• Example
• if ((Side1 Side2)
• (Side1 Side3)
• (Side2 Side3))
• cout ltlt Triangle is isosceles

13
Some General Layout Guidelines

• Format reinforces logic
• Easy to maintain
• Only one statement per line
• Put all begin and end statements ( in C
  and C) on separate lines
• Put one data declaration or formal parameter per
  line
• Order declarations in some way
• Sequential blocks separated by blank lines
• Single-statement blocks formatted the same
• Rewrite tricky code vs comment

• Incomplete statements end incorrectly
• Each statement written without side-effects
• Each line only one statement
• At most one data declaration per line
• Use white space liberally
• All classes in a file obvious
• Everything in alphabetical order, if no other way
  to organize
• Pick the most elegant language
• It looks beautiful
• From C pp. 773-4.

14
Quiz Exercise 1General Layout Guidelines
15
Self-Documenting Code Efficient Commenting
16
Self-Documenting Example

• ltCFQUERY NAME"q_allParkTypes" Datasource"example
  Apps"gt
• SELECT Distinct(ParkType) FROM tblParks
• WHERE ParkType is not NULL Order by ParkType
• lt/CFQUERYgt
• (Cold Fusion) from http//www.adobe.com/devnet/c
  oldfusion/articles/remoting_05.html

17
Self-Documenting Example
From www.15seconds.com/issue/030429.htm .
18
Self-Documenting Example
Visual Basic for AutoDesk, from
www.augi.com/publications/hotnews.asp?page901 .
19
Self-Documenting Overview

• Self-documenting code refers to writing the code
  so that a few comments as possible are needed in
  the source program in order to understand it
• Factors include meaningful variable names and
  good program layout
• Comments should be used efficiently, and only
  when helpful in understanding code

20
Efficient Commenting Some Guidelines

• Some guidelines for efficient commenting
• Make the comments easy to modify (such as block
  comments at the beginning of a routine)
• Use pseudocode for comments in the source code
• Comment as you go

21
Efficient commenting Comments first ?

• // This procedure moves the bullet upwards. It's
  called
• //NUM_BULLET_MOVES_PER_SECOND times per second.
  It returns TRUE if the
• //bullet is to be erased (because it hit a target
  or the top of the screen) and FALSE
• //otherwise. Boolean player_bulletmove_it()
  Boolean is_destroyed FALSE
• // Calculate the bullet's new position.
• Small chunk of code.
• // See if an enemy is in the new position. If
  so, call enemy destruction call and
• // set is_destroyed to TRUE
• small chunk of code
• // See if bullet hits top of screen. If so, set
  is_destroyed to TRUE
• Small chunk of code.
• // Change bullet's position.
• Small chunk of code.
• Return is_destroyed

From http//www.ibm.com/developerworks/linux/libra
ry/l-clear-code/.
22
What about this idea on commenting individual
lines?

• Commenting at the end of an individual line
  should be used when annotating each data
  declaration with its purpose, or at the end of a
  block e.g.
• // end while
• which makes perfect blocks!

23
Some General Self-Documenting Commenting
Guidelines

• Self-Documenting
• Ease of maint 1st
• Meaningful variables
• Comments only when needed
• Extra variables used to clarify
• Data types simple
• Nominal path thru code is clear
• Interfaces obvious
• Refs to variables close together
• Class interface says it all
• Class name says it all
• From C pp. 780-1.

• Commenting
• Commenting style is easy to maintain
• Indent comments with their corresponding code
• Follow IEEE guidelines
• Follow JavaDoc guidelines
• Put units on data declarations
• Comments focus on why vs how
• Make perfect blocks using comments
• Use pseudocode
• Comment as you go
• From C pp. 816-7.

24
Quiz Exercise 2Self-Documenting Code
Commenting Guidelines