
Ask HN: How well documented are the codebases you work on? - el_benhameen
I&#x27;m playing code detective today, and it got me wondering how common good documentation really is.
======
twobyfour
Usually very nearly zero.

The primary codebase I currently work on is typical. When I arrived here, the
only documentation we had was a sorely out of date document about how to get a
working copy running on an OS used by only a fifth of our developers, plus the
very occasional inline comment.

We now have:

\- Up to date instructions on installation on the most common development
platform

\- A couple documents about some of the more confusing corners of our codebase

\- A test suite with perhaps 20% coverage, which serves as documentation of
intended behavior

\- More inline comments than before

\- More Python doc strings than before - not API docs so much as "purpose of
this function" docs.

I would guess that about 5% of our code is commented. A bit more might not
hurt. We're never going to go in and backfill commentary for half a million
lines of code, but I'd like the team to get more into the habit of adding it
as they go along.

I find standalone documentation to be more trouble than it's worth for small
teams. It gets out of date too quickly, and nobody has time to keep it up.
What's more valuable is documentation for frameworks and libraries. We rely on
a handful of major open source libraries as well as SDKs for vendors, and we
have a very strong preference for those with good docs.

