3 ms·
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 doc
by twobyfour 9y ago
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.