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.

[–] Zagorath@aussie.zone 5 points 11 months ago (1 children)

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 4 points 11 months ago (1 children)

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 2 points 11 months ago

There’s nothing limiting what a comment should be as far as I know.

Nothing technical, sure. Just good coding practices.

[–] Fal@yiffit.net 2 points 11 months ago

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