How to write good commit messages and pull requests: a team guide

Good commit messages and PR descriptions are documentation that writes itself. They preserve the context of why a change was made, which is often more important than what changed. Future developers including your future self will thank you. Good communication in commits and PRs distinguishes professional engineers.

Structure your commit messages with a concise subject line and an optional body. The subject line should complete the sentence "If applied, this commit will..." for example, "Add rate limiting to the login endpoint" or "Fix race condition in cache invalidation". Keep the subject under 50 characters. The subject line is what appears in git log summaries and should tell the whole story at a glance.

Include the "why" in the commit body. The code shows what changed. The commit message should explain why. What problem was this change solving? What alternatives were considered? What context would help someone understand this decision in six months? A good commit body answers these questions. The diff shows the mechanism; the message shows the motivation.

Link commits to issues or tickets. A reference like "Closes #427" or "Related to PROJ-123" creates traceability between code changes and the work that motivated them. This is invaluable for debugging production issues and understanding historical decisions. Traceability turns commits into a searchable knowledge base.

Write PR descriptions that set context for reviewers. Explain what the PR does, why it's needed, and how it's structured. Highlight areas you want specific feedback on. Include screenshots or screen recordings for UI changes. A good PR description saves reviewers time and produces better reviews. The quality of your PR description determines the quality of your code review.

Keep PRs small and focused. A PR should do one thing and do it well. Large PRs are harder to review, more likely to contain bugs, and take longer to merge. Split large changes into logical, independently reviewable PRs. A good rule: a PR should be reviewable in 30 minutes or less.

Use PR templates to ensure consistency. Templates remind contributors to include context, screenshots, testing notes, and migration instructions. They also set expectations for what a good PR looks like. Standardized PR formats reduce cognitive load for reviewers and ensure nothing important is forgotten.

Respond to review feedback promptly and graciously. Review is a conversation, not an evaluation. Thank reviewers for their time, explain your decisions when you disagree, and make requested changes when they improve the code. Good-faith engagement in code review builds team trust. How you respond to feedback says more about you than how you write code.

Practical Implementation

Adopt a mindset of continuous improvement. Every project, every sprint, every incident is an opportunity to learn and improve. Hold retrospectives after major milestones and incidents. Write down lessons learned and share them with your team.

Build systems that are easy to change. Good modularity, comprehensive tests, and clear documentation make change safe. The cost of change in a well-designed system should be proportional to the complexity of the change, not the size of the codebase.

Common Challenges

The biggest challenge in engineering is managing complexity. Systems naturally grow more complex over time. Fight this trend with deliberate effort: refactor aggressively, delete dead code, simplify interfaces, and document architecture decisions.

Communication overhead grows quadratically with team size. The more people involved in a decision, the longer it takes. Keep teams small (6-8 people) and give them autonomy over their domain. Use written proposals for cross-team decisions to allow asynchronous collaboration.

Real-World Application

A practical engineering practice: write a one-page design document for any change that takes more than a day. Include the problem, proposed solution, alternatives considered, and key risks. Share it with stakeholders for feedback before writing code. This simple practice prevents costly wrong turns.

Key Takeaways

Fight complexity continuously. Keep teams small. Write things down. Learn from everything. The best engineers build systems that make future changes easy.

Advanced Implementation

Implement architecture decision records for every significant technical decision. An ADR captures the context, decision, consequences, and alternatives. Over time, ADRs become the definitive history of your system's evolution. They answer the question "why did we do it this way?" that future engineers will inevitably ask.

Use RFCs (Request for Comments) for major changes. An RFC is a written proposal that is shared with the team for review before implementation begins. RFCs surface issues early, incorporate diverse perspectives, and create a shared understanding of the design. The time invested in writing an RFC is repaid many times over by avoiding wrong turns.

Knowledge Management

Build a shared team knowledge base. Common wisdom and tribal knowledge should be documented and accessible. Use a wiki, README files, or a documentation platform. Keep documentation up to date as part of the definition of done for each task.

Implement brown bag sessions where team members share knowledge on topics of interest. Weekly 30-minute sessions on any technical topic build a culture of learning and sharing. The best teams are those where everyone is both a teacher and a student.

Common Mistakes and How to Avoid Them

The most common engineering mistake is underestimating the value of simplicity. Complex solutions are harder to debug, harder to change, and harder to operate. Always ask: "What is the simplest thing that could possibly work?" The simplest solution is usually the best one, at least as a starting point.

Another frequent error is not writing things down. Tribal knowledge that is not documented becomes a bottleneck. Decisions that are not recorded cannot be revisited. Architecture that is not described cannot be understood. Write down decisions, designs, and processes.

Conclusion

Great engineering is about managing complexity, making good decisions, and building systems that are easy to change. Invest in simplicity, documentation, and testing. The best engineers are not the ones who write the most code they are the ones who build the most value with the least complexity.

Getting Started

If you are new to the engineering field, focus on building a strong foundation in the fundamentals. Learn how computers work CPU, memory, storage, networking. Learn how operating systems work processes, threads, file systems, networking stacks. Learn how programming languages work compilers, interpreters, type systems, memory management. These fundamentals rarely change, while frameworks and tools come and go.

Develop strong debugging skills early. Learn to use debuggers, profilers, and logging effectively. Learn systematic debugging techniques like binary search and hypothesis testing. Good debugging skills make you productive from day one and improve every tool you learn.

Pro Tips

Write code that is easy to delete. The best code is code that can be safely removed when requirements change. Loose coupling, clear interfaces, and comprehensive tests make code deletable. Code that is hard to delete becomes permanent technical debt that constrains future development.

Read code more than you write it. Reading production code, open-source libraries, and well-written codebases teaches patterns and practices that improve your own code. Code review is one of the best learning opportunities review your teammates' code and ask them to review yours.

Related Concepts

Understanding system design helps you build systems that work at scale. Learn about load balancing, caching, database scaling, message queues, and microservices. System design interviews test this knowledge, but more importantly, system design skills help you build better systems regardless of scale.

Understanding how to measure engineering effectiveness helps you improve your team's performance. Learn about DORA metrics (deployment frequency, lead time, mean time to recovery, change failure rate) and how to improve them. Data-driven improvement is more reliable than intuition-based improvement.

Action Plan

This week: read the codebase for one system you do not usually work on. Understand its architecture, data flow, and design decisions. Share what you learned with your team.

This month: refactor one piece of code that is hard to understand or change. Make it easier to read and modify. Add tests if the code does not have them.

This quarter: learn a new technology that is outside your comfort zone. If you are a frontend developer, build a backend service. If you are a backend developer, build a frontend component. Cross-disciplinary knowledge makes you a more versatile engineer.

-

Rizwan Saleem | https://rizwansaleem.co