The process of adding comments in code has long been referred to as “documenting the code,” and it’s something developers have done (often grudgingly) for years. While it’s true that code comments are part of documenting the code, we should note right up front that “code comments” and “documentation” are not the same thing. They serve related, but different, purposes.
Since documentation is increasingly taking its place in the permanent landscape of code development, it seems a good time to consider whether both comments and documentation are necessary, when to use which, and how to use them together.
The importance of code comments
Many developers readily admit that they often ignore code comments (also referred to as inline documentation) – skipping over those lines that start with // (or # for the Pythoneers amongst us). Still, it’s common to hear engineers complain that code comments act as interruptions, making the code harder to read and preventing it from being “neat.”
At the same, we’ve heard plenty of stories recounting the times that code comments have saved the day. And it’s not hard to understand why. Inline, text-only code comments are easy to find and explain “why” a specific line of code was written in a particular way. In this capacity, they serve an important tactical function when we need to resolve performance issues or bugs.
However, as a result of their very specific location and nature, code comments cannot and do not explain the bigger picture (for example, how does this block of code in the backend interact with a different block of code in the frontend?) This inherent limitation makes it impossible for code comments to explain flows and recurring patterns, complex logic, or algorithms.
Another inherent limitation of code comments is their relatively short shelf-life. Between dev turnover and continuous deployment, there’s a decent risk that a code comment will be deleted or overwritten – and with it the history of “what happened here?” An even greater potential risk is that a line of code will be changed and the corresponding code comment won’t be, making the comment not just outdated, but wrong.
This is where high-level code documentation enters the picture.
This is part of a series of articles about code collaboration.
The importance of high-level documentation
Picking up where code comments leave off, high-level documentation does easily explain flows and patterns – what the code is doing and why. It can also include overviews and guidelines that provide a larger context and perspective for your codebase. As a result, high-level documentation doesn’t usually require a lot of maintenance.
Unfortunately, high-level documentation also has its limitations: it’s more difficult to maintain and update. It’s often hard to find it or even know that it exists (in Confluence? Notion? a Google Doc somewhere?). And its ongoing value can easily be missed in a culture where documentation is still not prioritized.
On the flip side, high-level code documentation theoretically lasts longer, is more often consumed than updated, has the potential to help dev teams understand the big picture and context of entire code blocks, and is more versatile – allowing developers to link between relevant code blocks, snippets, and other resources.
Related content: read our guide to code comments best practices.
How code comments and documentation work with Swimm
We commonly hear fellow developers say, “I don’t believe in documentation. Good code should explain itself!”
While this statement appears to talk about documentation, it’s actually questioning the need for code comments. But in today’s engineering world, we know better. Even if you have good code comments, you still need high-level documentation. And even if you have good documentation, you still need code comments.
Swimm is the perfect crossbreed between code comments and high-level documentation. With Swimm, devs can add code snippets to their documentation, meaning that code comments are available right inside the doc whenever you select a code snippet. And when you’re using one of Swimm’s IDE plugins, links to available documentation appear right within the code, meaning it’s exactly where it needs to be exactly when you need it – while you’re writing code! Moreover, with Swimm, there’s no more risk of code comments becoming outdated or accidentally deleted.
Swimm is a hybrid, code-coupled documentation platform: high-level documentation is saved to your repository as part of the codebase, so you can consume it inline, just when you need it. And at other times, you can consume it outside the codebase, inside Swimm’s app. Because documentation is code-coupled, you find your documents in time; they describe flow and patterns using the actual code; and documentation coverage is automatically detected and flagged, so the days of abandoned and lost documentation are over.
Related content: read our guide to code comments best practices.
Bottom line
High-level code documentation is more than just a “nice to have.” GitHub’s 2021 State of the Octoverse reported that developers enjoy a 50% productivity boost with easy-to-source documentation. It doesn’t take long for good documentation to save your team significantly more time than the initial investment to write it.
In the final analysis, both code comments and code documentation are assets for dev teams, and the days of viewing them as a nuisance are over. So take the dive into Continuous Documentation – supercharge your code comments, optimize your codebase, and support your dev team, all in one fell swoop. This is one swim that will take you far!
Swimm’s community of developers is growing rapidly. We invite you to try out Swimm’s demo to experience how Continuous Documentation optimizes the software development cycle for improved productivity and better cross-team collaboration. With code-coupled documentation, development velocity improves significantly, and onboarding is faster, more efficient, and more productive.
