JavaScript Documentation Recommendations

March 19, 2009

For the project I’m currently working on, here are some best practices I’m using for JavaScript documentation:

  • Use YUI Doc syntax. Even if I never actually run YUI Doc, it’s a standardized comment format.
  • At the top of every JS source file, put a multi-line comment, with the first line starting with the source file name. I combine my JS files in the build process, so this allows me to easily find out which source file a particular line of code is from. I even add these headers to JS library files I use.
  • In that file header comment, add an @global directive that lists all the global variables the file creates. Ideally, each of your files would correspond to an @module, and you wouldn’t create any global variables other than classes in that module; and any instances you create would be inside anonymous closures. But some JS libraries you use may create global variables (DWR, for example), and it’s helpful to document the variables they create.