Implementation Decision Rationales – Program Comprehension in Agile

Most of the daily work of a software developer is maintenance and further development of existing software products. Therefore it is crucial for a developer to understand what has been implemented, and this understanding will most often come from reading the code.

In addition to understanding what has been built the developer needs to understand the "why" of the code design, as there are an abundance of possibilities for implementing something (even in the case of an apparently trivial task).

It is necessary to be able to tie the pure syntactical nature of the source code to its meaning in the application domain. This happens whenever a developer tries to understand the structure and behavior of a piece of code - known in academia since the late 70s as Program Understanding or Program Comprehension.

Why should these concepts from the pre-OOP Jurassic era of computing matter in contemporary agile software development approaches?

It is evident that the common agile practice of continuous code refactoring increases the need for Program Comprehension as the code has to be understood again and again. Agile projects favor as much face-to-face communication as possible with fellow developers and with non-developer stakeholders, but almost inevitably there will come a time when the only way to understand what has been built (and how it has been built) is to "consult" the code.

Once again, this leads us to Program Comprehension.

Consequently, it is advisable to have documentation that supports more or less directly the Program Comprehension needs of a developer - in addition to the concept of "the code is the documentation".

The agile value "working software over comprehensive documentation" makes it clear that such documentation has to bring a benefit discernible to the customer - to justify the effort of documenting while working in the spirit of the YAGNI principle. A challenging endeavor as we deal with a matter that is apparently related solely to programming.

Design Decision Rationales as a solution

A possible solution could be an approach to documentation based on Design Decision Rationales, originally known from the discipline of system development. By extracting the essence from its various definitions in literature, you can say that a Design Decision Rationale states the reason behind a decision that was made during the design of a software system, to justify and clarify the thinking behind that decision. A useful rationale can also argue why alternative design options have been rejected.

As was stated above, there are many possible ways to implement a design in code. Applied to software development with that in mind, the notion of an "Implementation Decision Rationale" comes to the fore, so that the decisions which were made regarding the implementation are explained. Obviously, that would be helpful for a developer in respect of Program Comprehension. Looking again at the implications of code refactoring, such a rationale could justify, for example, why an obfuscating part of the code was implemented like that (or why it was not refactored subsequently). There are indeed cases where refactoring is virtually impossible due to the extreme costliness of it. Just think of any ugly performance optimization in the code that can hardly be avoided (unless you are not faced with the development of performance-critical software at all).

Are agile values or principles violated?

So, does such a documentation approach align with agile software development?

Literature for practitioners also substantiates the value of this approach: Andreas Rüping explicitly addresses the idea in his pattern collection for documenting in Agile with a pattern named - not surprisingly - "Design Rationale". Likewise Robert C. Martin (one of the authors of the Agile Manifesto) addresses it explicitly in his Agile book when reflecting on the agile value "working software over comprehensive documentation".

So should this approach be accepted as an agile practice? If so, the documentation should be based on informally represented Design Decision Rationales in text form. There is no common representation of them, but the recommended approach is a short block of text written in natural language - freely adapted from user stories.

Here is a very brief (and fictitious) example of the implementation of credentials verification in a typical login scenario:

password is passed together with its original set date to determine internal encryption
passwords set after 2008-10-01 have been encrypted in DB with SHA-2, not anymore with MD5

Never neglect customer satisfaction!

When the Program Comprehension of a developer is supported by documentation, a consequential benefit sould be the improved quality of the resulting software product. Without doubt this would be of benefit to the customer.

It is quite likely that the customer won't request such documentation, as programming-related matters are usually not understood by non-developers. This means that the developers have to advocate for the production of this "just enough" Program Comprehension documentation.

But if the customer does not appreciate the value of these qualities, then you have a problem. Bear in mind that the first principle incorporates the expression "our highest priority" (certainly, the highest priority does not mean the only priority). We should have a secondary, more discernible benefit in addition to the primary one (support of Program Comprehension) to justify the effort of documenting.

As quoted here from an article in IEEE Expert, there are further identifiable benefits from the inclusion of Design Decision Rationales:

Managers or users can use them to evaluate the design.
Lawyers can use them to determine if the design is intellectual property.

Nonetheless, we don't have to think that far beyond ordinary software development (lawyers are usually not involved as project stakeholder, aren't they?). Instead, consider the facilitation of a crude change impact analysis conducted by a project manager as a non-developer stakeholder. Such an activity could feasibly be enabled by Design Decision Rationales which are understandable - at least partially - by non-developers.

Suggestion for an implementation

