Why Software Needs Checklists
Software engineering is creative, yes - but it's also deeply procedural. Each time we write or deploy code, there are dozens of small, crucial decisions that can either support a solid product or introduce dangerous inconsistencies. While automated tools catch many issues, structured pre-checks help ensure that the right things are done at the right time, regardless of how experienced the developer is.
Borrowing from Aviation: A Proven System
Checklists don’t mean you’re not a good pilot - they mean you care enough to not rely on memory when stakes are high.
In aviation, checklists prevent overlooked steps that could be fatal. In software, while lives may not always be on the line, systems can crash, data can be lost, and customer trust can be damaged. That’s why applying a similar system to our workflows can make a huge impact. The purpose is not to add bureaucracy but to embed a culture of reliability and shared responsibility among team members.
Introducing the Developer's Pre-Flight System
This system is broken into four stages that match key moments in your development workflow. Each one has its own purpose, and together, they build a strong safety net that can prevent both small errors and critical failures.
- Pre-Code Checklist
- Pre-Commit Checklist
- Pre-Push / Pull Request Checklist
- Pre-Deployment Checklist
Stage 1: Pre-Code Checklist
Think of this as your "cockpit prep". It ensures you understand the destination and how to get there. Before you touch the keyboard, it's critical to align with the project goals, clarify the scope, and ensure you're ready for uninterrupted development.
- Are requirements clear? Without a solid understanding of what needs to be built, you risk going in the wrong direction. Requirements should be written down, approved, and understood - preferably with examples or acceptance criteria.
- Has the task been broken down? Large tasks should be broken into manageable, testable pieces. This reduces complexity, makes progress more visible, and allows you to deliver value incrementally.
- Do you understand the business case? Understanding why a feature matters enables you to make smarter decisions and avoid unnecessary work. It helps you prioritize edge cases and error handling based on real-world usage.
- Can you reuse something? Check if a similar component or function already exists. Reinventing the wheel increases technical debt and future maintenance. Code reuse also promotes consistency in behavior and user experience.
- Do you have access? Make sure you can access the repo, databases, and environments. Being blocked later can kill momentum and cause rushed decisions. Setting things up ahead saves frustration.
- Any setup needed? Containers, API keys, feature flags, or cloud credentials---prepare your local and test environment. Time spent here pays off in smoother development later.
Stage 2: Pre-Commit Checklist
This is your "before engine start". You're about to put your code into the shared codebase, so you need to ensure that your work meets the agreed technical standards. A good pre-commit checklist catches issues early, reducing friction in peer reviews and CI failures.
- Did it compile/run locally without errors? You’d be surprised how many commits break the build. Always confirm your changes compile and run locally in a clean state.
- Did all tests pass? Whether unit, integration, or snapshot tests---these must pass before committing. Tests are your safety net, especially for shared or legacy codebases.
- Did you format/lint the code? Consistent code style prevents nitpicky review comments and merge conflicts. Tools like Prettier, Black, or ESLint enforce team-wide conventions automatically.
- Did you include/exclude sensitive data? Double-check for secrets, tokens, private keys, or credentials accidentally left in logs, config, or comments. Use a secrets scanner to be safe.
- Is your commit message clean? Clear, concise commit messages help your team (and future you) understand what was done and why. Follow a style guide like Conventional Commits for consistency.
- Have you cleaned up commented-out code? Leftover debug code clutters the repo and may confuse others. If you need it later, keep it in a draft branch or snippet manager.
Automation Tip:
Most of these can be automated with Git hooks. Add them to your workflow to enforce checks locally before the commit even happens:
pre-commit- Great for running multiple checks with a YAML config (Python ecosystem)Husky- Perfect for front-end projects using Node.js, React, etc.Lefthook- A language-agnostic alternative that scales well with teams
Stage 3: Pre-Push / Pre-Pull Request Checklist
This is your "before takeoff". Now that the code is committed, you're about to share it with the team or push it to CI. This stage focuses on validation, documentation, and presentation.
- Is your branch up to date? Rebase or merge changes from the target branch to avoid conflicts later. CI pipelines also tend to break on outdated branches.
- Did you test the feature end-to-end? Especially for UI and APIs. Don’t just trust unit tests - simulate how a user or client would interact with the system.
- Have you included visuals for UI changes? Screenshots, screen recordings, or GIFs help reviewers understand what changed visually and quickly catch regressions.
- Did you write or update tests? New features and bug fixes should have corresponding tests. This increases confidence for future refactoring.
- Are migrations or scripts documented? Schema changes, cron jobs, or background workers need extra attention. Annotate how to test them or validate results.
- Are changes explained in the PR? A good PR description saves time. Explain the "why", not just the "what". Link related issues or documentation.
Stage 4: Pre-Deployment Checklist
This is the final "before landing". You’re about to deploy changes to a live environment - this is high-stakes territory. The focus is on risk mitigation, observability, and communication.
- Has it passed QA or staging approval? Only code that has been verified in a production-like environment should go live. Manual QA or automated smoke tests can help.
- Are rollback steps in place? Every deployment should have a way to revert. Feature flags, database backups, and versioning are crucial tools here.
- Are logs and alerts configured? Ensure your observability stack is ready to detect and report issues. Alert fatigue is real - use thresholds wisely.
- Are environment variables correct? Check staging vs production configs. Misconfigured secrets or toggles can silently break functionality.
- Have you notified stakeholders? Make sure everyone impacted knows when and what is being deployed. Consider release notes or internal broadcast tools.
- Is this a good time to deploy? Avoid deploying just before weekends, holidays, or after hours unless it’s absolutely necessary and supported.
Post-Flight: The Retrospective Checklist
A good pilot always debriefs. Developers should too. After a major feature or deployment, take time to reflect and capture learnings. These discussions create a culture of continuous improvement and shared learning.
- What worked well? Identify and repeat the successful patterns, both technical and team-related.
- What was painful? Address frustrations head-on. Maybe a test was flaky, or a tool slowed you down. Fix the bottlenecks.
- Were there near-misses? Bugs that almost made it to production are goldmines for process improvement. Analyze and learn.
- How can the checklist improve? Was anything missing or unnecessary? Trim or enhance the checklist to keep it lean and relevant.
Final Thoughts: It's Not About Perfection
Checklists don’t make you a better developer by themselves. But they help you bring your best self to the table, even when you’re tired or distracted. They reduce cognitive load, prevent silly mistakes, and create a safety net for your whole team.
Discipline equals freedom. -- Jocko Willink
By using checklists, we build habits of consistency, reduce errors, and deliver better, safer software. Just like aviation relies on structure to fly safely, software teams can rely on rituals that support excellence---even on tough days.
Want to try it yourself?
Start with a simple markdown file in your repo or a shared Confluence page. Encourage your team to suggest improvements. Over time, your checklist becomes a trusted co-pilot in your software journey.
Ready for takeoff?