Anti-Patterns & System Documentation
Identifying destructive version control behaviors and the engineering necessity of ADRs and comprehensive READMEs.
Destructive Anti-Patterns in Git
A powerful tool used without discipline becomes a liability. While Git’s distributed nature protects against central server failures, it relies entirely on developer discipline to maintain a coherent project history. The following anti-patterns routinely sabotage collaborative engineering teams.
1. The Force Push on Shared Branches
Executing git push --force overwrites the remote repository’s history with the developer’s local history. If another engineer has already pulled the remote branch and based their work on it, a force push will orphans their commits, causing catastrophic merge conflicts when they attempt to push their work.
main, develop, or any branch shared by multiple engineers. Limit force pushing strictly to personal, ephemeral feature branches (usually after performing a local interactive rebase to clean up your commit history before a pull request).2. The “Dirty” Commit
A commit should encapsulate a single, logical unit of work. A dirty commit mixes multiple unrelated changes into one snapshot—for example, fixing a database query, formatting an unrelated CSS file, and updating a library dependency all at once. If the dependency update breaks the build, rolling back the commit (using git revert) will also unintentionally destroy the valid database fix.
3. Ghost Commits
Commits with messages like "fixes", "WIP", or "typo" provide zero historical context. When a regression is identified six months later via git blame, a ghost commit forces the debugging engineer to reverse-engineer the original author’s intent from raw code diffs.
Documentation as Code
Code explains how a system operates. Documentation explains why the system exists and how to interact with it. In professional environments, documentation is treated with the same rigor as source code; it lives in the repository and goes through the same review process.
The System Entry Point: The README
A repository without a README.md is a locked black box. At minimum, a professional README must contain:
- System Purpose: A high-level description of the business or technical problem the software solves.
- Prerequisites & Dependencies: The exact language versions, system packages, and environment variables required to run the code.
- Execution Instructions: The precise CLI commands to build, test, and run the application locally.
Architectural Decision Records (ADRs)
When an engineering team makes a massive structural choice (e.g., migrating from PostgreSQL to MongoDB, or choosing Trunk-Based branching over GitFlow), the code itself cannot explain why this decision was made.
An ADR is a short text file stored within the repository (often in a docs/adr/ directory) that captures the context, the considered alternatives, and the specific reasons a major architectural decision was approved. It serves as institutional memory, preventing future engineers from continuously questioning or unknowingly reverting critical design choices.
Test Your Understanding
Q:An engineer submits a pull request containing a single commit with 4,500 lines of changed code spanning the database schema, the API routing layer, and the frontend UI. The code works perfectly. Should this pull request be approved? Reveal ▾
git reset to unstage the changes, and then selectively commit the database schema, the API, and the UI as distinct, logical units of work.