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

Writing documentation is a crucial a part of coding. Listed below are some practices we “don’t” observe at Google whereas writing code feedback.

Photograph by Cess Idul on Unsplash.

I didn’t give you this subject on my own. I’ve all the time believed this to be a reasonably subjective subject. It nonetheless is — however, just a few days again I got here throughout the next article:

After going by this text I felt — this has nothing to do with any Google inner or external guidelines. The writer didn’t current any references we might cross test both (as of Could 1st 2022). To me, a number of the suggestions by the writer seem like “anti-practices”.

And I did advocate for these within the feedback part and it appeared to resonate with the opposite readers. However, that stated — the article continues to exist. So, I felt like writing one other tackle the identical subject with my opinions.

This text relies on externally available Open Source documentation guidelines from Google, different few open sources out there on-line and my very own private expertise working for these organizations. I hope you discover my analysis worthwhile.

Disclaimer: This text shouldn’t be affiliated with any group I work for and are purely reflection of my ideas, private analysis and expertise.

Photograph by the Author (Minhaz) on Unsplash.

It’s straightforward to put in writing one thing a pc understands, it’s a lot tougher to put in writing one thing each a pc and human perceive.

Right here’s an inventory of how you shouldn’t write documentation to your code.

For every level, I’m additionally including my actual recommendations/suggestions prefixed with [RS] = [Real suggestion].

Right here we go!

Clarify each line of code!

You need to by no means make assumption about who’s going to learn your code sooner or later. Therefore, it’s fascinating to clarify each line of code. Right here’s an instance

// Assign a as inverse of enter after which 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 feedback be like this. Supply: reddit. Noticed this picture within the the supply article from StackOverflow blog by Ellen Spertus.

[RS] The first objective of the inline feedback is to supply data that the code itself can not comprise, for instance “why” one thing is written the best way it’s.

Typically, choose to put in writing code for human first, computer systems second. That is after all a rule with exception (like typically we have to write hard-to-read code for efficiency causes).

An instance of this was introduced within the article linked above:

// matches US social safety quantity
let sample = Sample("^3-d2-d4$")

I believe this documentation is basically redundant. As a substitute, you’ll be able to all the time write the code like this:

let socialSecurityPatterUS = Sample("^3-d2-d4$")

Right here’s one other instance from the StackOverflow blog article

non-public static Node getBestChildNode(Node node) 
Node n; // finest youngster node candidate
// remainder of the code under to search out one of the best node.

Documentation isn’t supposed for use as an excuse for unhealthy code. You may all the time change the code to be straightforward to learn like this:

non-public static Node getBestChildNode(Node node) 
Node bestNode;
// remainder of the code under to search out one of the best node.

Though, there may be one case the place it’s helpful to be verbose whereas writing documentation — if you end up writing documentation for strategies in your interfaces (or public strategies within the courses).

At this level, documentation is meant to share extra data on

  • What the tactic does?
  • What sort of inputs it expects? notably if sure assumptions are made concerning the inputs.
  • What sort of output to count on?
  • If the tactic can fail, beneath what circumstances it will fail?

A lot in order that, a reader mustn’t need to learn the implementation code to grasp all these.

Documentation needs to be good, even when the code isn’t

Documentation is a severe enterprise! Consider writing documentation as writing an article on Medium.

Write your first draft > learn it aloud for your self > if attainable get it reviewed by friends (earlier than the precise code overview) > repair the grammar > ship it for code overview (strive getting 3+ approvals) > learn it as soon as extra earlier than submitting.

In actual fact, throughout the dash planning, you must add additional story objects only for writing documentation.

[RS] Your documentation ought to be pretty much as good as attainable inside an affordable timeframe. Comply with the nice over good rule when writing documentation. Docs can by no means be good and it’s okay to enhance them steadily over time.

Write documentation so good, you by no means have to replace it!

Code could come and go! We write them, modify them and typically later delete them. However documentation is completely different — they shouldn’t change it doesn’t matter what.

Make it your measure of success — how usually you don’t change documentation when altering code.

That is what occurs if the documentation shouldn’t be up to date with code. Meme from 9gag.com

[RS] Documentation is meant to be saved contemporary — if there’s a main change in code that begins to contradict with the documentation, the documentation ought to be up to date with the code.

Don’t take away documentation when eradicating code!

Just like the purpose above, after you have written such good documentation it will be a disgrace to simply take away them in a while.

In case you need to take away the precise code — simply maintain your documentation there for fellow colleagues to learn and soak up! It’s an opportunity for others to find out about your greatness!

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

Should you forked the code from some exterior hyperlink, maintain it to your self

There may be lots of onerous work that goes into discovering code examples on-line that solves nontrivial a part of the issue. It usually comes with further context. However different don’t have to learn about it! In future, if one thing comes up — others can all the time attain out to you!

[RS] No! Reusing the code is a great transfer. It’s all the time an important thought so as to add supply to a doc, exterior hyperlink or code path if the forked code has nont-rivial logic like makes use of magic constants. See this instance

// 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;

That is usually relevant for self-written code as effectively. When you have magic constants derived from analysis, investigation or tuning, add the hyperlink to supply doc for readers to get extra context.

Tips are for code, documentation is private

At a group or firm stage, it is smart to have tips for writing code. It has a number of benefits. However documentations are a private matter and ought to be the selection of the code writer.

[RS] Whereas that is true to some extent, normal documentation tips ought to be part of the type information adopted by a company. This has a number of benefits ranging from consistency all the best way to lowering code overview and submission time.

Nevertheless, the requirements of documentation overview ought to be completely different from the requirements of code overview. Reviewers can and may ask for enhancements, however generally, the writer ought to all the time have the ability to invoke the “Good Over Good Rule”.

If you’re thinking about studying about code critiques generally, you’ll be able to learn the next article:

Automations are for warehouses, documentation is handwritten like a poem

Automations are helpful in warehouses. If you’re actually keen, automation will be useful in code overview instruments to scale back the time to submission. However documentation is private as talked about above. No pc or automation ought to inform us find out how to write documentation!

[RS] Properly, as said above — there must be extra flexibility round find out how to write documentation in code. It’s not enjoyable to obtain subjective opinions on how a sure code remark ought to seem like. However there are benefits to utilizing static evaluation instruments — notably one that may discover spelling or grammatical errors. This can assist you write extra correct feedback for wider viewers to learn and perceive!

Applications have to be written for folks to learn and solely by the way for machines to execute.

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

As soon as once more, for this subject — it is a borderline subjective space. It’s onerous to outline a single algorithm that work finest for all. Though, having some widespread agreed-upon tips helps guarantee consistency.

Previously, I attempted to demystify an identical work from one other writer claiming to be Google lead and it was well-received by the Medium readers:

Thanks for studying! Trying ahead to listening to your opinions

More Posts