Best Practices and Coding Guidelines

NOTE: This repository is archived. The content is now part of my blog and will be always available under darekkay.com/best-practices.

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.

General
HTML
CSS
JavaScript
- ReactJS
- Redux
Images
Code quality
Performance
Design
Accessibility
Security
Privacy
SEO
User experience
DevOps
Git
- GitHub
Code collaboration
Marketing
Business
Writing
Work methods
- Project Management
- Remote work
Communication
Public speaking

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

Do not use protocol-relative URLs, e.g. //example.com.
Add rel="noopener" when using target="_blank" to improve performance and prevent security vulnerabilities.
Prefer defer over async when loading scripts.
Provide basic document metadata:
- Define a doctype at the beginning of a HTML page.
- Specify the document's language.
- Declare an explicit character encoding.
- Add mobile support.

<!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 16x16 and 32x32 icons.
- Consider using SVG favicons.
- Place a 180x180 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">

Place paragraphs in a <p> tag. Do not use multiple <br> tags.
Do not write closing tag comments, e.g. .
Do not set values for boolean attributes, such as disabled, selected or checked.
Provide type, inputmode and autocomplete values to input fields if applicable. Test possible values here.
Use translate="no" for content that should not be translated.

CSS

Consider including normalize.css or sanitize.css before own stylesheets.
Don't use @import.
Avoid shorthand properties.
Use border-box box-sizing by default.
Place media queries close to their relevant rule sets. Do not bundle them in a separate stylesheet or at the end of the document.
Provide a print layout.
- Emulate print media in Chrome.
Remove unused CSS.
Consider a utility-first approach.
Use CSS containment when appropriate.
Use relative units.

JavaScript

Test your website with JavaScript disabled, because not everyone has JavaScript.
- Add <noscript> as fallback.
Organize your files around features, not roles.
Use Subresource Integrity for all external scripts.

ReactJS

Consider using PureComponent over Component.
- For functional components, React.memo can be used since React 16.6.0.
- Use this method sparingly for components whose rendering time could be neglected.
Don't overuse useCallback.
Pay attention to using bind or arrow functions in render() to avoid creating new values each render cycle.
- For functional components, use useCallback to memoize the callback.
- For class components, define the callback outside of the render() method.
As of React 16, functional components are slightly more performant than class components.
Use code splitting to lazy load components that are not instantly needed with React.Lazy and React.Suspense.
Use React.StrictMode.
- Be aware that StrictMode components may render twice in development mode.
Never mutate props.
Don't use array indexes as keys.
Render lists in dedicated components.
Rethink your mental model regarding useEffect.
Use multiple useEffect calls for independent concerns.

Redux

Prefer normalized state.

Images

Consider using inline SVGs instead of icon fonts.
Use WEBP images with a fallback for older browsers.
Use responsive images, especially for Retina displays.

Code quality

Enforce a zero-warnings policy.
- Avoid handling code isses as warnings. Set linter rules to either "off" or "error".
Avoid hasty abstractions.
- Prefer duplication over the wrong abstraction.
Include units in variable names.

Performance

Find performance issues with Google's PageSpeed Insights.
Enable gzip compression and test it.
Consider avoiding web fonts.
- If you do, notice the performance best practices.
- Use Google WebFonts helper to create an optimized font subset.
Prefer readable code over micro performance optimizations such as performant CSS selectors or using a for loop over forEach.
Serve videos instead of GIFs.

Design

Ensure a thumb-friendly navigational design.
Remove unnecessary borders from design elements.
- Consider replacing borders with box shadows.
Avoid floating labels
Avoid messages under fields.

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.
- Avoid low-contrast font colors.
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 44x44px target click size.

View my accessibility notes for more information.

Security

Use HTTPS everywhere. Yes, your site does need HTTPS.
- Test your SSL rating on SSL Labs.
Define a Certificate Authority Authorization (CAA).
Define a Referrer Policy.
Define a Content Security Policy.
Scan your website for security issues:
- Mozilla Observatory
- securityheaders.io
Hash user passwords using a cryptographically strong algorithm, like Argon2, PBKDF2, Scrypt, or Bcrypt.
Enable Two-Factor Authentication (2FA).

Privacy

Include a privacy notice.
Comply with the EU Cookie Law.
- Check the cookies for a domain with Cookie Metrix.
Collect only the bare minimum amount of data needed for its purpose.

SEO

Verify your site in Google Search Console.
Use canonical URLs to prevent search engines from indexing duplicate content.
Provide a sitemap.
Provide a robots.txt file.
Keep title 60 characters or less.
Keep meta descriptions 160 characters or less.

User experience

Be consistent. Use familiar conventions and apply them consistently.
Provide a way to try the app without signing up:
- Public demo
- Guest account, which can be then easily turned into a full account
Show a different view when there is no data, e.g. a tutorial link or description (examples).
Only provide choices when a good default does not exist.
- Options can be costlier than features.
Provide smart defaults based on frequently chosen input.
Include something funny/goofy.
Hide easter-eggs.
- Send custom HTTP headers.
Provide a search feature, e.g. using OpenSearch.
Ensure a good visual stability, i.e., elements on the page should not shift in ways that users don't expect.
Know when (not) to split a form field into multiple inputs.
Don't set the language of your website based on user location.
Test for unnecessary scrollbars.
Tie the sign up button text to your product.
When adding links to downloadable files, include an information about the file's size and its format.
Mark required input fields.
Redirect a request to /.well-known/change-password to the change-passwords URL.

DevOps

Avoid 2:00 and 3:00 am cron jobs
Prefer the ~all SPF mechanism instead of -all or ?all.

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 which 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

Provide a social media image.

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

Consider the purchasing power parity on product/service pricing.

Writing

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-definint (= optional) clauses (comma)
help (to) do:
- to is optional
- no -ing on the infinitive

Work methods

Project management

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

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

No well-actually's: Do not correct someone about something that's not relevant to the conversation or tangential to what they're trying to say.
No feigning surprise: Do not act surprised when someone doesn't know something.
No backseat driving: Do not lob advice from across the room (or across the online chat) without really joining or engaging in a conversation.
Avoid oppresive language

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.

Related work

License

This work is dedicated to the public domain.

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

darekkay / best-practices

Programming Languages

Labels

Projects that are alternatives of or similar to best-practices