Document Your Software Project

摘要

Software projects are growing in complexity. We're expected to get more done in less time than we did last year. It's vital to come up to speed quickly on any given body of code, whether it's a new third-party library or a neglected legacy subsystem. Many projects lean on API documents that have been automatically extracted from source code comments. Other teams churn out elaborate diagrams that explain every detail of the architecture. While these can both be helpful as a reference, they do little to answer the basic questions about the code: What's this for? What file should I look in first? What's this project's equivalent of a "Hello world!" program? In this paper, we'll use the metaphor of a magazine article to think about the ways you can help anyone come up to speed with a code base, whether it's a new hire today or you, five years from now. Getting the emphasis and level of detail right are crucial. Everything else, especially the specific choice of tools, is secondary. Even so, we'll spend some time looking at a couple of open-source software packages that may be of help.