How to Write Clean, Maintainable CSS: Principles and Practical Tips

Preface

What are the "three musketeers" of front‑end development? Most developers answer HTML, CSS, and JavaScript. HTML builds structure, CSS handles layout and visual styling, and JavaScript adds dynamic behavior. While all three are essential, developers often focus on HTML and JS and neglect CSS, leading to bulky, hard‑to‑maintain style sheets.

CSS code tends to be written once and rarely changed, which can foster a lazy attitude and result in messy, unmaintainable styles. When a teammate needs to modify existing CSS, it can become a nightmare, prompting a complete rewrite.

1. CSS and Aesthetics

Beauty is subjective, influenced by culture, knowledge, and personal taste. In front‑end development, aesthetics manifest in code quality: clean, well‑structured CSS is pleasing, while tangled styles feel like "garbage".

CSS brings visual appeal to pages, as shown in the following animation:

Because CSS makes pages prettier, we should also strive to make CSS itself beautiful.

2. What Makes CSS Pleasant?

Good CSS is easy to read and modify. Comparing two snippets, the left is cramped and confusing, while the right uses spacing, limited nesting, and BEM naming, making it more comfortable to read.

Logical blocks are spaced, avoiding an overwhelming view.

Nesting depth does not exceed three levels, preventing excessive complexity.

Following BEM naming conveys element relationships.

Thus, CSS should be divided into small, self‑explanatory sections that reduce cognitive load.

3. CSS Writing Principles

Less is more Self‑explanatory Reusable

Less is more : Removing redundant rules reduces browser workload and encourages thoughtful design. Example of simplifying margin declarations:

// redundant code
.footer {
  margin-top: 30px;
  margin-bottom: 20px;
}

// optimized
.footer {
  margin: 30px 0 20px 0;
}

Self‑explanatory : CSS should convey its purpose without extra comments. BEM naming provides semantic class names that map clearly to HTML structure.

// ambiguous selector
.footer:first-child {
  color: #FFF;
  font-size: 18px;
}

// clear BEM naming
.footer-title {
  color: #FFF;
  font-size: 18px;
}

Using BEM eliminates naming conflicts and makes the relationship between CSS and DOM obvious.

<div class="person-center__wrap">
  <div class="person-center__main">
    <div class="userInfo-name">王狗蛋</div>
    <div class="userinfo-age">24</div>
  </div>
  <div class="person-center__footer">
    <div class="sctions-comfirm">确定</div>
  </div>
</div>

Reusable : Pre‑processors like SASS allow variables, loops, and conditionals, turning CSS into a more logical language.

4. Tips for Keeping CSS Clean

1. Define a Project Style Guide

Follow the project's CSS conventions to avoid personal preferences that clash with the team.

2. Maintain Consistency

Use the same units, naming patterns, and formatting throughout the codebase.

3. Format for Readability

Either keep each rule on a single line or separate rules with blank lines; the key is readability under a consistent convention.

.box { background-color: #567895; }
h2 { background-color: black; color: white; }

.person-center {
  &-wrap { width: 100%; }
  &-main { color: #FFF; font-size: 16px; font-weight: 500; }
}

4. Add Meaningful Comments

Use comments to explain business context or complex sections, aiding future maintenance.

/* This is a CSS comment
   spanning multiple lines. */

/* || General styles */
... 
/* || Typography */
...

5. Group Global Styles

Define base styles for elements like body, p, headings, lists, tables, and links.

/* || GENERAL STYLES */
body { ... }
h1, h2, h3, h4 { ... }
ul { ... }
blockquote { ... }

6. Avoid Over‑Specific Selectors

Overly specific selectors hinder reuse. Prefer reusable classes.

article.main p.box { border: 1px solid #ccc; }

/* Better */
.box { border: 1px solid #ccc; }

7. Split Large Stylesheets

Organize styles into separate files such as reset.css, variables.less, etc., and use pre‑processor mixins to share common code.

8. Leverage Tools

Use tools like stylelint with Git hooks, and adopt SASS/LESS to enforce standards and reduce mental load.

9. Learn and Imitate

Continuously learn from peers, community resources, and best‑practice examples to improve your CSS craftsmanship.

5. Coding as a Dialogue with Yourself

Writing code is a conversation with your future self. Clean, well‑structured CSS serves as a reliable anchor over years, enabling an iterative cycle of practice, modification, and refinement.