Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 39 ยท Getting Started

Sass Comments and Output Styles

Learn silent // comments, loud /* */ comments, the /*! */ license form, expanded versus compressed CSS, @charset handling and how source maps help debugging.

Comments look like the least interesting part of a language, but in Sass they come in two kinds with very different behavior, and the compiler's output style decides what ends up in the CSS your visitors download. Understanding both lets you document your stylesheets freely without shipping notes to production, and lets you keep a license banner where legally required.

Silent comments

A comment that starts with // runs to the end of the line. It is silent: it never appears in the compiled CSS, in any output style.

SCSS
// Brand colors (update with the design team)
$brand: #0ea5e9;

.button {
  padding: 8px 16px; // matches the input height
}

Plain CSS has no // comments, so these exist only in Sass. They are perfect for notes to the next developer, TODOs, and explanations that visitors do not need. You can also comment out code with them, one line at a time.

Loud comments

/* ... */ comments are the CSS kind. In expanded output they are kept, so they cost bytes on the wire. In compressed output they are removed, with one exception covered below.

SCSS
/* Layout helpers */
.container { max-width: 60rem; }

Loud comments can span lines, and they can contain interpolation, which inserts a Sass value into the text:

SCSS
$version: 3;
/* Theme build #{$version} */

That compiles to /* Theme build 3 */. Interpolation is the same #{ } syntax you will use later for selectors and property names, and Interpolation covers it in depth.

Preserved comments

A loud comment that begins with /*! is preserved even in compressed mode. Use it for license headers or build banners that must stay in the minified file.

SCSS
/*! MyTheme v3 | MIT License */

Documentation comments

By convention, /// (three slashes) marks a documentation comment. To Sass it is just a silent comment, but tools such as SassDoc read them to generate API docs:

SCSS
/// Converts a pixel size to rem.
/// @param {Number} $px - the size in pixels
/// @return {Number}
@function rem($px) { @return math.div($px, 16px) * 1rem; }

Writing /// before each public mixin and function makes a design system much easier to maintain. You will write functions like this in Custom functions.

Silent, loud and preserved comments

Output styles

Dart Sass offers two output styles:

Style Looks like Use it for
expanded (default) Normal CSS, one declaration per line Development, readable diffs
compressed One line, no extra spaces, loud comments removed Production

Older Sass versions had nested and compact. Dart Sass dropped them, so if a tutorial mentions --style=nested, ignore it.

Compressed output is not a replacement for a real minifier. Sass only removes whitespace and comments; it does not merge duplicate rules, shorten colors across your whole file or remove dead CSS. Many teams compile with expanded and let a bundler step (such as cssnano or Lightning CSS) minify, or compile with compressed for simple sites. Gzip or Brotli on the server shrinks both about equally.

Keep the default expanded style while you develop. When something looks wrong in the browser, reading the generated CSS is the quickest way to see what Sass actually produced.

Character encoding and @charset

If your stylesheet contains non-ASCII characters (an accented font name, an emoji in a content value), the CSS file must declare its encoding so the browser reads it correctly. Dart Sass handles this automatically: in expanded mode it adds @charset "UTF-8"; at the top, and in compressed mode it adds a byte-order mark instead (an invisible character that is smaller). Pure ASCII output gets neither.

You can turn this off with --no-charset on the command line or charset: false in the API, which is useful when you concatenate files afterwards and add your own declaration.

Charset in the output

Sass writes the characters it finds into the output as real characters, so both the Cafรฉ name and a CSS escape like \201C (doubled inside the JavaScript string) end up as non-ASCII text. That is why the default output starts with @charset "UTF-8"; and the charset: false output does not.

Source maps

A source map is a small .map file that connects each line of the generated CSS back to the SCSS line that produced it. With maps on, browser dev tools show _buttons.scss:12 instead of styles.css:3047. The command line writes them by default, as styles.css.map, and appends a comment pointing to it. Two options help:

  • --embed-sources stores the original SCSS inside the map, so it works even when the source files are not deployed.
  • --no-source-map turns them off. Production builds that serve the CSS publicly often skip maps or keep them private.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which comment never appears in the compiled CSS?

    // comments are silent. /* / comments are kept in expanded output, and /! */ comments are kept even when compressed.
  2. 2. How do you keep a license banner in compressed output?

    A loud comment starting with an exclamation mark after the opening is preserved in every output style.
  3. 3. Which output styles does Dart Sass support?

    nested and compact were removed after Ruby Sass. Dart Sass has expanded (default) and compressed.
  4. 4. What does the /// convention mean?

    To the compiler it is an ordinary silent comment. By convention doc tools read the triple-slash form.

Summary

  • // comments are silent; /* */ comments appear in expanded output and are removed when compressed.
  • /*! ... */ survives compression, and /// is the doc-comment convention.
  • Loud comments can contain #{ } interpolation.
  • Dart Sass has two output styles, expanded and compressed, and adds @charset or a BOM for non-ASCII output.
  • Source maps link generated CSS back to SCSS lines for debugging.

Next: Variables