Clear Documentation

Designing and Maintaining Software (DAMS)
 Louis Rose

Bad documentation Misleading or contradictory

CustomerGateway find_customer(id)

Used to look up a customer by their customer number

Bad documentation Redundant // Utility method that returns if // this.closed is true. Throws an // exception if the timeout is // reached and this.closed is // still not true public void waitForClose(long timeoutMillis) throws Exception { if (!closed) { wait(timeoutMillis); if (!closed) throw new Exception; } }

Bad documentation Mandated and Journaling

Bad documentation Missed opportunities def progressed? # automatic progression: all grades are 40 or greater, # compensated progression: grades are 40 + no more # than 2 grades require compensation grades.all? { |g| g >= 40 } or (compensated(grades).average >= 40 and grades.select { |g| g < 40 }.size <= 2) end

Better documentation Prefer expressive artefacts over annotations def progressed? progressed_automatically? or progressed_via_compensation? end def progressed_automatically? grades.all? { |g| g >= 40 } end def progressed_via_compensation? compensated(grades).average >= 40 and grades.select { |g| g < 40 }.size <= 2 end

Bad comments All of the above and…

Bad comments Turning off code def update(name, address, email) user.name = name user.address = Address.new(address) user.email = email user.save # if user.valid end

Bad comments End of scope markers end # inner if end # while end # block end #outer if end # method end # class end # module

Literate Programming “I believe that the time is ripe for significantly better documentation of programs, and that we can best achieve this by considering programs to be works of literature.” - Donald E. Knuth
 Literate Programming
 Comput. J. 27(2): 97-111 (1984)

Literate Programming


 
 https://github.com/jashkenas/journo/

Summary Good documentation complements
 and elaborates on the design artefact
 
 Bad documentation can be stale,
 misleading, contradictory, redundant,
 or trying to compensate for a weakness
 in the artefact Literate programming could be
 the future of clear code?

Designing and Maintaining Software (DAMS) - GitHub

Clear Documentation. Designing and Maintaining Software (DAMS). Louis Rose. Page 2. Bad documentation. Misleading or contradictory find_customer(id). CustomerGateway. Used to look up a customer by their customer number. Page 3. Bad documentation. Redundant. // Utility method that returns if. // this.closed is true.

337KB Sizes 0 Downloads 100 Views

Recommend Documents

Designing and Maintaining Software (DAMS) - GitHub
ASTs are tree data structures that can be analysed for meaning (following JLJ in SYAC 2014/15) ... More Cohesive. Avoids Duplication. Clearer. More Extensible.

Designing and Maintaining Software (DAMS) - GitHub
%w.rack tilt date INT TERM..map{|l|trap(l){$r.stop}rescue require l};. $u=Date;$z=($u.new.year + 145).abs;puts "== Almost Sinatra/No Version has taken the stage on #$z for development with backup from Webrick". $n=Module.new{extend. Rack;a,D,S,q=Rack

Designing and Maintaining Software (DAMS) - GitHub
R&D: sketch habitable solutions on paper, using UML. 4. Evaluate solutions and implement the best, using TDD. Probably start again at 3. 5. Give to the product owner to validate. Probably start again at 1. 6. Put into production for customers to eval

Designing and Maintaining Software (DAMS) - GitHub
Observers. Designing and Maintaining Software (DAMS). Louis Rose. Page 2. Page 3. Delivery people need to know when pizzas are ready class Pizza def initialize(delivery_person). @delivery_person = delivery_person end def bake cook # blocking call. @d

Designing and Maintaining Software (DAMS) - GitHub
When we are testing the way that a unit behaves when a condition is met, use a stub to setup the condition. Solution: use stubs for queries class Subscription ... def bill(amount) unless payments.exists(subscription_id: id) payments.charge(subscripti