Comments: How Google Developers write their comments

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.

Informative Comments

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

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))

Clarification

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

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")
}

TODO Comments

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

Conclusion

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
KD Knowledge Diet

KD Knowledge Diet

2.4K Followers

Software Engineer, Mobile Developer living in Seoul. I hate people using difficult words. Why not using simple words? Keep It Simple Stupid!