Comments

[julien]

How are we supposed to write comments, and should we have a convention for that?

This is not really an important topic, but since we have this great place to talk about guidelines and conventions, I wanted to ask all of you what you think about comments.

I'm talking about code comments, not "JSDoc" type comments.

I don't think we have a convention right now, so everyone has "his" preferred way of writting comments.

Here are various examples of what comments look like in some of our projects.

//This is a comment with no space at the begining and no period at the end 

//This is another comment, no space between but ended with a period.

//this is a comment, all in lowecase

// This is what I would choose.

{
   stuff: 'value'         // This is super important.
}

{
   another: 'thing'     /*optional*/
}

You get the idea.

I don't really mind which one we use and I don't think we should spend time implementing an eslint rule that enforces this (because I assume that could take some precious time) but I just thought I'd bring this up for anyone who is interested.

As far as I'm concerned, I'd use a "logical" (you could argue that this is only logical for me) rule:

Start you comment with a capital letter and end it with a period.

Looking forward to read your thoughts.

[wincent]

Your suggestions sound reasonable to me. The general rule of thumb I have been applying is:

• I use JSDoc-style comments (ie. starting with /**) for comments that could conceivably be considered documentation — eg. usage instructions, API descriptions etc — for a piece of code; I do this even in repos where we don't actually use any JSDoc tooling (example), or when the "documentation" fits on a single line (example).
  • Separate topic: I am not a huge fan of JSDoc annotations as such because I think nobody reads the extracted documentation, and for doing things like communicating type information I think there are much better tools (like TypeScript).
• For cases where I am explaining some internal detail of the code (to help the reader understand how it works, but where such explanation wouldn't really belong in any extracted "documentation"), I use line comment syntax (even for comments that go on for multiple lines). Examples.
• Always leave a space after the //.
• In all cases, start with a capital letter, end with a period.
• I almost never use // in the trailing position of a line (ie. after code), except for the rare (// eslint-disable-line case).

Gotchas:

• Some ESLint directives only work with block comment syntax (eg. eslint-disable); while others (eg. eslint-disable-line and eslint-disable-next-line) work with block and line comments.

[izaera]

I agree with what @wincent says.

Only two minor things:

1. JSDoc types may be useful when transitioning from JS to TS because tsc can read them when the proper settings are configured. They even want to be able to generate .d.ts files from them in the next version.
2. I sometimes don't add a trailing . if the comment is only one sentence. This is a style rule used in many newspapers and media, AFAIK, because for headers and titles it doesn't look good to put an ending period. For example:

// This is a comment that will have more than one sentence. Thus, we use periods. 

vs

// Push configured directories into array

But I agree it's just a matter or personal taste.

We can even leave it open so that we can argue for endless hours every time we do a review or have some time to spare trolling our fellows.

My two cents...

[edalgrin]

For general CSS, I use the same rules written in the clay-css-contributing-documentation

Comments should generally use the single line syntax, // comment, since single line comments are removed by the Sass preprocessor.

Multiline comments, /* comment */, should only be used in places where we want to preserve the comment in the CSS output such as copyright text or attribution.

[wincent]

My two cents...

But @izaera, that is only one sentence, and you still used three periods. Maybe you meant to use U+2026 HORIZONTAL ELLIPSIS.

[izaera]

// My two cents