How Google Developers Don’t Write Their Comments

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:

Comments: How Google Developers write their comments

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”.

Another easier approach we recommend is naming the variable as “usSocialSecurityPattern”.

And I did advocate for those in the comments section and it seemed to resonate with the other readers. But…