if you are working with coworkers who are doing such slipshod work as to not change a comment two lines away from their modification, and the code review practices you have in place are not adequate to catch such a thing getting merged in, there are no guidelines that will help you, sorry
deleted by creator
I mean, I get how this is how I might not think to keep it up to date–but I would never submit a pull request or approve one without checking this kind of thing. The balance of requiring effort from the writers, maintainers, and readers of code is always in flux, it’s true. But if you’re building something big enough that people working on it can forget how a part works, you need comments, and you need them to be good, and, moreover, the kind of people who don’t care about keeping comments up to date are not going to be keeping method names / abstractions up to date either.
deleted by creator
I was recently in a project where they had a git hook to enforce that every method, class and module has a documentation comment.
So, even a method Db.init() had to have a comment “Initializes the DB.”.As a result, the quality of those comments in general was awful. If you have to fill in 20 documentation comments, you’re not going to go into huge detail, even when in some places a description might actually make sense.
And then as a result of that, 95% of comments were not worth reading, which meant no one read them, which meant no one fixed them or complained about them being bad in code reviews.
It was basically just wasted time, that we had to fill those comments in.
My rule is comments should:
- summarise what something does, or
- explain why something is the way it is If it’s not a summary or a why then it’s not adding value
A continual sine-wave of articles telling us to comment our code, then delete it.
This is why we still need comments.
deleted by creator
deleted by creator
in which an internet-using agent whose credibility is a random variable throws yet another hot take on top of the gargantuan pile, and then fails to engage with any reader feedback.
extra credit:
- are docstrings comments?
- what would Knuth do?
The ideal number of comments is zero. It was hard to write, it should be hard to read.
