Documentation for Program Comprehension in

Agile Software Development

Fabian Kiss

Scrum User Group Lake Constance

Sep 2011

Program Comprehension

To understand a completed computer program (source code)What has been implemented? How?

Agile

Working software over comprehensive documentation

→ code = documention

Why supporting Program Comprehension by

documentation?

Agile supports Program Comprehension

◮ Striving for high-quality source code (Clean Code,Refactoring)

◮ Exemplification of the program’s ”use” through Unit Tests

Why supporting Program Comprehension by

documentation?

Agile supports Program Comprehension

◮ Striving for high-quality source code (Clean Code,Refactoring)

◮ Exemplification of the program’s ”use” through Unit Tests

Why supporting Program Comprehension by

documentation?

Agile supports Program Comprehension

◮ Striving for high-quality source code (Clean Code,Refactoring)

◮ Exemplification of the program’s ”use” through Unit Tests

Why supporting Program Comprehension by

documentation?

Agile impedes Program Comprehension

◮ Continuous refactoring

◮ Experienced team for initial development, less experiencedteam for maintenance

◮ Unrefactorable obfuscating code

◮ Face-to-face communication is preferred: What if nobody(anymore) knows a certain information?

Why supporting Program Comprehension by

documentation?

Agile impedes Program Comprehension

◮ Continuous refactoring

◮ Experienced team for initial development, less experiencedteam for maintenance

◮ Unrefactorable obfuscating code

◮ Face-to-face communication is preferred: What if nobody(anymore) knows a certain information?

Why supporting Program Comprehension by

documentation?

Agile impedes Program Comprehension

◮ Continuous refactoring

◮ Experienced team for initial development, less experiencedteam for maintenance

◮ Unrefactorable obfuscating code

◮ Face-to-face communication is preferred: What if nobody(anymore) knows a certain information?

Why supporting Program Comprehension by

documentation?

Agile impedes Program Comprehension

◮ Continuous refactoring

◮ Experienced team for initial development, less experiencedteam for maintenance

◮ Unrefactorable obfuscating code

◮ Face-to-face communication is preferred: What if nobody(anymore) knows a certain information?

Why supporting Program Comprehension by

documentation?

Agile impedes Program Comprehension

◮ Continuous refactoring

◮ Experienced team for initial development, less experiencedteam for maintenance

◮ Unrefactorable obfuscating code

◮ Face-to-face communication is preferred: What if nobody(anymore) knows a certain information?

Goal

Documenting particularly for the support of ProgramComprehension without impeding agility

→ requirements for that documentation...

Low-level context

Documentation has to be attached to the software indevelopment at a low-level context (source code)

Rationale

◮ Program Comprehension is a matter of programming

◮ Meeting ”the code is the documentation”

◮ Agile itself ”lives” at a low-level context (agile practices)

Low-level context

Documentation has to be attached to the software indevelopment at a low-level context (source code)

Rationale

◮ Program Comprehension is a matter of programming

◮ Meeting ”the code is the documentation”

◮ Agile itself ”lives” at a low-level context (agile practices)

Low-level context

Documentation has to be attached to the software indevelopment at a low-level context (source code)

Rationale

◮ Program Comprehension is a matter of programming

◮ Meeting ”the code is the documentation”

◮ Agile itself ”lives” at a low-level context (agile practices)

Low-level context

Documentation has to be attached to the software indevelopment at a low-level context (source code)

Rationale

◮ Program Comprehension is a matter of programming

◮ Meeting ”the code is the documentation”

◮ Agile itself ”lives” at a low-level context (agile practices)

High-level benefit

From the low-level documentation a higher-leveldocumentation (artifact) has to be extracted such that itadds directly a benefit for other involved stakeholders:

1. Progress of software development is made moretransparent

2. Improved quality of developed software product /additional value

High-level benefit

From the low-level documentation a higher-leveldocumentation (artifact) has to be extracted such that itadds directly a benefit for other involved stakeholders:

1. Progress of software development is made moretransparent

2. Improved quality of developed software product /additional value

High-level benefit

From the low-level documentation a higher-leveldocumentation (artifact) has to be extracted such that itadds directly a benefit for other involved stakeholders:

1. Progress of software development is made moretransparent

2. Improved quality of developed software product /additional value

High-level benefit

Rationale

◮ 1st type: agile principle ”working software is the primarymeasure of progress”

◮ 2nd type: agile principle ”continuous attention to technicalexcellence and good design enhances agility”

◮ Such a direct benefit – obtained by the low-leveldocumentation – helps a developer to justify the effort for(continually) documenting at a low level

High-level benefit

Rationale

◮ 1st type: agile principle ”working software is the primarymeasure of progress”

◮ 2nd type: agile principle ”continuous attention to technicalexcellence and good design enhances agility”

◮ Such a direct benefit – obtained by the low-leveldocumentation – helps a developer to justify the effort for(continually) documenting at a low level

High-level benefit

Rationale

◮ 1st type: agile principle ”working software is the primarymeasure of progress”

◮ 2nd type: agile principle ”continuous attention to technicalexcellence and good design enhances agility”

◮ Such a direct benefit – obtained by the low-leveldocumentation – helps a developer to justify the effort for(continually) documenting at a low level

No separate artifact

A documentation for supporting Program Comprehensionmust not be explicitly produced, as it is not explicitlyrequested (by the customer)

Rationale

◮ Agile principle: ”simplicity – the art of maximizing theamount of work not done – is essential”

◮ Overdoing low-level documentation in favor of thesubsequently extracted high-level documentation artifact isnot necessary

No separate artifact

A documentation for supporting Program Comprehensionmust not be explicitly produced, as it is not explicitlyrequested (by the customer)

Rationale

◮ Agile principle: ”simplicity – the art of maximizing theamount of work not done – is essential”

◮ Overdoing low-level documentation in favor of thesubsequently extracted high-level documentation artifact isnot necessary

No separate artifact

A documentation for supporting Program Comprehensionmust not be explicitly produced, as it is not explicitlyrequested (by the customer)

Rationale

◮ Agile principle: ”simplicity – the art of maximizing theamount of work not done – is essential”

◮ Overdoing low-level documentation in favor of thesubsequently extracted high-level documentation artifact isnot necessary

Primary purpose

A documentation for supporting Program Comprehensionhas to serve primarily that purpose

Rationale

◮ A specific purpose is needed as a starting point, because”documentation” is too broad

◮ Alternatively presuming particular documentation artifactsfrom software development process violates generality

Primary purpose

A documentation for supporting Program Comprehensionhas to serve primarily that purpose

Rationale

◮ A specific purpose is needed as a starting point, because”documentation” is too broad

◮ Alternatively presuming particular documentation artifactsfrom software development process violates generality

Primary purpose

A documentation for supporting Program Comprehensionhas to serve primarily that purpose

Rationale

◮ A specific purpose is needed as a starting point, because”documentation” is too broad

◮ Alternatively presuming particular documentation artifactsfrom software development process violates generality

How a concrete solution could look like?

An exemplary documentation technique meeting all therequirements:

Code documentation based on Design Decision Rationales

http://www.infoq.com/articles/decision-rationales-program-comprehension