Clean Code 原則下的 HTML & CSS 類別結構速查表

 

Clean Code 原則下的 HTML & CSS 類別結構速查表 📝

核心原則 (Core Principles)

  1. 可讀性 (Readability)：類別名稱應清晰、具描述性，讓人一眼就能理解其用途。
  2. 一致性 (Consistency)：遵循一套固定的命名約定和結構模式。
  3. 可維護性 (Maintainability)：易於修改、更新和除錯，減少副作用。
  4. 可擴展性 (Scalability)：能輕鬆應對新增功能或組件，而不破壞現有結構。
  5. 解耦 (Decoupling)：將結構 (HTML)、表現 (CSS) 和行為 (JavaScript) 分離。類別名稱應專注於樣式，而非特定內容或 JavaScript 功能。

主流命名約定 (Popular Naming Conventions)

以下介紹幾種廣泛使用的 CSS 架構和命名約定，它們都遵循 Clean Code 的精神：

1. BEM (Block, Element, Modifier)

BEM 是一種非常流行的 CSS 架構，它通過嚴格的命名約定來創建模組化、可重用的 CSS。
  • Block (塊)：獨立的、可複用的組件。
    • 命名：單獨的類別名稱，通常是名詞或名詞短語。
    • 範例：.card, .button, .header
  • Element (元素)：Block 的一部分，沒有獨立的意義，只能存在於 Block 中。
    • 命名：block__element (雙底線分隔)
    • 範例：.card__title, .button__icon, .header__logo
  • Modifier (修飾符)：Block 或 Element 的屬性或狀態，用於改變外觀或行為。
    • 命名：block--modifier 或 block__element--modifier (雙連字號分隔)
    • 範例：.card--featured, .button--primary, .button--disabled, .header__logo--small
  • HTML 結構範例 (BEM)：
    html
    <article class="card card--featured">
  <img class="card__image" src="image.jpg" alt="Card Image">
  <h3 class="card__title">Featured Article</h3>
  <p class="card__description">This is a description for the featured card.</p>
  <button class="button button--primary">Read More</button>
</article>
  • CSS 結構範例 (BEM)：
    css
    /* Block */
.card {
  border: 1px solid #ccc;
  padding: 16px;
  margin-bottom: 20px;
  background-color: #fff;
}

/* Element */
.card__title {
  font-size: 1.5em;
  margin-bottom: 8px;
  color: #333;
}

.card__description {
  color: #666;
  line-height: 1.6;
}

/* Modifier */
.card--featured {
  border-left: 5px solid blue;
  background-color: #f0f8ff;
}

.button {
  padding: 10px 15px;
  border: none;
  cursor: pointer;
  border-radius: 4px;
}

.button--primary {
  background-color: blue;
  color: white;
}

.button--primary:hover {
  background-color: darkblue;
}

2. OOCSS (Object-Oriented CSS)

OOCSS 的核心思想是將 UI 分解成獨立的、可重用的「物件」(Objects)，並遵循兩個主要原則：
  • 將容器和內容分開 (Separate the container from the content)：
    • 創建可重複使用的樣式「物件」，例如一個帶有特定邊框和間距的盒子。
    • 範例：.box, .media-object
  • 將樣式與結構分開 (Separate the style from the structure)：
    • 創建可組合的「修飾符類別」(Modifier Classes)，用於改變物件的外觀或狀態，而不是創建新的類別。
    • 範例：.is-active, .is-hidden, .is-primary (通常以 is- 或 has- 開頭表示狀態或修飾)
  • HTML 結構範例 (OOCSS)：
    html
    <div class="box is-featured">
  <div class="box__header">
    <h2>Section Title</h2>
  </div>
  <div class="box__body">
    <p>Content goes here.</p>
  </div>
</div>

<button class="button button--primary">Click Me</button>
  • CSS 結構範例 (OOCSS)：
    css
    /* Object: Box */
.box {
  border: 1px solid #ccc;
  padding: 1rem;
  margin-bottom: 1rem;
}

.box__header {
  border-bottom: 1px solid #eee;
  padding-bottom: 0.5rem;
  margin-bottom: 0.5rem;
}

.box__body {
  /* ... */
}

/* Modifier: State */
.is-featured {
  border-color: blue;
  background-color: #f0f8ff;
}

.is-hidden {
  display: none;
}

