Item — HN Reader

Documentation has a cost, and a risk. It must be maintained when the code changes, if not one deceives future developers and increase the chance of bugs. Ideally the code itself should be documentation enough; keep code comments for complex parts of the code which are not obvious -- these comments then stand-out because they are rare.

The only place where you should document the obvious is in the public API, so I'd say the existing team are probably on the right path. Sorry :-)

1 comments

Thanks! Yes, I hear the same from them and I try to consider this approach :)

It is an additional effort, for sure. It is not without its benefits, though, and I'm trying to find out if it's worth it.

Why I originally brought this up with them is because I started working on a feature and found the code barely comprehensible. I spent a lot of time to try to keep everything in my head and failing repeatedly and felt like documentation would have helped me a lot. I.e. I was exactly in the position of a new external contributor and found the experience lacking.