CSS and JavaScript: keeping code maintainable

Why maintainable code matters

Code that is easy to read, understand, and update saves time and money. When code is messy or hard to follow, every change takes longer and risks breaking things.

For more on code quality and performance, see performance, quality code, and knowing what you are doing.

CSS: organisation and structure

1) Use consistent naming

• Choose a convention: BEM, utility classes, or component-based naming. Stick to it.
• Be descriptive: .button-primary is clearer than .btn1.
• Avoid deep nesting: Keep selectors shallow (e.g. .card .title not .page .section .card .content .title).

2) Organize by purpose

• Separate concerns: Layout, typography, components, utilities in different files or sections.
• Group related styles: Keep button styles together, form styles together, etc.
• Use comments: Mark sections so you can find things later.

3) Avoid duplication

• Use variables: Colors, spacing, fonts in CSS custom properties or a preprocessor.
• Reuse components: Build reusable patterns instead of copying styles.
• DRY principle: Do not repeat yourself. If you write the same style many times, extract it.

4) Keep specificity low

• Avoid !important: Usually a sign of specificity problems. Fix the root cause instead.
• Prefer classes over IDs: Classes are easier to override and reuse.
• Keep selectors simple: .card-title is better than .page .section .card .content .title.

JavaScript: structure and practices

1) Use clear names

• Descriptive variables: userEmail not ue or data.
• Function names that describe action: validateForm() not check().
• Constants for magic numbers: const MAX_RETRIES = 3 not if (count < 3).

2) Keep functions small and focused

• One job per function: A function should do one thing well.
• Short functions: If a function is long, break it into smaller pieces.
• Clear inputs and outputs: Functions should have obvious parameters and return values.

3) Organize code logically

• Group related code: Keep form handling together, navigation together, etc.
• Separate concerns: Data fetching, DOM manipulation, and business logic in different places.
• Use modules: Split code into files that each handle a specific area.

4) Handle errors gracefully

• Validate inputs: Check data before using it.
• Use try/catch: Handle errors instead of letting them crash the page.
• Provide fallbacks: If something fails, show a message or use a default.

Common problems and fixes

Problem: CSS that is hard to override

• Cause: High specificity, !important, inline styles.
• Fix: Lower specificity, use classes, remove !important.

Problem: JavaScript that breaks when you change HTML

• Cause: Tight coupling between JavaScript and specific HTML structure.
• Fix: Use data attributes or classes for hooks, not fragile selectors.

Problem: Code that nobody understands

• Cause: Unclear names, no comments, complex logic.
• Fix: Better names, comments for why (not what), simpler logic.

Problem: Changes break other things

• Cause: Tight coupling, shared state, no clear boundaries.
• Fix: Separate concerns, minimize shared state, clear module boundaries.

What to ask developers

If you are hiring or working with developers, ask about:

• Code organisation: How is code structured? Can I find things easily?
• Naming conventions: What naming do you use? Is it consistent?
• Documentation: Is code commented? Is there a README or guide?
• Testing: How do you test changes? Can I see it working before it goes live?

For more on working with developers, see working with web developers and ten things to check before you hire a web developer.

When code quality matters most

• Long-term sites: Sites you will update for years need maintainable code.
• Team projects: Multiple people working on code need clear structure.
• Complex features: Interactive features, forms, and dynamic content benefit from good organisation.
• Performance: Well-structured code is often faster and easier to optimise.

Summary

CSS: Consistent naming, organise by purpose, avoid duplication, keep specificity low.

JavaScript: Clear names, small focused functions, logical organisation, handle errors gracefully.

Common problems: Hard to override CSS, tight coupling, unclear code, changes break things.

Ask developers: About code organisation, naming, documentation, and testing.

For more on code quality and performance, see performance, quality code, and knowing what you are doing. For help with website development, see website build services. You can also get in touch to discuss your project.