/* Object: Button */
.button {
  padding: 0.5rem 1rem;
  border: none;
  cursor: pointer;
}

/* Modifier: Theme */
.button--primary {
  background-color: blue;
  color: white;
}

3. SMACSS (Scalable and Modular Architecture for CSS)

SMACSS 是一種 CSS 架構方法論，它將 CSS 規則分類，以便更好地組織和管理。
  • Categories (類別)：
    • Base (基礎)：預設樣式，如重置 (reset) 或標準化元素樣式 (如 body, h1, p, a)。通常不加類別名稱，直接寫元素選擇器。
    • Layout (佈局)：頁面的主要區域，如頁眉、頁腳、導航欄、內容區域。通常以 l- 或 layout- 作為前綴。
      • 範例：.l-header, .l-sidebar, .l-content
    • Module (模組)：可重複使用的組件，類似 BEM 中的 Block。命名方式與 BEM 相似。
      • 範例：.card, .button, .modal
    • State (狀態)：描述組件或佈局的特定狀態，通常與 JavaScript 互動。通常以 is- 或 has- 作為前綴。
      • 範例：.is-active, .is-hidden, .has-error
    • Theme (主題)：用於改變 UI 的外觀，如顏色方案、字體風格。通常與 Layout 或 Module 結合使用，或以 theme- 作為前綴。
      • 範例：.theme-dark, .theme-light
  • HTML 結構範例 (SMACSS)：
    html
    <body>
  <header class="l-header theme-dark">
    <div class="container">
      <a href="/" class="logo">MySite</a>
      <nav class="main-nav">
        <ul>
          <li><a href="#" class="is-active">Home</a></li>
          <li><a href="#">About</a></li>
        </ul>
      </nav>
    </div>
  </header>

  <main class="l-content">
    <div class="container">
      <article class="card">
        <h3 class="card__title">Article Title</h3>
        <p class="card__text">Content...</p>
      </article>
    </div>
  </main>
</body>
  • CSS 結構範例 (SMACSS)：
    css
    /* Base */
body {
  font-family: sans-serif;
  margin: 0;
  line-height: 1.5;
}
a {
  color: blue;
  text-decoration: none;
}

/* Layout */
.l-header {
  background-color: #333;
  padding: 1rem 0;
}
.l-content {
  padding: 2rem 0;
}
.container {
  max-width: 1100px;
  margin: 0 auto;
  padding: 0 15px;
}

/* Module */
.logo {
  font-size: 1.8em;
  font-weight: bold;
  color: white;
}
.main-nav ul {
  list-style: none;
  padding: 0;
  display: flex; /* 使用 Flexbox 佈局導航 */
}
.main-nav li {
  margin-left: 20px;
}
.main-nav a {
  color: white;
}
.card {
  border: 1px solid #eee;
  padding: 1rem;
}
.card__title {
  margin-top: 0;
  margin-bottom: 0.5rem;
}

/* State */
.is-active {
  font-weight: bold;
  border-bottom: 2px solid white; /* 在導航中標記活動項 */
}

/* Theme */
.theme-dark {
  background-color: #222;
  color: #eee;
}
.theme-dark .logo {
  color: #fff;
}
.theme-dark .main-nav a {
  color: #ccc;
}
.theme-dark .main-nav a.is-active {
  color: white;
  border-bottom-color: #fff;
}
.theme-dark .card {
  border-color: #444;
  background-color: #333;
}

一般性類別命名建議 (General Class Naming Tips)

  • 避免使用通用或過於籠統的名稱：如 .red, .big, .text, .box1。這些名稱缺乏上下文，難以理解和維護。
  • 使用有意義的名稱：名稱應反映元素的功能或內容。
    • 例如：.user-profile 而非 .user-box。
    • 例如：.error-message 而非 .message-red。
  • 避免使用與 JavaScript 相關的類別名稱：除非該類別的唯一目的是由 JavaScript 控制，否則應避免將類別名稱與特定 JavaScript 功能綁定（例如 .js-modal-trigger）。這會造成結構與行為的耦合。
  • 保持簡潔但具描述性：名稱不應過於冗長，但也要足夠清晰。
  • 使用連字號 (-) 分隔單詞：這是 CSS 類別命名中最常見且被廣泛接受的風格。
  • CSS 屬性與類別名稱的對應：盡量讓類別名稱直接或間接映射到 CSS 屬性。
    • 例如：.text-center 對應 text-align: center;
    • 例如：.d-flex 對應 display: flex; (常用於框架，如 Bootstrap)
    • 例如：.rounded 對應 border-radius: ...;
  • 狀態類別：使用 is- 或 has- 前綴來表示元素的狀態或條件。
    • is-active, is-disabled, is-visible, is-hidden
    • has-error, has-success, has-warning
  • 佈局類別：使用 l- 或 layout- 前綴來表示佈局結構。
    • l-container, l-grid, l-row, l-col
  • 工具類別/功能類別 (Utility Classes)：用於單一、原子化的樣式，通常是通用的。
    • 範例：.text-center, .mb-4 (margin-bottom: 1rem), .p-2 (padding: 0.5rem)。
    • 注意：過度使用工具類別可能會讓 HTML 變得雜亂，需要平衡。

