Better Architectural Documentation in 5 easy steps

Documenting code can be a time consuming challenge, especially when dealing with unfamiliar spaghetti code. Diagrams and UML tools can help with this but what appears to be a comprehensive diagram to one person might actually result in more confusion to someone else. It’s important to maintain a clear idea of what concepts your diagram is conveying. I often find myself attempting to document entirely with inline comments. This is often very useful but presents challenges when documenting concepts that span multiple classes/methods. There are several tricks I’ve found that make the task of diagramming code significantly easier.

Images cannot survive in a vacuum

Diagrams should not be the only source of documentation for your codebase. Inline comments, javadoc, and architectural guidelines all help compliment diagrammatic documentation. Diagramming tools that allow you to add ordered comments or javadoc directly within the diagram can help ease the burden on documenters by combining corresponding types of documentation in a single image.

Highlight stumbling blocks

Just like commenting every line of code is not generally a good idea; creating diagrams explaining every nuance of your code should not be your top priority. Diagrams should help show complex or confusing sections of code clearly. Some examples of areas that should be documented are: interesting architectural designs, complex build or layout systems, unique design patterns, complex logic, unintuitive logic or methods, or important exceptions to common use cases. These types of scenarios are often stumbling blocks for new developers. Having diagrams available helps to prevent uninitiated developers from accidentally introducing bugs to key sections.

Organization is key

Diagrams are useless if they are not readily available to all members of the team. Diagrams should be as easily shared between developers as the code they are working on. This way there is less of a chance of misunderstanding code concepts and everyone is guaranteed to be on the same page. Diagrams can be shared by checking them into the corresponding source repository or using a server to host the diagrams to the entire team. Make sure to also keep diagrams organized in a way that makes sense for your project; grouping by package, component, or level of detail are all excellent methods.

Keep Updating your diagrams

Diagrams should receive routine maintenance to ensure they are up to date. Old diagrams become progressively less helpful as the underlying code changes more and more. It is helpful to schedule updates every month or so and even more often for code that changes more frequently or in agile environments. Utilizing diagramming tools that detect changes in your code and allow for easy saving and updating makes maintenance significantly easier.

Less is more

A diagram containing too many components does not necessarily convey more information. More classes, methods, and connections often result in a cluttered diagram that is too convoluted to understand at a glance. However, a concise diagram created within a clearly defined scope and describing a key code concept will much more effectively make even the most complex code easy to understand. Large sprawling diagrams can often be broken down into sub-concepts and organized to provide a fuller, more complete picture.

(BONUS) Multiple versions

Keep copies of older versions of your diagrams. This helps new developers better understand how the code has evolved and may help illuminate hidden pitfalls or allow others to avoid making the same mistakes. It is also helpful to keep separate versions of your documentation for both unexperienced developers and those familiar with the codebase. Such targeted documentation will result in much quicker understanding for any developer.

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