Comments | CSS + SCSS

Main Objective

Code that is commented well is extremely important, no matter where or what that code is.
Same goes for dedicating time itself into describing the individual components.

Don't leave others guessing as to the purpose of uncommon or non-obvious code. Even if the code is obvious from your perspective, others may be confused as to why things were done a certain way.

Some questions you should consider:

Why is the code is needed? Is there a reason it is within a certain file?
If there were any ‘overrides’ or 'hacks' added, why?
- Example - Issues due to a library or a custom module, Drupal Core doing something funky, the well known !important is used at any time.

In the next section, we will dive into explaining the correct formatting of comments and some rules surrounding them. We believe these should be followed in both CSS and SCSS file.

Comment Format Types

1.) Global | All Files

Each file should start with a comment describing what the file does.
- A blank line should follow a file comment.
- The length of the lines should be kept to 80 characters, when possible.
  For more information, see the PHP file comment standards.
- Comments may not be nested.
Look at the code snippet directly below for an example on what the file description should look like:

 /* @file
 * Short description describing the file.
 *
 * The first sentence of the long description starts here and continues on this
 * line for a while finally concluding here at the end of this paragraph.
 */

2.) Single-Line

If a comment can be written inside of an 80 character line length limit, it can use a simple CSS comment style.
- The syntax for comments in CSS is: /* comment here */
- The comment must be placed on the line immediately above the property or ruleset it describes.
- The comment should be indented the same amount as the property or ruleset it describes.
- If the comment is describing a ruleset, place a blank line before the comment.
Look at the code snippet directly below for an example on how/where to place the docblock.

.example {
  /* Override the default margins. */
  margin: 0;
}

/* This is a variant of the .example component. */
.example--item {
  display: inline;
}

3.) Multi-Line

When describing a ruleset, or set of rulesets, any comment that requires 2 or more lines must follow the Doxygen comment style (commonly known as a “Docblock”).
- Keep in mind that each line should not exceed 80 characters, similar to a single-line comment.
Look at the code snippet directly below for an example on how/where to place the docblock.
- Must be on the line immediately above the ruleset (or rulesets) it describes.
- Place a blank line before the docblock comment.

/**
 * Short description using Doxygen-style comment format.
 *
 * The first sentence of the long description starts here and continues on this
 * line for a while finally concluding here at the end of this paragraph.
 *
 * The long description is ideal for more detailed explanations and
 * documentation. It can include example HTML, URLs, or any other information
 * that is deemed necessary or useful.
 */
.example-rule {
}

Sub-Objective

When the question of what format should be used, being the // and /**/ format types, you should consider where it is you are adding the comments, and wether you want them within the compiled file.

/**/ comments can be visible in compiled CSS, so writing proper and professional comment is critical!

Possible locations to consider:

Contrib or Custom module
.css file or .scss file
Drupal or WordPress

Before you answer, be sure to review what an invalid comment is!

Invalid Comments

Why do /**/ comments work in stylesheets, but // comments do not?

CSS treats new lines like all other whitespace, and would not be able to determine the end of the comment without a terminating delimiter. The // is not a valid syntax - only in C++ in the // comment an exception to whitespace neutrality.
This allows CSS to work correctly when stripped from whitespace and new line characters during minification.
However, // are valid in certain CSS processors such as Less and SASS.
- The browser will attempt to interpret the // syntax anyway and likely fail the rule based on it being a syntax error rather than it being a comment. The result will likely fail based on browser, but using it brings you into undefined behaviour.
  
  Code Example:
  
  Result:

Conclusion

Now that we know some information on comments and how they could be invalid, we can now answer the question - What comment format do we used?

At Kalamuna, we use the /**/ format, wether in CSS or SCSS.

The purpose of this decision is to simplify not confuse developers on what comment format they need to use in certain cases, reduce the risk of guessing, and remove the need to remember yet another thing.
This also helps in general to encourage Developers to add them!

When asking about which choice is wrong or right, there is no ‘correct’ answer here. Overall the /**/ format is more compatible compare to // across all the CSS/SCSS formats.

Whitespace Rules

Whether it be for comments or code (styles) - only a single blank line should be used.
Avoid using multiple lines if trying to simply space code chunks out. Should a new file be created?

Extra homework

When looking at both Drupal and Wordpress, are there differences between them when talking about comments and/or formatting?
NPM compilers, can a package be added instead? Example, a package that strips out comments regardless?
When the topic of code review pops up (not general QA) - When looking at a Pull Request in GitHub (for example), are comments apart of the review process?
Drupal 10 versus D9 / D8 / D7 - Are there differences with commenting standards, has anything changed?

To help promote developers to add comments, it could be helpful to look at:

Are there keyboard shortcuts to insert comments, which could help avoid missing closing statements or just make adding them quickly! Typing is hard sometimes for us all.
- When talking about shortcuts, can these be added or changed within your chosen Editor?
- Are there differences across editors? Sublime, VSCode, PHPStorm
  - The shortcut for VS code: alt + shift + a for windows OR option + shift + a for Mac

Kalawiki