Comment on Always write comments

<- View Parent
NotAnonymousAtAll@feddit.de ⁨1⁩ ⁨year⁩ ago

it’s really useful to comment functions/methods, because otherwise you never know if something’s a bug or a non-obvious feature. Comments act as a parity check to the code, since they tell you what the dev who wrote the code wanted the code to do.

Unit tests should be the parity check for other code. Those don’t get outdated with the next refactoring where someone didn’t remember to also adjust all the comments.

Also, everone thinks they write good, clean and obvious code. Hardly anyone purpously writes bad, hacky code. Yet if you look at code you wrote a year ago, or code someone else on your team wrote, it’s full of non-obvious hacks. That means, people constantly misjudge the obviousnes of their code. Comments should be put on anything that could maybe be non-obvious.

Why would people be better at judging if something needs a comment than at judging if something needs a better name or refactoring? Asking people to skip that judgement step and comment everything just gives you a bunch of useless boilerplate comments. That trains everyone reading that codebase to ignore comments because they are almost always useless anyway.

putting documentation of the code anywhere else than in a comment (e.g. Confluence) is a total waste of time

At least this we can 100 % agree on. Documentation should be a as close as possible to the code. (I just think most of the time that place is in the name of things, not in an actual comment.)

source
Sort:hotnewtop