總結 (Summary)

選擇一種命名約定（如 BEM）並堅持使用，是實現 Clean Code 目標的關鍵。這不僅能提高你個人程式碼的品質，也便於團隊協作和長期維護專案。記住，類別名稱的目的是為了讓你的 CSS 更具組織性、可預測性和可擴展性。

留言

發佈留言

此網誌的熱門文章

《Clean Code 2: Vue 3 檔案/資料夾結構》

  目錄 (10 主題版) Part 1: 最簡目錄總覽 🚀 Vue 3 專案結構入門  🏗️ 元件與模組化組織  🧩 路由與頁面架構  🗺️ 狀態管理結構  🗄️ API 服務層設計  🌐 共享資源與工具  🛠️ 測試結構  🧪 特性導向結構  🏢 命名規範與原則  🏷️ 實戰範例與總結  ✨ Part 2: 詳細目錄內容 📖 第一部分：基礎與核心結構 (Foundations & Core Structure)  🏗️ Vue 3 專案結構入門與原則 為何需要清晰的檔案結構？🤔 Vue CLI/Vite 預設結構解析 🧐 src  目錄的組織策略 📁 核心目錄 ( components ,  views ,  assets ,  utils  等) 的職責 🗂️ 元件與模組化組織的最佳實踐 元件的職責劃分與拆分 🧩 單檔案元件 (SFC) 的結構規範 📝 組織元件目錄 ( components ,  ui ,  layout  等) 🌳 共享元件與複合元件的區分 🤝 路由與頁面架構的最佳實踐 vue-router  配置與目錄結構 🗺️ 頁面 (Views/Pages) 與佈局 (Layouts) 的組織 🏘️ 動態路由與嵌套路由的結構化 🧭 路由守衛與權限管理的結構化 🛡️ 狀態管理結構 (Vuex/Pinia) Pinia Store 的模組化結構建議 🗄️ Vuex Modules 的組織方式 📦 Actions, Mutations, Getters 的邏輯劃分 🗃️ 狀態共享與跨 Store 依賴管理 🌐 API 服務層設計與組織 建立專門的 API 服務目錄 ( services ,  api ) 📡 Axios/Fetch 的封裝與配置 🌐 錯誤處理、響應格式統一與 Mock API 結構 ⚠️🎭 第二部分：進階組織與實踐 (Advanced Organization & Practices)  🚀 共享資源與工具的結構化 utils ,...
閱讀更多

[Laravel][ATOMIC] DB::transaction, DB::beginTransaction

  DB::beginTransaction()   will only begin a transaction, while for   DB::transaction()   you must pass a Closure function that will be executed   inside   a transaction. So this: DB:: transaction ( function () { // Do something and save to the db... }); is the same as this: // Open a try/catch block try { // Begin a transaction DB:: beginTransaction (); // Do something and save to the db... // Commit the transaction DB:: commit (); } catch (\ Exception $e ) { // An error occured; cancel the transaction... DB:: rollback (); // and throw the error again. throw $e ; } As you can see,  DB::transaction()  is a "helper" function to avoid writing code to catch errors, begin a transaction, commit the transaction, and optionally rollback (cancel the transaction) if an error occured. If you have a more complex logic, or need an specific behaviour, you will manually build your transaction; if your lo...
閱讀更多

[laravel 9] rename project

  Answers Sorted by:                                                Highest score (default)                                                                     Trending (recent votes count more)                                                                     Date modified (newest first)                        ...
閱讀更多