Hacker News new | ask | show | jobs
by cr3ative 1411 days ago
Absolutely, and there's a common thread in them: context. When I'm preparing to hand a project over, the README will be updated with design constraints (maybe even the RFC/project launch documents), why certain decisions were made; basically explaining anything which would raise an eyebrow.

I do this because I received a project with this note, and it stuck with me as an excellent idea; a letter to future explorers.
2 comments
nailer 1411 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
link
jrochkind1 1411 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
physicles 1411 days ago
I have a giant doc called rude-qa.md that has a bunch of questions an opinionated new hire (dev or manager) might ask about our architecture, followed by a brutally honest “here’s why we did it this way”. Often the answer is something along the lines of “I didn’t have enough experience designing systems back then. We could switch now but the cost is high and there’s not much benefit”. Humility is key. It really helps clarify my own thinking too.
link