Software Craftsmanship

1. Right – Making sundials. From website www.davidharbersundials.co.uk/craftsmanship.htm . Software Craftsmanship Steve Chenoweth CSSE 375, Rose-Hulman Based on Don Bagert’s 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? 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. 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. Some General Layout Guidelines

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. 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. Some General Self-Documenting & Commenting Guidelines

24. Quiz Exercise 2:Self-Documenting Code & Commenting Guidelines