Making Code Easy to Understand – What Developers Want (a study)
Wednesday, July 27th, 2011 - By Vineet Sinha
What exactly makes a codebase easy to understand; the documentation or the tools that you use? In our effort to help developers who are working with large codebases, we conducted a survey (see details and highlights) to find out what techniques developers use to better understand code.
One of the major questions that we had was that we wanted to know which documentation techniques were being used effectively (by the average Open Source project).
We found that there was a consistent opinion of most developers saying that projects were effectively using Javadoc, Code examples, and Articles on using Code. Other methods of documentation such as Articles on the Code Architecture, Diagrams of code components, Mailing list, Manual, and Test cases seemed to either be less useful for helping understanding or were not consistently used well. The responses:
| Documentation Technique | Saying Effectively Used |
|---|---|
| Javadoc | 45% |
| Code examples | 38% |
| Articles describing using code | 37% |
| Articles describing code architecture | 18% |
| Code structure, pattern usage, etc | 14% |
| Diagrams of code components | 4% |
| Mailing list | 4% |
| Test cases | 1% |
Knowing what is used effectively is important to us; we need to make sure that our code understanding tools support these practices.
We further asked developers what kind of resources they wish to have for this purpose. We wanted to find out what exactly is lacking with the currently available tools and why are they not as effective as the developers hope them to be.
According to the results of the survey, 45% of developers wish they had access to more articles explaining the code architecture and 42% wanted more diagrams of the code. More detailed responses are below:
| Documentation Technique | Want to Have |
|---|---|
| Articles describing code architecture | 45% |
| Diagrams of code components | 42% |
| Articles describing using code | 33% |
| Code Examples | 29% |
| Javadocs | 24% |
The message was clear. While developers are getting a lot of detailed information about projects (Javadoc, examples, articles describing code use), they are lacking the high level overviews that would allow them to better understand a new project or codebase at a glance. It does not matter whether this information comes in the form of a diagram or an article describing a codebase as long as it is still helpful to developers and allows them to understand new code quickly and easily.
Architexa has taken these results to heart and we are resolved to provide a tool that can provide high level overviews in the form of both diagrams and architectural explanations as well as more common documentation such as Javadoc and code examples.
This is one of the reasons we started the “Architecture of Open Source Applications” project (http://aosabook.org): we want to document the high-level architectures of particular systems, but also show people by example what such documentation should look like. All the content is open (Creative Commons license), Volume 2 is in the works, and we’re actively looking for contributors for Volume 3.
Greg,
Thanks for your response. I have been really happy to see initiatives like the AOSABook – we have also have something similar at http://www.codemaps.org (would be great to hear your thoughts on it). We have been thinking about writing a post about the AOSA book sometime soon.
The main feedback that we have been getting on such new initiatives, is that this information is about very high level (introductory) architecture – and does not talk about the architecture for the important and common tasks.
Simple extensions to Javadoc should provide enough parsable information to allow for at least the two top items in the wish list. I’ve done similar work for Micron in the past. Not that hard to allow Javadoc to do it’s thing and your own parser to do adjunct work.
I know of some tools which does allow one to create diagrams from javadoc but I am yet to find a tool effective enough to create useful diagrams automatically. If you could point out some example/link of a good tool to create such diagrams well, do let me know. In my experience some human input is invariably necessary to create something useful for a larger audience.
For a framework/API/SDK/lib – then yes, articles/etc. are great – examples help a lot – especially since I typically don’t delve into the actual code. Which is an issue – those articles/etc. are not helping me understand the code, but rather to use the API/SDK/etc. – i.e., the interface, not the actual codebase.
OTOH, when I am exposed to a new codebase, usually for some application or system, I rarely see any “articles” or anything of that level about the code. I might see a smattering of high level architecture descriptions, and hopefully the project will have Javadocs (although most of which I have seen are useless).
Since I must eventually dive into the code itself, either to modify it, fix a bug, or extend it, it is “Code structure, pattern usage, etc” that matter the most to me at that point. Unfortunately there is a lot code out there that is a SPOC (Steaming Pile of Code) and about the only patterns these codebases follow are anti-patterns, and the “structure” is best described as something akin to spaghetti.
My point is, easy to understand code is easy to understand code – i.e., the code itself must be understandable. Articles and external docs are icing on the cake, but if the cake itself is crap then you wouldn’t want to eat it.
Definitely hoping for more understandable code, as well as tools to help understand code, and more tips on making code easy to read.
-Vineet
ps: If you have any such resources that you want to post here, or if you want to write something we will appreciate a note.
[...] What Developers Want. The Goals of [...]
Interesting survey vineet. We are more focused on controlling and removing complexity from the architecture than comprehension per se, but we consistently get the same answer when we ask architects how they convinced management to support major restructuring jobs: they show them a diagram of the top level components and their interdependencies. It seems that even non-technical senior managers can “comprehend” quite alot about software architecture when it is presented as a picture
.
I could not agree more with your study !
But although developpers do want paper doc explaining high level design choices & architecture, such paper docs have a blocking drawbacks : it is nearly impossible to maintain them.
Developpers change code every day, and do not browse through the entire doc / articles to update the informations. Sooner or later, paper doc becomes unsychronized, contains informations that are not true any more and can lead to misunderstanding issues. Eventually, doc will not be used (as shown by your study : only 18%/4% of readers use architecture articles/diagrams although 45%/42% would like to have it).
You may be interested by the new Eclipse Project we’re proposing to ensure doc & code synchronization :: Mylyn Intent.
Presentation : http://alagarde.tumblr.com/post/3064712740/intent-discovery-part-1-the-intents-behind
Wiki : http://wiki.eclipse.org/Intent
I agree – it is currently hard to maintain such documentation. We have actually built something that helps in doing that, and are slowly deploying various features to customers.
What we are doing is intended to have very similar results as Mylyn Intent, and we have been seriously considering joining the project. However, you guys are taking a different approach than what we like and we currently have some concerns around the performance of such an approach.
I figure we will have some good lessons learned over the next year – and will then be able to merge them together.
Lets stay in touch.
Vineet
–
President & CTO, Architexa
Understand & Document Code In Seconds
Please continue discussion on the forum: link