Consistency

About

Consistency in software development eases readability, maintainability, and collaboration between teams. Consistency attains cognitive fluency, as developers process information better when encountering predictable patterns. Furthermore, consistent code reduces the learning curve during collaboration and maintenance.

Enforcing consistency is achieved via defining a clear set of Standards, Best Practices, and Guidelines.

1. Standards. I borrow the definition from ISO standards, where standards are a set of rules to be strictly followed without deviation. Standards must be explicitly defined and not open to interpretation. Because of the "strictness", new standards must go through rigorous testing before being added.
2. Best Practices. The definition for both "Best Practice" and "Guideline" is best defined in this W3C email, although Wikipedia definitions for "Best Practice" and "Guideline" are also accepted for clarification purposes. Best Practices are methods or techniques that consistently show results superior to those achieved with other means and are used as a benchmark. Best Practices are opinionated, in other words, they are specific, and if not applicable to your use case, developer discretion can be applied on whether Best Practices should be adhered to.
3. Guidelines. A Guideline is a tip, a trick, a note, a suggestion, or answer to a frequently asked question. Guidelines are typically not explicitly defined. These are personal tips that can be ignored if a better implementation exists. Hence, guidelines can change frequently.

Philosophically, consistency has also applied in daily life via habits and schedules. Documenting them creates accountability and helps identify iterative improvement over inefficiencies in said habits and schedules.

How to use / contribute this document:

This document is a collection of official Standards, Best Practices, and Guidelines, and does not include unofficial recommendations. Each item must be For each item, my personal interpretation of what / how / why is included.

In this document, 🔴 = Standards, 🟡 = Best Practices, and 🟢 = Guidelines.

Software Development

C

🟡 ClangFormat with LLVM Coding Standards

ClangFormat defaults to format according to LLVM style. The LLVM Coding Standards are broadly applicable to popular open source projects. Generate the default LLVM .clang-format with:

clang-format -style=llvm -dump-config # omitting style defaults to llvm

🔴 Default Compiler Warnings

Before using a linter, C compiler provides extensive warning flags (eg -Wall & -Wextra).

gcc -Wall -Wextra main.c -o output

🟡 Clang-Tidy Linter with LLVM Configuration

LLVM's configuration is more general & applicable for a wide range of topics. Clang-Tidy can be used to lint for LLVM & Google configuration. Generate the default LLVM .clang-tidy with:

clang-tidy --dump-config

Docker

🟡 Building best practices for Dockerfile

A collection of Dockerfile best practices & optimizations for Dockerfile instructions. Apply developer discretion, as certain "best practices" are optional (eg "Build and test your images in CI").

Git

🔴 commitlint for Conventional Commits

"type" field must be strictly be in type-enum. Since commitlint is based on Commit Message Format by Angular, the type definition can be referenced here. For missing type definitions, refer to types of conventional commits by Graphite.

Pull Request Naming Convention

PR commits should be squashed and merged to create a single meaningful clean commit. With this, the PR name is the commit message, & should follow Commit Message Format by Angular.

🟡 gitignore by GitHub

GitHub provides gitignore templates for each OS, language, & version. For monorepos / monoliths, place each gitignore inside each project.

🔴 keep a changelog

Document notable changes between each release inside CHANGELOG.md, which is in the format of keep a changelog.

🔴 Semantic Versioning

"v" prefix is still used for git tag names in the following format as documented in Is "v1.2.3" a semantic version?:

git tag v1.2.3 -m "Release version 1.2.3"

Guidelines for Tags & Releases

• Keep the names of tags & (GitHub) releases consistent (eg "v1.2.3").
• If making a commit message for a tag / release, follow this convention. Note the lack of "v" in the version for messages.

  git commit -m "chore(release): 1.2.3"

  • Reference: Determine the version bump by Nx, Community configurations by semantic-release

Go

🟡 Go Best Practices

Go Best Practices documents some of the patterns that have evolved over time that solve common problems, read well, and are robust to code maintenance needs.

🔴 gofmt Formatter for Go Style Guide

Google's official Go Style Guide is enforced by gofmt, the official Go formatter.

🔴 Staticcheck Linter

State of the art linter for Go.

🟢 Standard Go Project Layout

Basic layout for medium to complex Go application projects.

HTML / CSS

