MS Docs

Comments convention

Comments convention - it is a document to normalize and bring one style in code to all teammates. You can choose to comment on something or not, as you wish. But when you write some comments, read this doc to know how to.

All comments must be valid for all languages and correspond to each language statement about the comment. For example:

<!-- HTML comments  -->
1
/*  CSS comments  */
1
// JS single line comment

/*  or multi-line comments */
1
2
3

To comment something in your function, CSS-selector or HTML-tag and keep it display correctly on other IDE/code-reader - you must separate the start-comment and the end-comment characters with new line or space in 2-3 chars (if you add a comment in one line)

Good: 👍

<!--  some code/text/etc   -->
1

Bad ❌

<!-------  some code/text/etc  -------->
<!-------some code/text/etc-------->
1
2

on other readers/VSCode-themes this comment can be display in not readeble way

Naming comment of func()/html-section/scss-section use same as naming-convention recommends. If you describe what the f()/html/scss-section does try it describe in a short but understandable way. Don't make it like a poem! Keep it not wider than 60 columns, if you write some mini-doc or big description of your function/section use style as described and shown below.

logo HTML:

For global section such as:

  • bootstrap-container
  • <main> or <div class="main/container etc..">
  • section/article (depends on, what is global)

before that section use comments like this:

<!--
******************************************************************************
******************************************************************************
  TITLE SECTION NAME
******************************************************************************
******************************************************************************
-->
1
2
3
4
5
6
7

alt text

Commenting on the section and mark it like a show in the example, will make it easy to navigate and will help to use the mini-map of code much easy.

All Global sections can/would be divided into small sections, which we need to mark too.

For sub-sections:

  • bootstrap-row
  • section/article
  • <div> (that contain semanticly relevant content/tags to him)

before that section use comments like this:

<!--
*******************************************************************************
  SUB SECTION NAME
*******************************************************************************
-->
1
2
3
4
5

If you have a component or template/HTML markup, you can use a single line comment but keep the newline/white-spaces as explained early.

logo SCSS:

To change default behavior for comments of SCSS/CSS file in VSCode, use this short-cut:

Mac: SHIFT + OPTION + A

Windows: SHIFT + ALT + A

Linux: CTRL + SHIFT + A

For global section such as:

  • responsive
  • global/main selector
/*
=============================================================================
=============================================================================
  RESPONSIVE
=============================================================================
=============================================================================
*/
1
2
3
4
5
6
7

For sub section:

/*
=============================================================================
  SUB SECTION NAME
=============================================================================
*/
1
2
3
4
5

remember to centering text

For one-line comment:

/*  some comment  */
1

logo JS:

For comments in JS files, we use AIRBNB documentationopen in new window about comments.

Use /* ... */ for multiline comments.

BAD 🚫

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

  return element;
}
1
2
3
4
5
6
7
8
9
10

GOOD 🙏

/*
 *  make() returns a new element
 *  based on the passed-in tag name
 */
function make(tag) {
  // ...

  return element;
}
1
2
3
4
5
6
7
8
9

Use // for single line comments. Place single line comments on a newline above the subject of the comment. Put an empty line before the comment unless it’s on the first line of a block.

BAD 🛑

const active = true; // is current tab
1

GOOD 👌

// is current tab
const active = true;

// bad
function getType() {
  console.log('fetching type...');
  // set the default type to 'no type'
  const type = this.type || 'no type';

  return type;
}
1
2
3
4
5
6
7
8
9
10
11

GOOD 🆒

function getType() {
  console.log('fetching type...');

  // set the default type to 'no type'
  const type = this.type || 'no type';

  return type;
}
1
2
3
4
5
6
7
8

also GOOD 😀

function getType() {
  // set the default type to 'no type'
  const type = this.type || 'no type';

  return type;
}
1
2
3
4
5
6

Start all comments with a space to make it easier to read:

BAD 🙅‍♀️

//is current tab
const active = true;
1
2

GOOD 👏

// is current tab
const active = true;
1
2

BAD😡

/*
 *make() returns a new element
 *based on the passed-in tag name
 */

function make(tag) {
  // ...

  return element;
}
1
2
3
4
5
6
7
8
9
10

GOOD 💯👼

/*
 *  make() returns a new element
 *  based on the passed-in tag name
 */

function make(tag) {
  // ...

  return element;
}
1
2
3
4
5
6
7
8
9
10

Also, you can use (but not must) some notes for better understanding. This may be unnecessary because on code-review you will receive comments and other feedback from your teammates or TL.

airbnb doc - 18.5open in new window