Annotation specification

The Importance of Commenting Standards

Good commenting standards enhance code readability and facilitate team collaboration and maintenance. As a stylesheet language, CSS benefits from well-structured comments that clearly delineate style modules, explain functionality, and justify special handling.

Single-Line Comment Standards

Single-line comments are suitable for brief explanations. Use // as a prefix, with a single space between the symbol and the comment:

// Main heading style  
h1 {  
  font-size: 2rem;  
}  

// Navbar background color  
.navbar {  
  background-color: #f8f9fa;  
}  

Key points:

1. Place comments above the described object.
2. Do not leave blank lines between the comment and the code.
3. Keep each comment line under 80 characters.

Multi-Line Comment Standards

For complex modules, use multi-line comments with the /* */ format:

/*  
 * Card component styles  
 * Includes container, title, and content sections  
 * Follows BEM naming convention  
 */  
.card {  
  border-radius: 8px;  
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);  
}  

Multi-line comment guidelines:

1. The first and last lines should contain only comment symbols.
2. Each middle line starts with * and is indented with one space.
3. Add one blank line above and below the comment block.

Module Division Comments

Large stylesheets should use special comment markers to delineate module boundaries:

/* ======================  
   Layout Styles  
   ====================== */  

/* ======================  
   Form Components  
   ====================== */  

Recommended visual separators:

• Use at least 10 equals signs or hyphens.
• Center the module name.
• Include two blank lines above and below.

Conditional Comments

Add explanations for styles targeting specific browsers or environments:

/* Rounded corner fallback for IE9 and below */  
.rounded {  
  border-radius: 5px;  
  behavior: url(border-radius.htc); /* Uses HTC behavior file */  
}  

Color Value Comments

Explain the purpose of special color values:

.color-palette {  
  --primary: #3498db;  /* Primary brand color */  
  --danger: #e74c3c;   /* Error alert color */  
  --success: #2ecc71;  /* Success state color */  
}  

Disabled Code Comments

Temporarily disabled code should be retained with an explanation:

/*  
.dropdown-menu {  
  display: none;  // Phase 2 feature postponed  
}  
*/  

File Header Comments

Include basic information at the file header:

/*!  
 * Project: E-Commerce Platform Stylesheet  
 * Created: 2023-06-15  
 * Last Modified: 2023-08-20  
 * Author: Frontend Team  
 * Description: Global styles and component library  
 */  

Special Marker Comments

Use conventional markers for better readability:

// TODO: Optimize mobile responsiveness  
.responsive-img {  
  max-width: 100%;  
}  

// FIXME: Rendering issue in Safari  
.animation-box {  
  transform: rotate(15deg);  
}  

Common markers:

• TODO: Pending tasks
• FIXME: Issues requiring fixes
• HACK: Temporary workarounds
• NOTE: Important notes

Preprocessor Language Comments

Commenting standards for Sass/Less:

// Single-line comments are not compiled to CSS  
/* Multi-line comments are preserved in output */  

/// Documentation comments (SassDoc)  
/// @group utilities  
/// @param {Number} $size - Size value  
@mixin size($size) {  
  width: $size;  
  height: $size;  
}  

Comments and Version Control

Git-integrated commenting suggestions:

/* [v1.2.3] Added floating button styles */  
.float-btn {  
  position: fixed;  
  right: 20px;  
  bottom: 20px;  
}  

Comment Density Control

Maintain balanced commenting:

1. Include 1–2 lines of comments per 10–15 lines of code.
2. Avoid over-commenting self-explanatory code.
3. Always comment complex algorithms or special logic.

Comment Style Consistency

Team-wide uniformity:

1. Use either Chinese or English (English recommended).
2. Follow punctuation rules.
3. Standardize terminology.
4. Define clear hierarchy standards.

Comment Maintenance Responsibility

Comment update requirements:

1. Update relevant comments when modifying code.
2. Remove obsolete comments when deleting code.
3. Clean up outdated TODO markers promptly.
4. Conduct regular comment reviews.

Comment Tool Integration

Enhance comments with tools:

1. Configure ESLint for comment rule checks.
2. Use Stylelint to validate comment formats.
3. Generate style documentation with SassDoc.
4. Standardize comment formatting via Prettier.

# Stylelint comment rule example  
"comment-word-blacklist": [  
  ["/^TODO:/", "FIXME"],  
  {  
    "message": "Please use English comments (TODO/FIXME)"  
  }  
]