How can non-engineers visualize code to understand complex software projects?



Code hero image

 The challenge: how can someone who is not a software engineer assess the scope, quality, and overall progress of a complex application development project? How can one visualize code? At first, it seems impossible: code is a highly technical and specific idiom. Depending on the file, it might contain business logic, tests, front end code, server or environmental configurations, or more. 

So while looking directly at code may not be useful for non-engineers, it is possible for anyone who knows the business problem—the problem domain—to understand code visualizations, reports, and progress updates.  

The benefits are enormous. Seeing the big picture reveals all the supporting effort that’s needed to make things work. Assessing code quality assures the development effort is producing a quality product. And understanding the overall progress enables smart choices about scope and features so that software can get to the market more quickly, where it can receive invaluable feedback from users. 

Here are four approaches to visualizing code that we’re using with our clients to good effect, that help clarify the code itself as well as the overall code quality. 

Visualize the domain model with diagrams

A domain model represents the “bones” of an application: all the buckets, if you will, of the objects it handles, a description of their attributes, and the relationships between them. Technically, they are called entity-relationship diagrams, or ERDs.  You might consider them similar to tables and column headers in a spreadsheet — although they do not necessarily map to database tables, but rather show how the problem domain is modeled. 

entity relationship diagram

Ideally, the entity-relationship diagram is built automatically and directly from the application code. There are also tools that can build from the database schema, although this is not ideal, as it’s focused more data storage than problem modeling. 

Visualize all the software components with dependency graphs

A dependency graph shows how your software is designed in relationship to lower level software components. Some of these components represent utilities, like testing suites or load capacity simulators; others represent pre-built components, like text editors or search engines; and others show the details of deployment, like servers or asset pipelines.  

For modern web applications, dependency graphs are seldom small: they may push the limits of visualization, for all the connections between the subsystems.    Expect a huge, very dense graph. Here’s just a snippet example from one of our projects: 

Dependency graph

Step through your software’s workflow with sequence diagrams

A sequence diagram shows the interactions between the objects of a complex system, in timed sequence from top to bottom. They are ideal tools to communicate the logic of an application, workflow, or business process: they are clear and easy to read, they clarify requirements and edge cases, and they show the dependencies between systems. 

sequence diagram

It’s also easy to understand how far along a software project has progressed, based on much of the sequence diagram has been implemented. 

Baseline your project’s code quality through code coverage reports

Software testing suites autogenerate test coverage reports. The show, when tests are run, how much of a project’s code is executed. Higher test coverage percentages mean that more code is “exercised” during testing — so a higher percentage of coverage reduces the risk that the code contains bugs, relative to untested code. 

sample test coverage report from GitLab

Test coverage reports also give a rough sense of the complexity of your application: they show the total number of files, grouped by type, and number of lines of code. 

What kinds of tools have you seen or used?  Tell us about them below, we're interested to hear about them. 

Photo by Markus Spiske on Unsplash.