1

Software Craftsmanship

Steve Chenoweth

CSSE 375, Rose-Hulman

Based on Don Bagert’s 2006 Lecture

Right – Making sundials. From website www.davidharbersundials.co.uk/craftsmanship.htm .

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?

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

;;;=============================================================

;Yes, Marty? (towers 4 1 2)

6

Beautiful code layout?

Examples from Karen & Bob Hanmer’s “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 code’s logical structure

Consistently represent the code’s 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 << “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 1:General Layout Guidelines

15

Self-Documenting Code & Efficient Commenting

16

Self-Documenting: Example

<CFQUERY NAME="q_allParkTypes" Datasource="exampleApps"> SELECT Distinct(ParkType) FROM tblParks

WHERE ParkType is not NULL Order by ParkType

</CFQUERY>

(Cold Fusion) – from http://www.adobe.com/devnet/coldfusion/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?page=901 .

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_bullet::move_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/library/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 2:Self-Documenting Code &

Commenting Guidelines