Comments & Documentation

Every SCSS file SHOULD begin with a purpose comment. Hacks and workarounds MUST include an explanatory comment. Standardized prefixes (TODO, HACK, NOTE, FIXME) SHOULD be used. Dead code SHOULD be removed from component files.

Introduction

This standard defines how comments MUST be written in SCSS files to ensure clarity, consistency, and maintainability.

File Header

Every SCSS file SHOULD begin with a single-line comment describing the purpose of the component or module:

// Main header component — top navigation bar with logo and menu

Section Dividers

For files with multiple logical sections, section dividers SHOULD use the following format:

// -- SECTION NAME ----------------------------------

Required Comments

Complex calculations or unusual techniques MUST be commented.
Hacks and workarounds MUST include a comment with an explanation and ideally a reference to a related issue:

// HACK: Safari does not support gap in flexbox below v14.1 (see issue #456)
margin-right: $unit__small;

// TODO: Replace with CSS grid when dropping IE11 support

Comment Prefixes

The following prefixes SHOULD be used to categorize comments:

// TODO: — planned change or improvement
// HACK: — workaround for a known issue
// NOTE: — important context or explanation
// FIXME: — known bug that needs attention

Comment Style

Single-line SCSS comments (//) SHOULD be preferred over multi-line CSS comments (/* */). Single-line comments are stripped during compilation and do not appear in the production output.

Multi-line /* */ comments SHOULD only be used when the comment needs to appear in the compiled CSS output (e.g. license headers).

Dead Code

Commented-out code inside component files SHOULD be removed if it is no longer relevant. If it needs to be kept temporarily, it MUST include a comment explaining why.