CHAPTER 2 Writing Maintainable, Future-Friendly Code
Design Document
Design documents describe the architecture and options available within
some piece of software. It is frequently written before coding begins and
updated once coding is complete. Design documents answer the question,
“How does this work?” It’s quite common to see diagrams as well as discus-
sions around design philosophy, design patterns used, and assumptions
the software makes. Chromium, the open-source project on which Google
Chrome and Opera are based, has an excellent set of design documents^15.
When you inherit some code that you must begin to maintain, the design
document for that code should be the first place you go to get a good under-
standing of the code.
In general, getting started guides and tutorials are necessary when
you’re creating a library for others to use. API documentation and design
documents are good regardless of the software you’re writing. The exact
structure of these documents necessarily varies based on the software
you’re creating and the intended audience.
API documentation is the minimum that a project should have for
documentation. Most languages, including JavaScript and CSS, have tools
for generating documentation from the source code. These documentation
generators use comments embedded within the code to create standalone
documentation (typically in HTML format) describing the code. The exact
comment style depends on the tool being used. Here are some tools worth
investigating:- JSDoc^16 : the original JavaScript documentation generator. It uses
JavaDoc-style comments to create API documentation. - YUIDoc^17 : a JavaScript documentation generator from the YUI team.
It also uses JavaDoc-style comments to create API documentation.
15 http://www.chromium.org/developers/design-documents
16 http://usejsdoc.org
17 http://yuilibrary.com/projects/yuidoc