• 0 Posts
  • 10 Comments
Joined 1 year ago
cake
Cake day: July 11th, 2023

help-circle








  • 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 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.)


  • About comments:

    Please please please, do not always write comments. Try to write code that does not need comments whenever possible. Proper variable, class and method names go a long way. If you think a block of code needs a comment, turn it into a method and give it a proper name instead.

    Comments should be a last resort for cases where making the code self explanatory is not possible, and those should be rare.

    About optimization:

    Optimal code is code that fulfills it’s purpose without observable issues.

    If you try to make something faster without any prior complaints or measurements indicating that it being slow is an actual issue, you are not optimizing, you are just engaging in mental masturbation.