I think most people would be blown away once they see how heavily complex codebases are commented.
I don’t buy into “Your code should be self explanatory” and the reasoning for that is once we start adding business insights into codebase, it loses half its meaning.
The code can’t talk back to us and tell why certain things are behaving in certain way. No matter how “clean” we keep it. We can’t always add meaning to it.
So for me, “WHY” something was done in certain way is absolutely critical before I can add any new features or refactor it.
I know “WHAT” I need to do if requirements are clear but from what I’ve seen most codebases rarely answers “WHY” unless someone has been kind enough to leave comments.
What I’ve also seen is as the code becomes more and more complex, the developers who maintain it tend to add as many comment as possible, not for future developers but for themselves (tests are not a replacement for comments, sorry!).
I guess it goes to show that even people who regularly maintain it need additional comments to make sense of their own code as the complexity grows.
I don’t think a function, class name, variable, how things are connected can ever give you a full picture.
For context I’m working on an invoice management software and there’s no way it would’ve continued making sense without meaningful comments.
Even though the “code” itself is quite clean the insights/comments and tests have become essential for proper development.
Maybe this problem is specific to certain type of software!
Top comments (2)
The idea that code document itself is just flawed, it misses the other 50% of the story. The code may document itself, what you need to understand are the developer intentions & the domain specificities :)
i think some people are just thinks that "Your code should be self explanatory" and "Don't add comments or documentation".
after few days let him/here reread the code they wrote and they wouldn't understand it ,maybe it's self explanation is expired 😂😂