SPA2005 session: Software, Document Thyself

One-line description:An interactive workshop on the craft of self-documenting code
 
Session format: Workshop [read about the different session types]
 
Abstract:Coding clearly and concisely is a virtue; this workshop will provide some techniques hands-on exercises.

The session will begin by presenting three contrasting code examples, each achieving the same objective in different ways. These examples will form the basis of a discussion on what makes readable code. Focusing on one of the examples, the group will discuss how they might refactor it into a self-documenting structure.

During this group discussion, the workshop leader will use the examples to define and motivate self-documenting code. He will then propose and demonstrate several techniques for achieving it.

Having discussed some basic theory, the interactive refactoring exercise will begin. Attendees will work in pairs, writing code either on a piece of paper - since it does not have to run - or on a laptop, according to their preference. The exercise will be to refactor the code into a more readable form that is as self-documenting as possible.

Once the code is written, each pairs will share their code with another pair. The pairs will then be able to exchange initial impressions of the refactored code and opportunities for improvement.

Finally, the group will discuss insights they have gained from the process, with a focus on practical steps that will facilitate self-documenting code.
 
Audience background:- Participants require at least basic coding skills
- Participants should be able to read Java code, although they will be free to write in any language
 
Benefits of participating:- Appreciate strengths and weaknesses of self-documenting code
- Improve understanding of how to write self-documenting code
- Have an opportunity share ideas and compare work with others
 
Materials provided:- Code examples (before and after refactoring) will be presented as well as handed out.
- Thesauri will be provided during the refactoring exercise, since one of the techniques to be discussed is the use of a thesaurus.
- Participants may bring a laptop to refactor the provided examples. Alternatively, it is fine to perform the exercises on paper if they wish.
 
Process:0-5 Participants read code examples (presented upon entering the tutorial).
5-15 Group discussion of examples, used by instructor to introduce and motivate general concepts of self-documenting code.
15-25 Instructor presents and demonstrate techniques for achieving self-documenting code.
25-50 Participants refactor provided code example.
50-55 Participants look at partner's refactored code.
55-65 In pairs, attendees discuss each other's code and opportunities for improvement.
65-75 Wrap-up: Group discussion about insights gained.
 
Outputs:- The presentation will be available at a suitable website and/or the SPA wiki.
- Code examples showing how participants refactored the code.
- A summary of interesting observations and comments will be added upon completion of the tutorial.
 
History:The session has not previously been presented.

I have previously presented a workshop on HCI patterns with a similar structure at the Australian Computer-Human Interaction professionals SIG and at two universities (Melbourne and RMIT).
 
Presenters
1. Michael Mahemoff
Baldock Services
2. 3.