3 ms·

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

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

dorwi 5y ago
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.
- usr1106 5y ago
  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.
  - LordDragonfang 5y ago
    In my experience, then, most tools upgrades are misguided.
  - pc86 5y ago
    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.
  - worik 5y ago
    No we should live in light! But make the boss understand...
- furstenheim 5y ago
  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
xixixao 5y ago
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?”
- rmbyrro 5y ago
  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.
- ijidak 5y ago
  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.
skrtskrt 5y ago
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!

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

dorwi 5y ago

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.

usr1106 5y ago
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.
- LordDragonfang 5y ago
  In my experience, then, most tools upgrades are misguided.
- pc86 5y ago
  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.
- worik 5y ago
  No we should live in light! But make the boss understand...
furstenheim 5y ago
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

xixixao 5y ago

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?”

rmbyrro 5y ago
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.
ijidak 5y ago
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.

skrtskrt 5y ago

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!