By Nicholas Zakas CHAPTER 2- Docco^18 : a JavaScript narrative documentation generator. Instead
of creating API documentation, this tool creates a narrative where
the description of the code shows up on the left and the actual code
shows up on the right. - KSS^19 : a CSS style guide generator. Extracts comments inside of CSS,
SCSS or LESS files and generates a style guide with example output.
There are documentation generators for almost any language you
would use to build a Web application. Research them, learn them and use
them. The best way to ensure good comments in code is knowing they’ll
end up in actual documentation. I’ve seen this happen several times: as
soon as documentation starts getting generated and the result is available
for all to see, more time is spent crafting the comments that show up.
There is no such thing as too much documentation for code, but there
is such a thing as too little. The best way to encourage documentation
writing is to make it part of the feature deliverable. A feature should not be
considered complete until adequate documentation is written and placed
in the appropriate location. Requiring a design document before coding
starts also helps keep documentation at the front of everyone’s minds. Re-
gardless of how you decide to set it up, documentation needs to be part of
the deliverable whenever code is written. The exact type of documentation
will depend on the type of code, but all code needs documentation, even if
it’s just the addition of one sentence to an existing document.
Having some good coding style guides, a well-defined architecture, and
generous amounts of documentation sets up any project for success. The
truly challenging part comes when you want to include code that wasn’t
written by your team, and having guidelines for how to do that is import-
ant for the overall health of your application.
18 http://jashkenas.github.io/docco/
19 http://warpspire.com/kss/styleguides