The merits of inline documentation

2012 March 21

I 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 disadvantages.

Advantages

  • Documentation is less likely to become outdated because it is edited alongside the source. Agreed.
  • Typed annotations are useful with tools like the Closure compiler. True, but I don't know if these tools are popular enough to motivate inline documentation (I don't use them).
  • DRYness. Whatever documentation you can lift from the source is documentation you don't need to write and maintain separately. This especially applies to associating documentation with its section of source code.

Disadvantages

  • There is too much noise; code is harder to read. This is mostly subjective, and I don't relate. In your editor, fold the sections of comments you find distracting, as you would do with any other text.
  • Important comments are lost in the crowd. This may be, but I think developers will (or at least should) read the generated documentation before they read the source, meaning they've already seen the comments that are drowning in tags.
  • Most IDEs do not use tags or comments for code completion or error checking. I don't think they will use out-of-line documentation for that either, so I consider this an idea, not a disadvantage.
  • Comments are redundant because you already have access to the source. Reading source code takes more time and concentration then reading prose, and many nuances come through better in comments than in code.
  • External documentation is more flexible and informative. This is a limitation with existing tools; it is not a disadvantage of inline documentation. I hope to address this concern for JavaScript with JFDoc.
  • External documentation is better for translation. Absolutely right, and I cannot imagine a way for inline documentation to overcome this. Fortunately, it is not a concern for most projects. English is the lingua franca of software development.
  • No one reads inline documentation, only the generated output. Perhaps, but I don't understand how this is a disadvantage.