JavaScript Documentation Recommendations

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.
Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: