Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Comment with a ticket-id would be more efficient.


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.


When/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.


While 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.


No, 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.


And the commit message is an amazing place to put that.


Not if you want them read by non-developers.


Why would you have non-developers reading code?




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: