Are code comments really necessary? Share your insights and experiences on whether meticulously crafted code can be self-explanatory enough to render comments redundant. Are comments an essential part of code documentation, or can they sometimes be more confusing than helpful? Join the conversation!
Follow the DEVteam for more discussions and online camaraderie!
Top comments (18)
Yeah, comments are double strain. If you comment each line of code - the result will be messed code. On the other hand no comments at all also a bad thing. The optimum amount of comments is about 10% of codelines, or even only in critical places. And these comments should be only to myself, not to the public.
Comments are needed, there’s no b&w here. Sometimes, for instance, you need a quirky crutch which is not obvious in terms of goals and/or mechanics (don’t ask me why, years of working for enterprise). If you work in a team you definitely need to let your peers know the reasoning. And that’s not the only case.
Needless to say you don’t have to annotate each variable and function, ideally the names and/or input/output types should be self-explanatory. But that’s just not always possible (not meaning we don’t need to strive for that). I’ll die on this hill 😅 as well as other JS/DOM warriors I believe.
Absolutely. For example, our groovy backend integrates with Odoo ERP using xmlrpc. For some reason, it expects an extra level of nesting for its filters. If you look at the code, it looks like the developer is just nesting objects in a list for no reason, so a comment explaining that this is required with a link to the docs gives the reader context.
I think people who say "code should be self-explanatory" have not written complex systems which inevitably have peculiar behaviors and baffling quirks that you simply cannot explain without a comment.
Unless all the code you are working on is "boilerplate", comments should show up once you start doing things that are different than what already exists in the codebase.
Other considerations I usually have are providing external context for a reviewer reviewing my code, such as why such a thing changed and comments to the external reference.
I think of it like "footnotes" in a book, a book can flow freely and be well written without having footnotes, but having those footnotes can help provide context to a reader if such is required.
These "footnotes" are usually more important in situations such as initial review, and refactoring. Odds are if your bug fixing you hopefully aren't running into a wall of comments, as that is a sign you feel into "commenting complex code" rather than just simplifying the code to make it simpler, but that isn't always possible.
I used to think code should always be self-explanatory until I had to work on complex systems which had odd behaviors you simply couldn't explain without comments. This is especially true if you're doing something like bit shifting, pointer offsets, etc. where the reader cannot easily discern what the code does just by looking at it. Clean Code advocates would tell you to wrap it in a function that basically explains what it does but I strongly disagree.
Well self explanatory code helps us avoid comments but there are places where comments are required. Though when code-base changes/gets updated comments tend to remain in their old version and create confusion. So personally i try to be very precise with my comments and on point in order to avoid that.
Comments are good if used very sparingly to explain the non-obvious reasoning behind a code. Otherwise, they only serve to interrupt the reading flow and thus reduce code quality.
Both well-written code and well-placed comments have their place in software development, and they serve different purposes.
Well-written code is crucial because it's the foundation of any software. It should be clean, efficient, and follow established coding standards and conventions. Good code should be self-explanatory to some extent, meaning that another developer should be able to understand what the code does just by reading it. This is especially important in a team setting where multiple developers might be working on the same codebase.
However, even the best-written code can't always convey the "why" behind certain decisions. This is where comments come in. Comments can provide context, explain the reasoning behind a particular approach, or clarify complex sections of code. They can also be used to generate documentation, mark areas that need improvement, or provide information about known issues.
That being said, comments should be used judiciously. Over-commenting can clutter the code and make it harder to read. Comments that simply restate what the code is doing are usually unnecessary. Also, comments need to be maintained just like code. Outdated or incorrect comments can be misleading and cause confusion.
Imho the information about what a function does is exactly the thing I would not comment. The name of the function should be clear enough to state what it does.
However, often the context why a function does what it does is way more important for the next developer to understand, especially if he stumbles over that function half a year later (where you usually have no clue about this specific code).
Code says how or what; comments say why.
As a student learning how to write code for the first time, comments are invaluable! What might be easy to understand or self-explanatory to a seasoned programmer isn't for us newbies. Seeing others comments on unusual workarounds, quirks and in general more complex ideas is very appreciated!
Agree Agree Agree
well written code speaks for itself but comments are good communication tool for any other BS you want to add to your work
Code describes what to do. Comments describe why. And in some cases of beloved terse coding comments can explain what the magic syntax exploits to follow actually do 😉
People say code should be self documenting, but code says what it does, whereas comments say what it should do. If the two don't align then there is a bug.
Comments are good for code maintenance and helpful in code reviews too.
Well written code should be able to speak for itself. This is part of clean code.
The guy who wrote Clean Code is a charlatan who never proved to work on high performance, large-scale systems. Some of the stuff he advocates for is true while others are opinionated suggestions he treats as axioms although they were never proven to increase systems' quality.
If you're writing a complex system, you will have to do some complex work that will require comments. Open the source code for tcp in linux, for example; this is well written and it's full of comments: link.