Software, Document Thyself

This is a set of slides from the workshop I led at SPA 2005, "Software, Document Thyself". The slides were auto-generated from Star Office (as was this page, after which I've edited it).

A PDF with the lot

The slides as a retro '97-style web presentation

Table of contents

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

Author: Michael Mahemoff

E-mail: [email protected]


A Really Badly Formatted Outline of the Whole Thing, Minus Pics

Google will appreciate this if no-one else does ...

Software, Document Thyself

SPA 2005

Michael Mahemoff

After an Automated Commenting Tool Instead?

Workshop Plan

Why Self-Document?

Read and discuss “AppointmentDAO” example

A few tips

In pairs, refactor an example

Review someone else's example

Closing discussion

Why Self-Document?

External documentation is boring ... no-one updates it, no-one reads it.

Comments detract from


Why Self-Document?

Taking a Step Back

Learning from HCI and UI Design


Consistent Within an Application

Metaphor and Common Ontology

Consistent Across Applications – Standard Ways to Accomplish a Task

Familiar Language

Attention Layering – Overall Structure in a Blink

Learning Trajectory – from Novice to Expert

Tip: Tastes Vary

Tip: Reduce Waste

Tip: Provide Affordances

Use terms consistently

Consistent domain model

Tip: Choose Names Carefully

Synonyms Exercise:




Can use a thesaurus (see

Tip: Refactor Mercilessly

Refactor using design patterns (see Gamma et al., “Design Patterns”).

Extract complicated method into Strategy class.

Describe creation process with Factory Method.

Refactor using standard refactorings (see Fowler, “Refactoring”)

- Extract code block into separate method.

- Replace local variable with query method.

Tip: Focus on The Typical Case

Don't play the throw-catch game ... favour unchecked exceptions (Java).

Use assertions instead of comments and if...then exceptions.

Use guard clauses to divert exceptional cases.

Refactoring Exercise

In pairs, refactor example towards self-documenting.

Style over substance: you're allowed to break functionality!

Refactoring Review

Look at another pair's code (based on a different example). Note in particular:

First impressions

Strengths and weaknesses

Possible improvements


Where are comments justified?

Classes, attributes, methods, code blocks

What types of comments?

Specification: What does this do?

Quality level “This is an Evil Hack”

Input/Output Assumptions/Calling contract

Caller details

Non-functional info, e.g. Performance



Tips and Individual Practices

Patterns and idioms

Use of assertions

Checked/unchecked exceptions



Agreeing on the Right Level of Comments

Idiosyncracies and Individual Taste

Coding Standards and Combined Ownership – Conflict?

Creative Commons License
This work is licensed under a Creative Commons Attribution 3.0 Unported License.