🟡 Prettier Code Formatter with Google Style Guide

See this for handling conflicts between Prettier & a style guide.

🟢 HTML ESLint & CSS Plugin for ESLint Linter

Note that ESLint released official support for CSS linting.

JavaScript

🔴 Prettier Code Formatter with Airbnb Style Guide

Prettier unfortunately does not have a definitive style guide but documents its formatting choices in its rationale.

Note the use of "X Code Formatter with Y Style Guide". Write code according to a style guide (eg Airbnb's Style Guide), & in case of conflicts, prefer Prettier.

🔴 ESLint Linter

Most popular JavaScript linter.

🟢 JSDoc

API documentation generator for JavaScript via code comments. Imperative to document classes, methods, functions & constants (configs).

Markdown

CommonMark, the official specification, has not reached maturity (latest version is 0.31.2 as of 2025). Hence, GitHub Flavored Markdown spec is used. Note that GitHub Flavored Markdown is a strict superset of CommonMark.

🟡 Prettier Code Formatter with Google Markdown Style Guide

See this for handling conflicts between Prettier & a style guide. NOTE: As of 2025, Prettier deletes the closing tag in a Table of Contents, make sure to restore it.

Python

🔴 Ruff Linter & Code Formatter

Ruff performs linting, formatting, & import sorting, reducing toolchain complexity. Ruff is a drop-in replacement for Black, which loosely follows PEP 8.

🔴 uv Python Package Manager

uv is a Python package & project manager (eg via uv init).

But what about pip / pipx?

While uv is intended to be a drop-in replacement for pip, certain differences exist. In general, use uv add instead of pip & uvx (uv tool run) instead of pipx.

Rust

🔴 rustfmt Formatter for the Rust Style Guide

Rust Style Guide defines the default Rust style. The official code formatter is rustfmt.

cargo fmt

🔴 Clippy Linter

cargo check helps to check that the code compiles successfully first. Thereafter, Clippy is the official linter for Rust & it can be used in conjunction with cargo check.

cargo check && cargo clippy

Shell

🔴 shfmt Formatter for Shell Style Guide

Google's Shell Style Guide is the most popular style guide for Shell. shfmt formats with the following flags as specified in the documentation examples:

shfmt -i 2 -ci -bn

🟢 ShellCheck Linter

A static analysis tool for shell scripts.

YAML

🟡 Prettier Code Formatter

The YAML spec does not dictate a style guide, but YAML is self-explanatory.

Digital Life

Linux (Debian / Ubuntu)

cozydot is an automated post-install, update, & config (dotfile) manager for Linux. In the context of consistency, cozydot maintains consistency between multiple systems & ensures reliability by tracking changes made, thus reducing potential errors while setting up.

macOS (Apple silicon)

Guide for setting up the M3 MacBook Air with macOS Tahoe 26.6. The MacBook is both a mobile computer and a primary machine for heavy development work.

1. Install macOS updates via System Settings → General → Software Update. Keep automatic system data files and security updates enabled.
2. Enable FileVault via System Settings → Privacy & Security → FileVault. Store the recovery key in a password manager or enable recovery through the Apple Account.
3. Enable Find My Mac and iCloud Keychain / Passwords. Use iCloud for credentials, recovery, and Apple settings, but keep active repositories, build directories, and package caches outside iCloud Drive.
4. Configure Time Machine to an external drive for system recovery. This is separate from normal file backups and should not replace them.
5. Install the Xcode Command Line Tools:

   xcode-select --install

6. Install Homebrew for Apple silicon. Keep Homebrew under /opt/homebrew and ensure its shell environment is configured with brew shellenv.
7. Install Git, GPG, and other command-line tools through Homebrew. Keep macOS-native binaries separate from Linux / WSL binaries.
8. Configure Git, SSH, GPG signing, and credentials. Store private keys in the macOS keychain or another encrypted password manager vault, not in the repository.
9. Use cozydot for application installation and dotfile management. Keep macOS paths and settings separate from Linux / WSL packages.
10. Recommended defaults:
    • Use a strong login password and require it immediately after sleep or the screen saver.
    • Enable automatic updates for macOS and Homebrew. Review major macOS upgrades before installing them on active development projects.
    • Use the native keyboard, trackpad, and window-management settings first. Add a third-party utility only when a specific workflow is missing.
    • Keep development projects in the local filesystem rather than iCloud Drive or external volumes.

cozydot handles macOS application installation and configuration alongside the existing Linux / WSL setup. Keep platform-specific paths, packages, and settings separate rather than sharing commands blindly between systems.

Windows

Guide for installing Windows 11 & post-install.

1. Install Windows 11. Bypass network connection by opening Command Prompt with Shift + F10, then running OOBE\BYPASSNRO.
2. After install finishes, install updates & drivers via Settings.
3. Run Win11Debloat with standard options.
4. Install Office C2R, then activate with Microsoft Activation Scripts.
5. Install Microsoft Visual C++ Redistributable dependency.
6. Enable Hyper-V, then install WSL with wsl --install.
7. Download your preferred NerdFont & add font.

Installing Apps

1. Git (Windows & WSL):
   • NOTE: Install Git & GPG separately as WSL uses Plan 9 to bridge Windows & Linux. This allows sharing files but can cause compatibility issues with binaries.
   • Installing & configuring Git on Windows:
     1. Install Git for Windows & Gpg4win. Copy this .gitconfig over.
     2. Generate a new GPG key & copy the key ID with:

        gpg --full-generate-key
        gpg --list-secret-keys --keyid-format=long

        • NOTE: Use the same email as your GitHub account.
     3. Storing credentials with Git Credential Manager with:

        git config --global credential.helper "C:/Program\ Files/Git/mingw64/bin/git-credential-manager.exe" # or git credential-manager configure
        git config --global credential.credentialStore wincredman
        git config --global gpg.program "C:/Program Files (x86)/GnuPG/bin/gpg.exe"

        • NOTE: If GPG is not desired, remove lines pertaining to GPG.
        • Reference: Caching your GitHub credentials in Git, Credential stores
     4. [Optional] Export signing key & owner trust with:

        gpg --export-ownertrust > otrust.txt; gpg --export <key ID> > private.asc

   • Installing & configuring Git on WSL:
     1. Install git, gpg, pass, Git Credential Manager with the following command, & copy this .gitconfig over.

        sudo apt-get update
        sudo apt-get install -y git gpg pass
        curl -sL https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb -o /tmp/gcm.deb
        sudo dpkg -i /tmp/gcm.deb

     2. Import GPG key & owner trust on WSL with:

        gpg --import-ownertrust /mnt/c/Users/<otrust path>
        gpg --import /mnt/c/Users/<private.asc path>

   • On both Windows & WSL .gitconfig, set your username, email, & the signing key (key ID).
     • Reference: Setting your commit email address, Telling Git about your signing key
2. VS Code (Windows & WSL):
   1. Install VS Code & the WSL extension as per developing in WSL.
3. Docker (Windows & WSL):
   1. Follow the steps in turn on Docker Desktop WSL 2 to install Docker Desktop for Windows & use WSL 2 based engine.
   2. [Optional] Follow the steps in enabling Docker support in WSL 2 distributions to enable Docker command in WSL by setting the default distro for WSL. This typically defaults to Ubuntu & does not require further action.
   • NOTE: Follow best practices to optimize your experience.
   • NOTE: Set logging driver to local in daemon.json to prevent disk exhaustion.

cozydot supports WSL too.

Android

Miscellaneous

🟢 Password Manager Vault Structure

The purpose of having a structured (sorted / tagged / labeled) vault is mainly aesthetical. Retrieving passwords should be done via search. Refer to Gmail's philosophy of Search, don't sort. Nevertheless, here is my vault structure:

• banking 💳: Also includes crypto logins. eg Coinbase, PayPal
• commerce 🛍️: eg Shein, Temu
• credentials 📄: eg Coursera, Credly
• dev 👨‍💻: For developer work. eg Claude, GitHub
• emails ✉️
• entertainment 🎮: eg Netflix, Steam
• gov 🏛️: For logins into government services
• hardware ⚙️: Laptop / phone logins & GPG / SSH keys
• IDs 🪪: Personal identification & family members
• socials 🌐: Social media. eg Discord, Instagram, X
• utilities 🛠️: Other random permanent logins. eg Mozilla, Strava
• No Folder: Temporary logins. eg uni applications

Credits

• adore_blvnk