undefined | Better HN

0 pointskazinator1y ago0 comments

That's a different kind of why not: about why we didn't do it in this seemingly obvious incorrect way, but had to do it in a more complicated correct way.

If that obvious incorrect way happens to match what you're thinking of doing, then that kind of why-not documentation will help.

Warning future developers not to make certain changes is indeed something that should go in a comment. We can make a short comment like, /* if you think you can rewrite this in a simpler way, read commit df037acb first */

There are unfortunate situations when things have to be changed in multiple places together; you must not forget all of them. That deserves comments.

If you have an enumeration that has to pack into 3 bits, there should be a comment warning not to add more elements than eight without increasing the number of bits; especially if there is no compile time assertion for it.

0 comments

thehappyfellow1y ago

I think I get it better now but I’m still not finding why keeping the whole comment in a commit message is better than in the source code. If it’s in source, I don’t need a context switch to read it, I can improve it (e.g. if the wording was ambiguous), I can easily extend it without asking people to read commits X, Y and Z in order.

What’s the advantage?

j / k navigate · click thread line to collapse