Ask HN: What is your personal motivation for documenting code?

In large personal projects I try to be thorough in my documentation and naming conventions it helps me to write more durable software. When I am on my own time I prefer to keep my software as durable as possible because I am not being paid a salary to qualify all the extra time spent on regression, defects, and reviewing prior decisions. I would rather spend this personal time on design decisions instead, and central to the corresponding planning processes is well written documentation. It also helps when the documentation is itself interactive.

You are scaling yourself - So you have more time to focus on tasks that matter.

Rather than answering the same questions repeatedly, you can point other teammates to your doc.

It’s also not just a one time thing - Once the docs started gaining traction, you will see your teammates contributing. It takes time to get there, but it will get better over time, and it’s worth it.

Downside 1. Docs can get outdated - There will be times you need to go and refactor the docs. 2. You won’t get promoted because you wrote good docs.

If the documentation is in the code, it's a helpful way for me to remember what I did, and why - so I do it. Although naming is super important, I've found that what I consider to be an obvious name can be perplexing or even confusing to others. Extensive inline documentation really helps here. It's more conversational, you can put in some extra relevant information, even present context and examples. It helps both me, a future me (important), and some poor anonymous future developer responsible for making changes better understand what's going on. This style is also grep-able and amenable to dev tooling intervention. If the documentation is independent of the code, there are some challenges. "non-attached" documentation is notoriously difficult to maintain. Even with the best will in the world it atrophies over time, becomes unreliable, even contradictory of the code itself. This style of documentation works best for top-level designs, where it's not expected that many future edits are required; and where there is a manager or curator who's willing to pound the table to ensure its maintenance.

> There's a statement that good code is self-explanatory

Yeah, and that's a statement that has never been true except in trivial cases. Comments and documentation tell the "why", and comments provide additional clarity. Good code tells the "what".

The reason I document boils down to the old saw: be kind to the developer who has to touch the code in the future, particularly because that developer will probably be you.

For whoever comes after me, or just me sometimes. Good code is self documenting but often the broader intention is not. If I look at code my first question isn't what, it's why?