Upload
fabian-kiss
View
786
Download
3
Tags:
Embed Size (px)
DESCRIPTION
Most of the daily work of a software developer is maintenance and further development of existing software products. Is there a kind of documentation which particularly facilitates these tasks? Can such a documentation be agile?
Citation preview
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