Oh, hello there!
So… yep. What is self-documenting code?
It is a concept that applies to a codebase which is so beautifully expressive that it doesn't even need any documentation.
Sounds like a fairy tale, doesn't it?
Many strong and respected people in IT say that comments in code are a sign of poorly written code, and these comments indicate that you simply struggled to write your code in a clear, expressive way.
They insist that self-documented code is the goal we should aim for – we should use correct and expressive names for variables, classes, and functions, build a good structure, and this will be enough for other developers to understand our code!
OF COURSE, all of these rules of "Clean Code" should be followed, but I believe they are wrong (people, not rules :) about comments, and they are mistaken in thinking that everyone else is as smart as they are.
Write 50,000 lines of code in a "Clean Style," and it will automatically evolve into a complex structure. Then, come back after 6 months...
"Obvious" things are not always obvious at all. It is an illusion!
Even if we are completely sure that we understand something at a specific point in time, it might be false... or even if it is true, it might not be true at a different point in time.
Even if we are smart and experienced enough to come back to our 50,000-line system after 6 months and understand it quickly, it is only because we have built a strong "context" of some subjective coding and architecture style in our own brains. Someone else's brain neurons are BUILT DIFFERENTLY.
Furthermore, it is just impossible to express everything related to software design in pure code. Because code, no matter which paradigm it follows, only expresses "what to do."
It is such a small part of the information related to the system…
In the design process, we also need to think about "what not to do", "what needs to be done", "what needs to be optimized" and so on.
You might think that comments are a bad place to store such information because we have JIRA and a lot of other really useful tracking systems. So instead of writing a TODO comment, I am going to create a ticket and send it to the backlog. You might be right, but not every team uses JIRA or follows popular development practices, and this one ticket might be lost in backlog for centuries.
Many teams do not write any formal documentation, so I believe, that comments could be really helpful there.
Another thought here is that even a fantastically pure piece of code can't tell us what it is doing in the context of the whole system design.
Because it just "doesn't know" anything about the system and encapsulates only the related logic in its module.
So, a comment with such meta information about "what this thing is doing in our system" will be really helpful for any developer.
Code that is expressive and clean, with "self-documenting" logic that this code implements – that's fine and nice, thanks for note being stupid.
Comments on this code describe meta-information, explaining how this code fits into the overall system – God bless the human being who wrote it.
So, I hope you understand why, in my humble opinion, self-documented code is bullshit. Even if its concept has a bunch of reasonable, legitimate points, such as:
Comments may become out of date and out of sync with the code.
Comments can be boilerplate junk and make the file less readable.
Comments are just good manners towards the devs.
This is all true, but...
There is just no other way to describe design meta-information.
Top comments (21)
There are bad comments, and good comments.
There is bad code, and good code. And bad code can be written in any programming language.
What I consider a bad comment is:
i += 1; // add 1 to i.int i; // heightinstead ofint height;What I consider good comments is:
YES, YES! My friend, I am so happy with your comment! This is exactly the thing I meant here!
Nice post, but I somewhat disagree. I do believe that code should be expressive enough that it doesn't require comments. The exception would be comments that explain specific business logic or technical details that someone new to the platform needs to know.
Yeah mate, you are right! Read other comments and my answers as well.
No one talking here about commenting method named as "get_entity_by_id" :)
Expressive code is somewhat a must, comments are optional.
Reading any code is harder than writing it, no comment in the world will fix that, it can help.
If comment misguide you and you believe it, o boy, you are in for a ride.
Exactly!
I think you have to support pretty bad legacy software.
Because if it is done right -> it should be pretty self explanatory (including helpful names for functions and variables), following DRY / SOLID principles.
You have code reviews, to check if a given piece of code is understandable by other team members (without being the ones directly involved in writing it). If it is not, or you do not have a review-process in place then I suggest changing that.
You have to decide as a team how the code you wrote looks like, that guidelines to follow and how much documentation is need / acceptable.
Well argued, Stacy. I remember back about 2 decades ago, there used to be a lot of documentation tools published for various languages, now some languages such as Rust, have documentation built in.
So even the Rust creators think comments are necessary.
I would tend to think that Rust creators are very smart people, smart software engineers.
Cheers.
Nobody said it was easy hehehe. I agree I've never seen a large codebase that was "cleanly written", as you said, things evolve and also people are lazy, so they just add some more lines to that already existing function instead of refactoring it. Things grow and become hard to understand, but I disagree that comments will help solve that problem. The rule of thumb is: if you're tempted to add a comment to explain what a few lines of code do, instead, make a new function and explain what the function does by giving it a good name! Yes, that sounds easier than it is, but it's still better than adding a comment that either explain what we can already see in the code, or even worse, it starts to drift in the codebase as people add new lines of code and don't update/move/remove the comment.
Nah, I am talking about meta-information that cannot be completely described through awesome, clearly named, and structured code alone.
You can give a some class in a hierarchy a clear name, and it will be obvious what this specific class is responsible for in its module or even in the entire service (this is the level of concrete realization). And this is the place where comments are usually serve as indicators of bad style, I am totally agree with you.
However, there are things like Abstract Data Types (ADTs) and internal parts of libraries that you would like to understand in place – what they are for in the overall system (this is the level of architecture).
100 % true.
If you seek a new job and hear we have a culture of self documenting code, say thanks you, stand up and leave the room.
Self documenting means no one cares a penny about the codebase and it is in a terrible condition.
Of course, perhaps, there is few companies that do have it done right
Hey, you are right. Unfortunately, in 3 out of 5 cases, they use 'self-documenting code' as an excuse for laziness and carelessness about formal specifications and architecture.
I think that you miss the most is documentation of business process and architecture and why things happen. Documenting it as important. Doing it in exclusively code comments is not.
It is worth only documenting something that does not change often
otherwise documentation feels suffocating and bothersome -> devs will skip it and it quickly becomes outdated, wrong and misleading.
These can't be done in a good way in code -> a separate Wiki is a much better place for that, including features like graphs and links.
For example I recommend plantuml.com/sequence-diagram
Of course it depends on the discipline of your team to keep it updated.
You much easily share your Wiki page with business people of your org and get quick heads up/downs this way - I find it is the best way to check if you have a common understanding of the needed processes.
Hello, thank you for your comments! I appreciate the chance to respond to both in one go.
It appears there might have been a misunderstanding about the message I intended to convey. Practices such as maintaining clean code, following agreements, adhering to internal guidelines, and treating "self-documented code" as a valuable tool are essential for any coders identifying themselves as an engineers.
However, my concern lies with the potential for treating "self-documented code" as a mere ritual, labeling every comment line as boilerplate, and using it as an excuse to bypass the Object-Oriented Analysis and Design (OOA/D) process. I want to emphasize this point. (I am happy if you have never encountered proponents of such "practices", either in real life or online.)
I fully agree with your perspective on the importance of documenting elements that do not change often. Yet, In the codebase, components like Abstract Data Classes or long-standing elements such as "technical debt" objects may remain stable for various reasons.
For instance, "technical debt" objects that persist over time pose a challenge in understanding their role in the overall system, especially for newcomers to the team.
While it is possible (and likely almost needed) to document these aspects outside of the code, it might be viewed as a less-than-ideal practice.
Expecting someone to constantly navigate between the IDE and external documentation, especially in a vast system with numerous interfaces and Abstract Data Types (ADTs), can indeed be a daunting task.
This challenge isn't exclusive to what is typically considered "legacy code" but is a common reality for any system surpassing 300-400k lines of code.
It's all about finding a balance between effective documentation and facilitating a smooth understanding of the codebase for all team members, including newcomers.
Stopped by to agree with you.
Side note: "it's" !== "its". "it's" is shorthand for "it is".
Much appreciated for your help with the mistakes! Thank you!
personally i dont use comments in my code. What is your perpective ??
I am not using it for obvious and well-named parts of the code, but it is essential to describe ADT's interfaces and intricate aspects of libraries, etc.
Some comments may only be visible to logged-in visitors. Sign in to view all comments.