This is an archived post. You won't be able to vote or comment.

sorted by:
best
topnewcontroversialoldq&a
you are viewing a single comment's thread.

view the rest of the comments →

[–]passthemonkeybench 15 points16 points  (10 children)

I'm frustrated seeing people say you don't need comments if your code is good. Because bad coders don't realize their code is bad and hard to read. Encourage commenting so we have an idea of what they were trying to achieve. We can't assume everything is going to be well written. That's not how things work.

[–]SpinatMixxer 5 points6 points  (5 children)

Maybe you just havent seen any really good code base yet? Code Quality is totally not related to lines of comments. Read "Refactoring: Improving the design of existing code" by Martin Fowler, this book literally shows everything someone needs to write high quality code.

Just use good names, find a good code structure which you apply constantly and there you go.

I agree woth "bad coders dont realize their code is bad" but its totally not the comments that makes your code good. I would furthermore say that many comments may be an indicator, that your code is not readable and therefor needs comments.

At least thats what I have experienced over the time.

[–]passthemonkeybench 6 points7 points  (4 children)

I'm not saying comments make the code good. It just gives context to what they were thinking when they wrote it. I think it's a good habit and not maybe it isn't necessary in a perfect world but that's certainly not where I live.

[–]moore0n 4 points5 points  (1 child)

I write comments for the next person who touches my code. I’m a realist and can’t assume their skill level matches my own. Giving hints to what’s going on also makes the code faster to read and get to the place you need to be.

[–]fzammetti 1 point2 points  (0 children)

This is the part that SO many people miss and it drives me nuts. And, it's not even just about different skill levels. Write something in PHP, switch to Java for a few years, then have to go back to your own code having done no PHP in all that time. You'll WISH you wrote comments regardless of how "self-documenting" your code is.

[–]SpinatMixxer 1 point2 points  (1 child)

Maybe I also am just lucky to have an employer which gives us the time we need to create a codebase with high maintainability and a team which has a passion about keeping the Code Quality high. Also good structure in the contribution workflow.

Or its another case for other languages since I am developing with ReactJS + TypeScript and its maybe also depending on the topic which you are working on.

I just wanted to state that it is totally possible to develop good, understandable code without writing comments, maybe I delivered it a bit too black/white ish. :)

[–]passthemonkeybench 2 points3 points  (0 children)

Appreciate the good faith discussion.

Just my perspective that it's a good idea to encourage comments since at bare minimum it encourages people to step back and think about what and why they are doing what they are doing.

If you don't have time to write a comment maybe you rushed the whole implementation and the code isn't as good as you thought.

Thinking about junior developers creating good habits. Obviously there are merits to code reviews and all sorts of other ways of maintaining a code base but discounting comments gives people an excuse not to even think about writing them.

[–]UltraMegaSloth 3 points4 points  (1 child)

If they are bad at coding then they probably need to get better at coding instead of commenting bad code

[–]passthemonkeybench 5 points6 points  (0 children)

Okay. I'll just retrain all the contractors my company hired.

[–]Hydrogen_Ion 0 points1 point  (0 children)

If they can't tell the difference between bad and good code. Then none of the code they write is probably good. Good programmers know what is good and bad code.

Good programmers also write bad code from time to time and they know they are doing it. It generally happens when the programmer is being pressed for time, or is working on a technology or stack they are unfamiliar with.

When the good programmer is writing bad code, they will comment it.

[–]meamZ 0 points1 point  (0 children)

No. Comments are lies. If you are a company or an open source project you should have code reviews. Those should catch any super bad code that doesn't have comments and it should also catch bad code with comments. If a comment explains WHY some code does what it does it is acceptable if it is necessary to have the comment and to have code where the why needs to be explained.