Course contentsShow
← Software Engineering
Lesson 111 of 1,9333. Collaboration with GitFree lesson

Commit Message Body: The Why, Not the What

Learn to explain motivation, context, and trade-offs in commit bodies rather than restating code changes.

Commit Message Body: The Why, Not the What

What you'll learn: How to write commit message bodies that explain the reasoning behind your changes, not just repeat what the code does.

The Core Idea

Your commit's subject line tells what you changed (following the 50/72 rule you just learned). The body should explain why you made those changes, what problem they solve, and what alternatives you considered.

Think of it like explaining a decision to a teammate who wasn't in the room:

  • Bad: "Added validation to the login form" (this just repeats what the diff shows)
  • Good: "Added validation to prevent empty password submissions. Users were accidentally clicking submit without entering credentials, then getting confused by cryptic server errors. Client-side validation provides immediate feedback."

What Goes in the Body

Focus on:

  • Motivation: What problem does this solve? What bug does it fix?
  • Context: What situation led to this change?
  • Trade-offs: Why this approach over alternatives?
  • Side effects: What else does this impact?

Example

Fix password validation on login form

Users reported confusion when submitting the form with empty passwords,
receiving a generic 500 error from the server. Adding client-side
validation catches this early and shows a clear message.

Considered doing this server-side only, but the round-trip delay
created poor UX. Client-side validation is faster and degrades
gracefully if JavaScript is disabled (server still validates).

Notice how the code changes are obvious from reading the diff, but the reasoning requires the body.

Key Takeaway: Your commit body should answer "Why did I make this decision?" not "What did I change?"—the diff already shows what changed.