The document discusses how agile software development both supports and impedes program comprehension. It supports comprehension through striving for high-quality code and unit tests, but can also impede it through continuous refactoring and lack of documentation. The document proposes that documentation in agile should be at a low level (attached to source code), extract higher-level documentation for other stakeholders, not create separate documentation artifacts, serve the primary purpose of program comprehension, and provides an example technique of code documentation based on design decision rationales.

1. Documentation for Program Comprehension in
Agile Software Development
Fabian Kiss
Scrum User Group Lake Constance
Sep 2011

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

3. Agile
Working software over comprehensive documentation
→ code = documention

4. 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

5. 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

6. 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

7. Why supporting Program Comprehension by
documentation?
Agile impedes Program Comprehension
Continuous refactoring
Experienced team for initial development, less experienced
team for maintenance
Unrefactorable obfuscating code
Face-to-face communication is preferred: What if nobody
(anymore) knows a certain information?

8. Why supporting Program Comprehension by
documentation?
Agile impedes Program Comprehension
Continuous refactoring
Experienced team for initial development, less experienced
team for maintenance
Unrefactorable obfuscating code
Face-to-face communication is preferred: What if nobody
(anymore) knows a certain information?

9. Why supporting Program Comprehension by
documentation?
Agile impedes Program Comprehension
Continuous refactoring
Experienced team for initial development, less experienced
team for maintenance
Unrefactorable obfuscating code
Face-to-face communication is preferred: What if nobody
(anymore) knows a certain information?

10. Why supporting Program Comprehension by
documentation?
Agile impedes Program Comprehension
Continuous refactoring
Experienced team for initial development, less experienced
team for maintenance
Unrefactorable obfuscating code
Face-to-face communication is preferred: What if nobody
(anymore) knows a certain information?

11. Why supporting Program Comprehension by
documentation?
Agile impedes Program Comprehension
Continuous refactoring
Experienced team for initial development, less experienced
team for maintenance
Unrefactorable obfuscating code
Face-to-face communication is preferred: What if nobody
(anymore) knows a certain information?

12. Goal
Documenting particularly for the support of Program
Comprehension without impeding agility
→ requirements for that documentation...

13. Low-level context
Documentation has to be attached to the software in
development 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)

14. Low-level context
Documentation has to be attached to the software in
development 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)

15. Low-level context
Documentation has to be attached to the software in
development 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)

16. Low-level context
Documentation has to be attached to the software in
development 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)

17. High-level benefit
From the low-level documentation a higher-level
documentation (artifact) has to be extracted such that it
adds directly a benefit for other involved stakeholders:
1. Progress of software development is made more
transparent
2. Improved quality of developed software product /
additional value

18. High-level benefit
From the low-level documentation a higher-level
documentation (artifact) has to be extracted such that it
adds directly a benefit for other involved stakeholders:
1. Progress of software development is made more
transparent
2. Improved quality of developed software product /
additional value

19. High-level benefit
From the low-level documentation a higher-level
documentation (artifact) has to be extracted such that it
adds directly a benefit for other involved stakeholders:
1. Progress of software development is made more
transparent
2. Improved quality of developed software product /
additional value

20. High-level benefit
Rationale
1st type: agile principle ”working software is the primary
measure of progress”
2nd type: agile principle ”continuous attention to technical
excellence and good design enhances agility”
Such a direct benefit – obtained by the low-level
documentation – helps a developer to justify the effort for
(continually) documenting at a low level

21. High-level benefit
Rationale
1st type: agile principle ”working software is the primary
measure of progress”
2nd type: agile principle ”continuous attention to technical
excellence and good design enhances agility”
Such a direct benefit – obtained by the low-level
documentation – helps a developer to justify the effort for
(continually) documenting at a low level

22. High-level benefit
Rationale
1st type: agile principle ”working software is the primary
measure of progress”
2nd type: agile principle ”continuous attention to technical
excellence and good design enhances agility”
Such a direct benefit – obtained by the low-level
documentation – helps a developer to justify the effort for
(continually) documenting at a low level

23. No separate artifact
A documentation for supporting Program Comprehension
must not be explicitly produced, as it is not explicitly
requested (by the customer)
Rationale
Agile principle: ”simplicity – the art of maximizing the
amount of work not done – is essential”
Overdoing low-level documentation in favor of the
subsequently extracted high-level documentation artifact is
not necessary

24. No separate artifact
A documentation for supporting Program Comprehension
must not be explicitly produced, as it is not explicitly
requested (by the customer)
Rationale
Agile principle: ”simplicity – the art of maximizing the
amount of work not done – is essential”
Overdoing low-level documentation in favor of the
subsequently extracted high-level documentation artifact is
not necessary

25. No separate artifact
A documentation for supporting Program Comprehension
must not be explicitly produced, as it is not explicitly
requested (by the customer)
Rationale
Agile principle: ”simplicity – the art of maximizing the
amount of work not done – is essential”
Overdoing low-level documentation in favor of the
subsequently extracted high-level documentation artifact is
not necessary

26. Primary purpose
A documentation for supporting Program Comprehension
has to serve primarily that purpose
Rationale
A specific purpose is needed as a starting point, because
”documentation” is too broad
Alternatively presuming particular documentation artifacts
from software development process violates generality

27. Primary purpose
A documentation for supporting Program Comprehension
has to serve primarily that purpose
Rationale
A specific purpose is needed as a starting point, because
”documentation” is too broad
Alternatively presuming particular documentation artifacts
from software development process violates generality

28. Primary purpose
A documentation for supporting Program Comprehension
has to serve primarily that purpose
Rationale
A specific purpose is needed as a starting point, because
”documentation” is too broad
Alternatively presuming particular documentation artifacts
from software development process violates generality

29. How a concrete solution could look like?
An exemplary documentation technique meeting all the
requirements:
Code documentation based on Design Decision Rationales
http://www.infoq.com/articles/decision-rationales-program-comprehension