Why you shouldn't write comments
Posted by vegan_antitheist@reddit | learnprogramming | View on Reddit | 5 comments
The Java channel just posted this short:
https://www.youtube.com/shorts/q5EuaH5n65g
I think the reason why beginners write such useless comments is because tutorials use them to describe what the code does. But you should never do that in your own code. I rare situations you might use a commend to explain why it is like that.
Sometimes you describe a technical detail that is irrelevant for javadoc because you could just as well do something else to produce the correct result. You try to make it obvious but a quick note to why it was solved like this might be useful.
Sometimes it's just about something not being obvious.
For example if you do getFirst() on a stream and it's not obvious why the first element is the right one because sorting was done somewhere else. In that case you might want to explain that. And the method the generates the sequence must have a javadoc explaining the order that can be expected. But even better would be an assertions, where you check that it's really the expected item or that the order of the list if correct. Assertions are even more misunderstood than comments. They don't replace unit tests. They replace comments.
Whenever you want to write a comment, do this:
- Try to rewrite the code so it's easy to understand without a comment.
- Use javadoc instead of comments.
- Describe what the caller can expect from the method, not how it's implemented.
- In some cases you might even want to use a Java snippet. Did you know you can include real, compilable code in your javadoc? See: Programmer's Guide to Snippets
- Use assertions instead of comments.
mredding@reddit
Implementation is itself HOW. Expressiveness and abstraction are WHAT. Comments are WHY. Don't tell me what the code can tell me. Don't do what the language can do for you.
ProjectMarworyn@reddit
This is one of those beaten horses where any extreme is wrong. - Self commenting code is good - Sometimes comments are useful (on personal learning projects using them frequently can help a lot)
The real villian is the chronic lack of documentation of most production code bases.
desrtfx@reddit
I think that a beginner might need to use more comments, but everybody, as early as possible, should get into the habit of not documenting the obvious (what), but documenting why something has been done in a certain way.
Yet, unfortunately, educational institutions always lag behind in enforcing their students to document the obvious, leading to comment bloat.
Form long time experience, I generally dislike comments apart from documentation comments. Comments that explain the code are only technical debt and a visual distraction.
idiotiesystemique@reddit
Comments are to explain why something is done, not what is done.
BeginningOne8195@reddit
I think beginner comments are still useful while learning, but yeah long term the goal is definitely to write code that explains itself as much as possible.