sprintly/sprint.ly-culture — pull request #24 by justinabrahms (2014-07-30 00:35:11+00:00)
Title: Strawman for jsdoc discussion.

I think we should stop using jsdoc.

1. It means I can fit less code on the screen, decreasing information density (which I view as a desirable trait).
2. I don't want to write it, because it provides me little or no value.
3. We lack a build process that automatically validates that the documentation is correct and up to date.

For number one, jsdoc makes one line methods [4 more lines long](https://github.com/sprintly/sprint.ly/blob/6615-reports-update-on-item-move/html/static/js-sp/sprintly/views/main/product_item_list_view.js#L122), which gives them (imo) unwarranted visual weight. This doubles the amount of text on the screen while halving the amount of information provided.

Specifically for number two, I think the promise of jsdoc is that you'll use a module using only the autocomplete in your IDE, not looking at the actual module itself. I've personally found this to not reflect how I personally work, though I recognize it's possible I'm not representative.

Third, without a build process that validates what we're doing, these will get out of date. In my opinion, less documentation is preferable to misleading/out-of-date documentation.

--

If we're looking for another mechanism of documenting (and I'm not sure that I personally am), I would prefer something more akin to [backbone](https://github.com/jashkenas/backbone/blob/master/backbone.js#L155). Text blocks that say what a thing does, not needing to go into detail about the argument types which should be self explanatory.