Darek Kay's picture Darek Kay

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:

General

  • 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.

HTML

<!doctype html>
<html lang="en">
<head>
<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">

CSS

JavaScript

ReactJS

Redux

Images

Code quality

Testing

Performance

Fonts

Design

Accessibility

  • 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 an 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.

Security

Privacy

  • 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.

SEO

User experience

DevOps

Git

  • 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.
    • Create a release for each tag on GitHub.

GitHub

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.

Marketing

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

Business

Writing

Documentation

Style

  • Prefer active over 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

Grammar

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

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, meaning you 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.

Communication

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