Software, Document Thyself

A PDF with the lot

The slides as a retro '97-style web presentation

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

Software, Document Thyself

SPA 2005

Michael Mahemoff

http://mahemoff.com

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

code.

Why Self-Document?

Taking a Step Back

Learning from HCI and UI Design

Principles

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:

“get”

“factory”

“finished”

Can use a thesaurus (see programmasaurus.org)

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

Discussion

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

Rationale

Discussion

Tips and Individual Practices

Patterns and idioms

Use of assertions

Checked/unchecked exceptions

...

Discussion

Agreeing on the Right Level of Comments

Idiosyncracies and Individual Taste

Coding Standards and Combined Ownership – Conflict?

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