Skip to content

Commit

Permalink
Update intro to emphasize "Why?"
Browse files Browse the repository at this point in the history
Because when a future reader is trying to understand a change, the reason why is often the most important (and sometimes hardest to find).

PiperOrigin-RevId: 632610202
  • Loading branch information
code-health-devguide-copybara authored and copybara-github committed May 10, 2024
1 parent 900d9b0 commit 50d0e52
Showing 1 changed file with 22 additions and 4 deletions.
26 changes: 22 additions & 4 deletions review/developer/cl-descriptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,35 @@



A CL description is a public record of **what** change is being made and **why**
it was made. It will become a permanent part of our version control history, and
will possibly be read by hundreds of people other than your reviewers over the
years.
A CL description is a public record of change, and it is important that it
communicates:

1. **What** change is being made? This should summarize the major changes such
that readers have a sense of what is being changed without needing to read
the entire CL.

1. **Why** are these changes being made? What contexts did you have as an
author when making this change? Were there decisions you made that aren't
reflected in the source code? etc.

The CL description will become a permanent part of our version control history
and will possibly be read by hundreds of people over the years.

Future developers will search for your CL based on its description. Someone in
the future might be looking for your change because of a faint memory of its
relevance but without the specifics handy. If all the important information is
in the code and not the description, it's going to be a lot harder for them to
locate your CL.

And then, after they find the CL, will they be able to understand *why* the
change was made? Reading source code may reveal what the software is doing but
it may not reveal why it exists, which can make it harder for future developers
to know whether they can move
[Chesterton's fence](https://abseil.io/resources/swe-book/html/ch03.html#understand_context).

A well-written CL description will help those future engineers -- sometimes,
including yourself!

## First Line {#first-line}

<a id="firstline"></a> <!-- Keep previous permalink to avoid breaking old links. -->
Expand Down

0 comments on commit 50d0e52

Please sign in to comment.