2011.03.09

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.

Related

Tags: , , ,
Comments (9)

Comments

Michael Mathews
2011-03-24 13:11:45

We're sorry to see you go, Miller. But, frankly, I can't argue with any of your listed reasons for dumping inline docs. (And I do agree that inline docs can be distracting when applied in large doses.) However I also can't argue with my reasons for creating JSDoc in the first place, namely that keeping documentation in separate files means they are more likely to get lost or out-of-date. Relying on pure discipline to enforce a rule that you write documentation in an external file could of course work in your case, but being a developer I naturally want to write a tool to help with that. If you do decide to work on something like that yourself, and would like a partner to help with the work, please let me know.

Miller Medeiros
2011-03-29 12:17:24

JSDoc Toolkit is an awesome tool and I've been using it for most of my projects on the past couple years but lately I just got tired of the extra effort since in my case I don't think the benefits of inline docs pay-off that much. Keep the good work. Cheers.

Graham Lyons
2011-05-03 06:46:24

I'd certainly agree that often trying to read code with inline documentation is a real chore but personally I find this version more useful: https://gist.github.com/863421/bd9e0d8e37a7e62615193bda48e50c4cd2c09bb9

Just looking at the constructor I can see which of the arguments are functions, objects, numbers etc without having to look for them in the code below. Quite subjective of course but that was my first thought on looking at this example.

TJ Holowaychuk
2011-11-28 16:40:41

I agree that you shouldn't have massive inline docs, but they aid contributions and hell they even remind myself things when I'm back in my own code. Projects like node are brutal for this, when you want to contribute almost none of the code makes sense since the vast majority of it is undocumented from a contributor stand-point, "oh we did this hear because of this limitation", "this is faster so we're doing it this way" blah blah

Node Roundup: 0.6.5, NodeUp, Logme, Consolidate.js, mdoc, Firmata, Nodeflakes
2011-12-14 20:17:41

[...] rather than JSDoc-style API documentation. Miller wrote a post about this topic called Inline Documentation: Why I’m Ditching it.FirmataFirmata (GitHub: jgautier / firmata, License: MIT, npm: firmata) by Julian Gautier is a [...]

A'braham Barakhyahu
2012-02-16 19:31:50

I wonder if you could split the difference and have something that will take your commented file and provide a narrative version (like docco) and a version without the comments. I can see where comments can get in the way if they don't provide more insight to the code, than your mastery of language and patterns.

A'braham Barakhyahu
2012-02-16 19:34:45

Disregard my last comment. This is about inline documentation and not comments. I'm tired. :(

The Merits of Inline Documentation « The Blog
2012-03-20 21:14:36

[...] read the reasons from Miller Medeiros, the creator of mdoc, on why he is ditching inline documentation, and I’m not convinced. Let me amend his lists of advantages and [...]

Eduardo de Matos
2013-01-26 13:28:10

Inline documentation is not meant to be read inline, it's meant to be converted into a real documentation app.

Take a look at ExtJS documentation (navigate through components), it's amazing how good it is, and everything is generated from source code using JSDuck.