3 ms·
On a long-lived codebase you're going to end up with nearly as many such comments as there are lines of code. Now that's a cluttered mess.
by Izkata 3y ago
On a long-lived codebase you're going to end up with nearly as many such comments as there are lines of code. Now that's a cluttered mess.
- mixmastamyk 3y agoWhen/how to comment is an art in itself, in no conflict to what I wrote. Either a short quip, doc string, or link to the full story is an accessible combo. Nothing is the correct choice for unsurprising code.
- Terr_ 3y agoWhile it's often said that comments should capture the "why" of code, I don't usually think that ought to extend to "cuz ticket#" except when that ticket number is an significant bug/limitation that explains a nasty hack. Noting each feature ticket that ever affected a line--or even just at the function level--is sort of like maintaining a few thousand incomplete micro-changelogs. Doing it "acceptably well" takes much more effort than grooming the commit history so that someone can click "show change history for selected lines" in their IDE. Plus consider all the unnecessary noise it makes for people reading the code, or reviewing a PR.
- mixmastamyk 3y agoNo, it's not difficult (cut/paste), nor a burden for reading in docstrings or even comments. The point is a short link that tells a long story, which should be accessible to non-developers.
- Izkata 3y agoAnd the commit message is an amazing place to put that.
- mixmastamyk 3y agoNot if you want them read by non-developers.
- Izkata 3y agoWhy would you have non-developers reading code?