This notion of code documentation with developers as the primary target audience and other stakeholders as a secondary one resembles the common employment of xDoc for generating different variants of an API reference. Actually, xDoc could be an effective approach for implementing Design Decision Rationales as discussed in this article.

Why not simply add one or two doc tags for making them explicit? For example, an @decision tag supplemented by one or more @reason tags.

Let's just see how the example above could look like when implemented using this style:

/**
* @decision password is passed together with its original set date to determine internal encryption
* @reason passwords set after 2008-10-01 have been encrypted in DB with SHA-2, not anymore with MD5
*/

It is a straightforward process to customise an xDoc tool for generating a nicely formatted representation of that code documentation. Stating Design Decision Rationales on a method level (doc comments are more or less supposed to be placed there) warrants a certain non-triviality of them (justifying single If statements would certainly be ridiculous).

With that documentation approach, development will probably take longer initially, but the time saved in not needing to struggle to understand the decisions made over and over will more than compensate for this additional effort.

The suggested implementation by means of an xDoc tool is not only lightweight when practiced but also introducing it is lightweight: You can hardly lose anything as you most likely use xDoc anyway (don’t you?). Particular doc comments can be removed quickly if you choose to get rid of them again.

At the very least you gain some practical documentation wisdom specific to agile software development! So why not trying to document your decisions instead of writing the usual, rather aimless code comments?

About the author

Fabian Kiss is a software developer who loves agile and lean environments. In his daily work he is never tired of convincing a stakeholder of the benefits attained by practicing sustainability throughout the entire development lifecycle.

The idea is viable but there is at least one issue that I see now. As the code evolves, a single piece of code can be subjected to multiple refactorings. Therefore, the piece can be influenced by multiple decisions. If we use the suggested notation, we should write down multiple reasons for those decisions. This way the comments will become cluttered very soon (there can be a dozen of different decisions connected to the piece of code) and the whole thing will become unreadable.

There is a solution, though. You can store information about decisions and rationales behind the code in SVN/Git commit’s comment. This way you can clearly see the connection between the code and the decision/reason behind it, and you can also see a HISTORY of decisions that influenced the code.

Putting this kind of information into the commit comment has even more advantages, in my experience: it typically also allows you to see *who* made that decision, and in *which* context (at least of other code changes, preferably even the context of a user story).

Regarding your specific example, this information can even easily be put into one or more automated tests. That way, we can also ensure that the information doesn't get accidentally ignored when the code gets changed.

SVN / Git / VCS comments easily get lost when the project goes to maintenance at a different company / on version control system "upgrade".

So, it should be in the code.

Also, maintainers are lazy to look at ANY documentation; don't even try to create one for them.

What a maintainer will do - and I speak from experience, even if not personal - they get a request, they try to locate the class which is most possibly responsible for the change in question, read the comments at the top of the file, near and inside the affected functions, and do the change.

They won't change comments. They're unlikely to add [meaningful] comments. Sometimes, when the comment no longer applies, they remove them, but some of them are too lazy to do that.

That's their working style. This is what you should prepare your source code for.

If a code never leaves its original development team, and the development team doesn't change rapidly (suddenly only one student remains, with the last two original, but 2nd-generation developers filling their notification period - that's "rapid" change) then commit messages are the way to go.

But if the code is to live for 10+ years, the only place where you could put such is the code itself.

Just today I was asked why I try to express JS patterns in C++-style, don't I know javascript enough? I answered: I do, but imagine if it gets to a maintainer programmer with originally a java background who thinks he knows javascript after a week of jQuery...

So, the real test of a code's style is when it comes to maintainability.

As for Fabian: don't take the manifesto too seriously. Releasing early spaghetti was never an intention of the original authors, I'm sure.

..but specific lines in source code can easily be tied to specific commits. Think svn blame. Commit comments IMO should provide context, and point to the user story/use case/requirement/bug report addressed or partly addressed by the commit.

Is your profile up-to-date? Please take a moment to review and update.

Email Address

Note: If updating/changing your email, a validation request will be sent

Company name:

Keep current company name

Update Company name to:

Company role:

Keep current company role

Update company role to:

Company size:

Keep current company Size

Update company size to:

Country/Zone:

Keep current country/zone

Update country/zone to:

State/Province/Region:

Keep current state/province/region

Update state/province/region to:

Subscribe to our newsletter?

Subscribe to our industry email notices?

You will be sent an email to validate the new email address. This pop-up will close itself in a few moments.

We notice you're using an ad blocker

We understand why you use ad blockers. However to keep InfoQ free we need your support. InfoQ will not provide your data to third parties without individual opt-in consent. We only work with advertisers relevant to our readers. Please consider whitelisting us.