Ask HN: Code documentation is all right? | Hacker News Reader

Ask HN: Code documentation is all right?

3 pointsplvch1 comment

Currently researching the question with very limited industry experience myself and wonder: does everything ok here?

Complete and clear documentation of large legacy codebase is how common exactly in your experience?

Did API-documentation tools in the era of microservices aka Swagger/Postman/etc. eliminated the question completely?

My priors: - Clear documentation on high-level decisions and architecture is a good guide - Well docs on particular piece of code / service saves ton of time for other person to work with - to update or debug. - It's actually more probable in your company/team that code won't be documented on level considered "good" - The trickiest truth: it's rather boring to create and maintain documentation yourself and rarely rewarded career-wise, even inside one team.

So: lots of newbees to the industry (see-me) won't have a knowledge of those processes from college; likely won't see them implemented in their team/org; likely won't see any career benefits from implementing the process as it won't seem great at perf review. Cycle ends here.

What am I missing in the view here?

Getting people to maintain documentation is hard.

For me there's two distinct areas of documentation, code level and business level.

Business level documentation is about the higher level logic and processes, and something that I don't regularly see being done well. You'll quite often find that decisions were made in meetings and, while it was minuted, no one can find the minutes when they're needed (or worse they can find conflicting decisions made at different meetings).

Code level documentation is about the actual code base and certainly takes a bit of work and commitment from a team to keep up to date. It's very easy for code to slowly slip away from the documentation, which will cause confusion when working with the code in the future. Worst case you can always look at the code to figure out what it's doing, comments may attempt to tell you why it's doing something, but you can't trust them 100%.

One thing I like about OpenAPI/Swagger is that you can actually get your microservices to use them so it knows what APIs it has, what parameters they require and what the criteria is for those parameters. By actually using the API definition in that way you can make sure that your APIs and their parameters have to be documented and up to date (at least to from the point of view of methods, endpoints and parameters and their validation criteria).

Reply on news.ycombinator.com