287
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
this post was submitted on 27 Nov 2023
287 points (92.1% liked)
Programmer Humor
33160 readers
540 users here now
Welcome to Programmer Humor!
This is a place where you can post jokes, memes, humor, etc. related to programming!
For sharing awful code theres also Programming Horror.
Rules
- Keep content in english
- No advertisements
- Posts must be related to programming or programmer topics
founded 3 years ago
MODERATORS
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.
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.
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.
Nothing technical, sure. Just good coding practices.
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