Write better comments by removing "we"

By removing unnecessary usages of "we" and being direct and explicit, you can increase the signal-to-noise ratio of your comments.

Programming note: This is a rant post. I plan to do these every few months when the mood strikes me. I’ll be back to my current events posts on Monday!

In every codebase I’ve ever worked in, people have used the word “we” in inline comments. Here’s an example from the Kubernetes codebase:

// We should check if resourceVersion is already set by the requestor
// as it might be older than the pod we just fetched and should be
// honored.

I’m not a Kubernetes developer so I can’t tell you exactly why the code exists. But I can show you that the comment is simpler and more direct if you remove “we” and state what is meant as plainly as possible.

Here is a version without “we” that keeps the original developer’s writing style:

// Check if resourceVersion is already set by the requestor as it
// might be older than the pod from getPod and should be honored.

The edited version is better for three reasons:

1. The first “We should” can be removed without changing the meaning at all. It softens the language for no reason.

2. “pod from getPod” is more explicit than “pod we just fetched.”

3. The entire comment’s signal-to-noise ratio is higher because of the previous 2 points.

Every large codebase I’ve ever examined has “we” in comments. Here are examples from Linux, Ruby, LLVM, Bluesky Social, Tensorflow, SQLite. Basically anywhere you check, you will find “we.” Hell, I wouldn’t be surprised if I added “we” in some comment in the past year, and I think it doesn’t belong!

So where does it come from? It’s mostly the author’s we, where a generic third person is referenced. “By adding 2 and 3, we get 5.” Some usages are also the editorial we, where “we” is a fancy substitution for saying “I” everywhere. And I’ve worked around programmers long enough to know that some uses are the royal we, a practice noted by Wikipedia as being typically used by “a single person who is a monarch or holds a high office to refer to themself.”

I want to make my takeaway as clear as possible. So here it is, alone and bold:

Instead of saying “we” in code comments, directly and explicitly state what you mean.

Here, “direct” means that you should cut to the chase and “explicit” means that you should be specific.

Let’s look at the example above again. The “We should” is not direct and the sentence can survive without it. It delays the point you are trying to make. Just remove it.

How about the other one, “the pod we just fetched”? This is a little indirect. If the variable had a descriptive name we could refer to it, but since the variable name is “pod” we avoid ambiguity by changing it to “the pod from getPod,” which is specific and concise.

When is the appropriate time to bring this up with your colleagues? Never!¹ If you read this and you agree with me, you dig a grave. You find that feeling deep inside and you bury it. Personally, I never mention this in code reviews. My coworkers produce good work and they shouldn’t waste their time on my pet peeves. If a comment has other problems, sometimes I’ll suggest a rewrite that omits the “we.” Sometimes I’ll rewrite a comment if I’m modifying the code already. But it’s not worth it to mention. I just want you to focus on improving your own writing.

Examples of good usages of “we” in code comments

You should use “we” when you can identify the group of people included in “we.”

It could look like anything:

You could be referring to your team, your project, or your company: “We acquired a license from this library for this use case, see this link for details.”

You could be referring to people who made a decision: “We met with the auth team and together we devised this caching strategy to avoid overloading the service.”

It could be in comments that are real documentation. What is real documentation? Something that tells you something without reading the code directly. For example, many programming languages support exporting comments as documentation. When you’re reading documentation for a library or a programming language, there’s an implicit understanding that the word “we” means “the community of users for this service.” So I think it’s great to use “we” in code comments that are also meant to be exported into standalone documentation.

1. That’s right, I’m the first person to admit that I shouldn’t have written this newsletter to begin with.