Table of contents1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
Author: Michael Mahemoff
E-mail: [email protected]
Software, Document Thyself
After an Automated Commenting Tool Instead?
Read and discuss “AppointmentDAO” example
A few tips
In pairs, refactor an example
Review someone else's example
External documentation is boring ... no-one updates it, no-one reads it.
Comments detract from
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
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
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.
In pairs, refactor example towards self-documenting.
Style over substance: you're allowed to break functionality!
Look at another pair's code (based on a different example). Note in particular:
Strengths and weaknesses
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
Non-functional info, e.g. Performance
Tips and Individual Practices
Patterns and idioms
Use of assertions
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.