MediumWhen code is a maze, smart developers make maps | by Simon Smart | MediumSitemapOpen in appSign upSign inMedium LogoGet appWriteSearchSign upSign inSuggestions on how to leave signposts (comments)Suggestions on how to make maps (documentation)Simon SmartSoftware EngineeringSoftware DevelopmentProgrammingSoftware ArchitectureDocumentationWhen code is a maze, smart developers make mapsSimon Smart4 min read·Nov 26, 2025--ListenSharePress enter or click to view image in full sizeModern code is difficult to understand, perhaps more so than any time in the past. Popular modern coding practices have done away with “spaghetti code” in favour of decoupled patterns: “ravioli code” where components act autonomously.A significant problem with decoupling is that it can make it much harder for developers to understand how the pieces fit together and what actually happens when the program runs. With “spaghetti” there were at least threads (strands?) to follow, but with something like a publisher/subscriber system it can be extremely difficult to determine what a piece of code will do, or what caused a piece of code to execute.Even in the ‘old days’, code could be difficult to navigate. Now it’s frequently a labyrinth. Different levels of coupling have legitimate advantages in different situations, but I’m not going to be arguing their merits here; it’s very much a luxury for a developer to be in a position to make decisions on how code is architected. What every developer will need to do is to find their way through whatever code they are faced with.So how do developers do this? Frequently, we just throw ourselves into the code, charge into the maze and run around hoping we’ll bump into what we need. Eventually, after many hours of exploration, we find the right place and leave. And then next time we do it again. And the next time, and the next time, and so on. In most cases, we spend much more time trying to understand the code than we ever do making changes to it.Effort spent on reducing the time we spend in that maze can have huge returns on the time we invest. As the title says, smart developers don’t let what they’ve learned be forgotten, they leave signposts to help others navigate; they make maps to share what they’ve learned.In code, comments are our signposts. There’s a movement among some developers to reject comments outright; reasons given are that comments require maintenance, and even that allowing comments encourages developers to write code that isn’t intuitive. I would argue that, in the mazes we must navigate, signposts are absolutely essential, even more so than they were in the past.Our maps, of course, are documentation. Diagrams, written guides, video notes, or whatever other forms it might take, it can all pay massive dividends in reducing the amount of time that developers need to spend analysing code and systems. Unfortunately, like comments, it’s rarely given the priority that it would if its value was really understood. The same arguments are made about needing to maintain documentation, but when you’re lost in a maze a tattered old map is often much better than no map at all.I can’t authoritatively state the right way to document your code, but I can make some suggestions.Suggestions on how to leave signposts (comments)Use a combination of in-line and standalone comments, depending on the situationTypically keep comments on a single line without line breaks — if a comment is useful, developers will scroll to read them, if it’s not they can easily scroll past it.Don’t add comments that have no value. There’s no need for a comment to explain that X + 1 adds 1 to X!Your goal should be for the reader to understand the code without needing additional outside knowledge or context (other than understanding the language itself, of course).Comments should typically explain why the code is doing something, but not always. There are plenty of cases where comments are important to understand what is going on!Be explicit in comments and share as much information as is useful — don’t omit useful context in favour of brevity.Just like signposts, it’s often most useful for them to show where you came from, where you’re going, and even where you are! Comments don’t need to be confined to explaining how the code works; explaining how execution can reach the code you’re looking at can be even more valuable in many cases.If someone raises a question during code review, it’s almost always a sign that a comment is needed. Don’t ignore these questions, as they will arise again and again.Suggestions on how to make maps (documentation)Documentation should be stored in a public location that everyone can access.Diagrams can be extremely useful maps to your code. There are many options available for these, but I personally favour Mermaid and draw.io.Focus on the parts of your system that are the most important, usually the parts that developers need to work on the most often.Don’t think you need to write hundreds of pages to make useful documentation; even a few paragraphs can provide massive value when they cover obscure parts of the system.If you’re using a system that supports it, add contextual links in your documentation that point directly to the code.Links work both ways; your comments can link to your documentation.Just like with comments, be as explicit as possible in your documentation. Ideally a reader shouldn’t need additional context to understand your documents, but if additional context is needed there should be another document to link to!Use headings, bold, italic, underlines and colours to add visual context to your documents. For example, if you always colour an “INSERT” operation yellow, your readers will quickly gain an intuitive understanding without needing to read every word.These are of course just suggestions and there are many other approaches you could take. What I can say is that these techniques have worked for me and frequently saved huge amounts of time and effort.Good luck out there; may you never find yourself lost in a maze with no map.Software EngineeringSoftware DevelopmentProgrammingSoftware ArchitectureDocumentation----Written by Simon Smart2 followers·1 followingHelpStatusAboutCareersPressBlogStorePrivacyRulesTermsText to speech

Modern code, characterized by decoupled patterns such as "ravioli code," presents significant challenges for comprehension, creating a labyrinth for developers trying to understand how various components interact during program execution. While different levels of coupling offer situational advantages, the fundamental requirement for every developer is the ability to navigate this complexity. Often, developers spend more time attempting to understand existing code than implementing changes. To mitigate the effort spent navigating this maze, smart developers emphasize the importance of leaving signposts and maps to share their learned knowledge.

In the context of code, comments serve as essential signposts. Although there is a movement among some developers to reject comments due to maintenance concerns, the author argues that signposts are absolutely essential for navigating code mazes. Suggestions for effective commenting involve using a combination of in-line and standalone comments, typically keeping them on a single line to facilitate easy reading, and ensuring they add value by explaining the reasoning behind the code's actions rather than tautological statements. Comments should aim to allow the reader to understand the code's intent without needing external context, and they should explicitly detail execution flow, which can be especially valuable when preparing for code reviews.

Documentation serves as the larger maps for navigating systems, and it must be given priority when complexity is high. Documentation should be accessible in a public location for broad use. Visual aids like diagrams are highly effective for mapping code structure, with the author favoring tools like Mermaid and draw.io. Documentation efforts should focus on the most critical parts of the system, particularly those areas that developers interact with most frequently. Rather than attempting to write exhaustive documentation, even brief explanations covering obscure system parts can provide substantial value.

To enhance the utility of documentation, contextual links should be incorporated to point directly to relevant code sections, establishing a two-way relationship where comments can link to documentation. Furthermore, visual aids should be enhanced using formatting elements such as headings, bold text, italics, and color to provide intuitive context. A key principle is explicitness: visual cues, such as consistently coloring specific operations, can convey understanding more rapidly than lengthy textual explanations. Ultimately, the goal of both comments and documentation is to provide clear context so that a reader does not need additional knowledge to understand the material; if external context is necessary, a link to supplementary documentation should be provided. These techniques, when applied rigorously, are suggested to save significant amounts of time and effort in system analysis.