20

I (don't) like how some people say "If your code needs comments, your code is probably ugly and should be rewritten".
Well, asshats. You have never considered complex calculations/functions or "temporary" workarounds, right?
Sometimes, you have to do it in a not-very-readable way for efficiency. There is no way around that in that case, and comments that either explain the code below or provide alternative, slower code that's commented really help others understand your code.
If I ever work with you and you don't bother commenting your code at all (or rather use slow code because more efficient code doesn't appeal to your "muh code dun need comments" approach), I will hate you.

Comments
  • 8
    Personally I see comments as a last resort.

    As you say, if its very non intuitive but offers some very good benefit I some time use comments to prevent others from breaking it.

    Also if there are external considerations that just are not possible to visualize in the code.

    But as far as possible I try to break things out into methods.

    The compiler will inline such code anyway in almost all cases and you could even add compiler directives to ensure it.

    The main benefit is I get an extra scope for name.

    In c# I can also use regions in a similar way.

    And if I still have to I try to use a method annotation as its also used in intellisense and just before the method. Less risk that a merge suddenly injects something in between a comment and the code.

    The danger with comments is that after a while they might lie and that can be harmful to future development.

    Especially merging have wrecked havoc on some comments so they are best kept in code that are unlikely to be changed.
  • 0
    I agree.
  • 7
    I like comments that explain what the purpose of some code is in case this isn't obvious. This is especially necessary when the code has no obvious relationship to the problem domain, or when the problem domain itself is complicated, or when the code relies on non-obvious properties either of the problem domain or of previous data treatment in other code parts.

    Or with close to the metal stuff, it's even good to just say what the code is doing to spare the reader going through the reference manuals of the chips or the PCB schematics.
  • 2
    "temporary" workarounds sounds like an excuse to me. These things tend to stick around forever
  • 1
    @Ederbit which is why I put "temporary" in quotes. The argument for not commenting this is "uh but I'll change it tomorrow pinky promise :)", and then it sticks around forever, the original author left and someone has to change something in a hacky mess without knowing what it does.
Your Job Suck?
Get a Better Job
Add Comment