萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網頁製作 >> Div CSS 教學

CSS 註釋規範與 DocBlock 風格實踐

基礎語法

/* 單行註釋 */

/*
  多行註釋
  可跨多行
*/

區塊標註範例

/* ---------- 文字樣式開始 ---------- */

/* 白色 12px 文字 */
.dreamduwhite12px {
  color: white;
  font-size: 12px;
}

/* 黑色 16px 文字 */
.dreamdublack16px {
  color: black;
  font-size: 16px;
}

/* ---------- 文字樣式結束 ---------- */

DocBlock 風格建議(行寬 ≤ 80 字元)

/**
 * 這是一個 DocBlock 風格註釋
 *
 * 詳細描述該程式碼區塊的功能、用途、參數等。
 * 每行不超過 80 字元,便於終端機閱讀。
 *
 * 可在註釋中使用標記語言:
 * @param {String} name - 使用者名稱
 * @returns {Boolean} 是否驗證通過
 */

風格指南重點

  • 使用 /** ... */ 區分文件化註釋與普通註釋
  • 模組/元件開頭加上標題區塊(名稱、版本、作者、日期)
  • 複雜邏輯前加入意圖說明,而非重述程式碼
  • 標註 TODO、FIXME、HACK 等行動標籤

工具整合

搭配 Stylelint、PostCSS、VS Code CSS Document 等工具,可自動產生樣式文件、檢查註釋完整性,提升團隊協作品質。

copyright © 萬盛學電腦網 all rights reserved