Code Visibility: one factor of code quality that you shouldn’t forget


Wednesday, July 13th, 2011 - By xin Zhou

Every developer cares about code quality. But how do you maintain code quality throughout the software development cycle? Readability, modularity, and efficiency all are important factors of writing good code but there isn’t much agreement on the best way to maintain a high level of code quality.

One factor which is often missed in discussions is code visibility, or making sure your code has a clear structure so that others can easily understand it. (Take a look at the diagram above for some of the difficulties encountered when there is a lack of code visibility).

Good code visibility is especially important for large projects and teams. It improves the project’s understandability, maintainability and usability which have a large influence on software quality.

There are lots of articles talking about improving your own code’s visibility:

But the real question is when you are given a code that is terribly written, what can you do to quickly improve its visibility?

One of the most effective ways is drawing diagrams. It used to take time; but there are now tools to help you draw diagrams and use them to understand the code.

With diagrams one can highlight major dependencies and components of the code, so that team members have an accurate view of the large parts of the code. Such as the below example of the architecture of the JDT codebase.


View more Architectural Documentation on Eclipse JDT

Diagrams can add visibility to the original code. They offer a blueprint of the software product and make it easy to detect and correct errors shown in the diagrams and then rewrite the code to improve quality.

Diagrams can also help make good documentation, which helps a lot when you need to do a code review, when new team members come onboard, or when returning to code you haven’t seen in months. Hence the code quality won’t deteriorate as development continues, and as software architecture is updated by different developers.

Moreover, it’s often easier to misunderstand code than well created diagrams drawn in a standard notation. Some tools also allow diagrams, the code and Javadoc to be shared securely online. All these can help teams in collaborating, so that code quality can be improved for large projects and open source projects taken by developers with different backgrounds and geographic locations.

Well diagrammed code will help improve code visibility. And this, in turn, improves code quality.

The only problem with creating diagrams is in maintaining them and making sure that they don’t get out of date. What if there were a class of tools that were connected with the code? What if they could let you know as soon as a diagram got out of date?

We have been working hard at work in building such a tool and would love to hear your thoughts.

 

2 Comments

  1. James says:

    I like this a lot. In fact, I think it would be really good to use diagrams as an actual measurement of code design quality! Asking each person to diagram their code and measuring them against the clock! :-)

    • Xin says:

      Actually, there are studies done on using UML diagrams to measure quality like
      Measuring design diagrams for product quality evaluation (pdf): http://bit.ly/pNEaLx
      But I think it’s hard to ask everyone to diagram their code for measurement. Some people are not fan of diagrammatic-thinking.

Leave a Reply