Writing clean, reusable, and maintainable code

INTRODUCTION

When developing websites, we always prioritise code quality, which is crucial to ensure the applications we create are scalable over time. By following programming standards and best practices, we can develop code that is clear and easy to maintain. This helps to speed up the development process, especially when working with a team. 

Using a consistent formatting style throughout the code, managing files logically, and sticking to naming conventions can also help the team feel comfortable and familiar with the codebase, making teamwork smoother.

Let’s look at how we make that happen in practice!

Effective use of organised code

Writing organised code means using clear and descriptive names for variables and classes and keeping functions small, descriptive and focused on a single task. In addition, proper formatting through indentation, spacing, and appropriate nesting enhances the readability of the codebase, contributing to its overall clarity.

At Studio Republic, we’ve integrated various industry-standard practices that we consider most beneficial to our coding approach.

Many modern web technologies lean towards a component-based approach for web development. We’ve embraced this by integrating it into our boilerplate, ensuring that all HTML, CSS, and JavaScript are tailored to each component individually.

File management

To enhance our development practices, we have integrated our component-based approach with the Scalable and Modular Architecture for CSS (SMACSS) methodology. 

SMACSS provides a structured framework for managing web files, promoting modularity and scalability by organising layouts, components, and global elements systematically. This combination vastly improves efficiency within our development workflow. 

As a result, we can easily separate global elements into different manageable files based on their specific use-case. We can also add and remove components and all their respective resources with minimal effort.

Organising CSS

While there are various methods for organising CSS, we’ve discovered that the most effective approach within a component-based framework is to consolidate all CSS properties relating to a specific class in one single location. 

Essentially, when you declare properties for a CSS class, you can also include properties from its parent classes using the parent selector ‘&’.

For example, consider a selector like “.card-grid.” You might need to adjust “.card-grid” based on a global selector such as “.profile-template.” If the card grid differs within the profile template, you might create a separate instance of “.card-grid” nested within a new selector named “.profile-template.” However, this approach can complicate removing everything related to “.card-grid” from the project.

Instead, keeping every component self-contained using the parent selector, means everything related to each class, even things outside their immediate scope, will be affected:

This approach improves organisation by keeping related styles together and therefore improving the overall maintenance of each and every component.

Implementing the BEM naming convention

BEM stands for Block Element Modifier. It is a popular naming convention for writing CSS and HTML classes in a clear and unique way. It follows a structure like “block__element–modifier,” helping you see how different parts of your HTML relate to each other.

BEM in HTML

The benefits of using BEM means that every class written for each component directly references the component itself, reducing the likelihood of accidentally using classes outside the component’s scope. 

This is especially useful when you have a standard naming convention for headings and paragraphs (i.e. heading, copy) which are easily repeatable elements in a website. Instead, you would have something like: ‘featured-banner__heading’, therefore keeping ‘heading’ unique to the featured banner component.

BEM in CSS

BEM can enhance the cleanliness of your CSS code by reducing the need for nesting. With BEM, you can reference the class name itself and keep the specificity level low, reducing the need for !important flags or additional nesting:

JavaScript

One effective way we’ve found to write JavaScript unique to each component is to use a class-based approach that extends from a global class. The global class can be used for functionality utilised throughout the entire website, while extended classes are used specifically for each component. This breaks down the JavaScript into individual parts, making it easier to understand the scope of each function.

This method promotes code reusability by allowing shared methods and properties to be defined once in the global class and inherited by component-specific classes. Readability is also enhanced as each component-specific function is encapsulated within its own class, clarifying the code’s structure.

HTML via Twig Templating

We organise our HTML structure using Twig. Twig’s syntax is clean, intuitive, and easy to read. It supports template inheritance, allowing developers to define a base template with common layout elements (e.g., header, footer, navigation) and then extend or override specific blocks in child templates. This results in a more efficient and maintainable codebase.

Twig also allows seamless data passing into templates, enhancing flexibility and customisation. Its modular design streamlines development, ensuring consistency and making updates manageable as projects evolve.

Lastly, Twig’s combination of clean syntax, template inheritance, and data-passing capabilities contributes to a more efficient and maintainable codebase. This perfectly aligns with the principles of component-based development.

Conclusion

In a component-based development environment, adhering to these best practices and programming standards can create scalable applications that are easier to manage and evolve over time. 

The result is a streamlined workflow that enhances productivity and code quality, ultimately leading to better-performing applications and a more cohesive development process.