Often, you hear “code comments” and “code documentation” used at least somewhat interchangeably. Perhaps the idea of code documentation has a little more formalism to it, in passing. And code comments may cover a bit less ground.
But still, I hear the terms serve as synonyms for one another. And I hear this in particular when it comes to the actual construct of code comments — meaning, literally, the feature of compilers and interpreters that allows you to say, “Disregard everything after these two slashes. I’m editorializing for the benefit of other humans.” “Comment your code” and “document your code” offer the same mandate.
But I find that problematic. And it’s not just because I’m some kind of stickler for semantics. I think this causes us to have weird arguments, sometimes nonsensical and sometimes unnecessary.
Code Documentation vs Code Comments
To explain myself and my reasoning, I’ll offer definitions for both terms.
- Code comments: any meta text you put in source code.
- Code documentation: creating a conceptual maintenance manual for your source code (in the dictionary sense of documentation).
Having established that, let me stave off some possible objections. First, you might ask, “Isn’t the entire point of code comments to help create that user manual?” In theory, maybe. But in practice, come on, you know better. People use comments to add legal boilerplate, express themselves with ASCII art, try their hand at comedy, and probably even to gossip.
Secondly, maybe you’re someone that concedes that people do use comments this way, but you say that it’s abuse. In other words, sure, that happens — but it shouldn’t. If people did code comments right, they would all constitute code documentation. But I would still argue against this idea. Code comments can represent note-taking. “Note to self” and “note for later” both count.
So let’s create a relationship definition. Code documentation means creating a maintenance manual for your code, and that manual may or may not use the code comment as a medium.
I’ll also say that I think you should document your code, but it doesn’t matter terribly if you comment it.