DEV Community

Cover image for Do Code Comments Deserve a Special Spot or Can Well-Written Code Speak for Itself? staff for The DEV Team

Posted on

Do Code Comments Deserve a Special Spot or Can Well-Written Code Speak for Itself?

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!

Image by pch.vector on Freepik

Top comments (19)

vsaulis profile image
Vladas Saulis • Edited

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.

bradtaniguchi profile image

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.

fyodorio profile image

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.

ephilips profile image
Eesaa Philips

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.

ephilips profile image
Eesaa Philips

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.

michalispapamichael profile image
Michalis Papamichael

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.

wizdomtek profile image
Christopher Glikpo ⭐

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.

pauljlucas profile image
Paul J. Lucas

Code says how or what; comments say why.

lexlohr profile image
Alex Lohr

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.

velydev profile image

Probably the most important comment you can make is to first state what the unit of code does, or what it's supposed to do. For instance, if you write a function, state what is its purpose and how it interacts with the rest of the application.

That may sound obvious, but I've seen so much code where the author explains how the code works, even down to minutia, but there's barely any mention of what it does, if any at all. Once you know what the code is supposed to do, then it's much easier to follow its internal mechanics.

eddykaya profile image
Eddy Bobbin

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).

octofoxx profile image

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!

bridgesgap profile image

Agree Agree Agree

thumbone profile image
Bernd Wechner

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 😉

namenotavilable profile image
Adam Markiewicz

well written code speaks for itself but comments are good communication tool for any other BS you want to add to your work

richardcrawshaw profile image
Richard Crawshaw

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.

developerwithout profile image
Joshua Dix

Well written code should be able to speak for itself. This is part of clean code.

ephilips profile image
Eesaa Philips

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.

timothymwine profile image

Comments are good for code maintenance and helpful in code reviews too.