Do all the things like ++ or -- rants, post your own rants, comment on others' rants and build your customized dev avatarSign Up
Voxera617414dPersonally 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.
Fast-Nop1407214dI 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.
Ederbit62013d"temporary" workarounds sounds like an excuse to me. These things tend to stick around forever
@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?
Take a quick quiz from Triplebyte to skip the job search hassles and jump to final interviews at hot tech firms
Get a Better Job