This article helps clarify agile manifesto number two “Working software over comprehensive documentation” by defining the different types of documentation being referred to. An analysis is given on code documentation indicating the complexities that warrant it, and how refactoring and pair programming can also help to reduce complexity. Finally, an approach is given on how to evaluate when to document your code and when not to.

The second item in the agile manifesto “Working software over comprehensive documentation” indicates that working software is more valued than comprehensive documentation, but it’s important to note that there is still some real value in documentation.

I see two types of documentation being referred to here. 1) Code and technical documentation typically created in the code by developers working on the system, and 2) System and architectural documentation created by a combination of developers and architects to document the system at a higher level.

I will save discussing system and architectural documentation for future articles, as it is a much more in-depth topic.

So let’s discuss the first point – code documentation

Questions that many teams ask (agile, or not) are – “How much code documentation is enough?” or “Do we need to document our code at all?”. Some teams don’t ask, and subsequently don’t document. Many TDD and Agile Experts will indicate that TDD and will go a long way to self-document your code. You don’t necessarily need to do TDD, but there is a general consensus that good code should be somewhat self-documenting – to what level is subjective and opinions will vary.

Software code can be self-documenting, but there are almost always complex use cases or business logic that need to have more thorough documentation. In these cases it’s important that just enough documentation is created to reduce future maintenance and technical debt cost. Documentation in the code helps people understand and visualize what the code is supposed to do.

If technology is complex to implement, does something that is unexpected such as indirectly affecting another part of the system, or is difficult to understand without examining every step (or line of code), then you should at a minimum consider refactoring the code to make it easier to follow and understand. Refactoring may only go so far, and there may be complexities that need to be documented even if the code has been nicely refactored. If the code cannot be refactored for any reason, you have another warrant for documentation.

Think about what can happen if code isn’t documented well. Developers will spend too much time looking at complex code trying to figure out what a system does, how it works, and how it affects other systems. A developer may also jump in without a full understanding of how everything works and what the effects are on other systems. This could create serious regression bugs and create technical debt if the original intent of the code is deviated from. A little documentation gives you the quick facts about the intent of the code. Something every developer will value when looking at the code in the future.

Of course, in addition to documentation, pair programming can and should be used to aid in knowledge transfer and can be a good mechanism for peers to help each other understand how the code and system work. Pair programming is also a good mechanism for helping junior and intermediate developers understand when and where they should be documenting their code.

The way I distinguish what code should be documented and what shouldn’t be is based on future maintenance cost. Consider how your documentation lends itself to ease of ongoing maintenance and how easing the ongoing maintenance will reduce technical debt and contribute to working software over time. If your documentation will directly contribute to working software by eliminating future complexity and maintenance, then document. If there is no value to the ongoing future maintenance, then don’t. If you are unsure, ask someone a little more senior, or do some pair programming to help figure it out. I’ve also seen value in peer reviews to help ensure documentation is being covered adequately, but I still prefer to instill trust within the team to get it done properly rather than a formal review process. When in doubt, document – a little more documentation is always better than missing documentation.

A question came in the comments on how to weight the amount of documentation needed in a project. My article was meant to address that question regarding code documentation with my own opinions. System level documentation is much more in-depth, so look for a future article addressing documentation at the system level.

-Dan

Dan Douglas is a professional independent Software Consultant and an experienced and proven subject matter expert, decision maker, and leader in the area of Software Architecture. His professional experience represents over 12 years of architecting and developing highly successful large scale solutions. Dan has been the architect lead on over 15 development projects.

Advertisements

Share this:

Like this:

Related

About dandouglasDan Douglas is based in Toronto, Ontario, Canada and is a professional independent Software Consultant and an experienced and proven subject matter expert, decision maker, and leader in the area of Software Development and Architecture. His professional experience represents over 15 years of architecting and developing highly successful large scale solutions. Dan also believes that properly empowering teams with trust and responsibility yields the greatest results.
|
For inquiries about Dan's software consulting practice, please see the contact page. Dan has also built up a network of highly successful and professional Software Developers and Architects who are highly respected and can be called upon and used in conjunction with his own consulting practice to handle the largest of consulting projects.

Follow Blog via Email

Dan Douglas is based in Toronto, Ontario, Canada and does consulting work for both small organizations and large global organizations through his consulting company, Douglas Information Systems Corporation. He is an experienced and proven subject matter expert, decision maker, and leader in the area of Software Development and Architecture.

With over 16 years of experience, Dan has been the Architect Lead on over 15 development projects and has successfully delivered large scale “best in class” end to end solutions. Dan has developed and architected solutions across a wide vertical, including, government, medical, automative, hr, manufacturing, technology, consulting, and software firms.
Dan writes a lot of code as a hands on developer and is passionate about delivering the right solutions to customers through better code, better architected solutions, better business alignment, and better process.

"My articles are inspired by what's possible. My experience in my software consulting practice has given me the inspiration to write about what I've seen and what I've done, and to write about 'What's possible in software'." - Dan Douglas