How Google Developers “do Not” Write Their Comments | by Minhaz | May, 2022

Writing documentation is an important part of coding. Here are some practices we “do not” follow at Google while writing code comments.

Photo by Cess Idul on Unsplash.

I didn’t come up with this topic by myself. I have always believed this to be a fairly subjective topic. It still is — but, a few days back I came across the following article:

After going through this article I felt — this has nothing to do with any Google internal or external guidelines. The author didn’t present any references we could cross check either (as of May 1st 2022). To me, some of the recommendations by the author appear to be “anti-practices”.

And I did advocate for those in the comments section and it seemed to resonate with the other readers. But, that said — the article continues to exist. So, I felt like writing another take on the same topic with my opinions.

This article is based on externally available Open source documentation guidelines from Google, other few open resources available online and my own personal experience working for these organizations. I hope you find my research worthwhile.

Disclaimer: This article is not affiliated with any organization I work for and are purely reflection of my thoughts, personal research and experience.

Photo by the Author (Minhaz) on Unsplash.

It’s easy to write something a computer understands, it’s much harder to write something both a computer and human understand.

Here’s a list of ways you should not write documentation for your code.

For each point, I am also adding my real suggestions/recommendations prefixed with [RS] = [Real suggestion].

Here we go!

Explain every line of code!

You should never make an assumption about who is going to read your code in the future. Hence, it’s desirable to explain every line of code. Here’s an example

// Assign a as inverse of input and then b as a ^ (1/2.2f).
int a = 1 / input_value;
int b = pow(a, 1.0f/2.2f);
// Now return half of b.
return b / 2.0f;
Meme: Code comments be like this. Source: reddit. Saw this image in the source article from StackOverflow blog by Ellen Spertus.

[RS] The primary purpose of the inline comments is to provide information that the code itself cannot contain, for example “why” something is written the way it is.

In general, prefer to write code for human first, computers second. This is of course a rule with exception (like sometimes we need to write hard-to-read code for performance reasons).

An example of this was presented in the article linked above:

// matches US social security number
let pattern = Pattern("^\{3}-\d{2}-\d{4}$")

I think this documentation is largely redundant. Instead, you can always write the code like this:

let socialSecurityPatterUS = Pattern("^\{3}-\d{2}-\d{4}$")

Here’s another example from the StackOverflow blog article

private static Node getBestChildNode(Node node) {
Node n; // best child node candidate
// rest of the code below to find the best node.
}

Documentation isn’t supposed to be used as an excuse for bad code. You can always replace the code to be easy to read like this:

private static Node getBestChildNode(Node node) {
Node bestNode;
// rest of the code below to find the best node.
}

Although, there is one case where it’s useful to be verbose while writing documentation — when you are writing documentation for methods in your interfaces (or public methods in the classes).

At this point, the documentation is supposed to share more information on

  • What the method does?
  • What kind of inputs it expects? particularly if certain assumptions are made about the inputs.
  • What kind of output to expect?
  • If the method can fail, under what conditions it would fail?

So much so that, a reader should not have to read the implementation code to understand all these.

Documentation has to be perfect, even if the code isn’t

Documentation is a serious business! Think of writing documentation as writing an article on Medium.

Write your first draft > read it aloud for yourself > if possible get it reviewed by peers (before the actual code review) > fix the grammar > send it for code review (try getting 3+ approvals) > read it once more before submitting.

In fact, during the sprint planning, you should add extra story items just for writing documentation.

[RS] Your documentation should be as good as possible within a reasonable time frame. Follow the good over perfect rule when writing documentation. Docs can never be perfect and it’s ok to improve them gradually over time.

Write documentation so good, you never need to update it!

Code may come and go! We write them, modify them and sometimes later delete them. But the documentation is different — they shouldn’t change no matter what.

Make it your measure of success — how often you don’t change the documentation when changing code.

This is what happens if the documentation is not updated with code. Meme from 9gag.com

[RS] Documentation is supposed to be kept fresh — if there is a major change in code that starts to contradict the documentation, the documentation should be updated with the code.

Do not remove documentation when removing code!

Similar to the point above, once you have written such good documentation it would be a shame to just remove them later on.

In case you have to remove the actual code — just keep your documentation there for fellow colleagues to read and absorb! It’s a chance for others to learn about your greatness!

[RS] Goes without saying, documentation goes when the code goes.

If you forked the code from some external link, keep it to yourself

There is a lot of hard work that goes into finding code examples online that solves a nontrivial part of the problem. It often comes with additional context. But other don’t need to know about it! In future, if something comes up — others can always reach out to you!

[RS] No! Reusing the code is a smart move. It’s always a great idea to add source to a document, external link or code path if the forked code has nont-rivial logic like uses magic constants. See this example

// Converts YUV to RGB.
//
// Magic constants from https://en.wikipedia.org/wiki/YUV
void yuv2rgb(uint8_t y, uint8_t u, uint8_t v) {
int r = y + (1.370705 * (v - 128));
int g = y - (0.698001 * (v - 128)) - (0.337633 * (u - 128));;
int b = y + (1.732446 * (u - 128));
r = clamp(r, 0, 255);
g = clamp(g, 0, 255);
b = clamp(b, 0, 255);
return r, g, b;
}

This is often applicable for self-written code as well. If you have magic constants derived from research, investigation or tuning, add the link to source document for readers to get more context.

Guidelines are for code, documentation is personal

At a team or company level, it makes sense to have guidelines for writing code. It has several advantages. But the documentation is a personal matter and should be the choice of the code author.

[RS] While this is true to some extent, general documentation guidelines should be a part of the style guide followed by an organization. This has several advantages starting from consistency all the way to reducing code review and submission time.

However, the standards of documentation review should be different from the standards of code review. Reviewers can and should ask for improvements, but in general, the author should always be able to invoke the “Good Over Perfect Rule”.

If you are interested in learning about code reviews in general, you can read the following article:

Automations are for warehouses, documentation is handwritten like a poem

Automations are useful in warehouses. If you are really eager, automation can be helpful in code review tools to reduce the time to submission. But documentation is personal as mentioned above. No computer or automation should tell us how to write documentation!

[RS] Well, as stated above — there needs to be more flexibility around how to write documentation in code. It’s not fun to receive subjective opinions on how a certain code comment should look like. But there are advantages to using static analysis tools — particularly one that can find spelling or grammatical errors. This will help you write more accurate comments for the wider audience to read and understand!

Programs must be written for people to read and only incidentally for machines to execute.

By famed MIT professor Hal Abelson. So true — the machines don’t care about these comments, they strip them out the first chance they get!

Once again, for this topic — it’s a borderline subjective area. It’s hard to define a single set of rules that work best for all. Although, having some common agreed-upon guidelines helps ensure consistency.

In the past, I tried to demystify a similar work from another author claiming to be Google lead and it was well-received by the Medium readers:

Thanks for reading! Looking forward to hearing your opinions

Leave a Comment