I know this subject is controversial but I have to say it…
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).
- 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.
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 – .
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.