Hacker News new | ask | show | jobs
by nailer 1407 days ago
> why certain decisions were made; basically explaining anything which would raise an eyebrow.

Yes!

This is what comments (and READMEs etc) are for. Not explaining the what, ie how your programming language works (unless you're doing something most engineers wouldn't know). But explaining why they were made.

  // Workaround for https://github.com/org/project/issues/263
1 comments
jrochkind1 1407 days ago
In the contemporary world with git online, often in github, where you can put an actual URL to an Issue, PR, or commit in a comment in sourcecode -- it's SO valuable.

I think this is actually one of the under-rated most valuable aspects of github (and probably other similar systems), things it's changed the most -- that everything has a URI that can be linked to, including in code comments. And a reason I could never deal with "just git and email patches" without a web UI that gives everything a URI that can be linked to from text.

I especially like leaving links to issues in third-party open source dependencies. If someone comes along later and wants to change the thing that was a workaround to a bug -- they are easily started on the trail to figure out if the bug has been fixed, in what version of the dependency, etc.

link