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

3 points by octo-andrero 1 year ago | 8 comments

Hey guys! There's a statement that good code is self-explanatory, still there's a ton of articles in the web describing the importance of documentation. What makes you to write documentation (if you was not asked by the "manager") and what are benefits that you gain as a developer when codebase is well documented?

kayo_20211030 1 year ago |

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.

austin-cheney 1 year ago |

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.

octo-andrero 1 year ago | |

Could you share any examples of interactive documentation or tools to build interactive documentations? The only thing comes to my mind is Swagger / OpenAPI documentation pages from Spring that allows you to send the request.

austin-cheney 1 year ago | | |

* A terminal command just for displaying documentation on all other supported terminal commands by the application. Then more detailed documentation for each specific command with examples. Finally, a validation engine that allows per character validation of terminal input, as in a REPL.

* Similar input characteristics for a web-based interface.

* Documentation search function and/or auto-complete

kenha 1 year ago |

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.

beardyw 1 year ago |

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?

JohnFen 1 year ago |

> 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.