this post was submitted on 12 Dec 2023
799 points (99.0% liked)
Programmer Humor
19480 readers
577 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 1 year ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
P1000x this.
I can read a diff.
I need to know why.
No, a code comment isn't good enough, it's out of date after the next commit.
Code comments for "why"s that persist. Commits for why's that are temporary.
If you need to run X before Y, add a comment. If you added X before why because it was easier, leave it in a commit
Add a test that asserts that.
With a comment on the test detailing why it matters so people don't just assume the test is out of date when it fails.
And ideally test the underlying result of x before y, not the fact that x is called before y.
And while we're at it, assert in Y that X has been called, and again comment the reason for the preconditions.