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.

 

I am writing new articles once every 2-3 months. Interested in getting notified? Sign up here.