Darek Kay's picture
Darek Kay
Solving web mysteries

Best practices and coding guidelines

A guide for building better applications.

Don't follow this guide blindly. Read the references to learn more about certain rules. Some practices become outdated as the web evolves.

This page is a continuous work in progress.

Table of contents:


  • Be an early evaluator, but late adopter.
  • Provide 404 and 50x error pages.
    • Inline all external resources on error pages (e.g. CSS, images).
  • Test your website with adblockers enabled.
  • Monitor your website's availability, e.g. with Uptime Robot.
  • Offer an RSS feed for any kind of articles. Include the full content instead of snippets.


<!doctype html>
<html lang="en">
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Page Title</title>
  • Define favicons:
    • Place a favicon.ico in the root document folder, containing at least 16×16 and 32×32 icons.
    • Consider using SVG favicons.
    • Place a 180×180 apple-touch-icon.png in the root document folder for iOS devices.
    • Create a 192x192 icon for Android devices:
<link rel="icon" sizes="192x192" href="/favicon-192.png">






Code quality




  • Test your website with custom fonts disabled.
  • Consider avoiding web fonts.
  • Use Google WebFonts helper to create an optimized font subset.
  • Preload your most important font files. You probably don't need to preload italic/bold variants.
  • Consider trade-offs of performance best practices.
  • Don't use system-ui font family.
  • Don't change font weight on hover to prevent layout shift.



  • Use semantic HTML.
  • Provide an alt text for all images. Use alt="" for decorative images.
  • Provide a label for all form inputs. The placeholder attribute is not a usable alternative.
  • Write descriptive links.
  • The contrast ratio between the background and the foreground should be as high as possible.
  • When using colors to communicate information (such as states or graphs), use different styles or add a text/icon to distinguish different states. This is important for both colorblind people and for printing a page in grayscale.
  • The tab order should go from top to bottom, from left to right
    • Do not use a tabindex value greater than 0.
    • Do not hide the focus ring without providing an alternative.
  • Be aware of screen reader conflicts with accesskeys, making accesskeys mostly useless for blind users.
  • Make sure zooming in/out doesn't break the page.
  • Avoid using icons without labels
  • Ensure that interactive controls have at least a 44×44px target click size.

View my accessibility notes for more information.



  • Include a privacy notice.
  • Comply with the EU Cookie Law.
  • Collect only the bare minimum amount of data needed for its purpose.
  • Do not opt in into Google's FLoC network.


User experience




  • Commit early and often. Perfect later.
  • Copy/move a file in a different commit from any changes to it to retain the correct file history.
  • Do not force-push public branches that other people are working on.
  • Create a tag for each release using semantic versioning, e.g. v1.4.8.


Code collaboration

  • Include guidelines for contributors in CONTRIBUTING.MD.
    • Include a humans.txt file to acknowledge project contributors.
  • Use npm scripts so no further build tools have to be installed or used.
  • Consider recording a screencast or a console demo to demonstrate the setup and usage.


  • Summarize your core idea in a single sentence (elevator pitch).





  • Prefer active voice to passive voice.
  • Avoid ambiguous pronouns:
    • In general, if more than five words separate your noun from your pronoun, consider repeating the noun instead of using the pronoun.
    • If you introduce a second noun between your noun and your pronoun, reuse your noun instead of using a pronoun.
    • it, they, them, their, this, that
  • Pick specific verbs over vague ones. Reduce the usage of:
    • be / is / are / am / was / were
    • occur / happen
    • there is / there are
  • Keep list items parallel.
  • Put conditional clauses before instructions, not after.
  • Avoid unnecessary words:
    • really, pretty much, quite a few, obviously, basically, simply, of course, clearly, just, everyone knows, very, a bit, a little, quite, too, though, sort of, kind of, rather


  • that vs. which:
    • use that for defining (= non-optional) clauses (no comma)
    • use which for non-defining (= optional) clauses (comma)
  • help (to) do:


  • Historically, typographical curly apostrophes () are preferred. On the web, typewriter straight apostrophes (') are acceptable, too.
  • Use correct dashes:
    • Hyphen (-): Compound words (e.g. "sign-in", "cost-effective").
    • En dash (): Ranges (e.g. "1985–2022", "Mon–Tue").
    • Em dash (): Break between parts of a sentence. Stronger than a comma, weaker than a semicolon.

Work methods

Project management

  • Effective teams need trust. Replacing trust with process is called bureaucracy.
  • Start sprints on Wednesday to reduce the absence in sprint meetings due to days off and remote working.
  • Use appropriate defect severities. Do not misuse them to express a (customer) prioritization.
    • Severity 1 (Critical): System failure. No further processing is possible.
    • Severity 2 (High): Unable to proceed with selected function or dependants.
    • Severity 3 (Medium): Restricted function capability, however, processing can continue.
    • Severity 4 (Low): Minor cosmetic deviance.

Remote work

  • Go remote-first. Build your development team around a workflow that embraces the concepts of remote work, whether or not your employees are remote.
  • Prefer asynchronous communication.
  • Always use a camera in addition to audio during remote meetings.


Public speaking

  • Plan for the worst-case scenario, e.g. your computer dying.
  • Use a bright color theme on a beamer to improve readability (slides, console, editor/IDE).
  • Be prepared to zoom in your presentation
    • Win + + / Win + - on Windows
  • Prepare good verbal transitions between slides.
    • Keep the things you say and the things you show in sync.
Best practices and coding guidelines