Let’s face it; code can be hard to understand. We have all encountered a piece of code that took longer than expected to figure out or was easy to misunderstand. It could be a new library, a coworker’s code, or your own code from 6 month’s ago.
In a previous post we discuss the importance of taking time to study users in order to get feedback on innovative ideas. We did that to determine how developers understand code and why it can be a challenge.
We asked Open Source developers a number of questions. Two that stood out were their thoughts on the difficulty of understanding their code and what they generally wanted more of in such projects.
The first question we asked Open source developers was if they thought that the code they were working on was challenging to understand. Those using the libraries (API Clients) had a different take than those building the library (Core developers).
Core developers that worked to create frameworks and libraries for others to use felt their codebase was easier to understand when compared to the API developers using them.
The other question was how developers felt about resources for better understanding the Open Source project. We asked them about both the available resources and what they would like to see more of. Architectural documentation, helpful articles, diagrams, example code, and Javadoc were all considered as well as others.
There are some striking differences between what developers currently find useful for understanding code and what they would like to see more of.
As you can see API users more often encountered difficult to understand code. And generally, developers like anything that can help them understand better, but are currently lacking in Architectural and Diagramatic documentation.
Our goal is to help developers create this type of documentation. This will not only help them understand the code they are working on but also decrease the time spent understanding new code, and make documenting their own code easier. We are always looking for new ways to help software engineers understand code. Are there any ways that you would help your own understanding tasks?
I am writing new articles once every 2-3 months. Interested in getting notified? Sign up here.
