HTML Course 17.5 Best practices for working in a team (reviews, style guides)

17.5 Best Practices for Working in a Team (Reviews, Style Guides)

Collaborating on HTML projects requires clear guidelines and consistent reviews to ensure code quality, maintainability, and scalability. The following sections delve into detailed practices, examples, and code snippets to guide teams toward efficient and error-free HTML development.

1. Establish a Shared Style Guide

A style guide defines conventions and rules for writing HTML. It covers naming, formatting, attribute order, accessibility, and more. Store the guide in a central location (e.g., repository “docs/HTML-style-guide.md”) and keep it up-to-date.

• File Naming: kebab-case, e.g. main-header.html, user-profile.html
• Indentation: 2 spaces per level
• Tag and attribute casing: lowercase only
• Attribute order: id, class, name, type, src/href, aria-*, data-*
• Quotes: double quotes for attribute values
• Self-closing tags: no trailing slash (<br>, <img>)
• Commenting: use for section headers and complex markup

2. Define a Code-Review Workflow

Peer reviews catch errors early and share knowledge. A typical workflow:

1. Create a feature branch: feature/user-login-form
2. Open a pull request (PR): reference related issue/ticket
3. Assign reviewers: 1–2 teammates
4. Use a checklist: style guide adherence, accessibility, performance, semantics
5. Address comments: update code, leave replies
6. Merge when approved: ensure CI passes (linting/validation/tests)

3. Automate Linting and Formatting

Integrate tools to enforce the style guide automatically:

• HTMLHint configuration (.htmlhintrc)
• Prettier or custom formatter for consistent indentation and quotes
• EditorConfig for basic indentation, charset, line endings (.editorconfig)
• CI checks on every PR

4. Accessibility and Semantics

Make accessibility part of the style guide:

• Use semantic tags: <nav>, <header>, <main>, <section>, <footer>
• Always include alt attributes on images
• Use ARIA roles only when necessary
• Label form elements with <label for='…'>

5. Maintain a Pattern Library

Document reusable components (buttons, cards, forms) with examples:

6. Example: Enforcing Attribute Order and Indentation

The style guide mandates ordering: id, class, name, type, src/href, aria-*, data-*.

<img 
    src='avatar.jpg' class='user-avatar' id='avatar' 
    alt='User avatar'>

<img
  id='avatar'
  class='user-avatar'
  src='avatar.jpg'
  alt='User avatar'
>

7. Example: Semantic Form Markup with Comments

<form id='login-form' class='form form--login' action='/login' method='post'>
  <!-- Username field group -->
  <div class='form__group'>
    <label for='username'>Username</label>
    <input
      id='username'
      name='username'
      type='text'
      class='form__control'
      required
      aria-required='true'
    >
  </div>

  <!-- Password field group -->
  <div class='form__group'>
    <label for='password'>Password</label>
    <input
      id='password'
      name='password'
      type='password'
      class='form__control'
      required
      aria-required='true'
    >
  </div>

  <!-- Submit button -->
  <button type='submit' class='btn btn--primary'>Log In</button>
</form>

8. Sample .editorconfig

# EditorConfig helps maintain consistent coding styles
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true

[*.html]
indent_style = space
indent_size = 2
trim_trailing_whitespace = true

9. Review Checklist Template

• Semantic tags used appropriately?
• HTML passes validator (W3C)?
• Consistent indentation and attribute order?
• All images have alt attributes?
• Form elements labeled and accessible?
• ARIA roles only when native HTML isn’t sufficient?
• No inline CSS or JavaScript?
• Matches pattern library/component guidelines?
• Clear commit message and linked issue?

By following these practices—defining a clear style guide, automating checks, conducting thorough reviews, and documenting patterns—teams can produce consistent, accessible, and maintainable HTML at scale.