As CSS projects grow, it's important to keep the code clean, well-organized, and documented. This not only facilitates long-term maintenance, but also enables other developers to easily understand it. In this chapter, we'll explore best practices for keeping your CSS clear and well-documented.

Comments in CSS

Comments are an essential tool for documenting your code. They can be used to describe specific sections, explain why certain styles have been applied, or simply to remember important things.

Example of comments

css

The image shows how comments work

Good practices for comments

• Comment sections: Use comments to separate and describe large CSS code sections.
• Comment important decisions: Explain why you chose a specific styling approach, especially if it's not obvious.
• Avoid over-commenting: Avoid obvious comments, such as explaining what each CSS property does, as it can create noise in the code.

Splitting CSS into modules

Keeping your CSS modular and well-organized helps prevent it from growing in a disorganized way. In large projects, it's a good practice to split CSS into smaller files, each focusing on a specific aspect of the design.

Example of modular structure

plaintext

Naming Conventions

Maintaining a clear and consistent naming convention is crucial for your CSS to be easy to read and maintain. One of the most recommended conventions is BEM (Block, Element, Modifier), which we have already discussed in previous chapters.

General rules for naming

1. Blocks: Represent an independent component.
   • Example: .card, .navbar
2. Elements: Are parts of the block and depend on it.
   • Example: .card__title, .navbar__link
3. Modifiers: Variants of a block or an element.
   • Example: .card--highlighted, .navbar__link--active

html

Image showing BEM conventions

Using Tools to Format CSS

Maintaining a consistent format in your CSS code is fundamental for readability. Tools like Prettier or Stylelint can help you apply a consistent style to your code and avoid errors.

Using Prettier to format CSS

Prettier is a tool that allows you to automatically format your CSS code according to the conventions you define.

1. Install Prettier:

   bash
   

2. Configure Prettier: Create a .prettierrc file at the root of your project and define the formatting rules.

   json
   

3. Format your code: Prettier can format your CSS file with a simple command.

   bash
   

Avoiding Repeated Rules

Another key aspect of keeping code clean is avoiding repetition of CSS rules. If you find yourself writing the same properties in multiple places, consider refactoring the code to avoid duplication.

Using variables to avoid repetition

If you're using a preprocessor like Sass, you can define variables to avoid repeating values like colors, font sizes, or margins.

scss

This image compares code with and without the use of variables

Using a Design System

A design system is a collection of reusable patterns and components that ensure consistency in interface design. This can help keep CSS organized and coherent in large projects.

Example of a design system

A design system defines basic components like buttons, forms, cards, and tables with clear styling rules.

css

Documenting CSS

Besides using comments in the code, it's advisable to maintain external documentation of your CSS. This documentation can include:

• Style guides: A reference for CSS rules in the project.
• Variable lists: Documentation of all variables used in Sass or LESS.
• Component examples: Examples of how to use and apply design components.

Example of variable documentation

plaintext

Conclusion

Keeping CSS code clean and well-documented is essential for long-term projects. Using comments, avoiding repetition, maintaining consistent formatting, and documenting key rules and components will help you keep a scalable and easy-to-maintain project. In the next chapter, we'll see how to test and debug your CSS code to ensure it works correctly across all browsers.