News for hackers. Stuff that matters.
Re:Best practices for writing code comments by furstenheim on Friday December 24, 2021 @01:57PM (#29676591)
I miss the most important one. Explain business reasons.

Code does what it's written for. But it does not explain intent. Write that on a comment, link to the relevant ticket and document

Re:Best practices for writing code comments by xixixao on Friday December 24, 2021 @03:41PM (#29677531)
This is what source control blame is for. It’s very hard to estimate what business reasons will be important to readers of code in the future.

I very often nudge people to remove their comments entirely. Less experienced devs often write comments to explain code, instead of spending time on making the code itself readable/understandable. I often ask: “Can you modify the code such that the comment will become obsolete?”

Re:Best practices for writing code comments by ijidak on Friday December 24, 2021 @05:02PM (#29678199)
Hard disagree with this.

Yes, code should be easy to understand.

But well-written comments that explain assumptions and intent helps as code evolves over time.

Also, comments are quicker to scan than code itself.

A good comment can indicate code that can be ignored for the purposes of certain troubleshooting.

Finally, junior developers usually write code that is difficult to understand and don't comment.

I've rarely ever seen a junior developer that both writes unreadable code and takes the time to write comments.

Usually comments are a sign of seniority, someone who has pity on those who will come after him/her.

And thus that person tends to also write understandable code.

Perhaps there's an uncanny valley in between where comments are a band-aid for complexity, but I have never observed that in years of working with many developers.

Re:Best practices for writing code comments by rmbyrro on Friday December 24, 2021 @04:44PM (#29678036)
Exactly, it's better to document on the VCS.

Comments there will be tied to that version of the code, can never go out of sync.

It's also good to learn how that piece of code evolved and what reasons to change. Avoids repeating past mistakes.

Re:Best practices for writing code comments by dorwi on Friday December 24, 2021 @02:41PM (#29677029)
Oh no, never link to tickets or docs that are not version controled in the same repo. Usually code tends to outlive the tools for organisation.
Re:Best practices for writing code comments by usr1106 on Friday December 24, 2021 @02:54PM (#29677135)
So should we live in darkness now because the link might break 3, 5 or 10 years later?

It's also a misguided tools upgrade if they have no way to redirect, convert or otherwise handle old links.

Re:Best practices for writing code comments by pc86 on Friday December 24, 2021 @05:45PM (#29678502)
Link to things in the same repo, like a wiki or external document (if you're linking to external stuff anyway). You have to assume whatever you link to will disappear without notification. At least if it's in the repo, you can check out the old commit and get the file back, and hopefully find the commit where it was removed and see why it was removed.

If you link to Sharepoint or something it's useless as soon as that link changes.

Re:Best practices for writing code comments by LordDragonfang on Friday December 24, 2021 @03:45PM (#29677568)
In my experience, then, most tools upgrades are misguided.
Re:Best practices for writing code comments by worik on Saturday December 25, 2021 @04:58AM (#29681914)
No we should live in light!

But make the boss understand...

Re:Best practices for writing code comments by furstenheim on Friday December 24, 2021 @03:29PM (#29677421)
But even if the link eventually dies, you have the business explanation.

Normally the comment is an explanation of the intent but the referenced ticket has the full discussion and backing data that led to the decision

Re:Best practices for writing code comments by skrtskrt on Friday December 24, 2021 @04:02PM (#29677702)
I always say more generally “explain the why”, business OR technical reasons.

Bigger architecture decisions should go in ADRs (again, explain the why) but smaller stuff like explaining why you monkeypatched a library can save future devs a lot of lost investigation time and pain. Maybe by the time they are reading your comment/code, the patch you wrote is supported in the main library!