5 ms·

I have never cursed an author for having too many comments. There are many cursed developers out there after my long career.

by bregma 5y ago

teknopaul 5y ago
You never lived through auto-javadoc?
- etripe 5y ago
  Ah, the awesome flavour of Markov chain nonsense that is auto-generated docs. I think the existence of this phenomenon shows the danger of strictly adhering to policy that was written by someone who never suffers its effects.
GuB-42 5y ago
I have. And stripping comments before working on it is a thing I have done many times, on code I wasn't familiar with. The biggest problem is lies. If you don't update your comments, don't write them. If you know someone less careful than you is going to take over and not update your comments, don't write them either. And then, there are the redundant comments, the ones I see most often. For example - Don't describe the function both in the header and source code, it is a useless copy-paste that will never be updated correctly. (mostly for C/C++) - I know the syntax for declaring a constructor, thank you, you don't need to tell me that is is a constructor in the comments. And I can also guess that getX() gives me the value of X, no need to fill my screen with dozens of useless lines of comment. - I don't need a comment to know who did what. We are under source control and we have a "blame" command. - Don't use comments to disable code. Just delete it, it is not lost, we have history, and we are unlikely to need it anyways. But the one that makes me rage the most is something like "int time; // the time". Not only it is useless, but you are not giving the info I want: the fucking unit! I've seen it way too often, sometimes with far from obvious units, like tens of microseconds. So if you want to put a comment, at least tell us the unit. Or better yet, don't comment anything and make your variable something like time_in_ms, or define a type.

I have never cursed an author for having too many comments. There are many cursed developers out there after my long career.

by bregma 5y ago

I have never cursed an author for having too many comments. There are many cursed developers out there after my long career.

teknopaul 5y ago

You never lived through auto-javadoc?

etripe 5y ago
Ah, the awesome flavour of Markov chain nonsense that is auto-generated docs. I think the existence of this phenomenon shows the danger of strictly adhering to policy that was written by someone who never suffers its effects.

GuB-42 5y ago

I have. And stripping comments before working on it is a thing I have done many times, on code I wasn't familiar with. The biggest problem is lies. If you don't update your comments, don't write them. If you know someone less careful than you is going to take over and not update your comments, don't write them either. And then, there are the redundant comments, the ones I see most often. For example - Don't describe the function both in the header and source code, it is a useless copy-paste that will never be updated correctly. (mostly for C/C++) - I know the syntax for declaring a constructor, thank you, you don't need to tell me that is is a constructor in the comments. And I can also guess that getX() gives me the value of X, no need to fill my screen with dozens of useless lines of comment. - I don't need a comment to know who did what. We are under source control and we have a "blame" command. - Don't use comments to disable code. Just delete it, it is not lost, we have history, and we are unlikely to need it anyways. But the one that makes me rage the most is something like "int time; // the time". Not only it is useless, but you are not giving the info I want: the fucking unit! I've seen it way too often, sometimes with far from obvious units, like tens of microseconds. So if you want to put a comment, at least tell us the unit. Or better yet, don't comment anything and make your variable something like time_in_ms, or define a type.