Do you follow this AirB&B style guide documentation recommendation?

announce
1

The AirB&B Javascript Style Guide recommends functions include a multi-line comment above them with a description, types, and values for all parameters and return values.

Doing so would be a big help when you stumble something like the extended React version of the Meteor Todos tutorial or really any other tutorial. I’d think it would be great in any app or package where you might want collaborators. But I’ve not seen it in practice. Is anyone in the meteor community documenting their code this thoroughly? Should we be?

The relevant excerpt from the AirB&B Javascript Style Guide:

Comments

Use /** … */ for multi-line comments. Include a description, specify types and values for all parameters and return values.

// bad
// make() returns a new element
// based on the passed in tag name
//
// @param {String} tag
// @return {Element} element
function make(tag) {

// …stuff…

return element;
}

// good
/**

  • make() returns a new element
  • based on the passed in tag name
  • @param {String} tag
  • @return {Element} element
    */
    function make(tag) {

// …stuff…

return element;
}

2 Likes
2
3 Likes
3

It’s a matter of using the “standard” for this kind of documentation. You should take a look at jsDoc

4

And meteor-jsdoc for a meteor specific implementation.

2 Likes
5

And LatoDoc for the best jsDoc theme there is :wink:

1 Like
6

We use JSDoc for meteor core! But editor support isn’t always great and typing them out manually isn’t ideal. Sublime text has a great plugin for this.

7

For info, if you type /** and press enter in webstorm it will automatically add a JSDoc style comment and with the @param values automatically listed out.

2 Likes
8

I always find the place where editors fail the most is in automatic wrapping of comments - does WebStorm handle this well?

9

Awesome. Thanks, everyone. Looks like atom has several jsdoc packages.

It doesn’t look like there’s a jsdoc react meteor atom package, but if someone makes or finds one please share it here :slight_smile:

10

Yes - kind of. I don’t use automatic wrap, but if I’m typing a comment and hit enter, it automatically indents and inserts the * lined up with the previous line’s. Very nice.

1 Like