There’s nothing keeping the comments up to date with the code. Comments should be sparse and only on sections that aren’t obvious why they’re being done
SpeakinTelnet@programming.dev 11 months ago
I don’t care how much you think your code is readable, plain text comments are readable by everyone no matter the proficiency in the programming language used. That alone can make a huge difference when you’re just trying to understand how someone handled a situation.
Fal@yiffit.net 11 months ago
Zagorath@aussie.zone 11 months ago
Comments explain why, not what. Any comments that explain what a section of code is doing would probably be better off as separated methods.
Apart from basic documentation comments, like JavaDoc or C#'s XML documentation comments.
SpeakinTelnet@programming.dev 11 months ago
There’s nothing limiting what a comment should be as far as I know.
As an example of what I mean, I’ve seen in a 10k+ lines python code a few lines of bit manipulation. There was a comment explaining what those lines did and why. They didn’t expect everyone to be proficient in bit manipulation but it made it so that anyone could understand anyway.
Zagorath@aussie.zone 11 months ago
Nothing technical, sure. Just good coding practices.