Inline documentation, why I’m ditching it
I know this subject is controversial but I have to say it…
I started using JavaDoc-style documentation since FlashDevelop and FDT use it for code hinting and it used to help me a lot, but since nowadays I’m coding way more JavaScript and the editors I use don’t support JSDoc I don’t think it pays-off…
Inline Docs v.s. External Docs
Advantages of inline docs:
- reduce the chance of the documentation getting outdated (since you “remember” to update it while you edit the code).
- having typed annotations helps closure compiler to find errors while using “advanced settings”. (not that unit tests together with JSLint wouldn’t catch it)
Disadvantages of inline docs:
- too much “noise”, code gets harder to read, important comments are ignored (since there is no contrast).
- most JavaScript IDEs/editors don’t use JSDocs for code completion and/or error checking, making it almost useless during development.
- redundant in most cases since you already have access to the source code.
- discourage long descriptions and examples (most of the times it’s a single line description + arguments description which is usually not helpful)
- bad for translation
- usually not as flexible
- “nobody” reads inline documentation, only the output files.
I think JSDoc, ASDoc, Natural Docs, etc are “bad things” inherited from the Java school of thought… good in theory but s*cks in real life. Just compare this with this, there is no way to say that the one with inline docs is easier to read.. - Just by removing the noise I’ve noticed that code can be refactored to improve readability. Comments are usually a sign of poor/lazy/confusing implementations.
Conclusion
From now on I will avoid adding inline documentation to my projects, I will just create external files (mainly markdown) and educate myself to always update them after each change, maybe even create a tool to help the process – Edit (2011/11/28): I created a tool to convert markdown files into a structured documentation.
If the code is well structured, organized and the methods and parameters names are clear, there is no need for comments and/or documentation.
Good documentation consists of examples, clear explanation of the design, whys and hows. Make sure it’s easy to edit to foster contributions.
PS: DailyJS have a post about different documentation tools in case someone is interested… There is also a list of tools on the jswiki.