Comments: How Google Developers write their comments

4 min readApr 21, 2022

The more I write the code, the more I feel it. “It is better to be simple than complicated.” It is more advantageous to stick to the basics rather than luxurious techniques. Do you think everyone working at google would write genius code? Rather, the better the developer, the easier it is to write code that others can read.

Did you know that there are different types of comments? And can you put it to good use? Don’t worry. Even if you haven’t been able to use comments well, you’ve found this article and you’ll gain new skills.

Legal Comments

//  SwiftyJSON.swift
//
//  Copyright (c) 2014 - 2017 Ruoyu Fu, Pinglin Tang
//
//  Permission is hereby granted, free of charge, to any person obtaining a copy
//  of this software and associated documentation files (the "Software"), to deal
//  in the Software without restriction, including without limitation the rights
//  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
//  copies of the Software, and to permit persons to whom the Software is
//  furnished to do so, subject to the following conditions:
//
//  The above copyright notice and this permission notice shall be included in
//  all copies or substantial portions of the Software.
//
//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
//  THE SOFTWARE.

You’ve already seen this comments. So, if you’re working for a large company whether it is a tech company, medical company, oil and gas company, you will see that that have legal comments which will have a copyright. This includes usage, legal agreements and these kinds of things. These are legal comments. This is considered a good comment. This is required when you are working for a large organization.

Informative Comments

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

You can see this as a regex expression. The comment over there is simply saying it matches up US Social Security Number. This is informative if you are a person in the team who is not familiar with regex. You can simply read the expression without understanding it.

Explanation of Intent

(defun swift-skip-type-name ()
    "Hop over any comments, whitespace, and the name of a type if
one is present, returning t if so and nil otherwise"
  (swift-skip-comments-and-space)
  (let ((found nil))
    ;; repeatedly
    (while
        (and
         ;; match a tuple or an identifier + optional generic param list
         (cond
          ((looking-at "[[(]")
           (forward-sexp)
           (setq found t))          ((swift-skip-simple-type-name)
           (setq found t)))          ;; followed by "->"
         (prog2 (swift-skip-re "\\\\?+")
             (swift-skip-re "throws\\\\|rethrows\\\\|->")
           (swift-skip-re "->") ;; accounts for the throws/rethrows cases on the previous line
           (swift-skip-comments-and-space))))
    found))

This is elm. Don’t try to understand code. This kind of comments is intentional, explaining the intent of the code.

Clarification

assertTrue(a.compareTo(a) == 0) // a == a
assetrTrue(a.compareTo(b) != 0) // a != b
assertTrue(a.compareTo(b) != -1) // a < b

This type of comment is often used when you are writing test code and when you’re comparing something. Clarification comments can definitely help you out over here.

Warning of Consequences

import UIKit// This test is going to take a while to run
func test_sending_a_really_big_file() {
		loadFile(fileName: "bigfile.data")
}

This kind of comments is called Warning of Consequences. This is especially useful when you work with someone. Without this comment, if programs run so slowly, your co-worker would waste his/her time finding the problem.

TODO Comments

// TODO-Paige
// We expect this to go away when we do the checkout model
private func makeVersion() {}

This is really common. It’s so common that in different editors like XCode, vsCode and android studio, all code editor highlights this todo comment. The purpose of to-do comments is to say “Hey This is not complete yet. I have some works to be done”.

It’s always a good idea to mark your name with todo comment.

Conclusion

So far, you’ve seen several kinds of comments. Writing good comments is a very important skill than you think, so it is better to read it several times!