Android: Merge remote-tracking branch 'remotes/aosp/upstream-gh-pages' am: 0622f2c7dc am: 641d798005
am: 0ad6309bb5
Change-Id: Idb749b4479cc7049749ef3bc1660d2dce2b51d1d
diff --git a/METADATA b/METADATA
index 12a4e6d..016eef2 100644
--- a/METADATA
+++ b/METADATA
@@ -11,6 +11,6 @@
type: GIT
value: "https://github.com/google/styleguide.git"
}
- version: ""
+ version: "58e2a524cd806488709ff0af5445c4225d655e24"
last_upgrade_date { year: 2017 month: 11 day: 10 }
}
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b8f87fc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,54 @@
+Google Style Guides
+===================
+
+Every major open-source project has its own style guide: a set of conventions
+(sometimes arbitrary) about how to write code for that project. It is much
+easier to understand a large codebase when all the code in it is in a
+consistent style.
+
+“Style” covers a lot of ground, from “use camelCase for variable names” to
+“never use global variables” to “never use exceptions.” This project
+([google/styleguide](https://github.com/google/styleguide)) links to the
+style guidelines we use for Google code. If you are modifying a project that
+originated at Google, you may be pointed to this page to see the style guides
+that apply to that project.
+
+This project holds the [C++ Style Guide][cpp], [Objective-C Style Guide][objc],
+[Java Style Guide][java], [Python Style Guide][py], [R Style Guide][r],
+[Shell Style Guide][sh], [HTML/CSS Style Guide][htmlcss],
+[JavaScript Style Guide][js], [AngularJS Style Guide][angular],
+[Common Lisp Style Guide][cl], and [Vimscript Style Guide][vim]. This project
+also contains [cpplint][cpplint], a tool to assist with style guide compliance,
+and [google-c-style.el][emacs], an Emacs settings file for Google style.
+
+If your project requires that you create a new XML document format, the [XML
+Document Format Style Guide][xml] may be helpful. In addition to actual style
+rules, it also contains advice on designing your own vs. adapting an existing
+format, on XML instance document formatting, and on elements vs. attributes.
+
+The style guides in this project are licensed under the CC-By 3.0 License,
+which encourages you to share these documents.
+See [https://creativecommons.org/licenses/by/3.0/][ccl] for more details.
+
+The following Google style guides live outside of this project:
+[Go Code Review Comments][go] and [Effective Dart][dart].
+
+<a rel="license" href="https://creativecommons.org/licenses/by/3.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/3.0/88x31.png" /></a>
+
+[cpp]: https://google.github.io/styleguide/cppguide.html
+[objc]: objcguide.md
+[java]: https://google.github.io/styleguide/javaguide.html
+[py]: https://google.github.io/styleguide/pyguide.html
+[r]: https://google.github.io/styleguide/Rguide.xml
+[sh]: https://google.github.io/styleguide/shell.xml
+[htmlcss]: https://google.github.io/styleguide/htmlcssguide.html
+[js]: https://google.github.io/styleguide/jsguide.html
+[angular]: https://google.github.io/styleguide/angularjs-google-style.html
+[cl]: https://google.github.io/styleguide/lispguide.xml
+[vim]: https://google.github.io/styleguide/vimscriptguide.xml
+[cpplint]: https://github.com/google/styleguide/tree/gh-pages/cpplint
+[emacs]: https://raw.githubusercontent.com/google/styleguide/gh-pages/google-c-style.el
+[xml]: https://google.github.io/styleguide/xmlstyle.html
+[go]: https://golang.org/wiki/CodeReviewComments
+[dart]: https://www.dartlang.org/guides/language/effective-dart
+[ccl]: https://creativecommons.org/licenses/by/3.0/
diff --git a/Rguide.xml b/Rguide.xml
new file mode 100644
index 0000000..ef87872
--- /dev/null
+++ b/Rguide.xml
@@ -0,0 +1,447 @@
+<?xml version="1.0"?>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
+ <link rel="stylesheet" type="text/css" href="styleguide.css"/>
+ <title>Google's R Style Guide</title>
+ </head>
+
+ <body>
+
+ <h1>Google's R Style Guide</h1>
+
+ <p>
+ R is a high-level programming language used primarily for
+ statistical computing and graphics. The goal of the R
+ Programming Style Guide is to make our R code easier to read,
+ share, and verify. The rules below were designed in
+ collaboration with the entire R user community at Google.
+
+ </p>
+
+
+
+
+
+
+ <h2>Summary: R Style Rules</h2>
+
+ <ol>
+ <li><a href="#filenames">File Names</a>: end in <code>.R</code></li>
+ <li><a href="#identifiers">Identifiers</a>: <code>variable.name</code>
+ (or <code>variableName</code>),
+ <code>FunctionName</code>, <code>kConstantName</code></li>
+ <li><a href="#linelength">Line Length</a>: maximum 80 characters</li>
+ <li><a href="#indentation">Indentation</a>: two spaces, no tabs</li>
+ <li><a href="#spacing">Spacing</a></li>
+ <li><a href="#curlybraces">Curly Braces</a>: first on same line, last on
+ own line</li>
+ <li><a href="#else">else</a>: Surround else with braces </li>
+ <li><a href="#assignment">Assignment</a>: use <code><-</code>, not
+ <code>=</code></li>
+ <li><a href="#semicolons">Semicolons</a>: don't use them</li>
+ <li><a href="#generallayout"> General Layout and Ordering</a></li>
+ <li><a href="#comments"> Commenting Guidelines</a>: all comments begin
+ with <code>#</code> followed by a space; inline comments need two
+ spaces before the <code>#</code></li>
+ <li><a href="#functiondefinition">Function Definitions and Calls</a></li>
+ <li><a href="#functiondocumentation"> Function Documentation</a></li>
+ <li><a href="#examplefunction"> Example Function</a></li>
+ <li><a href="#todo"> TODO Style</a>: <code>TODO(username)</code></li>
+ </ol>
+
+ <h2>Summary: R Language Rules</h2>
+ <ol>
+ <li><a href="#attach"> <code>attach</code></a>: avoid using it</li>
+ <li><a href="#functionlanguage"> Functions</a>:
+ errors should be raised using <code>stop()</code></li>
+ <li><a href="#object"> Objects and Methods</a>: avoid S4 objects and
+ methods when possible; never mix S3 and S4 </li>
+ </ol>
+
+ <h3>Notation and Naming</h3>
+
+ <h4 id="filenames">File Names</h4>
+ <p>
+ File names should end in <code>.R</code> and, of course, be
+ meaningful.
+ <br/> GOOD: <code>predict_ad_revenue.R</code>
+ <br/> BAD: <code><span style="color:red">foo.R</span></code>
+ </p>
+
+ <h4 id="identifiers">Identifiers</h4>
+ <p>
+ Don't use underscores ( <code>_</code> ) or hyphens
+ ( <code>-</code> ) in identifiers.
+ Identifiers should be named according to the following conventions.
+ The preferred form for variable names is all lower case
+ letters and words separated with dots
+ (<code>variable.name</code>), but <code>variableName</code>
+ is also accepted;
+ function names have initial capital letters and no dots
+ (<code>FunctionName</code>);
+ constants are named like functions but with an initial
+ <code>k</code>.
+ </p>
+ <ul>
+ <li><code>variable.name</code> is preferred, <code>variableName</code> is accepted
+ <br/> GOOD: <code>avg.clicks</code>
+ <br/> OK: <code>avgClicks</code>
+ <br/> BAD: <code><span style="color:red">avg_Clicks</span></code>
+ </li>
+ <li><code>FunctionName </code>
+ <br/> GOOD: <code>CalculateAvgClicks</code>
+ <br/> BAD: <code><span style="color:red">calculate_avg_clicks
+ </span></code>,
+ <code><span style="color:red">calculateAvgClicks</span></code>
+ <br/> Make function names verbs.
+ <br/><em>Exception: When creating a classed object, the function
+ name (constructor) and class should match (e.g., lm).</em></li>
+ <li><code>kConstantName </code></li>
+ </ul>
+
+
+ <h3>Syntax</h3>
+
+ <h4 id="linelength">Line Length</h4>
+<p>
+ The maximum line length is 80 characters.
+</p>
+
+ <h4 id="indentation">Indentation</h4>
+ <p>
+ When indenting your code, use two spaces. Never use tabs or mix
+ tabs and spaces.
+ <br/><em>Exception: When a line break occurs inside parentheses,
+ align the wrapped line with the first character inside the
+ parenthesis.</em>
+ </p>
+
+ <h4 id="spacing">Spacing</h4>
+ <p>
+ Place spaces around all binary operators (<code>=</code>,
+ <code>+</code>, <code>-</code>, <code><-</code>, etc.).
+ <br/><em> Exception: Spaces around <code>=</code>'s are
+ optional when passing parameters in a function call.</em>
+ </p>
+ <p>
+ Do not place a space before a comma, but always place one after a
+ comma.
+ <br/><br/> GOOD:
+ </p>
+<pre>tab.prior <- table(df[df$days.from.opt < 0, "campaign.id"])
+total <- sum(x[, 1])
+total <- sum(x[1, ])</pre>
+ <p>
+ BAD:
+ </p>
+<pre><span style="color:red">tab.prior <- table(df[df$days.from.opt<0, "campaign.id"]) # Needs spaces around '<'
+tab.prior <- table(df[df$days.from.opt < 0,"campaign.id"]) # Needs a space after the comma
+tab.prior<- table(df[df$days.from.opt < 0, "campaign.id"]) # Needs a space before <-
+tab.prior<-table(df[df$days.from.opt < 0, "campaign.id"]) # Needs spaces around <-
+total <- sum(x[,1]) # Needs a space after the comma
+total <- sum(x[ ,1]) # Needs a space after the comma, not before</span>
+</pre>
+ <p>
+ Place a space before left parenthesis, except in a function call.
+ </p>
+ <p>
+ GOOD:
+ <br/><code>if (debug)</code>
+ </p>
+ <p>
+ BAD:
+ <br/><code><span style="color:red">if(debug)</span></code>
+ </p>
+ <p>
+ Extra spacing (i.e., more than one space in a row) is okay if it
+ improves alignment of equals signs or arrows (<code><-</code>).
+ </p>
+<pre>plot(x = x.coord,
+ y = data.mat[, MakeColName(metric, ptiles[1], "roiOpt")],
+ ylim = ylim,
+ xlab = "dates",
+ ylab = metric,
+ main = (paste(metric, " for 3 samples ", sep = "")))
+</pre>
+ <p>
+ Do not place spaces around code in parentheses or square brackets.
+ <br/><em> Exception: Always place a space after a comma.</em>
+ </p>
+ <p>
+ GOOD:</p><pre>if (debug)
+x[1, ]</pre>
+ <p>
+ BAD:</p><pre><span style="color:red">if ( debug ) # No spaces around debug
+x[1,] # Needs a space after the comma </span></pre>
+
+ <h4 id="curlybraces">Curly Braces</h4>
+ <p>
+ An opening curly brace should never go on its own line; a closing
+ curly brace should always go on its own line. You may omit curly
+ braces when a block consists of a single statement; however, you
+ must <em>consistently</em> either use or not use curly braces for
+ single statement blocks.
+ </p>
+ <pre>
+if (is.null(ylim)) {
+ ylim <- c(0, 0.06)
+}</pre>
+ <p>
+ xor (but not both)
+ </p>
+ <pre>
+if (is.null(ylim))
+ ylim <- c(0, 0.06)</pre>
+ <p>
+ Always begin the body of a block on a new line.
+ </p>
+ <p>
+ BAD:
+ <br/><code><span style="color:red"> if (is.null(ylim))
+ ylim <- c(0, 0.06)</span></code>
+ <br/><code><span style="color:red"> if (is.null(ylim))
+ {ylim <- c(0, 0.06)} </span></code>
+ </p>
+
+ <h4 id="else">Surround else with braces</h4>
+ <p>
+ An <code>else</code> statement should always be surrounded on the
+ same line by curly braces.</p>
+ <pre>
+if (condition) {
+ one or more lines
+} else {
+ one or more lines
+}
+</pre>
+ <p>
+ BAD:<br/>
+ </p>
+ <pre style="color:red">
+if (condition) {
+ one or more lines
+}
+else {
+ one or more lines
+}
+</pre>
+ <p>
+ BAD:<br/>
+ </p>
+ <pre style="color:red">
+if (condition)
+ one line
+else
+ one line
+</pre>
+
+ <h4 id="assignment">Assignment</h4>
+ <p>
+ Use <code><-</code>, not <code>=</code>, for assignment.
+ </p>
+ <p>
+ GOOD:
+ <br/><code> x <- 5 </code>
+ </p>
+ <p>
+ BAD:
+ <br/><code><span style="color:red"> x = 5</span></code>
+ </p>
+ <h4 id="semicolons">Semicolons</h4>
+ <p>
+ Do not terminate your lines with semicolons or use semicolons to
+ put more than one command on the same line. (Semicolons are not
+ necessary, and are omitted for consistency with other Google style
+ guides.)
+ </p>
+
+
+ <h3> Organization </h3>
+ <h4 id="generallayout">General Layout and Ordering</h4>
+ <p>
+ If everyone uses the same general ordering, we'll be able to
+ read and understand each other's scripts faster and more easily.
+ </p>
+ <ol>
+ <li>Copyright statement comment </li>
+ <li>Author comment</li>
+ <li>File description comment, including purpose of
+ program, inputs, and outputs</li>
+ <li><code>source()</code> and <code>library()</code> statements</li>
+ <li>Function definitions</li>
+ <li>Executed statements, if applicable (e.g.,
+ <code> print</code>, <code>plot</code>)</li>
+ </ol>
+ <p>
+ Unit tests should go in a separate file named
+ <code>originalfilename_test.R</code>.
+ </p>
+ <h4 id="comments">Commenting Guidelines</h4>
+ <p>
+ Comment your code. Entire commented lines should begin with
+ <code>#</code> and one space.
+ </p>
+ <p>
+ Short comments can be placed after code preceded by two spaces,
+ <code>#</code>, and then one space.
+ </p>
+<pre># Create histogram of frequency of campaigns by pct budget spent.
+hist(df$pct.spent,
+ breaks = "scott", # method for choosing number of buckets
+ main = "Histogram: fraction budget spent by campaignid",
+ xlab = "Fraction of budget spent",
+ ylab = "Frequency (count of campaignids)")
+</pre>
+ <h4 id="functiondefinition">Function Definitions and
+ Calls</h4>
+ <p>
+ Function definitions should first list arguments without default
+ values, followed by those with default values.
+ </p>
+ <p>
+ In both function definitions and function calls, multiple
+ arguments per line are allowed; line breaks are only allowed
+ between assignments.
+ <br/>GOOD:
+ </p>
+<pre>PredictCTR <- function(query, property, num.days,
+ show.plot = TRUE)
+</pre>
+ BAD:
+<pre><span style="color:red">PredictCTR <- function(query, property, num.days, show.plot =
+ TRUE)
+</span></pre>
+ <p> Ideally, unit tests should serve as sample function calls (for
+ shared library routines).
+ </p>
+ <h4 id="functiondocumentation">Function Documentation</h4>
+ <p> Functions should contain a comments section immediately below
+ the function definition line. These comments should consist of a
+ one-sentence description of the function; a list of the function's
+ arguments, denoted by <code>Args:</code>, with a description of
+ each (including the data type); and a description of the return
+ value, denoted by <code>Returns:</code>. The comments should be
+ descriptive enough that a caller can use the function without
+ reading any of the function's code.
+ </p>
+
+ <h4 id="examplefunction">Example Function</h4>
+<pre>
+CalculateSampleCovariance <- function(x, y, verbose = TRUE) {
+ # Computes the sample covariance between two vectors.
+ #
+ # Args:
+ # x: One of two vectors whose sample covariance is to be calculated.
+ # y: The other vector. x and y must have the same length, greater than one,
+ # with no missing values.
+ # verbose: If TRUE, prints sample covariance; if not, not. Default is TRUE.
+ #
+ # Returns:
+ # The sample covariance between x and y.
+ n <- length(x)
+ # Error handling
+ if (n <= 1 || n != length(y)) {
+ stop("Arguments x and y have different lengths: ",
+ length(x), " and ", length(y), ".")
+ }
+ if (TRUE %in% is.na(x) || TRUE %in% is.na(y)) {
+ stop(" Arguments x and y must not have missing values.")
+ }
+ covariance <- var(x, y)
+ if (verbose)
+ cat("Covariance = ", round(covariance, 4), ".\n", sep = "")
+ return(covariance)
+}
+</pre>
+
+<h4 id="todo">TODO Style</h4>
+
+<p>
+ Use a consistent style for TODOs throughout your code.
+ <br/><code>TODO(username): Explicit description of action to
+ be taken</code>
+</p>
+
+
+ <h3> Language </h3>
+
+ <h4 id="attach">Attach</h4>
+ <p> The possibilities for creating errors when using
+ <code>attach</code> are numerous. Avoid it.</p>
+ <h4 id="functionlanguage">Functions</h4>
+ <p> Errors should be raised using <code>stop()</code>.</p>
+ <h4 id="object">Objects and Methods</h4>
+ <p> The S language has two object systems, S3 and S4, both of which
+ are available in R. S3 methods are more interactive and flexible,
+ whereas S4 methods are more formal and rigorous. (For an illustration
+ of the two systems, see Thomas Lumley's
+ "Programmer's Niche: A Simple
+ Class, in S3 and S4" in R News 4/1, 2004, pgs. 33 - 36:
+ <a href="https://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf">
+ https://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf</a>.)
+ </p>
+ <p>Use S3 objects and methods unless there is a strong reason to use
+ S4 objects or methods. A primary justification for an S4 object
+ would be to use objects directly in C++ code. A primary
+ justification for an S4 generic/method would be to dispatch on two
+ arguments.
+ </p>
+ <p>Avoid mixing S3 and S4: S4 methods ignore S3 inheritance and
+ vice-versa.
+ </p>
+
+
+ <h3>Exceptions</h3>
+
+<p>
+ The coding conventions described above should be followed, unless
+ there is good reason to do otherwise. Exceptions include legacy
+ code and modifying third-party code.
+</p>
+
+
+<h3>Parting Words</h3>
+
+<p>
+ Use common sense and BE CONSISTENT.
+</p>
+ <p>
+ If you are editing code, take a few minutes to look at the code around
+ you and determine its style. If others use spaces around their
+ <code>if </code>
+ clauses, you should, too. If their comments have little boxes of stars
+ around them, make your comments have little boxes of stars around them,
+ too.
+ </p>
+ <p>
+ The point of having style guidelines is to have a common vocabulary of
+ coding so people can concentrate on <em>what</em> you are saying,
+ rather than on <em>how</em> you are saying it. We present global style
+ rules here so people
+ know the vocabulary. But local style is also important. If code you add
+ to a file looks drastically different from the existing code around it,
+ the discontinuity will throw readers out of their rhythm when they go to
+ read it. Try to avoid this.
+ </p>
+
+ <p>
+ OK, enough writing about writing code; the code itself is much more
+ interesting. Have fun!
+ </p>
+
+
+ <h3>References</h3>
+
+ <p>
+ <a href="http://www.maths.lth.se/help/R/RCC/">
+ http://www.maths.lth.se/help/R/RCC/</a> - R Coding Conventions
+ </p>
+ <p>
+ <a href="http://ess.r-project.org/">http://ess.r-project.org/</a> - For
+ emacs users. This runs R in your emacs and has an emacs mode.
+ </p>
+
+ </body>
+
+</html>
diff --git a/angularjs-google-style.html b/angularjs-google-style.html
new file mode 100644
index 0000000..6bcd5d2
--- /dev/null
+++ b/angularjs-google-style.html
@@ -0,0 +1,393 @@
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "https://www.w3.org/TR/REC-html40/strict.dtd">
+<html>
+<head>
+ <META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <base target="_blank">
+ <link rel="stylesheet" type="text/css" href="styleguide.css">
+ <script src="https://google-code-prettify.googlecode.com/svn/loader/run_prettify.js"></script>
+ <script language="javascript" src="/eng/doc/devguide/include/styleguide.js"></script>
+ <title>Google's AngularJS Style Guide</title>
+ <style type="text/css"><!--
+ th { background-color: #ddd; }
+ //--></style>
+</head>
+<body onload="prettyPrint();initStyleGuide();">
+<h1 class="external">An AngularJS Style Guide for Closure Users at Google</h1>
+
+<p class="external">This is the external version of a document that was primarily written for Google
+ engineers. It describes a recommended style for AngularJS apps that use Closure, as used
+ internally at Google. Members of the broader AngularJS community should feel free to apply
+ (or not apply) these recommendations, as relevant to their own use cases.</p>
+
+<p class="external">This document describes style for AngularJS apps in google3. This guide
+ supplements and extends the <a href="https://google.github.io/styleguide/jsguide.html">
+ Google JavaScript Style Guide</a>.
+</p>
+
+<p><b>Style Note</b>: Examples on the AngularJS external webpage, and many external apps, are
+ written in a style that freely uses closures, favors functional inheritance, and does not often use
+ <a class="external"
+ href="https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System">
+ JavaScript types</a>. Google follows a more rigorous Javascript style to support JSCompiler
+ optimizations and large code bases - see the javascript-style mailing list.
+ This is not an Angular-specific issue, and is not discussed further in this style guide.
+ (But if you want further reading:
+ <a href="http://martinfowler.com/bliki/Lambda.html">Martin Fowler on closures</a>,
+ <a href="http://jibbering.com/faq/notes/closures/">much longer description</a>, appendix A of the
+ <a href="https://books.google.com/books/about/Closure_The_Definitive_Guide.html?id=p7uyWPcVGZsC">
+ closure book</a> has a good description of inheritance patterns and why it prefers
+ pseudoclassical,
+ <a href="https://books.google.com/books/about/JavaScript.html?id=PXa2bby0oQ0C">
+ Javascript, the Good Parts</a> as a counter.)</p>
+
+<h5>1 Angular Language Rules</h5>
+<ul>
+ <li> <a target="_self" href="#googprovide">Manage dependencies with Closure's goog.require and
+ goog.provide</a>
+ <li> <a target="_self" href="#modules"> Modules</a>
+ <li> <a target="_self" href="#moduledeps"> Modules should reference other modules using the
+ "name" property</a>
+ <li> <a target="_self" href="#externs">Use the provided Angular externs file</a>
+ <li> <a target="_self" href="#compilerflags">JSCompiler Flags</a>
+ <li> <a target="_self" href="#controllers">Controllers and Scopes</a>
+ <li> <a target="_self" href="#directives">Directives</a>
+ <li> <a target="_self" href="#services">Services</a>
+</ul>
+<h5>2 Angular Style Rules</h5>
+<ul>
+ <li><a target="_self" href="#dollarsign">Reserve $ for Angular properties and services
+ </a>
+ <li><a target="_self" href="#customelements">Custom elements.</a>
+</ul>
+<h5>3 Angular Tips, Tricks, and Best Practices</h5>
+<ul>
+ <li><a target="_self" href="#testing">Testing</a>
+ <li><a target="_self" href="#appstructure">Consider using the Best Practices for App Structure</a>
+ <li><a target="_self" href="#scopeinheritance">Be aware of how scope inheritance works</a>
+ <li><a target="_self" href="#nginject">Use @ngInject for easy dependency injection compilation</a>
+</ul>
+
+<h5><a target="_self" href="#bestpractices">4 Best practices links and docs</a></h5>
+
+<h2>1 Angular Language Rules</h2>
+
+<h3 id="googprovide">Manage dependencies with Closure's goog.require and goog.provide</h3>
+<p>Choose a namespace for your project, and use goog.provide and goog.require.</p>
+<pre class="prettyprint lang-js">
+goog.provide('hello.about.AboutCtrl');
+goog.provide('hello.versions.Versions');
+</pre>
+
+<p><b>Why?</b>
+ Google BUILD rules integrate nicely with closure provide/require.</p>
+
+<h3 id="modules">Modules</h3>
+
+<p>Your main application module should be in your root client directory. A module should never be
+ altered other than the one where it is defined.</p>
+
+<p>Modules may either be defined in the same file as their components (this works well for a module
+ that contains exactly one service) or in a separate file for wiring pieces together.</p>
+
+<p><b>Why?</b>
+ A module should be consistent for anyone that wants to include it as a reusable component.
+ If a module can mean different things depending on which files are included, it is not consistent.
+</p>
+
+<h3 id="moduledeps">
+ Modules should reference other modules using the Angular Module's "name" property
+</h3>
+
+<p>For example:</p>
+
+<pre class="prettyprint lang-js">
+// file submodulea.js:
+ goog.provide('my.submoduleA');
+
+ my.submoduleA = angular.module('my.submoduleA', []);
+ // ...
+
+// file app.js
+ goog.require('my.submoduleA');
+
+ Yes: my.application.module = angular.module('hello', [my.submoduleA.name]);
+ <font color="red">
+ No: my.application.module = angular.module('hello', ['my.submoduleA']);
+ </font></pre>
+
+<p><b>Why?</b>
+ Using a property of my.submoduleA prevents Closure presubmit failures complaining that the file is
+ required but never used. Using the .name property avoids duplicating strings.</p>
+
+<h3 id="externs">Use a common externs file</h3>
+
+<p>This maximally allows the JS compiler to enforce type safety in the presence of externally
+ provided types from Angular, and means you don't have to worry about Angular vars being obfuscated
+ in a confusing way. </p>
+
+<p>Note to readers outside Google: the current externs file is located in an internal-to-Google
+ directory, but an example can be found on github <a href="https://github.com/angular/angular.js/pull/4722">
+ here</a>.</p>
+
+<h3 id="compilerflags">JSCompiler Flags</h3>
+<p><b>Reminder</b>: According to the JS style guide, customer facing code must be compiled.</p>
+
+<p><b>Recommended</b>: Use the JSCompiler (the closure compiler that works with js_binary by
+ default) and ANGULAR_COMPILER_FLAGS_FULL from //javascript/angular/build_defs/build_defs for
+ your base flags.
+</p>
+
+<p>Note - if you are using @export for methods, you will need to add the compiler flag</p>
+<pre>
+"--generate_exports",
+</pre>
+
+<p>If you are using @export for properties, you will need to add the flags:</p>
+<pre>
+"--generate_exports",
+"--remove_unused_prototype_props_in_externs=false",
+"--export_local_property_definitions",
+</pre>
+
+<h3 id="controllers">Controllers and Scopes</h3>
+<p>Controllers are classes. Methods should be defined on MyCtrl.prototype.</p>
+
+<p>Google Angular applications should use the <b>'controller as'</b> style to export the controller
+ onto the scope. This is fully implemented in Angular 1.2 and can be mimicked in pre-Angular 1.2
+ builds.
+</p>
+
+<p>Pre Angular 1.2, this looks like:</p>
+<pre class="prettyprint lang-js">
+/**
+ * Home controller.
+ *
+ * @param {!angular.Scope} $scope
+ * @constructor
+ * @ngInject
+ * @export
+ */
+hello.mainpage.HomeCtrl = function($scope) {
+ /** @export */
+ $scope.homeCtrl = this; // This is a bridge until Angular 1.2 controller-as
+
+ /**
+ * @type {string}
+ * @export
+ */
+ this.myColor = 'blue';
+};
+
+
+/**
+ * @param {number} a
+ * @param {number} b
+ * @export
+ */
+hello.mainpage.HomeCtrl.prototype.add = function(a, b) {
+ return a + b;
+};
+</pre>
+
+<p>And the template:</p>
+
+<pre>
+<div ng-controller="hello.mainpage.HomeCtrl"/>
+ <span ng-class="homeCtrl.myColor">I'm in a color!</span>
+ <span>{{homeCtrl.add(5, 6)}}</span>
+</div>
+</pre>
+
+<p>After Angular 1.2, this looks like:</p>
+
+<pre class="prettyprint lang-js">
+/**
+ * Home controller.
+ *
+ * @constructor
+ * @ngInject
+ * @export
+ */
+hello.mainpage.HomeCtrl = function() {
+ /**
+ * @type {string}
+ * @export
+ */
+ this.myColor = 'blue';
+};
+
+
+/**
+ * @param {number} a
+ * @param {number} b
+ * @export
+ */
+hello.mainpage.HomeCtrl.prototype.add = function(a, b) {
+ return a + b;
+};
+</pre>
+
+<p>If you are compiling with property renaming, expose properties and methods using the @export
+ annotation. Remember to @export the constructor as well.</p>
+
+<p>And in the template:</p>
+
+<pre>
+<div ng-controller="hello.mainpage.HomeCtrl as homeCtrl"/>
+ <span ng-class="homeCtrl.myColor">I'm in a color!</span>
+ <span>{{homeCtrl.add(5, 6)}}</span>
+</div>
+</pre>
+
+<p><b>Why?</b>
+ Putting methods and properties directly onto the controller, instead of building up a scope
+ object, fits better with the Google Closure class style. Additionally, using 'controller as'
+ makes it obvious which controller you are accessing when multiple controllers apply to an element.
+ Since there is always a '.' in the bindings, you don't have to worry about prototypal inheritance
+ masking primitives.</p>
+
+<h3 id="directives">Directives</h3>
+
+<p>All DOM manipulation should be done inside directives. Directives should be kept small and use
+ composition. Files defining directives should goog.provide a static function which returns the
+ directive definition object.</p>
+
+<pre class="prettyprint lang-js">
+goog.provide('hello.pane.paneDirective');
+
+/**
+ * Description and usage
+ * @return {angular.Directive} Directive definition object.
+ */
+hello.pane.paneDirective = function() {
+ // ...
+};
+</pre>
+
+<p><b>Exception</b>: DOM manipulation may occur in services for DOM elements disconnected from the
+ rest of the view, e.g. dialogs or keyboard shortcuts.</p>
+
+<h3 id="services">Services</h3>
+
+<p>Services registered on the module with <code>module.service</code> are classes.
+ Use <code>module.service</code> instead of <code>module.provider</code> or
+ <code>module.factory</code> unless you need to do initialization beyond just creating a
+ new instance of the class.</p>
+
+<pre class="prettyprint lang-js">
+/**
+ * @param {!angular.$http} $http The Angular http service.
+ * @constructor
+ */
+hello.request.Request = function($http) {
+ /** @type {!angular.$http} */
+ this.http_ = $http;
+};
+
+hello.request.Request.prototype.get = function() {/*...*/};
+</pre>
+
+<p>In the module:</p>
+
+<pre class="prettyprint lang-js">
+module.service('request', hello.request.Request);
+</pre>
+
+
+<h2>2 Angular Style Rules</h2>
+
+<h3 id="dollarsign">Reserve $ for Angular properties and services</h3>
+<p>Do not use $ to prepend your own object properties and service identifiers. Consider this style
+ of naming reserved by AngularJS and jQuery.</p>
+
+<p>Yes:</p>
+<pre class="prettyprint lang-js">
+ $scope.myModel = { value: 'foo' }
+ myModule.service('myService', function() { /*...*/ });
+ var MyCtrl = function($http) {this.http_ = $http;};
+</pre>
+
+<p><font color="red">No:</font></p>
+<pre class="prettyprint">
+ $scope.$myModel = { value: 'foo' } // BAD
+ $scope.myModel = { $value: 'foo' } // BAD
+ myModule.service('$myService', function() { ... }); // BAD
+ var MyCtrl = function($http) {this.$http_ = $http;}; // BAD
+</pre>
+
+<p><b>Why?</b>
+ It's useful to distinguish between Angular / jQuery builtins and things you add yourself.
+ In addition, $ is not an acceptable character for variables names in the JS style guide.
+</p>
+
+<h3 id="customelements">Custom elements</h3>
+
+<p>For custom elements (e.g. <code><ng-include src="template"></ng-include></code>), IE8
+ requires special support (html5shiv-like hacks) to enable css styling. Be aware of this
+ restriction in apps targeting old versions of IE.</p>
+
+<h2>3 Angular Tips, Tricks, and Best Practices</h2>
+
+<p>These are not strict style guide rules, but are placed here as reference for folks getting
+ started with Angular at Google.</p>
+
+<h3 id="testing">Testing</h3>
+
+<p>Angular is designed for test-driven development.</p>
+
+<p>The recommended unit testing setup is Jasmine + Karma (though you could use closure tests
+ or js_test)</p>
+
+<p>Angular provides easy adapters to load modules and use the injector in Jasmine tests.
+<ul>
+ <li><a href = "https://docs.angularjs.org/api/angular.mock.module">module</a>
+ <li><a href="https://docs.angularjs.org/api/angular.mock.inject">inject</a>
+</ul>
+</p>
+
+
+<h3 id="appstructure">Consider using the Best Practices for App Structure</h3>
+<p>
+ This <a href="https://docs.google.com/document/d/1XXMvReO8-Awi1EZXAXS4PzDzdNvV6pGcuaF4Q9821Es/pub">directory structure doc</a> describes how to structure your application with controllers in
+ nested subdirectories and all components (e.g. services and directives) in a 'components' dir.
+</p>
+
+
+<h3 id="scopeinheritance">Be aware of how scope inheritance works</h3>
+
+<p>See <a href="https://github.com/angular/angular.js/wiki/Understanding-Scopes#wiki-JSproto">
+ The Nuances of Scope Prototypal Inheritance</a></p>
+
+<h3 id="nginject">Use @ngInject for easy dependency injection compilation</h3>
+<p>This removes the need to add <code>myCtrl['$inject'] = ...</code> to prevent minification from
+ messing up Angular's dependency injection.</p>
+
+<p>Usage:</p>
+<pre class="prettyprint lang-js">
+/**
+ * My controller.
+ * @param {!angular.$http} $http
+ * @param {!my.app.myService} myService
+ * @constructor
+ * @export
+ * @ngInject
+ */
+my.app.MyCtrl = function($http, myService) {
+ //...
+};
+</pre>
+
+<h2 id="bestpractices">4 Best practices links and docs</h2>
+
+<ul>
+ <li><a href="https://github.com/angular/angular.js/wiki/Best-Practices">
+ Best Practices</a> from Angular on GitHub</li>
+ <li><a href="https://www.youtube.com/watch?v=ZhfUv0spHCY">
+ Meetup video</a> (not Google specific)</li>
+</ul>
+<address>
+ Last modified Feb 07 2013
+</address>
+</body>
+<html>
diff --git a/cppguide.html b/cppguide.html
new file mode 100644
index 0000000..590cc9f
--- /dev/null
+++ b/cppguide.html
@@ -0,0 +1,6170 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta http-equiv="content-type" content="text/html; charset=UTF-8">
+<title>Google C++ Style Guide</title>
+<link rel="stylesheet" type="text/css" href="include/styleguide.css">
+<script language="javascript" src="include/styleguide.js"></script>
+<link rel="shortcut icon" type="image/x-icon" href="https://www.google.com/favicon.ico" />
+</head>
+<body onload="initStyleGuide();">
+<div id="content">
+<h1>Google C++ Style Guide</h1>
+<div class="horizontal_toc" id="tocDiv"></div>
+
+<div class="main_body">
+
+<h2 class="ignoreLink" id="Background">Background</h2>
+
+<p>C++ is one of the main development languages used by
+many of Google's open-source projects. As every C++
+programmer knows, the language has many powerful features, but
+this power brings with it complexity, which in turn can make
+code more bug-prone and harder to read and maintain.</p>
+
+<p>The goal of this guide is to manage this complexity by
+describing in detail the dos and don'ts of writing C++ code.
+These rules exist to
+keep the code base manageable while still allowing
+coders to use C++ language features productively.</p>
+
+<p><em>Style</em>, also known as readability, is what we call
+the conventions that govern our C++ code. The term Style is a
+bit of a misnomer, since these conventions cover far more than
+just source file formatting.</p>
+
+<p>
+Most open-source projects developed by
+Google conform to the requirements in this guide.
+</p>
+
+
+
+
+
+<p>Note that this guide is not a C++ tutorial: we assume that
+the reader is familiar with the language. </p>
+
+<h3 id="Goals">Goals of the Style Guide</h3>
+<div class="stylebody">
+<p>Why do we have this document?</p>
+
+<p>There are a few core goals that we believe this guide should
+serve. These are the fundamental <b>why</b>s that
+underlie all of the individual rules. By bringing these ideas to
+the fore, we hope to ground discussions and make it clearer to our
+broader community why the rules are in place and why particular
+decisions have been made. If you understand what goals each rule is
+serving, it should be clearer to everyone when a rule may be waived
+(some can be), and what sort of argument or alternative would be
+necessary to change a rule in the guide.</p>
+
+<p>The goals of the style guide as we currently see them are as follows:</p>
+<dl>
+<dt>Style rules should pull their weight</dt>
+<dd>The benefit of a style rule
+must be large enough to justify asking all of our engineers to
+remember it. The benefit is measured relative to the codebase we would
+get without the rule, so a rule against a very harmful practice may
+still have a small benefit if people are unlikely to do it
+anyway. This principle mostly explains the rules we don’t have, rather
+than the rules we do: for example, <code>goto</code> contravenes many
+of the following principles, but is already vanishingly rare, so the Style
+Guide doesn’t discuss it.</dd>
+
+<dt>Optimize for the reader, not the writer</dt>
+<dd>Our codebase (and most individual components submitted to it) is
+expected to continue for quite some time. As a result, more time will
+be spent reading most of our code than writing it. We explicitly
+choose to optimize for the experience of our average software engineer
+reading, maintaining, and debugging code in our codebase rather than
+ease when writing said code. "Leave a trace for the reader" is a
+particularly common sub-point of this principle: When something
+surprising or unusual is happening in a snippet of code (for example,
+transfer of pointer ownership), leaving textual hints for the reader
+at the point of use is valuable (<code>std::unique_ptr</code>
+demonstrates the ownership transfer unambiguously at the call
+site). </dd>
+
+<dt>Be consistent with existing code</dt>
+<dd>Using one style consistently through our codebase lets us focus on
+other (more important) issues. Consistency also allows for
+automation: tools that format your code or adjust
+your <code>#include</code>s only work properly when your code is
+consistent with the expectations of the tooling. In many cases, rules
+that are attributed to "Be Consistent" boil down to "Just pick one and
+stop worrying about it"; the potential value of allowing flexibility
+on these points is outweighed by the cost of having people argue over
+them. </dd>
+
+<dt>Be consistent with the broader C++ community when appropriate</dt>
+<dd>Consistency with the way other organizations use C++ has value for
+the same reasons as consistency within our code base. If a feature in
+the C++ standard solves a problem, or if some idiom is widely known
+and accepted, that's an argument for using it. However, sometimes
+standard features and idioms are flawed, or were just designed without
+our codebase's needs in mind. In those cases (as described below) it's
+appropriate to constrain or ban standard features. In some cases we
+prefer a homegrown or third-party library over a library defined in
+the C++ Standard, either out of perceived superiority or insufficient
+value to transition the codebase to the standard interface.</dd>
+
+<dt>Avoid surprising or dangerous constructs</dt>
+<dd>C++ has features that are more surprising or dangerous than one
+might think at a glance. Some style guide restrictions are in place to
+prevent falling into these pitfalls. There is a high bar for style
+guide waivers on such restrictions, because waiving such rules often
+directly risks compromising program correctness.
+</dd>
+
+<dt>Avoid constructs that our average C++ programmer would find tricky
+or hard to maintain</dt>
+<dd>C++ has features that may not be generally appropriate because of
+the complexity they introduce to the code. In widely used
+code, it may be more acceptable to use
+trickier language constructs, because any benefits of more complex
+implementation are multiplied widely by usage, and the cost in understanding
+the complexity does not need to be paid again when working with new
+portions of the codebase. When in doubt, waivers to rules of this type
+can be sought by asking
+your project leads. This is specifically
+important for our codebase because code ownership and team membership
+changes over time: even if everyone that works with some piece of code
+currently understands it, such understanding is not guaranteed to hold a
+few years from now.</dd>
+
+<dt>Be mindful of our scale</dt>
+<dd>With a codebase of 100+ million lines and thousands of engineers,
+some mistakes and simplifications for one engineer can become costly
+for many. For instance it's particularly important to
+avoid polluting the global namespace: name collisions across a
+codebase of hundreds of millions of lines are difficult to work with
+and hard to avoid if everyone puts things into the global
+namespace.</dd>
+
+<dt>Concede to optimization when necessary</dt>
+<dd>Performance optimizations can sometimes be necessary and
+appropriate, even when they conflict with the other principles of this
+document.</dd>
+</dl>
+
+<p>The intent of this document is to provide maximal guidance with
+reasonable restriction. As always, common sense and good taste should
+prevail. By this we specifically refer to the established conventions
+of the entire Google C++ community, not just your personal preferences
+or those of your team. Be skeptical about and reluctant to use
+clever or unusual constructs: the absence of a prohibition is not the
+same as a license to proceed. Use your judgment, and if you are
+unsure, please don't hesitate to ask your project leads to get additional
+input.</p>
+
+</div>
+
+
+
+<h2 id="Header_Files">Header Files</h2>
+
+<p>In general, every <code>.cc</code> file should have an
+associated <code>.h</code> file. There are some common
+exceptions, such as unittests and
+small <code>.cc</code> files containing just a
+<code>main()</code> function.</p>
+
+<p>Correct use of header files can make a huge difference to
+the readability, size and performance of your code.</p>
+
+<p>The following rules will guide you through the various
+pitfalls of using header files.</p>
+
+<a id="The_-inl.h_Files"></a>
+<h3 id="Self_contained_Headers">Self-contained Headers</h3>
+
+<div class="summary">
+<p>Header files should be self-contained (compile on their own) and
+end in <code>.h</code>. Non-header files that are meant for inclusion
+should end in <code>.inc</code> and be used sparingly.</p>
+</div>
+
+<div class="stylebody">
+<p>All header files should be self-contained. Users and refactoring
+tools should not have to adhere to special conditions to include the
+header. Specifically, a header should
+have <a href="#The__define_Guard">header guards</a> and include all
+other headers it needs.</p>
+
+<p>Prefer placing the definitions for template and inline functions in
+the same file as their declarations. The definitions of these
+constructs must be included into every <code>.cc</code> file that uses
+them, or the program may fail to link in some build configurations. If
+declarations and definitions are in different files, including the
+former should transitively include the latter. Do not move these
+definitions to separately included header files (<code>-inl.h</code>);
+this practice was common in the past, but is no longer allowed.</p>
+
+<p>As an exception, a template that is explicitly instantiated for
+all relevant sets of template arguments, or that is a private
+implementation detail of a class, is allowed to be defined in the one
+and only <code>.cc</code> file that instantiates the template.</p>
+
+<p>There are rare cases where a file designed to be included is not
+self-contained. These are typically intended to be included at unusual
+locations, such as the middle of another file. They might not
+use <a href="#The__define_Guard">header guards</a>, and might not include
+their prerequisites. Name such files with the <code>.inc</code>
+extension. Use sparingly, and prefer self-contained headers when
+possible.</p>
+
+</div>
+
+<h3 id="The__define_Guard">The #define Guard</h3>
+
+<div class="summary">
+<p>All header files should have <code>#define</code> guards to
+prevent multiple inclusion. The format of the symbol name
+should be
+<code><i><PROJECT></i>_<i><PATH></i>_<i><FILE></i>_H_</code>.</p>
+</div>
+
+<div class="stylebody">
+
+
+
+<p>To guarantee uniqueness, they should
+be based on the full path in a project's source tree. For
+example, the file <code>foo/src/bar/baz.h</code> in
+project <code>foo</code> should have the following
+guard:</p>
+
+<pre>#ifndef FOO_BAR_BAZ_H_
+#define FOO_BAR_BAZ_H_
+
+...
+
+#endif // FOO_BAR_BAZ_H_
+</pre>
+
+
+
+
+</div>
+
+<h3 id="Forward_Declarations">Forward Declarations</h3>
+
+<div class="summary">
+ <p>Avoid using forward declarations where possible.
+ Just <code>#include</code> the headers you need.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p>A "forward declaration" is a declaration of a class,
+function, or template without an associated definition.</p>
+</div>
+
+<div class="pros">
+<ul>
+ <li>Forward declarations can save compile time, as
+ <code>#include</code>s force the compiler to open
+ more files and process more input.</li>
+
+ <li>Forward declarations can save on unnecessary
+ recompilation. <code>#include</code>s can force
+ your code to be recompiled more often, due to unrelated
+ changes in the header.</li>
+</ul>
+</div>
+
+<div class="cons">
+<ul>
+ <li>Forward declarations can hide a dependency, allowing
+ user code to skip necessary recompilation when headers
+ change.</li>
+
+ <li>A forward declaration may be broken by subsequent
+ changes to the library. Forward declarations of functions
+ and templates can prevent the header owners from making
+ otherwise-compatible changes to their APIs, such as
+ widening a parameter type, adding a template parameter
+ with a default value, or migrating to a new namespace.</li>
+
+ <li>Forward declaring symbols from namespace
+ <code>std::</code> yields undefined behavior.</li>
+
+ <li>It can be difficult to determine whether a forward
+ declaration or a full <code>#include</code> is needed.
+ Replacing an <code>#include</code> with a forward
+ declaration can silently change the meaning of
+ code:
+ <pre> // b.h:
+ struct B {};
+ struct D : B {};
+
+ // good_user.cc:
+ #include "b.h"
+ void f(B*);
+ void f(void*);
+ void test(D* x) { f(x); } // calls f(B*)
+ </pre>
+ If the <code>#include</code> was replaced with forward
+ decls for <code>B</code> and <code>D</code>,
+ <code>test()</code> would call <code>f(void*)</code>.
+ </li>
+
+ <li>Forward declaring multiple symbols from a header
+ can be more verbose than simply
+ <code>#include</code>ing the header.</li>
+
+ <li>Structuring code to enable forward declarations
+ (e.g. using pointer members instead of object members)
+ can make the code slower and more complex.</li>
+
+
+</ul>
+</div>
+
+<div class="decision">
+<ul>
+ <li>Try to avoid forward declarations of entities
+ defined in another project.</li>
+
+ <li>When using a function declared in a header file,
+ always <code>#include</code> that header.</li>
+
+ <li>When using a class template, prefer to
+ <code>#include</code> its header file.</li>
+</ul>
+
+<p>Please see <a href="#Names_and_Order_of_Includes">Names and Order
+of Includes</a> for rules about when to #include a header.</p>
+</div>
+
+</div>
+
+<h3 id="Inline_Functions">Inline Functions</h3>
+
+<div class="summary">
+<p>Define functions inline only when they are small, say, 10
+lines or fewer.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p>You can declare functions in a way that allows the compiler to expand
+them inline rather than calling them through the usual
+function call mechanism.</p>
+</div>
+
+<div class="pros">
+<p>Inlining a function can generate more efficient object
+code, as long as the inlined function is small. Feel free
+to inline accessors and mutators, and other short,
+performance-critical functions.</p>
+</div>
+
+<div class="cons">
+<p>Overuse of inlining can actually make programs slower.
+Depending on a function's size, inlining it can cause the
+code size to increase or decrease. Inlining a very small
+accessor function will usually decrease code size while
+inlining a very large function can dramatically increase
+code size. On modern processors smaller code usually runs
+faster due to better use of the instruction cache.</p>
+</div>
+
+<div class="decision">
+<p>A decent rule of thumb is to not inline a function if
+it is more than 10 lines long. Beware of destructors,
+which are often longer than they appear because of
+implicit member- and base-destructor calls!</p>
+
+<p>Another useful rule of thumb: it's typically not cost
+effective to inline functions with loops or switch
+statements (unless, in the common case, the loop or
+switch statement is never executed).</p>
+
+<p>It is important to know that functions are not always
+inlined even if they are declared as such; for example,
+virtual and recursive functions are not normally inlined.
+Usually recursive functions should not be inline. The
+main reason for making a virtual function inline is to
+place its definition in the class, either for convenience
+or to document its behavior, e.g., for accessors and
+mutators.</p>
+</div>
+
+</div>
+
+<h3 id="Names_and_Order_of_Includes">Names and Order of Includes</h3>
+
+<div class="summary">
+<p>Use standard order for readability and to avoid hidden
+dependencies: Related header, C library, C++ library, other libraries'
+<code>.h</code>, your project's <code>.h</code>.</p>
+</div>
+
+<div class="stylebody">
+<p>
+All of a project's header files should be
+listed as descendants of the project's source
+directory without use of UNIX directory shortcuts
+<code>.</code> (the current directory) or <code>..</code>
+(the parent directory). For example,
+
+<code>google-awesome-project/src/base/logging.h</code>
+should be included as:</p>
+
+<pre>#include "base/logging.h"
+</pre>
+
+<p>In <code><var>dir/foo</var>.cc</code> or
+<code><var>dir/foo_test</var>.cc</code>, whose main
+purpose is to implement or test the stuff in
+<code><var>dir2/foo2</var>.h</code>, order your includes
+as follows:</p>
+
+<ol>
+ <li><code><var>dir2/foo2</var>.h</code>.</li>
+
+ <li>C system files.</li>
+
+ <li>C++ system files.</li>
+
+ <li>Other libraries' <code>.h</code>
+ files.</li>
+
+ <li>
+ Your project's <code>.h</code>
+ files.</li>
+</ol>
+
+<p>With the preferred ordering, if
+<code><var>dir2/foo2</var>.h</code> omits any necessary
+includes, the build of <code><var>dir/foo</var>.cc</code>
+or <code><var>dir/foo</var>_test.cc</code> will break.
+Thus, this rule ensures that build breaks show up first
+for the people working on these files, not for innocent
+people in other packages.</p>
+
+<p><code><var>dir/foo</var>.cc</code> and
+<code><var>dir2/foo2</var>.h</code> are usually in the same
+directory (e.g. <code>base/basictypes_test.cc</code> and
+<code>base/basictypes.h</code>), but may sometimes be in different
+directories too.</p>
+
+
+
+<p>Within each section the includes should be ordered
+alphabetically. Note that older code might not conform to
+this rule and should be fixed when convenient.</p>
+
+<p>You should include all the headers that define the symbols you rely
+upon, except in the unusual case of <a href="#Forward_Declarations">forward
+declaration</a>. If you rely on symbols from <code>bar.h</code>,
+don't count on the fact that you included <code>foo.h</code> which
+(currently) includes <code>bar.h</code>: include <code>bar.h</code>
+yourself, unless <code>foo.h</code> explicitly demonstrates its intent
+to provide you the symbols of <code>bar.h</code>. However, any
+includes present in the related header do not need to be included
+again in the related <code>cc</code> (i.e., <code>foo.cc</code> can
+rely on <code>foo.h</code>'s includes).</p>
+
+<p>For example, the includes in
+
+<code>google-awesome-project/src/foo/internal/fooserver.cc</code>
+might look like this:</p>
+
+
+<pre>#include "foo/server/fooserver.h"
+
+#include <sys/types.h>
+#include <unistd.h>
+
+#include <hash_map>
+#include <vector>
+
+#include "base/basictypes.h"
+#include "base/commandlineflags.h"
+#include "foo/server/bar.h"
+</pre>
+
+<p class="exception">Sometimes, system-specific code needs
+conditional includes. Such code can put conditional
+includes after other includes. Of course, keep your
+system-specific code small and localized. Example:</p>
+
+<pre>#include "foo/public/fooserver.h"
+
+#include "base/port.h" // For LANG_CXX11.
+
+#ifdef LANG_CXX11
+#include <initializer_list>
+#endif // LANG_CXX11
+</pre>
+
+</div>
+
+<h2 id="Scoping">Scoping</h2>
+
+<h3 id="Namespaces">Namespaces</h3>
+
+<div class="summary">
+<p>With few exceptions, place code in a namespace. Namespaces
+should have unique names based on the project name, and possibly
+its path. Do not use <i>using-directives</i> (e.g.
+<code>using namespace foo</code>). Do not use
+inline namespaces. For unnamed namespaces, see
+<a href="#Unnamed_Namespaces_and_Static_Variables">Unnamed Namespaces and
+Static Variables</a>.
+</p></div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p>Namespaces subdivide the global scope
+into distinct, named scopes, and so are useful for preventing
+name collisions in the global scope.</p>
+</div>
+
+<div class="pros">
+
+<p>Namespaces provide a method for preventing name conflicts
+in large programs while allowing most code to use reasonably
+short names.</p>
+
+<p>For example, if two different projects have a class
+<code>Foo</code> in the global scope, these symbols may
+collide at compile time or at runtime. If each project
+places their code in a namespace, <code>project1::Foo</code>
+and <code>project2::Foo</code> are now distinct symbols that
+do not collide, and code within each project's namespace
+can continue to refer to <code>Foo</code> without the prefix.</p>
+
+<p>Inline namespaces automatically place their names in
+the enclosing scope. Consider the following snippet, for
+example:</p>
+
+<pre>namespace X {
+inline namespace Y {
+ void foo();
+} // namespace Y
+} // namespace X
+</pre>
+
+<p>The expressions <code>X::Y::foo()</code> and
+<code>X::foo()</code> are interchangeable. Inline
+namespaces are primarily intended for ABI compatibility
+across versions.</p>
+</div>
+
+<div class="cons">
+
+<p>Namespaces can be confusing, because they complicate
+the mechanics of figuring out what definition a name refers
+to.</p>
+
+<p>Inline namespaces, in particular, can be confusing
+because names aren't actually restricted to the namespace
+where they are declared. They are only useful as part of
+some larger versioning policy.</p>
+
+<p>In some contexts, it's necessary to repeatedly refer to
+symbols by their fully-qualified names. For deeply-nested
+namespaces, this can add a lot of clutter.</p>
+</div>
+
+<div class="decision">
+
+<p>Namespaces should be used as follows:</p>
+
+<ul>
+ <li>Follow the rules on <a href="#Namespace_Names">Namespace Names</a>.
+ </li><li>Terminate namespaces with comments as shown in the given examples.
+ </li><li>
+
+ <p>Namespaces wrap the entire source file after
+ includes,
+ <a href="https://gflags.github.io/gflags/">
+ gflags</a> definitions/declarations
+ and forward declarations of classes from other namespaces.</p>
+
+<pre>// In the .h file
+namespace mynamespace {
+
+// All declarations are within the namespace scope.
+// Notice the lack of indentation.
+class MyClass {
+ public:
+ ...
+ void Foo();
+};
+
+} // namespace mynamespace
+</pre>
+
+<pre>// In the .cc file
+namespace mynamespace {
+
+// Definition of functions is within scope of the namespace.
+void MyClass::Foo() {
+ ...
+}
+
+} // namespace mynamespace
+</pre>
+
+ <p>More complex <code>.cc</code> files might have additional details,
+ like flags or using-declarations.</p>
+
+<pre>#include "a.h"
+
+DEFINE_FLAG(bool, someflag, false, "dummy flag");
+
+namespace a {
+
+using ::foo::bar;
+
+...code for a... // Code goes against the left margin.
+
+} // namespace a
+</pre>
+ </li>
+
+
+
+ <li>Do not declare anything in namespace
+ <code>std</code>, including forward declarations of
+ standard library classes. Declaring entities in
+ namespace <code>std</code> is undefined behavior, i.e.,
+ not portable. To declare entities from the standard
+ library, include the appropriate header file.</li>
+
+ <li><p>You may not use a <i>using-directive</i>
+ to make all names from a namespace available.</p>
+
+<pre class="badcode">// Forbidden -- This pollutes the namespace.
+using namespace foo;
+</pre>
+ </li>
+
+ <li><p>Do not use <i>Namespace aliases</i> at namespace scope
+ in header files except in explicitly marked
+ internal-only namespaces, because anything imported into a namespace
+ in a header file becomes part of the public
+ API exported by that file.</p>
+
+<pre>// Shorten access to some commonly used names in .cc files.
+namespace baz = ::foo::bar::baz;
+</pre>
+
+<pre>// Shorten access to some commonly used names (in a .h file).
+namespace librarian {
+namespace impl { // Internal, not part of the API.
+namespace sidetable = ::pipeline_diagnostics::sidetable;
+} // namespace impl
+
+inline void my_inline_function() {
+ // namespace alias local to a function (or method).
+ namespace baz = ::foo::bar::baz;
+ ...
+}
+} // namespace librarian
+</pre>
+
+ </li><li>Do not use inline namespaces.</li>
+</ul>
+</div>
+</div>
+
+<h3 id="Unnamed_Namespaces_and_Static_Variables">Unnamed Namespaces and Static
+Variables</h3>
+
+<div class="summary">
+<p>When definitions in a <code>.cc</code> file do not need to be
+referenced outside that file, place them in an unnamed
+namespace or declare them <code>static</code>. Do not use either
+of these constructs in <code>.h</code> files.
+</p></div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p>All declarations can be given internal linkage by placing them in
+unnamed namespaces, and functions and variables can be given internal linkage by
+declaring them <code>static</code>. This means that anything you're declaring
+can't be accessed from another file. If a different file declares something
+with the same name, then the two entities are completely independent.</p>
+</div>
+
+<div class="decision">
+
+<p>Use of internal linkage in <code>.cc</code> files is encouraged
+for all code that does not need to be referenced elsewhere.
+Do not use internal linkage in <code>.h</code> files.</p>
+
+<p>Format unnamed namespaces like named namespaces. In the
+ terminating comment, leave the namespace name empty:</p>
+
+<pre>namespace {
+...
+} // namespace
+</pre>
+</div>
+</div>
+
+<h3 id="Nonmember,_Static_Member,_and_Global_Functions">Nonmember, Static Member, and Global Functions</h3>
+
+<div class="summary">
+<p>Prefer placing nonmember functions in a namespace; use completely global
+functions rarely. Prefer grouping functions with a namespace instead of
+using a class as if it were a namespace. Static methods of a class should
+generally be closely related to instances of the class or the class's static
+data.</p>
+</div>
+
+ <div class="stylebody">
+
+ <div class="pros">
+ <p>Nonmember and static member functions can be useful in
+ some situations. Putting nonmember functions in a
+ namespace avoids polluting the global namespace.</p>
+ </div>
+
+<div class="cons">
+<p>Nonmember and static member functions may make more sense
+as members of a new class, especially if they access
+external resources or have significant dependencies.</p>
+</div>
+
+<div class="decision">
+<p>Sometimes it is useful to define a
+function not bound to a class instance. Such a function
+can be either a static member or a nonmember function.
+Nonmember functions should not depend on external
+variables, and should nearly always exist in a namespace.
+Rather than creating classes only to group static member
+functions which do not share static data, use
+<a href="#Namespaces">namespaces</a> instead. For a header
+<code>myproject/foo_bar.h</code>, for example, write</p>
+<pre>namespace myproject {
+namespace foo_bar {
+void Function1();
+void Function2();
+} // namespace foo_bar
+} // namespace myproject
+</pre>
+<p>instead of</p>
+<pre class="badcode">namespace myproject {
+class FooBar {
+ public:
+ static void Function1();
+ static void Function2();
+};
+} // namespace myproject
+</pre>
+
+<p>If you define a nonmember function and it is only
+needed in its <code>.cc</code> file, use
+<a href="#Unnamed_Namespaces_and_Static_Variables">internal linkage</a> to limit
+its scope.</p>
+</div>
+
+</div>
+
+<h3 id="Local_Variables">Local Variables</h3>
+
+<div class="summary">
+<p>Place a function's variables in the narrowest scope
+possible, and initialize variables in the declaration.</p>
+</div>
+
+<div class="stylebody">
+
+<p>C++ allows you to declare variables anywhere in a
+function. We encourage you to declare them in as local a
+scope as possible, and as close to the first use as
+possible. This makes it easier for the reader to find the
+declaration and see what type the variable is and what it
+was initialized to. In particular, initialization should
+be used instead of declaration and assignment, e.g.:</p>
+
+<pre class="badcode">int i;
+i = f(); // Bad -- initialization separate from declaration.
+</pre>
+
+<pre>int j = g(); // Good -- declaration has initialization.
+</pre>
+
+<pre class="badcode">std::vector<int> v;
+v.push_back(1); // Prefer initializing using brace initialization.
+v.push_back(2);
+</pre>
+
+<pre>std::vector<int> v = {1, 2}; // Good -- v starts initialized.
+</pre>
+
+<p>Variables needed for <code>if</code>, <code>while</code>
+and <code>for</code> statements should normally be declared
+within those statements, so that such variables are confined
+to those scopes. E.g.:</p>
+
+<pre>while (const char* p = strchr(str, '/')) str = p + 1;
+</pre>
+
+<p>There is one caveat: if the variable is an object, its
+constructor is invoked every time it enters scope and is
+created, and its destructor is invoked every time it goes
+out of scope.</p>
+
+<pre class="badcode">// Inefficient implementation:
+for (int i = 0; i < 1000000; ++i) {
+ Foo f; // My ctor and dtor get called 1000000 times each.
+ f.DoSomething(i);
+}
+</pre>
+
+<p>It may be more efficient to declare such a variable
+used in a loop outside that loop:</p>
+
+<pre>Foo f; // My ctor and dtor get called once each.
+for (int i = 0; i < 1000000; ++i) {
+ f.DoSomething(i);
+}
+</pre>
+
+</div>
+
+<h3 id="Static_and_Global_Variables">Static and Global Variables</h3>
+
+<div class="summary">
+ <p>Variables of class type with <a href="http://en.cppreference.com/w/cpp/language/storage_duration#Storage_duration">
+ static storage duration</a> are forbidden: they cause hard-to-find bugs due
+ to indeterminate order of construction and destruction. However, such
+ variables are allowed if they are <code>constexpr</code>: they have no
+ dynamic initialization or destruction.</p>
+</div>
+
+<div class="stylebody">
+
+<p>Objects with static storage duration, including global
+variables, static variables, static class member
+variables, and function static variables, must be Plain
+Old Data (POD): only ints, chars, floats, or pointers, or
+arrays/structs of POD.</p>
+
+<p>The order in which class constructors and initializers
+for static variables are called is only partially
+specified in C++ and can even change from build to build,
+which can cause bugs that are difficult to find.
+Therefore in addition to banning globals of class type,
+we do not allow non-local static variables to be initialized
+with the result of a function, unless that function (such
+as getenv(), or getpid()) does not itself depend on any
+other globals. However, a static POD variable within
+function scope may be initialized with the result of a
+function, since its initialization order is well-defined
+and does not occur until control passes through its
+declaration.</p>
+
+<p>Likewise, global and static variables are destroyed
+when the program terminates, regardless of whether the
+termination is by returning from <code>main()</code> or
+by calling <code>exit()</code>. The order in which
+destructors are called is defined to be the reverse of
+the order in which the constructors were called. Since
+constructor order is indeterminate, so is destructor
+order. For example, at program-end time a static variable
+might have been destroyed, but code still running
+— perhaps in another thread
+— tries to access it and fails. Or the
+destructor for a static <code>string</code> variable
+might be run prior to the destructor for another variable
+that contains a reference to that string.</p>
+
+<p>One way to alleviate the destructor problem is to
+terminate the program by calling
+<code>quick_exit()</code> instead of <code>exit()</code>.
+The difference is that <code>quick_exit()</code> does not
+invoke destructors and does not invoke any handlers that
+were registered by calling <code>atexit()</code>. If you
+have a handler that needs to run when a program
+terminates via <code>quick_exit()</code> (flushing logs,
+for example), you can register it using
+<code>at_quick_exit()</code>. (If you have a handler that
+needs to run at both <code>exit()</code> and
+<code>quick_exit()</code>, you need to register it in
+both places.)</p>
+
+<p>As a result we only allow static variables to contain
+POD data. This rule completely disallows
+<code>std::vector</code> (use C arrays instead), or
+<code>string</code> (use <code>const char []</code>).</p>
+
+
+
+<p>If you need a static or global
+variable of a class type, consider initializing a pointer
+(which will never be freed), from either your main()
+function or from pthread_once(). Note that this must be a
+raw pointer, not a "smart" pointer, since the smart
+pointer's destructor will have the order-of-destructor
+issue that we are trying to avoid.</p>
+
+
+
+
+
+</div>
+
+<h2 id="Classes">Classes</h2>
+
+<p>Classes are the fundamental unit of code in C++. Naturally,
+we use them extensively. This section lists the main dos and
+don'ts you should follow when writing a class.</p>
+
+<h3 id="Doing_Work_in_Constructors">Doing Work in Constructors</h3>
+
+<div class="summary">
+<p>Avoid virtual method calls in constructors, and avoid
+initialization that can fail if you can't signal an error.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p>It is possible to perform arbitrary initialization in the body
+of the constructor.</p>
+</div>
+
+<div class="pros">
+<ul>
+ <li>No need to worry about whether the class has been initialized or
+ not.</li>
+
+ <li>Objects that are fully initialized by constructor call can
+ be <code>const</code> and may also be easier to use with standard containers
+ or algorithms.</li>
+</ul>
+
+</div>
+
+<div class="cons">
+<ul>
+ <li>If the work calls virtual functions, these calls
+ will not get dispatched to the subclass
+ implementations. Future modification to your class can
+ quietly introduce this problem even if your class is
+ not currently subclassed, causing much confusion.</li>
+
+ <li>There is no easy way for constructors to signal errors, short of
+ crashing the program (not always appropriate) or using exceptions
+ (which are <a href="#Exceptions">forbidden</a>).</li>
+
+ <li>If the work fails, we now have an object whose initialization
+ code failed, so it may be an unusual state requiring a <code>bool
+ IsValid()</code> state checking mechanism (or similar) which is easy
+ to forget to call.</li>
+
+ <li>You cannot take the address of a constructor, so whatever work
+ is done in the constructor cannot easily be handed off to, for
+ example, another thread.</li>
+</ul>
+</div>
+
+
+<div class="decision">
+<p>Constructors should never call virtual functions. If appropriate
+for your code
+,
+terminating the program may be an appropriate error handling
+response. Otherwise, consider a factory function
+or <code>Init()</code> method. Avoid <code>Init()</code> methods on objects with
+no other states that affect which public methods may be called
+(semi-constructed objects of this form are particularly hard to work
+with correctly).</p>
+</div>
+
+</div>
+
+<a id="Explicit_Constructors"></a>
+<h3 id="Implicit_Conversions">Implicit Conversions</h3>
+
+<div class="summary">
+<p>Do not define implicit conversions. Use the <code>explicit</code>
+keyword for conversion operators and single-argument
+constructors.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p>Implicit conversions allow an
+object of one type (called the <dfn>source type</dfn>) to
+be used where a different type (called the <dfn>destination
+type</dfn>) is expected, such as when passing an
+<code>int</code> argument to a function that takes a
+<code>double</code> parameter.</p>
+
+<p>In addition to the implicit conversions defined by the language,
+users can define their own, by adding appropriate members to the
+class definition of the source or destination type. An implicit
+conversion in the source type is defined by a type conversion operator
+named after the destination type (e.g. <code>operator
+bool()</code>). An implicit conversion in the destination
+type is defined by a constructor that can take the source type as
+its only argument (or only argument with no default value).</p>
+
+<p>The <code>explicit</code> keyword can be applied to a constructor
+or (since C++11) a conversion operator, to ensure that it can only be
+used when the destination type is explicit at the point of use,
+e.g. with a cast. This applies not only to implicit conversions, but to
+C++11's list initialization syntax:</p>
+<pre>class Foo {
+ explicit Foo(int x, double y);
+ ...
+};
+
+void Func(Foo f);
+</pre>
+<pre class="badcode">Func({42, 3.14}); // Error
+</pre>
+This kind of code isn't technically an implicit conversion, but the
+language treats it as one as far as <code>explicit</code> is concerned.
+</div>
+
+<div class="pros">
+<ul>
+<li>Implicit conversions can make a type more usable and
+ expressive by eliminating the need to explicitly name a type
+ when it's obvious.</li>
+<li>Implicit conversions can be a simpler alternative to
+ overloading.</li>
+<li>List initialization syntax is a concise and expressive
+ way of initializing objects.</li>
+</ul>
+</div>
+
+<div class="cons">
+<ul>
+<li>Implicit conversions can hide type-mismatch bugs, where the
+ destination type does not match the user's expectation, or
+ the user is unaware that any conversion will take place.</li>
+
+<li>Implicit conversions can make code harder to read, particularly
+ in the presence of overloading, by making it less obvious what
+ code is actually getting called.</li>
+
+<li>Constructors that take a single argument may accidentally
+ be usable as implicit type conversions, even if they are not
+ intended to do so.</li>
+
+<li>When a single-argument constructor is not marked
+ <code>explicit</code>, there's no reliable way to tell whether
+ it's intended to define an implicit conversion, or the author
+ simply forgot to mark it.</li>
+
+<li>It's not always clear which type should provide the conversion,
+ and if they both do, the code becomes ambiguous.</li>
+
+<li>List initialization can suffer from the same problems if
+ the destination type is implicit, particularly if the
+ list has only a single element.</li>
+</ul>
+</div>
+
+<div class="decision">
+<p>Type conversion operators, and constructors that are
+callable with a single argument, must be marked
+<code>explicit</code> in the class definition. As an
+exception, copy and move constructors should not be
+<code>explicit</code>, since they do not perform type
+conversion. Implicit conversions can sometimes be necessary and
+appropriate for types that are designed to transparently wrap other
+types. In that case, contact
+your project leads to request
+a waiver of this rule.</p>
+
+<p>Constructors that cannot be called with a single argument
+should usually omit <code>explicit</code>. Constructors that
+take a single <code>std::initializer_list</code> parameter should
+also omit <code>explicit</code>, in order to support copy-initialization
+(e.g. <code>MyType m = {1, 2};</code>).</p>
+</div>
+
+</div>
+
+<h3 id="Copyable_Movable_Types">Copyable and Movable Types</h3>
+<a id="Copy_Constructors"></a>
+<div class="summary">
+<p>Support copying and/or moving if these operations are clear and meaningful
+for your type. Otherwise, disable the implicitly generated special functions
+that perform copies and moves.
+</p></div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p>A copyable type allows its objects to be initialized or assigned
+from any other object of the same type, without changing the value of the source.
+For user-defined types, the copy behavior is defined by the copy
+constructor and the copy-assignment operator.
+<code>string</code> is an example of a copyable type.</p>
+
+<p>A movable type is one that can be initialized and assigned
+from temporaries (all copyable types are therefore movable).
+<code>std::unique_ptr<int></code> is an example of a movable but not
+copyable type. For user-defined types, the move behavior is defined by the move
+constructor and the move-assignment operator.</p>
+
+<p>The copy/move constructors can be implicitly invoked by the compiler
+in some situations, e.g. when passing objects by value.</p>
+</div>
+
+<div class="pros">
+<p>Objects of copyable and movable types can be passed and returned by value,
+which makes APIs simpler, safer, and more general. Unlike when passing objects
+by pointer or reference, there's no risk of confusion over ownership,
+lifetime, mutability, and similar issues, and no need to specify them in the
+contract. It also prevents non-local interactions between the client and the
+implementation, which makes them easier to understand, maintain, and optimize by
+the compiler. Further, such objects can be used with generic APIs that
+require pass-by-value, such as most containers, and they allow for additional
+flexibility in e.g., type composition.</p>
+
+<p>Copy/move constructors and assignment operators are usually
+easier to define correctly than alternatives
+like <code>Clone()</code>, <code>CopyFrom()</code> or <code>Swap()</code>,
+because they can be generated by the compiler, either implicitly or
+with <code>= default</code>. They are concise, and ensure
+that all data members are copied. Copy and move
+constructors are also generally more efficient, because they don't
+require heap allocation or separate initialization and assignment
+steps, and they're eligible for optimizations such as
+
+<a href="http://en.cppreference.com/w/cpp/language/copy_elision">
+copy elision</a>.</p>
+
+<p>Move operations allow the implicit and efficient transfer of
+resources out of rvalue objects. This allows a plainer coding style
+in some cases.</p>
+</div>
+
+<div class="cons">
+<p>Some types do not need to be copyable, and providing copy
+operations for such types can be confusing, nonsensical, or outright
+incorrect. Types representing singleton objects (<code>Registerer</code>),
+objects tied to a specific scope (<code>Cleanup</code>), or closely coupled to
+object identity (<code>Mutex</code>) cannot be copied meaningfully.
+Copy operations for base class types that are to be used
+polymorphically are hazardous, because use of them can lead to
+<a href="https://en.wikipedia.org/wiki/Object_slicing">object slicing</a>.
+Defaulted or carelessly-implemented copy operations can be incorrect, and the
+resulting bugs can be confusing and difficult to diagnose.</p>
+
+<p>Copy constructors are invoked implicitly, which makes the
+invocation easy to miss. This may cause confusion for programmers used to
+languages where pass-by-reference is conventional or mandatory. It may also
+encourage excessive copying, which can cause performance problems.</p>
+</div>
+
+<div class="decision">
+
+<p>Provide the copy and move operations if their meaning is clear to a casual
+user and the copying/moving does not incur unexpected costs. If you define a
+copy or move constructor, define the corresponding assignment operator, and
+vice-versa. If your type is copyable, do not define move operations unless they
+are significantly more efficient than the corresponding copy operations. If your
+type is not copyable, but the correctness of a move is obvious to users of the
+type, you may make the type move-only by defining both of the move operations.
+</p>
+
+<p>If your type provides copy operations, it is recommended that you design
+your class so that the default implementation of those operations is correct.
+Remember to review the correctness of any defaulted operations as you would any
+other code, and to document that your class is copyable and/or cheaply movable
+if that's an API guarantee.</p>
+
+<pre class="badcode">class Foo {
+ public:
+ Foo(Foo&& other) : field_(other.field) {}
+ // Bad, defines only move constructor, but not operator=.
+
+ private:
+ Field field_;
+};
+</pre>
+
+<p>Due to the risk of slicing, avoid providing an assignment
+operator or public copy/move constructor for a class that's
+intended to be derived from (and avoid deriving from a class
+with such members). If your base class needs to be
+copyable, provide a public virtual <code>Clone()</code>
+method, and a protected copy constructor that derived classes
+can use to implement it.</p>
+
+<p>If you do not want to support copy/move operations on your type,
+explicitly disable them using <code>= delete</code> in
+the <code>public:</code> section:</p>
+
+<pre class="code">// MyClass is neither copyable nor movable.
+MyClass(const MyClass&) = delete;
+MyClass& operator=(const MyClass&) = delete;
+</pre>
+
+<p></p>
+
+</div>
+</div>
+
+<h3 id="Structs_vs._Classes">Structs vs. Classes</h3>
+
+<div class="summary">
+<p>Use a <code>struct</code> only for passive objects that
+ carry data; everything else is a <code>class</code>.</p>
+</div>
+
+<div class="stylebody">
+
+<p>The <code>struct</code> and <code>class</code>
+keywords behave almost identically in C++. We add our own
+semantic meanings to each keyword, so you should use the
+appropriate keyword for the data-type you're
+defining.</p>
+
+<p><code>structs</code> should be used for passive
+objects that carry data, and may have associated
+constants, but lack any functionality other than
+access/setting the data members. The accessing/setting of
+fields is done by directly accessing the fields rather
+than through method invocations. Methods should not
+provide behavior but should only be used to set up the
+data members, e.g., constructor, destructor,
+<code>Initialize()</code>, <code>Reset()</code>,
+<code>Validate()</code>.</p>
+
+<p>If more functionality is required, a
+<code>class</code> is more appropriate. If in doubt, make
+it a <code>class</code>.</p>
+
+<p>For consistency with STL, you can use
+<code>struct</code> instead of <code>class</code> for
+functors and traits.</p>
+
+<p>Note that member variables in structs and classes have
+<a href="#Variable_Names">different naming rules</a>.</p>
+
+</div>
+
+<h3 id="Inheritance">Inheritance</h3>
+
+<div class="summary">
+<p>Composition is often more appropriate than inheritance.
+When using inheritance, make it <code>public</code>.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p> When a sub-class
+inherits from a base class, it includes the definitions
+of all the data and operations that the parent base class
+defines. In practice, inheritance is used in two major
+ways in C++: implementation inheritance, in which actual
+code is inherited by the child, and
+<a href="#Interfaces">interface inheritance</a>, in which
+only method names are inherited.</p>
+</div>
+
+<div class="pros">
+<p>Implementation inheritance reduces code size by re-using
+the base class code as it specializes an existing type.
+Because inheritance is a compile-time declaration, you
+and the compiler can understand the operation and detect
+errors. Interface inheritance can be used to
+programmatically enforce that a class expose a particular
+API. Again, the compiler can detect errors, in this case,
+when a class does not define a necessary method of the
+API.</p>
+</div>
+
+<div class="cons">
+<p>For implementation inheritance, because the code
+implementing a sub-class is spread between the base and
+the sub-class, it can be more difficult to understand an
+implementation. The sub-class cannot override functions
+that are not virtual, so the sub-class cannot change
+implementation. The base class may also define some data
+members, so that specifies physical layout of the base
+class.</p>
+</div>
+
+<div class="decision">
+
+<p>All inheritance should be <code>public</code>. If you
+want to do private inheritance, you should be including
+an instance of the base class as a member instead.</p>
+
+<p>Do not overuse implementation inheritance. Composition
+is often more appropriate. Try to restrict use of
+inheritance to the "is-a" case: <code>Bar</code>
+subclasses <code>Foo</code> if it can reasonably be said
+that <code>Bar</code> "is a kind of"
+<code>Foo</code>.</p>
+
+<p>Make your destructor <code>virtual</code> if
+necessary. If your class has virtual methods, its
+destructor should be virtual.</p>
+
+<p>Limit the use of <code>protected</code> to those
+member functions that might need to be accessed from
+subclasses. Note that <a href="#Access_Control">data
+members should be private</a>.</p>
+
+<p>Explicitly annotate overrides of virtual functions
+or virtual destructors with an <code>override</code>
+or (less frequently) <code>final</code> specifier.
+Older (pre-C++11) code will use the
+<code>virtual</code> keyword as an inferior
+alternative annotation. For clarity, use exactly one of
+<code>override</code>, <code>final</code>, or
+<code>virtual</code> when declaring an override.
+Rationale: A function or destructor marked
+<code>override</code> or <code>final</code> that is
+not an override of a base class virtual function will
+not compile, and this helps catch common errors. The
+specifiers serve as documentation; if no specifier is
+present, the reader has to check all ancestors of the
+class in question to determine if the function or
+destructor is virtual or not.</p>
+</div>
+
+</div>
+
+<h3 id="Multiple_Inheritance">Multiple Inheritance</h3>
+
+<div class="summary">
+<p>Only very rarely is multiple implementation inheritance
+actually useful. We allow multiple inheritance only when at
+most one of the base classes has an implementation; all
+other base classes must be <a href="#Interfaces">pure
+interface</a> classes tagged with the
+<code>Interface</code> suffix.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p>Multiple inheritance allows a sub-class to have more than
+one base class. We distinguish between base classes that are
+<em>pure interfaces</em> and those that have an
+<em>implementation</em>.</p>
+</div>
+
+<div class="pros">
+<p>Multiple implementation inheritance may let you re-use
+even more code than single inheritance (see <a href="#Inheritance">Inheritance</a>).</p>
+</div>
+
+<div class="cons">
+<p>Only very rarely is multiple <em>implementation</em>
+inheritance actually useful. When multiple implementation
+inheritance seems like the solution, you can usually find
+a different, more explicit, and cleaner solution.</p>
+</div>
+
+<div class="decision">
+<p> Multiple inheritance is allowed only when all
+superclasses, with the possible exception of the first one,
+are <a href="#Interfaces">pure interfaces</a>. In order to
+ensure that they remain pure interfaces, they must end with
+the <code>Interface</code> suffix.</p>
+</div>
+
+<div class="note">
+<p>There is an <a href="#Windows_Code">exception</a> to
+this rule on Windows.</p>
+</div>
+
+</div>
+
+<h3 id="Interfaces">Interfaces</h3>
+
+<div class="summary">
+<p>Classes that satisfy certain conditions are allowed, but
+not required, to end with an <code>Interface</code> suffix.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p>A class is a pure interface if it meets the following
+requirements:</p>
+
+<ul>
+ <li>It has only public pure virtual ("<code>=
+ 0</code>") methods and static methods (but see below
+ for destructor).</li>
+
+ <li>It may not have non-static data members.</li>
+
+ <li>It need not have any constructors defined. If a
+ constructor is provided, it must take no arguments and
+ it must be protected.</li>
+
+ <li>If it is a subclass, it may only be derived from
+ classes that satisfy these conditions and are tagged
+ with the <code>Interface</code> suffix.</li>
+</ul>
+
+<p>An interface class can never be directly instantiated
+because of the pure virtual method(s) it declares. To
+make sure all implementations of the interface can be
+destroyed correctly, the interface must also declare a
+virtual destructor (in an exception to the first rule,
+this should not be pure). See Stroustrup, <cite>The C++
+Programming Language</cite>, 3rd edition, section 12.4
+for details.</p>
+</div>
+
+<div class="pros">
+<p>Tagging a class with the <code>Interface</code> suffix
+lets others know that they must not add implemented
+methods or non static data members. This is particularly
+important in the case of <a href="#Multiple_Inheritance">multiple inheritance</a>.
+Additionally, the interface concept is already
+well-understood by Java programmers.</p>
+</div>
+
+<div class="cons">
+<p>The <code>Interface</code> suffix lengthens the class
+name, which can make it harder to read and understand.
+Also, the interface property may be considered an
+implementation detail that shouldn't be exposed to
+clients.</p>
+</div>
+
+<div class="decision">
+<p>A class may end
+with <code>Interface</code> only if it meets the above
+requirements. We do not require the converse, however:
+classes that meet the above requirements are not required
+to end with <code>Interface</code>.</p>
+</div>
+
+</div>
+
+<h3 id="Operator_Overloading">Operator Overloading</h3>
+
+<div class="summary">
+<p>Overload operators judiciously. Do not create user-defined literals.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p>C++ permits user code to
+<a href="http://en.cppreference.com/w/cpp/language/operators">declare
+overloaded versions of the built-in operators</a> using the
+<code>operator</code> keyword, so long as one of the parameters
+is a user-defined type. The <code>operator</code> keyword also
+permits user code to define new kinds of literals using
+<code>operator""</code>, and to define type-conversion functions
+such as <code>operator bool()</code>.</p>
+</div>
+
+<div class="pros">
+<p>Operator overloading can make code more concise and
+intuitive by enabling user-defined types to behave the same
+as built-in types. Overloaded operators are the idiomatic names
+for certain operations (e.g. <code>==</code>, <code><</code>,
+<code>=</code>, and <code><<</code>), and adhering to
+those conventions can make user-defined types more readable
+and enable them to interoperate with libraries that expect
+those names.</p>
+
+<p>User-defined literals are a very concise notation for
+creating objects of user-defined types.</p>
+</div>
+
+<div class="cons">
+<ul>
+ <li>Providing a correct, consistent, and unsurprising
+ set of operator overloads requires some care, and failure
+ to do so can lead to confusion and bugs.</li>
+
+ <li>Overuse of operators can lead to obfuscated code,
+ particularly if the overloaded operator's semantics
+ don't follow convention.</li>
+
+ <li>The hazards of function overloading apply just as
+ much to operator overloading, if not more so.</li>
+
+ <li>Operator overloads can fool our intuition into
+ thinking that expensive operations are cheap, built-in
+ operations.</li>
+
+ <li>Finding the call sites for overloaded operators may
+ require a search tool that's aware of C++ syntax, rather
+ than e.g. grep.</li>
+
+ <li>If you get the argument type of an overloaded operator
+ wrong, you may get a different overload rather than a
+ compiler error. For example, <code>foo < bar</code>
+ may do one thing, while <code>&foo < &bar</code>
+ does something totally different.</li>
+
+ <li>Certain operator overloads are inherently hazardous.
+ Overloading unary <code>&</code> can cause the same
+ code to have different meanings depending on whether
+ the overload declaration is visible. Overloads of
+ <code>&&</code>, <code>||</code>, and <code>,</code>
+ (comma) cannot match the evaluation-order semantics of the
+ built-in operators.</li>
+
+ <li>Operators are often defined outside the class,
+ so there's a risk of different files introducing
+ different definitions of the same operator. If both
+ definitions are linked into the same binary, this results
+ in undefined behavior, which can manifest as subtle
+ run-time bugs.</li>
+
+ <li>User-defined literals allow the creation of new
+ syntactic forms that are unfamiliar even to experienced C++
+ programmers.</li>
+</ul>
+</div>
+
+<div class="decision">
+<p>Define overloaded operators only if their meaning is
+obvious, unsurprising, and consistent with the corresponding
+built-in operators. For example, use <code>|</code> as a
+bitwise- or logical-or, not as a shell-style pipe.</p>
+
+<p>Define operators only on your own types. More precisely,
+define them in the same headers, .cc files, and namespaces
+as the types they operate on. That way, the operators are available
+wherever the type is, minimizing the risk of multiple
+definitions. If possible, avoid defining operators as templates,
+because they must satisfy this rule for any possible template
+arguments. If you define an operator, also define
+any related operators that make sense, and make sure they
+are defined consistently. For example, if you overload
+<code><</code>, overload all the comparison operators,
+and make sure <code><</code> and <code>></code> never
+return true for the same arguments.</p>
+
+<p>Prefer to define non-modifying binary operators as
+non-member functions. If a binary operator is defined as a
+class member, implicit conversions will apply to the
+right-hand argument, but not the left-hand one. It will
+confuse your users if <code>a < b</code> compiles but
+<code>b < a</code> doesn't.</p>
+
+<p>Don't go out of your way to avoid defining operator
+overloads. For example, prefer to define <code>==</code>,
+<code>=</code>, and <code><<</code>, rather than
+<code>Equals()</code>, <code>CopyFrom()</code>, and
+<code>PrintTo()</code>. Conversely, don't define
+operator overloads just because other libraries expect
+them. For example, if your type doesn't have a natural
+ordering, but you want to store it in a <code>std::set</code>,
+use a custom comparator rather than overloading
+<code><</code>.</p>
+
+<p>Do not overload <code>&&</code>, <code>||</code>,
+<code>,</code> (comma), or unary <code>&</code>. Do not overload
+<code>operator""</code>, i.e. do not introduce user-defined
+literals.</p>
+
+<p>Type conversion operators are covered in the section on
+<a href="#Implicit_Conversions">implicit conversions</a>.
+The <code>=</code> operator is covered in the section on
+<a href="#Copy_Constructors">copy constructors</a>. Overloading
+<code><<</code> for use with streams is covered in the
+section on <a href="#Streams">streams</a>. See also the rules on
+<a href="#Function_Overloading">function overloading</a>, which
+apply to operator overloading as well.</p>
+</div>
+
+</div>
+
+<h3 id="Access_Control">Access Control</h3>
+
+<div class="summary">
+<p> Make data members <code>private</code>, unless they are
+<code>static const</code> (and follow the <a href="#Constant_Names">
+naming convention for constants</a>). For technical
+reasons, we allow data members of a test fixture class to
+be <code>protected</code> when using
+
+
+<a href="https://github.com/google/googletest">Google
+Test</a>).</p>
+</div>
+
+<h3 id="Declaration_Order">Declaration Order</h3>
+
+<div class="summary">
+<p>Group similar declarations together, placing public parts
+earlier.</p>
+</div>
+
+<div class="stylebody">
+
+<p>A class definition should usually start with a
+<code>public:</code> section, followed by
+<code>protected:</code>, then <code>private:</code>. Omit
+sections that would be empty.</p>
+
+<p>Within each section, generally prefer grouping similar
+kinds of declarations together, and generally prefer the
+following order: types (including <code>typedef</code>,
+<code>using</code>, and nested structs and classes),
+constants, factory functions, constructors, assignment
+operators, destructor, all other methods, data members.</p>
+
+<p>Do not put large method definitions inline in the
+class definition. Usually, only trivial or
+performance-critical, and very short, methods may be
+defined inline. See <a href="#Inline_Functions">Inline
+Functions</a> for more details.</p>
+
+</div>
+
+<h2 id="Functions">Functions</h2>
+
+<h3 id="Function_Parameter_Ordering">Parameter Ordering</h3>
+
+<div class="summary">
+<p>When defining a function, parameter order is: inputs, then
+outputs.</p>
+</div>
+
+<div class="stylebody">
+<p>Parameters to C/C++ functions are either input to the
+function, output from the function, or both. Input
+parameters are usually values or <code>const</code>
+references, while output and input/output parameters will
+be pointers to non-<code>const</code>. When ordering
+function parameters, put all input-only parameters before
+any output parameters. In particular, do not add new
+parameters to the end of the function just because they
+are new; place new input-only parameters before the
+output parameters.</p>
+
+<p>This is not a hard-and-fast rule. Parameters that are
+both input and output (often classes/structs) muddy the
+waters, and, as always, consistency with related
+functions may require you to bend the rule.</p>
+
+</div>
+
+<h3 id="Write_Short_Functions">Write Short Functions</h3>
+
+<div class="summary">
+<p>Prefer small and focused functions.</p>
+</div>
+
+<div class="stylebody">
+<p>We recognize that long functions are sometimes
+appropriate, so no hard limit is placed on functions
+length. If a function exceeds about 40 lines, think about
+whether it can be broken up without harming the structure
+of the program.</p>
+
+<p>Even if your long function works perfectly now,
+someone modifying it in a few months may add new
+behavior. This could result in bugs that are hard to
+find. Keeping your functions short and simple makes it
+easier for other people to read and modify your code.</p>
+
+<p>You could find long and complicated functions when
+working with
+some code. Do not be
+intimidated by modifying existing code: if working with
+such a function proves to be difficult, you find that
+errors are hard to debug, or you want to use a piece of
+it in several different contexts, consider breaking up
+the function into smaller and more manageable pieces.</p>
+
+</div>
+
+<h3 id="Reference_Arguments">Reference Arguments</h3>
+
+<div class="summary">
+<p>All parameters passed by reference must be labeled
+<code>const</code>.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p>In C, if a
+function needs to modify a variable, the parameter must
+use a pointer, eg <code>int foo(int *pval)</code>. In
+C++, the function can alternatively declare a reference
+parameter: <code>int foo(int &val)</code>.</p>
+</div>
+
+<div class="pros">
+<p>Defining a parameter as reference avoids ugly code like
+<code>(*pval)++</code>. Necessary for some applications
+like copy constructors. Makes it clear, unlike with
+pointers, that a null pointer is not a possible
+value.</p>
+</div>
+
+<div class="cons">
+<p>References can be confusing, as they have value syntax
+but pointer semantics.</p>
+</div>
+
+<div class="decision">
+<p>Within function parameter lists all references must be
+<code>const</code>:</p>
+
+<pre>void Foo(const string &in, string *out);
+</pre>
+
+<p>In fact it is a very strong convention in Google code
+that input arguments are values or <code>const</code>
+references while output arguments are pointers. Input
+parameters may be <code>const</code> pointers, but we
+never allow non-<code>const</code> reference parameters
+except when required by convention, e.g.,
+<code>swap()</code>.</p>
+
+<p>However, there are some instances where using
+<code>const T*</code> is preferable to <code>const
+T&</code> for input parameters. For example:</p>
+
+<ul>
+ <li>You want to pass in a null pointer.</li>
+
+ <li>The function saves a pointer or reference to the
+ input.</li>
+</ul>
+
+<p> Remember that most of the time input
+parameters are going to be specified as <code>const
+T&</code>. Using <code>const T*</code> instead
+communicates to the reader that the input is somehow
+treated differently. So if you choose <code>const
+T*</code> rather than <code>const T&</code>, do so
+for a concrete reason; otherwise it will likely confuse
+readers by making them look for an explanation that
+doesn't exist.</p>
+</div>
+
+</div>
+
+<h3 id="Function_Overloading">Function Overloading</h3>
+
+<div class="summary">
+<p>Use overloaded functions (including constructors) only if a
+reader looking at a call site can get a good idea of what
+is happening without having to first figure out exactly
+which overload is being called.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p>You may write a function that takes a <code>const
+string&</code> and overload it with another that
+takes <code>const char*</code>.</p>
+
+<pre>class MyClass {
+ public:
+ void Analyze(const string &text);
+ void Analyze(const char *text, size_t textlen);
+};
+</pre>
+</div>
+
+<div class="pros">
+<p>Overloading can make code more intuitive by allowing an
+identically-named function to take different arguments.
+It may be necessary for templatized code, and it can be
+convenient for Visitors.</p>
+</div>
+
+<div class="cons">
+<p>If a function is overloaded by the argument types alone,
+a reader may have to understand C++'s complex matching
+rules in order to tell what's going on. Also many people
+are confused by the semantics of inheritance if a derived
+class overrides only some of the variants of a
+function.</p>
+</div>
+
+<div class="decision">
+<p>If you want to overload a function, consider qualifying
+the name with some information about the arguments, e.g.,
+<code>AppendString()</code>, <code>AppendInt()</code>
+rather than just <code>Append()</code>. If you are
+overloading a function to support variable number of
+arguments of the same type, consider making it take a
+<code>std::vector</code> so that the user can use an
+<a href="#Braced_Initializer_List">initializer list
+</a> to specify the arguments.</p>
+</div>
+
+</div>
+
+<h3 id="Default_Arguments">Default Arguments</h3>
+
+<div class="summary">
+<p>Default arguments are allowed on non-virtual functions
+when the default is guaranteed to always have the same
+value. Follow the same restrictions as for <a href="#Function_Overloading">function overloading</a>, and
+prefer overloaded functions if the readability gained with
+default arguments doesn't outweigh the downsides below.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="pros">
+<p>Often you have a function that uses default values, but
+occasionally you want to override the defaults. Default
+parameters allow an easy way to do this without having to
+define many functions for the rare exceptions. Compared
+to overloading the function, default arguments have a
+cleaner syntax, with less boilerplate and a clearer
+distinction between 'required' and 'optional'
+arguments.</p>
+</div>
+
+<div class="cons">
+<p>Defaulted arguments are another way to achieve the
+semantics of overloaded functions, so all the <a href="#Function_Overloading">reasons not to overload
+functions</a> apply.</p>
+
+<p>The defaults for arguments in a virtual function call are
+determined by the static type of the target object, and
+there's no guarantee that all overrides of a given function
+declare the same defaults.</p>
+
+<p>Default parameters are re-evaluated at each call site,
+which can bloat the generated code. Readers may also expect
+the default's value to be fixed at the declaration instead
+of varying at each call.</p>
+
+<p>Function pointers are confusing in the presence of
+default arguments, since the function signature often
+doesn't match the call signature. Adding
+function overloads avoids these problems.</p>
+</div>
+
+<div class="decision">
+<p>Default arguments are banned on virtual functions, where
+they don't work properly, and in cases where the specified
+default might not evaluate to the same value depending on
+when it was evaluated. (For example, don't write <code>void
+f(int n = counter++);</code>.)</p>
+
+<p>In some other cases, default arguments can improve the
+readability of their function declarations enough to
+overcome the downsides above, so they are allowed. When in
+doubt, use overloads.</p>
+</div>
+
+</div>
+
+<h3 id="trailing_return">Trailing Return Type Syntax</h3>
+<div class="summary">
+<p>Use trailing return types only where using the ordinary syntax (leading
+ return types) is impractical or much less readable.</p>
+</div>
+
+<div class="definition">
+<p>C++ allows two different forms of function declarations. In the older
+ form, the return type appears before the function name. For example:</p>
+<pre>int foo(int x);
+</pre>
+<p>The new form, introduced in C++11, uses the <code>auto</code>
+ keyword before the function name and a trailing return type after
+ the argument list. For example, the declaration above could
+ equivalently be written:</p>
+<pre>auto foo(int x) -> int;
+</pre>
+<p>The trailing return type is in the function's scope. This doesn't
+ make a difference for a simple case like <code>int</code> but it matters
+ for more complicated cases, like types declared in class scope or
+ types written in terms of the function parameters.</p>
+</div>
+
+<div class="stylebody">
+<div class="pros">
+<p>Trailing return types are the only way to explicitly specify the
+ return type of a <a href="#Lambda_expressions">lambda expression</a>.
+ In some cases the compiler is able to deduce a lambda's return type,
+ but not in all cases. Even when the compiler can deduce it automatically,
+ sometimes specifying it explicitly would be clearer for readers.
+</p>
+<p>Sometimes it's easier and more readable to specify a return type
+ after the function's parameter list has already appeared. This is
+ particularly true when the return type depends on template parameters.
+ For example:</p>
+ <pre>template <class T, class U> auto add(T t, U u) -> decltype(t + u);</pre>
+ versus
+ <pre>template <class T, class U> decltype(declval<T&>() + declval<U&>()) add(T t, U u);</pre>
+</div>
+
+<div class="cons">
+<p>Trailing return type syntax is relatively new and it has no
+ analogue in C++-like languages like C and Java, so some readers may
+ find it unfamiliar.</p>
+<p>Existing code bases have an enormous number of function
+ declarations that aren't going to get changed to use the new syntax,
+ so the realistic choices are using the old syntax only or using a mixture
+ of the two. Using a single version is better for uniformity of style.</p>
+</div>
+
+<div class="decision">
+<p>In most cases, continue to use the older style of function
+ declaration where the return type goes before the function name.
+ Use the new trailing-return-type form only in cases where it's
+ required (such as lambdas) or where, by putting the type after the
+ function's parameter list, it allows you to write the type in a much
+ more readable way. The latter case should be rare; it's mostly an
+ issue in fairly complicated template code, which is
+ <a href="#Template_metaprogramming">discouraged in most cases</a>.</p>
+
+</div>
+</div>
+
+<h2 id="Google-Specific_Magic">Google-Specific Magic</h2>
+
+
+
+<p>There are various tricks and utilities that
+we use to make C++ code more robust, and various ways we use
+C++ that may differ from what you see elsewhere.</p>
+
+
+
+<h3 id="Ownership_and_Smart_Pointers">Ownership and Smart Pointers</h3>
+
+<div class="summary">
+<p>Prefer to have single, fixed owners for dynamically
+allocated objects. Prefer to transfer ownership with smart
+pointers.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p>"Ownership" is a bookkeeping technique for managing
+dynamically allocated memory (and other resources). The
+owner of a dynamically allocated object is an object or
+function that is responsible for ensuring that it is
+deleted when no longer needed. Ownership can sometimes be
+shared, in which case the last owner is typically
+responsible for deleting it. Even when ownership is not
+shared, it can be transferred from one piece of code to
+another.</p>
+
+<p>"Smart" pointers are classes that act like pointers,
+e.g. by overloading the <code>*</code> and
+<code>-></code> operators. Some smart pointer types
+can be used to automate ownership bookkeeping, to ensure
+these responsibilities are met.
+<a href="http://en.cppreference.com/w/cpp/memory/unique_ptr">
+<code>std::unique_ptr</code></a> is a smart pointer type
+introduced in C++11, which expresses exclusive ownership
+of a dynamically allocated object; the object is deleted
+when the <code>std::unique_ptr</code> goes out of scope.
+It cannot be copied, but can be <em>moved</em> to
+represent ownership transfer.
+<a href="http://en.cppreference.com/w/cpp/memory/shared_ptr">
+<code>std::shared_ptr</code></a> is a smart pointer type
+that expresses shared ownership of
+a dynamically allocated object. <code>std::shared_ptr</code>s
+can be copied; ownership of the object is shared among
+all copies, and the object is deleted when the last
+<code>std::shared_ptr</code> is destroyed. </p>
+</div>
+
+<div class="pros">
+<ul>
+ <li>It's virtually impossible to manage dynamically
+ allocated memory without some sort of ownership
+ logic.</li>
+
+ <li>Transferring ownership of an object can be cheaper
+ than copying it (if copying it is even possible).</li>
+
+ <li>Transferring ownership can be simpler than
+ 'borrowing' a pointer or reference, because it reduces
+ the need to coordinate the lifetime of the object
+ between the two users.</li>
+
+ <li>Smart pointers can improve readability by making
+ ownership logic explicit, self-documenting, and
+ unambiguous.</li>
+
+ <li>Smart pointers can eliminate manual ownership
+ bookkeeping, simplifying the code and ruling out large
+ classes of errors.</li>
+
+ <li>For const objects, shared ownership can be a simple
+ and efficient alternative to deep copying.</li>
+</ul>
+</div>
+
+<div class="cons">
+<ul>
+ <li>Ownership must be represented and transferred via
+ pointers (whether smart or plain). Pointer semantics
+ are more complicated than value semantics, especially
+ in APIs: you have to worry not just about ownership,
+ but also aliasing, lifetime, and mutability, among
+ other issues.</li>
+
+ <li>The performance costs of value semantics are often
+ overestimated, so the performance benefits of ownership
+ transfer might not justify the readability and
+ complexity costs.</li>
+
+ <li>APIs that transfer ownership force their clients
+ into a single memory management model.</li>
+
+ <li>Code using smart pointers is less explicit about
+ where the resource releases take place.</li>
+
+ <li><code>std::unique_ptr</code> expresses ownership
+ transfer using C++11's move semantics, which are
+ relatively new and may confuse some programmers.</li>
+
+ <li>Shared ownership can be a tempting alternative to
+ careful ownership design, obfuscating the design of a
+ system.</li>
+
+ <li>Shared ownership requires explicit bookkeeping at
+ run-time, which can be costly.</li>
+
+ <li>In some cases (e.g. cyclic references), objects
+ with shared ownership may never be deleted.</li>
+
+ <li>Smart pointers are not perfect substitutes for
+ plain pointers.</li>
+</ul>
+</div>
+
+<div class="decision">
+<p>If dynamic allocation is necessary, prefer to keep
+ownership with the code that allocated it. If other code
+needs access to the object, consider passing it a copy,
+or passing a pointer or reference without transferring
+ownership. Prefer to use <code>std::unique_ptr</code> to
+make ownership transfer explicit. For example:</p>
+
+<pre>std::unique_ptr<Foo> FooFactory();
+void FooConsumer(std::unique_ptr<Foo> ptr);
+</pre>
+
+
+
+<p>Do not design your code to use shared ownership
+without a very good reason. One such reason is to avoid
+expensive copy operations, but you should only do this if
+the performance benefits are significant, and the
+underlying object is immutable (i.e.
+<code>std::shared_ptr<const Foo></code>). If you
+do use shared ownership, prefer to use
+<code>std::shared_ptr</code>.</p>
+
+<p>Never use <code>std::auto_ptr</code>. Instead, use
+<code>std::unique_ptr</code>.</p>
+</div>
+
+</div>
+
+<h3 id="cpplint">cpplint</h3>
+
+<div class="summary">
+<p>Use <code>cpplint.py</code>
+to detect style errors.</p>
+</div>
+
+<div class="stylebody">
+
+<p><code>cpplint.py</code>
+is a tool that reads a source file and identifies many
+style errors. It is not perfect, and has both false
+positives and false negatives, but it is still a valuable
+tool. False positives can be ignored by putting <code>//
+NOLINT</code> at the end of the line or
+<code>// NOLINTNEXTLINE</code> in the previous line.</p>
+
+
+
+<p>Some projects have instructions on
+how to run <code>cpplint.py</code> from their project
+tools. If the project you are contributing to does not,
+you can download
+<a href="https://raw.githubusercontent.com/google/styleguide/gh-pages/cpplint/cpplint.py">
+<code>cpplint.py</code></a> separately.</p>
+
+</div>
+
+
+
+<h2 id="Other_C++_Features">Other C++ Features</h2>
+
+<h3 id="Rvalue_references">Rvalue References</h3>
+
+<div class="summary">
+<p>Use rvalue references only to define move constructors and move assignment
+operators, or for perfect forwarding.
+</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p> Rvalue references
+are a type of reference that can only bind to temporary
+objects. The syntax is similar to traditional reference
+syntax. For example, <code>void f(string&&
+s);</code> declares a function whose argument is an
+rvalue reference to a string.</p>
+</div>
+
+<div class="pros">
+<ul>
+ <li>Defining a move constructor (a constructor taking
+ an rvalue reference to the class type) makes it
+ possible to move a value instead of copying it. If
+ <code>v1</code> is a <code>std::vector<string></code>,
+ for example, then <code>auto v2(std::move(v1))</code>
+ will probably just result in some simple pointer
+ manipulation instead of copying a large amount of data.
+ In some cases this can result in a major performance
+ improvement.</li>
+
+ <li>Rvalue references make it possible to write a
+ generic function wrapper that forwards its arguments to
+ another function, and works whether or not its
+ arguments are temporary objects. (This is sometimes called
+ "perfect forwarding".)</li>
+
+ <li>Rvalue references make it possible to implement
+ types that are movable but not copyable, which can be
+ useful for types that have no sensible definition of
+ copying but where you might still want to pass them as
+ function arguments, put them in containers, etc.</li>
+
+ <li><code>std::move</code> is necessary to make
+ effective use of some standard-library types, such as
+ <code>std::unique_ptr</code>.</li>
+</ul>
+</div>
+
+<div class="cons">
+<ul>
+ <li>Rvalue references are a relatively new feature
+ (introduced as part of C++11), and not yet widely
+ understood. Rules like reference collapsing, and
+ automatic synthesis of move constructors, are
+ complicated.</li>
+</ul>
+</div>
+
+<div class="decision">
+ <p>Use rvalue references only to define move constructors and move assignment
+ operators (as described in <a href="#Copyable_Movable_Types">Copyable and
+ Movable Types</a>) and, in conjunction with <code><a href="http://en.cppreference.com/w/cpp/utility/forward">std::forward</a></code>,
+to support perfect forwarding. You may use <code>std::move</code> to express
+moving a value from one object to another rather than copying it. </p>
+</div>
+
+</div>
+
+<h3 id="Friends">Friends</h3>
+
+<div class="summary">
+<p>We allow use of <code>friend</code> classes and functions,
+within reason.</p>
+</div>
+
+<div class="stylebody">
+
+<p>Friends should usually be defined in the same file so
+that the reader does not have to look in another file to
+find uses of the private members of a class. A common use
+of <code>friend</code> is to have a
+<code>FooBuilder</code> class be a friend of
+<code>Foo</code> so that it can construct the inner state
+of <code>Foo</code> correctly, without exposing this
+state to the world. In some cases it may be useful to
+make a unittest class a friend of the class it tests.</p>
+
+<p>Friends extend, but do not break, the encapsulation
+boundary of a class. In some cases this is better than
+making a member public when you want to give only one
+other class access to it. However, most classes should
+interact with other classes solely through their public
+members.</p>
+
+</div>
+
+<h3 id="Exceptions">Exceptions</h3>
+
+<div class="summary">
+<p>We do not use C++ exceptions.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="pros">
+<ul>
+ <li>Exceptions allow higher levels of an application to
+ decide how to handle "can't happen" failures in deeply
+ nested functions, without the obscuring and error-prone
+ bookkeeping of error codes.</li>
+
+
+
+ <li>Exceptions are used by most other
+ modern languages. Using them in C++ would make it more
+ consistent with Python, Java, and the C++ that others
+ are familiar with.</li>
+
+ <li>Some third-party C++ libraries use exceptions, and
+ turning them off internally makes it harder to
+ integrate with those libraries.</li>
+
+ <li>Exceptions are the only way for a constructor to
+ fail. We can simulate this with a factory function or
+ an <code>Init()</code> method, but these require heap
+ allocation or a new "invalid" state, respectively.</li>
+
+ <li>Exceptions are really handy in testing
+ frameworks.</li>
+</ul>
+</div>
+
+<div class="cons">
+<ul>
+ <li>When you add a <code>throw</code> statement to an
+ existing function, you must examine all of its
+ transitive callers. Either they must make at least the
+ basic exception safety guarantee, or they must never
+ catch the exception and be happy with the program
+ terminating as a result. For instance, if
+ <code>f()</code> calls <code>g()</code> calls
+ <code>h()</code>, and <code>h</code> throws an
+ exception that <code>f</code> catches, <code>g</code>
+ has to be careful or it may not clean up properly.</li>
+
+ <li>More generally, exceptions make the control flow of
+ programs difficult to evaluate by looking at code:
+ functions may return in places you don't expect. This
+ causes maintainability and debugging difficulties. You
+ can minimize this cost via some rules on how and where
+ exceptions can be used, but at the cost of more that a
+ developer needs to know and understand.</li>
+
+ <li>Exception safety requires both RAII and different
+ coding practices. Lots of supporting machinery is
+ needed to make writing correct exception-safe code
+ easy. Further, to avoid requiring readers to understand
+ the entire call graph, exception-safe code must isolate
+ logic that writes to persistent state into a "commit"
+ phase. This will have both benefits and costs (perhaps
+ where you're forced to obfuscate code to isolate the
+ commit). Allowing exceptions would force us to always
+ pay those costs even when they're not worth it.</li>
+
+ <li>Turning on exceptions adds data to each binary
+ produced, increasing compile time (probably slightly)
+ and possibly increasing address space pressure.
+ </li>
+
+ <li>The availability of exceptions may encourage
+ developers to throw them when they are not appropriate
+ or recover from them when it's not safe to do so. For
+ example, invalid user input should not cause exceptions
+ to be thrown. We would need to make the style guide
+ even longer to document these restrictions!</li>
+</ul>
+</div>
+
+<div class="decision">
+<p>On their face, the benefits of using exceptions
+outweigh the costs, especially in new projects. However,
+for existing code, the introduction of exceptions has
+implications on all dependent code. If exceptions can be
+propagated beyond a new project, it also becomes
+problematic to integrate the new project into existing
+exception-free code. Because most existing C++ code at
+Google is not prepared to deal with exceptions, it is
+comparatively difficult to adopt new code that generates
+exceptions.</p>
+
+<p>Given that Google's existing code is not
+exception-tolerant, the costs of using exceptions are
+somewhat greater than the costs in a new project. The
+conversion process would be slow and error-prone. We
+don't believe that the available alternatives to
+exceptions, such as error codes and assertions, introduce
+a significant burden. </p>
+
+<p>Our advice against using exceptions is not predicated
+on philosophical or moral grounds, but practical ones.
+ Because we'd like to use our open-source
+projects at Google and it's difficult to do so if those
+projects use exceptions, we need to advise against
+exceptions in Google open-source projects as well.
+Things would probably be different if we had to do it all
+over again from scratch.</p>
+
+<p>This prohibition also applies to the exception-related
+features added in C++11, such as <code>noexcept</code>,
+<code>std::exception_ptr</code>, and
+<code>std::nested_exception</code>.</p>
+
+<p>There is an <a href="#Windows_Code">exception</a> to
+this rule (no pun intended) for Windows code.</p>
+</div>
+
+</div>
+
+<h3 id="Run-Time_Type_Information__RTTI_">Run-Time Type
+Information (RTTI)</h3>
+
+<div class="summary">
+<p>Avoid using Run Time Type Information (RTTI).</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p> RTTI allows a
+programmer to query the C++ class of an object at run
+time. This is done by use of <code>typeid</code> or
+<code>dynamic_cast</code>.</p>
+</div>
+
+<div class="cons">
+<p>Querying the type of an object at run-time frequently
+means a design problem. Needing to know the type of an
+object at runtime is often an indication that the design
+of your class hierarchy is flawed.</p>
+
+<p>Undisciplined use of RTTI makes code hard to maintain.
+It can lead to type-based decision trees or switch
+statements scattered throughout the code, all of which
+must be examined when making further changes.</p>
+</div>
+
+<div class="pros">
+<p>The standard alternatives to RTTI (described below)
+require modification or redesign of the class hierarchy
+in question. Sometimes such modifications are infeasible
+or undesirable, particularly in widely-used or mature
+code.</p>
+
+<p>RTTI can be useful in some unit tests. For example, it
+is useful in tests of factory classes where the test has
+to verify that a newly created object has the expected
+dynamic type. It is also useful in managing the
+relationship between objects and their mocks.</p>
+
+<p>RTTI is useful when considering multiple abstract
+objects. Consider</p>
+
+<pre>bool Base::Equal(Base* other) = 0;
+bool Derived::Equal(Base* other) {
+ Derived* that = dynamic_cast<Derived*>(other);
+ if (that == NULL)
+ return false;
+ ...
+}
+</pre>
+</div>
+
+<div class="decision">
+<p>RTTI has legitimate uses but is prone to abuse, so you
+must be careful when using it. You may use it freely in
+unittests, but avoid it when possible in other code. In
+particular, think twice before using RTTI in new code. If
+you find yourself needing to write code that behaves
+differently based on the class of an object, consider one
+of the following alternatives to querying the type:</p>
+
+<ul>
+ <li>Virtual methods are the preferred way of executing
+ different code paths depending on a specific subclass
+ type. This puts the work within the object itself.</li>
+
+ <li>If the work belongs outside the object and instead
+ in some processing code, consider a double-dispatch
+ solution, such as the Visitor design pattern. This
+ allows a facility outside the object itself to
+ determine the type of class using the built-in type
+ system.</li>
+</ul>
+
+<p>When the logic of a program guarantees that a given
+instance of a base class is in fact an instance of a
+particular derived class, then a
+<code>dynamic_cast</code> may be used freely on the
+object. Usually one
+can use a <code>static_cast</code> as an alternative in
+such situations.</p>
+
+<p>Decision trees based on type are a strong indication
+that your code is on the wrong track.</p>
+
+<pre class="badcode">if (typeid(*data) == typeid(D1)) {
+ ...
+} else if (typeid(*data) == typeid(D2)) {
+ ...
+} else if (typeid(*data) == typeid(D3)) {
+...
+</pre>
+
+<p>Code such as this usually breaks when additional
+subclasses are added to the class hierarchy. Moreover,
+when properties of a subclass change, it is difficult to
+find and modify all the affected code segments.</p>
+
+<p>Do not hand-implement an RTTI-like workaround. The
+arguments against RTTI apply just as much to workarounds
+like class hierarchies with type tags. Moreover,
+workarounds disguise your true intent.</p>
+</div>
+
+</div>
+
+<h3 id="Casting">Casting</h3>
+
+<div class="summary">
+<p>Use C++-style casts
+like <code>static_cast<float>(double_value)</code>, or brace
+initialization for conversion of arithmetic types like
+<code>int64 y = int64{1} << 42</code>. Do not use
+cast formats like
+<code>int y = (int)x</code> or <code>int y = int(x)</code> (but the latter
+is okay when invoking a constructor of a class type).</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p> C++ introduced a
+different cast system from C that distinguishes the types
+of cast operations.</p>
+</div>
+
+<div class="pros">
+<p>The problem with C casts is the ambiguity of the operation;
+sometimes you are doing a <em>conversion</em>
+(e.g., <code>(int)3.5</code>) and sometimes you are doing
+a <em>cast</em> (e.g., <code>(int)"hello"</code>). Brace
+initialization and C++ casts can often help avoid this
+ambiguity. Additionally, C++ casts are more visible when searching for
+them.</p>
+</div>
+
+<div class="cons">
+<p>The C++-style cast syntax is verbose and cumbersome.</p>
+</div>
+
+<div class="decision">
+<p>Do not use C-style casts. Instead, use these C++-style casts when
+explicit type conversion is necessary. </p>
+
+<ul>
+ <li>Use brace initialization to convert arithmetic types
+ (e.g. <code>int64{x}</code>). This is the safest approach because code
+ will not compile if conversion can result in information loss. The
+ syntax is also concise.</li>
+
+
+
+ <li>Use <code>static_cast</code> as the equivalent of a C-style cast
+ that does value conversion, when you need to
+ explicitly up-cast a pointer from a class to its superclass, or when
+ you need to explicitly cast a pointer from a superclass to a
+ subclass. In this last case, you must be sure your object is
+ actually an instance of the subclass.</li>
+
+
+
+ <li>Use <code>const_cast</code> to remove the
+ <code>const</code> qualifier (see <a href="#Use_of_const">const</a>).</li>
+
+ <li>Use <code>reinterpret_cast</code> to do unsafe
+ conversions of pointer types to and from integer and
+ other pointer types. Use this only if you know what you
+ are doing and you understand the aliasing issues.
+ </li>
+
+
+</ul>
+
+<p>See the <a href="#Run-Time_Type_Information__RTTI_">
+RTTI section</a> for guidance on the use of
+<code>dynamic_cast</code>.</p>
+</div>
+
+</div>
+
+<h3 id="Streams">Streams</h3>
+
+<div class="summary">
+<p>Use streams where appropriate, and stick to "simple"
+usages.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p>Streams are the standard I/O abstraction in C++, as
+exemplified by the standard header <code><iostream></code>.
+They are widely used in Google code, but only for debug logging
+and test diagnostics.</p>
+</div>
+
+<div class="pros">
+<p>The <code><<</code> and <code>>></code>
+stream operators provide an API for formatted I/O that
+is easily learned, portable, reusable, and extensible.
+<code>printf</code>, by contrast, doesn't even support
+<code>string</code>, to say nothing of user-defined types,
+and is very difficult to use portably.
+<code>printf</code> also obliges you to choose among the
+numerous slightly different versions of that function,
+and navigate the dozens of conversion specifiers.</p>
+
+<p>Streams provide first-class support for console I/O
+via <code>std::cin</code>, <code>std::cout</code>,
+<code>std::cerr</code>, and <code>std::clog</code>.
+The C APIs do as well, but are hampered by the need to
+manually buffer the input. </p>
+</div>
+
+<div class="cons">
+<ul>
+<li>Stream formatting can be configured by mutating the
+state of the stream. Such mutations are persistent, so
+the behavior of your code can be affected by the entire
+previous history of the stream, unless you go out of your
+way to restore it to a known state every time other code
+might have touched it. User code can not only modify the
+built-in state, it can add new state variables and behaviors
+through a registration system.</li>
+
+<li>It is difficult to precisely control stream output, due
+to the above issues, the way code and data are mixed in
+streaming code, and the use of operator overloading (which
+may select a different overload than you expect).</li>
+
+<li>The practice of building up output through chains
+of <code><<</code> operators interferes with
+internationalization, because it bakes word order into the
+code, and streams' support for localization is <a href="http://www.boost.org/doc/libs/1_48_0/libs/locale/doc/html/rationale.html#rationale_why">
+flawed</a>.</li>
+
+
+
+
+
+<li>The streams API is subtle and complex, so programmers must
+develop experience with it in order to use it effectively.
+However, streams were historically banned in Google code (except
+for logging and diagnostics), so Google engineers tend not to
+have that experience. Consequently, streams-based code is likely
+to be less readable and maintainable by Googlers than code based
+on more familiar abstractions.</li>
+
+<li>Resolving the many overloads of <code><<</code> is
+extremely costly for the compiler. When used pervasively in a
+large code base, it can consume as much as 20% of the parsing
+and semantic analysis time.</li>
+</ul>
+</div>
+
+<div class="decision">
+<p>Use streams only when they are the best tool for the job.
+This is typically the case when the I/O is ad-hoc, local,
+human-readable, and targeted at other developers rather than
+end-users. Be consistent with the code around you, and with the
+codebase as a whole; if there's an established tool for
+your problem, use that tool instead. </p>
+
+<p>Avoid using streams for I/O that faces external users or
+handles untrusted data. Instead, find and use the appropriate
+templating libraries to handle issues like internationalization,
+localization, and security hardening.</p>
+
+<p>If you do use streams, avoid the stateful parts of the
+streams API (other than error state), such as <code>imbue()</code>,
+<code>xalloc()</code>, and <code>register_callback()</code>.
+Use explicit formatting functions rather than
+stream manipulators or formatting flags to control formatting
+details such as number base, precision, or padding.</p>
+
+<p>Overload <code><<</code> as a streaming operator
+for your type only if your type represents a value, and
+<code><<</code> writes out a human-readable string
+representation of that value. Avoid exposing implementation
+details in the output of <code><<</code>; if you need to print
+object internals for debugging, use named functions instead
+(a method named <code>DebugString()</code> is the most common
+convention).</p>
+</div>
+
+</div>
+
+<h3 id="Preincrement_and_Predecrement">Preincrement and Predecrement</h3>
+
+<div class="summary">
+<p>Use prefix form (<code>++i</code>) of the increment and
+decrement operators with iterators and other template
+objects.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p> When a variable
+is incremented (<code>++i</code> or <code>i++</code>) or
+decremented (<code>--i</code> or <code>i--</code>) and
+the value of the expression is not used, one must decide
+whether to preincrement (decrement) or postincrement
+(decrement).</p>
+</div>
+
+<div class="pros">
+<p>When the return value is ignored, the "pre" form
+(<code>++i</code>) is never less efficient than the
+"post" form (<code>i++</code>), and is often more
+efficient. This is because post-increment (or decrement)
+requires a copy of <code>i</code> to be made, which is
+the value of the expression. If <code>i</code> is an
+iterator or other non-scalar type, copying <code>i</code>
+could be expensive. Since the two types of increment
+behave the same when the value is ignored, why not just
+always pre-increment?</p>
+</div>
+
+<div class="cons">
+<p>The tradition developed, in C, of using post-increment
+when the expression value is not used, especially in
+<code>for</code> loops. Some find post-increment easier
+to read, since the "subject" (<code>i</code>) precedes
+the "verb" (<code>++</code>), just like in English.</p>
+</div>
+
+<div class="decision">
+<p> For simple scalar
+(non-object) values there is no reason to prefer one form
+and we allow either. For iterators and other template
+types, use pre-increment.</p>
+</div>
+
+</div>
+
+<h3 id="Use_of_const">Use of const</h3>
+
+<div class="summary">
+<p>Use <code>const</code> whenever it makes sense. With C++11,
+<code>constexpr</code> is a better choice for some uses of
+const.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p> Declared variables and parameters can be preceded
+by the keyword <code>const</code> to indicate the variables
+are not changed (e.g., <code>const int foo</code>). Class
+functions can have the <code>const</code> qualifier to
+indicate the function does not change the state of the
+class member variables (e.g., <code>class Foo { int
+Bar(char c) const; };</code>).</p>
+</div>
+
+<div class="pros">
+<p>Easier for people to understand how variables are being
+used. Allows the compiler to do better type checking,
+and, conceivably, generate better code. Helps people
+convince themselves of program correctness because they
+know the functions they call are limited in how they can
+modify your variables. Helps people know what functions
+are safe to use without locks in multi-threaded
+programs.</p>
+</div>
+
+<div class="cons">
+<p><code>const</code> is viral: if you pass a
+<code>const</code> variable to a function, that function
+must have <code>const</code> in its prototype (or the
+variable will need a <code>const_cast</code>). This can
+be a particular problem when calling library
+functions.</p>
+</div>
+
+<div class="decision">
+<p><code>const</code> variables, data members, methods
+and arguments add a level of compile-time type checking;
+it is better to detect errors as soon as possible.
+Therefore we strongly recommend that you use
+<code>const</code> whenever it makes sense to do so:</p>
+
+<ul>
+ <li>If a function guarantees that it will not modify an argument
+ passed by reference or by pointer, the corresponding function parameter
+ should be a reference-to-const (<code>const T&</code>) or
+ pointer-to-const (<code>const T*</code>), respectively.</li>
+
+ <li>Declare methods to be <code>const</code> whenever
+ possible. Accessors should almost always be
+ <code>const</code>. Other methods should be const if
+ they do not modify any data members, do not call any
+ non-<code>const</code> methods, and do not return a
+ non-<code>const</code> pointer or
+ non-<code>const</code> reference to a data member.</li>
+
+ <li>Consider making data members <code>const</code>
+ whenever they do not need to be modified after
+ construction.</li>
+</ul>
+
+<p>The <code>mutable</code> keyword is allowed but is
+unsafe when used with threads, so thread safety should be
+carefully considered first.</p>
+</div>
+
+<div class="stylepoint_subsection">
+<h4>Where to put the const</h4>
+
+<p>Some people favor the form <code>int const *foo</code>
+to <code>const int* foo</code>. They argue that this is
+more readable because it's more consistent: it keeps the
+rule that <code>const</code> always follows the object
+it's describing. However, this consistency argument
+doesn't apply in codebases with few deeply-nested pointer
+expressions since most <code>const</code> expressions
+have only one <code>const</code>, and it applies to the
+underlying value. In such cases, there's no consistency
+to maintain. Putting the <code>const</code> first is
+arguably more readable, since it follows English in
+putting the "adjective" (<code>const</code>) before the
+"noun" (<code>int</code>).</p>
+
+<p>That said, while we encourage putting
+<code>const</code> first, we do not require it. But be
+consistent with the code around you!</p>
+</div>
+
+</div>
+
+<h3 id="Use_of_constexpr">Use of constexpr</h3>
+
+<div class="summary">
+<p>In C++11, use <code>constexpr</code> to define true
+constants or to ensure constant initialization.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p> Some variables can be declared <code>constexpr</code>
+to indicate the variables are true constants, i.e. fixed at
+compilation/link time. Some functions and constructors
+can be declared <code>constexpr</code> which enables them
+to be used in defining a <code>constexpr</code>
+variable.</p>
+</div>
+
+<div class="pros">
+<p>Use of <code>constexpr</code> enables definition of
+constants with floating-point expressions rather than
+just literals; definition of constants of user-defined
+types; and definition of constants with function
+calls.</p>
+</div>
+
+<div class="cons">
+<p>Prematurely marking something as constexpr may cause
+migration problems if later on it has to be downgraded.
+Current restrictions on what is allowed in constexpr
+functions and constructors may invite obscure workarounds
+in these definitions.</p>
+</div>
+
+<div class="decision">
+<p><code>constexpr</code> definitions enable a more
+robust specification of the constant parts of an
+interface. Use <code>constexpr</code> to specify true
+constants and the functions that support their
+definitions. Avoid complexifying function definitions to
+enable their use with <code>constexpr</code>. Do not use
+<code>constexpr</code> to force inlining.</p>
+</div>
+
+</div>
+
+<h3 id="Integer_Types">Integer Types</h3>
+
+<div class="summary">
+<p>Of the built-in C++ integer types, the only one used
+ is
+<code>int</code>. If a program needs a variable of a
+different size, use
+a precise-width integer type from
+<code><stdint.h></code>, such as
+<code>int16_t</code>. If your variable represents a
+value that could ever be greater than or equal to 2^31
+(2GiB), use a 64-bit type such as
+<code>int64_t</code>.
+Keep in mind that even if your value won't ever be too large
+for an <code>int</code>, it may be used in intermediate
+calculations which may require a larger type. When in doubt,
+choose a larger type.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p> C++ does not specify the sizes of its integer types.
+Typically people assume that <code>short</code> is 16 bits,
+<code>int</code> is 32 bits, <code>long</code> is 32 bits
+and <code>long long</code> is 64 bits.</p>
+</div>
+
+<div class="pros">
+<p>Uniformity of declaration.</p>
+</div>
+
+<div class="cons">
+<p>The sizes of integral types in C++ can vary based on
+compiler and architecture.</p>
+</div>
+
+<div class="decision">
+
+<p>
+<code><stdint.h></code> defines types
+like <code>int16_t</code>, <code>uint32_t</code>,
+<code>int64_t</code>, etc. You should always use
+those in preference to <code>short</code>, <code>unsigned
+long long</code> and the like, when you need a guarantee
+on the size of an integer. Of the C integer types, only
+<code>int</code> should be used. When appropriate, you
+are welcome to use standard types like
+<code>size_t</code> and <code>ptrdiff_t</code>.</p>
+
+<p>We use <code>int</code> very often, for integers we
+know are not going to be too big, e.g., loop counters.
+Use plain old <code>int</code> for such things. You
+should assume that an <code>int</code> is
+
+at least 32 bits, but don't
+assume that it has more than 32 bits. If you need a 64-bit
+integer type, use
+<code>int64_t</code>
+or
+<code>uint64_t</code>.</p>
+
+<p>For integers we know can be "big",
+ use
+<code>int64_t</code>.
+</p>
+
+<p>You should not use the unsigned integer types such as
+<code>uint32_t</code>, unless there is a valid
+reason such as representing a bit pattern rather than a
+number, or you need defined overflow modulo 2^N. In
+particular, do not use unsigned types to say a number
+will never be negative. Instead, use
+assertions for this.</p>
+
+
+
+<p>If your code is a container that returns a size, be
+sure to use a type that will accommodate any possible
+usage of your container. When in doubt, use a larger type
+rather than a smaller type.</p>
+
+<p>Use care when converting integer types. Integer
+conversions and promotions can cause non-intuitive
+behavior. </p>
+</div>
+
+<div class="stylepoint_subsection">
+
+<h4>On Unsigned Integers</h4>
+
+<p>Some people, including some textbook authors,
+recommend using unsigned types to represent numbers that
+are never negative. This is intended as a form of
+self-documentation. However, in C, the advantages of such
+documentation are outweighed by the real bugs it can
+introduce. Consider:</p>
+
+<pre>for (unsigned int i = foo.Length()-1; i >= 0; --i) ...
+</pre>
+
+<p>This code will never terminate! Sometimes gcc will
+notice this bug and warn you, but often it will not.
+Equally bad bugs can occur when comparing signed and
+unsigned variables. Basically, C's type-promotion scheme
+causes unsigned types to behave differently than one
+might expect.</p>
+
+<p>So, document that a variable is non-negative using
+assertions. Don't use an unsigned
+type.</p>
+</div>
+
+</div>
+
+<h3 id="64-bit_Portability">64-bit Portability</h3>
+
+<div class="summary">
+<p>Code should be 64-bit and 32-bit friendly. Bear in mind
+problems of printing, comparisons, and structure alignment.</p>
+</div>
+
+<div class="stylebody">
+
+<ul>
+ <li>
+ <p><code>printf()</code> specifiers for some types
+ are not cleanly portable between 32-bit and 64-bit
+ systems. C99 defines some portable format specifiers.
+ Unfortunately, MSVC 7.1 does not understand some of
+ these specifiers and the standard is missing a few,
+ so we
+ have to define our own ugly versions in some cases
+ (in the style of the standard include file
+ <code>inttypes.h</code>):</p>
+
+ <div>
+ <pre>// printf macros for size_t, in the style of inttypes.h
+#ifdef _LP64
+#define __PRIS_PREFIX "z"
+#else
+#define __PRIS_PREFIX
+#endif
+
+// Use these macros after a % in a printf format string
+// to get correct 32/64 bit behavior, like this:
+// size_t size = records.size();
+// printf("%" PRIuS "\n", size);
+
+#define PRIdS __PRIS_PREFIX "d"
+#define PRIxS __PRIS_PREFIX "x"
+#define PRIuS __PRIS_PREFIX "u"
+#define PRIXS __PRIS_PREFIX "X"
+#define PRIoS __PRIS_PREFIX "o"
+ </pre>
+ </div>
+
+ <table border="1" summary="portable printf specifiers">
+ <tbody><tr align="center">
+ <th>Type</th>
+ <th>DO NOT use</th>
+ <th>DO use</th>
+ <th>Notes</th>
+ </tr>
+
+ <tr align="center">
+ <td><code>void *</code> (or any pointer)</td>
+ <td><code>%lx</code></td>
+ <td><code>%p</code></td>
+ <td></td>
+ </tr>
+
+
+
+ <tr align="center">
+ <td><code>int64_t</code></td>
+ <td><code>%qd</code>, <code>%lld</code></td>
+ <td><code>%" PRId64 "</code></td>
+ <td></td>
+ </tr>
+
+
+
+ <tr align="center">
+ <td><code>uint64_t</code></td>
+ <td><code>%qu</code>, <code>%llu</code>,
+ <code>%llx</code></td>
+ <td><code>%" PRIu64 "</code>,
+ <code>%" PRIx64 "</code></td>
+ <td></td>
+ </tr>
+
+
+
+ <tr align="center">
+ <td><code>size_t</code></td>
+ <td><code>%u</code></td>
+ <td><code>%" PRIuS "</code>, <code>%" PRIxS "</code></td>
+ <td>
+ C99 specifies <code>%zu</code></td>
+ </tr>
+
+ <tr align="center">
+ <td><code>ptrdiff_t</code></td>
+ <td><code>%d</code></td>
+ <td><code>%" PRIdS "</code></td>
+ <td>
+ C99 specifies <code>%td</code></td>
+ </tr>
+
+
+ </tbody></table>
+
+ <p>Note that the <code>PRI*</code> macros expand to
+ independent strings which are concatenated by the
+ compiler. Hence if you are using a non-constant
+ format string, you need to insert the value of the
+ macro into the format, rather than the name. Note also
+ that spaces are required around the macro identifier to
+ separate it from the string literal. It is
+ still possible, as usual, to include length
+ specifiers, etc., after the <code>%</code> when using
+ the <code>PRI*</code> macros. So, e.g.
+ <code>printf("x = %30" PRIuS "\n", x)</code> would
+ expand on 32-bit Linux to <code>printf("x = %30" "u"
+ "\n", x)</code>, which the compiler will treat as
+ <code>printf("x = %30u\n", x)</code>.</p>
+
+
+ </li>
+
+ <li>Remember that <code>sizeof(void *)</code> !=
+ <code>sizeof(int)</code>. Use <code>intptr_t</code> if
+ you want a pointer-sized integer.</li>
+
+ <li>You may need to be careful with structure
+ alignments, particularly for structures being stored on
+ disk. Any class/structure with a
+ <code>int64_t</code>/<code>uint64_t</code>
+ member will by default end up being 8-byte aligned on a
+ 64-bit system. If you have such structures being shared
+ on disk between 32-bit and 64-bit code, you will need
+ to ensure that they are packed the same on both
+ architectures.
+ Most compilers offer a way to
+ alter structure alignment. For gcc, you can use
+ <code>__attribute__((packed))</code>. MSVC offers
+ <code>#pragma pack()</code> and
+ <code>__declspec(align())</code>.</li>
+
+ <li>
+ <p>Use the <code>LL</code> or <code>ULL</code>
+ suffixes as needed to create 64-bit constants. For
+ example:</p>
+
+
+<pre>int64_t my_value = 0x123456789LL;
+uint64_t my_mask = 3ULL << 48;
+</pre>
+ </li>
+</ul>
+
+</div>
+
+<h3 id="Preprocessor_Macros">Preprocessor Macros</h3>
+
+<div class="summary">
+<p>Avoid defining macros, especially in headers; prefer
+inline functions, enums, and <code>const</code> variables.
+Name macros with a project-specific prefix. Do not use
+macros to define pieces of a C++ API.</p>
+</div>
+
+<div class="stylebody">
+
+<p>Macros mean that the code you see is not the same as
+the code the compiler sees. This can introduce unexpected
+behavior, especially since macros have global scope.</p>
+
+<p>The problems introduced by macros are especially severe
+when they are used to define pieces of a C++ API,
+and still more so for public APIs. Every error message from
+the compiler when developers incorrectly use that interface
+now must explain how the macros formed the interface.
+Refactoring and analysis tools have a dramatically harder
+time updating the interface. As a consequence, we
+specifically disallow using macros in this way.
+For example, avoid patterns like:</p>
+
+<pre class="badcode">class WOMBAT_TYPE(Foo) {
+ // ...
+
+ public:
+ EXPAND_PUBLIC_WOMBAT_API(Foo)
+
+ EXPAND_WOMBAT_COMPARISONS(Foo, ==, <)
+};
+</pre>
+
+<p>Luckily, macros are not nearly as necessary in C++ as
+they are in C. Instead of using a macro to inline
+performance-critical code, use an inline function.
+Instead of using a macro to store a constant, use a
+<code>const</code> variable. Instead of using a macro to
+"abbreviate" a long variable name, use a reference.
+Instead of using a macro to conditionally compile code
+... well, don't do that at all (except, of course, for
+the <code>#define</code> guards to prevent double
+inclusion of header files). It makes testing much more
+difficult.</p>
+
+<p>Macros can do things these other techniques cannot,
+and you do see them in the codebase, especially in the
+lower-level libraries. And some of their special features
+(like stringifying, concatenation, and so forth) are not
+available through the language proper. But before using a
+macro, consider carefully whether there's a non-macro way
+to achieve the same result. If you need to use a macro to
+define an interface, contact
+your project leads to request
+a waiver of this rule.</p>
+
+<p>The following usage pattern will avoid many problems
+with macros; if you use macros, follow it whenever
+possible:</p>
+
+<ul>
+ <li>Don't define macros in a <code>.h</code> file.</li>
+
+ <li><code>#define</code> macros right before you use
+ them, and <code>#undef</code> them right after.</li>
+
+ <li>Do not just <code>#undef</code> an existing macro
+ before replacing it with your own; instead, pick a name
+ that's likely to be unique.</li>
+
+ <li>Try not to use macros that expand to unbalanced C++
+ constructs, or at least document that behavior
+ well.</li>
+
+ <li>Prefer not using <code>##</code> to generate
+ function/class/variable names.</li>
+</ul>
+
+<p>Exporting macros from headers (i.e. defining them in a header
+without <code>#undef</code>ing them before the end of the header)
+is extremely strongly discouraged. If you do export a macro from a
+header, it must have a globally unique name. To achieve this, it
+must be named with a prefix consisting of your project's namespace
+name (but upper case). </p>
+
+</div>
+
+<h3 id="0_and_nullptr/NULL">0 and nullptr/NULL</h3>
+
+<div class="summary">
+<p>Use <code>0</code> for integers, <code>0.0</code> for
+reals, <code>nullptr</code> (or <code>NULL</code>) for
+pointers, and <code>'\0'</code> for chars.</p>
+</div>
+
+<div class="stylebody">
+
+<p>Use <code>0</code> for integers and <code>0.0</code>
+for reals. This is not controversial.</p>
+
+<p> For
+pointers (address values), there is a choice between
+<code>0</code>, <code>NULL</code>, and
+<code>nullptr</code>. For projects that allow C++11
+features, use <code>nullptr</code>. For C++03 projects,
+we prefer <code>NULL</code> because it looks like a
+pointer. In fact, some C++ compilers provide special
+definitions of <code>NULL</code> which enable them to
+give useful warnings, particularly in situations where
+<code>sizeof(NULL)</code> is not equal to
+<code>sizeof(0)</code>.</p>
+
+<p>Use <code>'\0'</code> for chars. This is the correct
+type and also makes code more readable.</p>
+
+</div>
+
+<h3 id="sizeof">sizeof</h3>
+
+<div class="summary">
+<p>Prefer <code>sizeof(<var>varname</var>)</code> to
+<code>sizeof(<var>type</var>)</code>.</p>
+</div>
+
+<div class="stylebody">
+
+<p>Use <code>sizeof(<var>varname</var>)</code> when you
+take the size of a particular variable.
+<code>sizeof(<var>varname</var>)</code> will update
+appropriately if someone changes the variable type either
+now or later. You may use
+<code>sizeof(<var>type</var>)</code> for code unrelated
+to any particular variable, such as code that manages an
+external or internal data format where a variable of an
+appropriate C++ type is not convenient.</p>
+
+<pre>Struct data;
+memset(&data, 0, sizeof(data));
+</pre>
+
+<pre class="badcode">memset(&data, 0, sizeof(Struct));
+</pre>
+
+<pre>if (raw_size < sizeof(int)) {
+ LOG(ERROR) << "compressed record not big enough for count: " << raw_size;
+ return false;
+}
+</pre>
+
+</div>
+
+<h3 id="auto">auto</h3>
+
+<div class="summary">
+<p>Use <code>auto</code> to avoid type names that are noisy, obvious,
+or unimportant - cases where the type doesn't aid in clarity for the
+reader. Continue to use manifest type declarations when it helps
+readability.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="pros">
+<p>
+</p><ul>
+<li>C++ type names can be long and cumbersome, especially when they
+involve templates or namespaces.</li>
+<li>When a C++ type name is repeated within a single declaration or a
+small code region, the repetition may not be aiding readability.</li>
+<li>It is sometimes safer to let the type be specified by the type of
+the initialization expression, since that avoids the possibility of
+unintended copies or type conversions.</li>
+</ul>
+</div>
+<div class="cons">
+
+<p>Sometimes code is clearer when types are manifest,
+especially when a variable's initialization depends on
+things that were declared far away. In expressions
+like:</p>
+
+<pre class="badcode">auto foo = x.add_foo();
+auto i = y.Find(key);
+</pre>
+
+<p>it may not be obvious what the resulting types are if the type
+of <code>y</code> isn't very well known, or if <code>y</code> was
+declared many lines earlier.</p>
+
+<p>Programmers have to understand the difference between
+<code>auto</code> and <code>const auto&</code> or
+they'll get copies when they didn't mean to.</p>
+
+<p>If an <code>auto</code> variable is used as part of an
+interface, e.g. as a constant in a header, then a
+programmer might change its type while only intending to
+change its value, leading to a more radical API change
+than intended.</p>
+</div>
+
+<div class="decision">
+
+<p><code>auto</code> is permitted when it increases readability,
+particularly as described below. Never initialize an <code>auto</code>-typed
+variable with a braced initializer list.</p>
+
+<p>Specific cases where <code>auto</code> is allowed or encouraged:
+</p><ul>
+<li>(Encouraged) For iterators and other long/cluttery type names, particularly
+when the type is clear from context (calls
+to <code>find</code>, <code>begin</code>, or <code>end</code> for
+instance).</li>
+<li>(Allowed) When the type is clear from local context (in the same expression
+or within a few lines). Initialization of a pointer or smart pointer
+with calls
+to <code>new</code>
+commonly falls into this category, as does use of <code>auto</code> in
+a range-based loop over a container whose type is spelled out
+nearby.</li>
+<li>(Allowed) When the type doesn't matter because it isn't being used for
+anything other than equality comparison.</li>
+<li>(Encouraged) When iterating over a map with a range-based loop
+(because it is often assumed that the correct type
+is <code>std::pair<KeyType, ValueType></code> whereas it is actually
+<code>std::pair<const KeyType, ValueType></code>). This is
+particularly well paired with local <code>key</code>
+and <code>value</code> aliases for <code>.first</code>
+and <code>.second</code> (often const-ref).
+<pre class="code">for (const auto& item : some_map) {
+ const KeyType& key = item.first;
+ const ValType& value = item.second;
+ // The rest of the loop can now just refer to key and value,
+ // a reader can see the types in question, and we've avoided
+ // the too-common case of extra copies in this iteration.
+}
+</pre>
+</li>
+</ul>
+
+</div>
+
+</div>
+
+<h3 id="Braced_Initializer_List">Braced Initializer List</h3>
+
+<div class="summary">
+<p>You may use braced initializer lists.</p>
+</div>
+
+<div class="stylebody">
+
+<p>In C++03, aggregate types (arrays and structs with no
+constructor) could be initialized with braced initializer lists.</p>
+
+<pre>struct Point { int x; int y; };
+Point p = {1, 2};
+</pre>
+
+<p>In C++11, this syntax was generalized, and any object type can now
+be created with a braced initializer list, known as a
+<i>braced-init-list</i> in the C++ grammar. Here are a few examples
+of its use.</p>
+
+<pre>// Vector takes a braced-init-list of elements.
+std::vector<string> v{"foo", "bar"};
+
+// Basically the same, ignoring some small technicalities.
+// You may choose to use either form.
+std::vector<string> v = {"foo", "bar"};
+
+// Usable with 'new' expressions.
+auto p = new vector<string>{"foo", "bar"};
+
+// A map can take a list of pairs. Nested braced-init-lists work.
+std::map<int, string> m = {{1, "one"}, {2, "2"}};
+
+// A braced-init-list can be implicitly converted to a return type.
+std::vector<int> test_function() { return {1, 2, 3}; }
+
+// Iterate over a braced-init-list.
+for (int i : {-1, -2, -3}) {}
+
+// Call a function using a braced-init-list.
+void TestFunction2(std::vector<int> v) {}
+TestFunction2({1, 2, 3});
+</pre>
+
+<p>A user-defined type can also define a constructor and/or assignment operator
+that take <code>std::initializer_list<T></code>, which is automatically
+created from <i>braced-init-list</i>:</p>
+
+<pre>class MyType {
+ public:
+ // std::initializer_list references the underlying init list.
+ // It should be passed by value.
+ MyType(std::initializer_list<int> init_list) {
+ for (int i : init_list) append(i);
+ }
+ MyType& operator=(std::initializer_list<int> init_list) {
+ clear();
+ for (int i : init_list) append(i);
+ }
+};
+MyType m{2, 3, 5, 7};
+</pre>
+
+<p>Finally, brace initialization can also call ordinary
+constructors of data types, even if they do not have
+<code>std::initializer_list<T></code> constructors.</p>
+
+<pre>double d{1.23};
+// Calls ordinary constructor as long as MyOtherType has no
+// std::initializer_list constructor.
+class MyOtherType {
+ public:
+ explicit MyOtherType(string);
+ MyOtherType(int, string);
+};
+MyOtherType m = {1, "b"};
+// If the constructor is explicit, you can't use the "= {}" form.
+MyOtherType m{"b"};
+</pre>
+
+<p>Never assign a <i>braced-init-list</i> to an auto
+local variable. In the single element case, what this
+means can be confusing.</p>
+
+<pre class="badcode">auto d = {1.23}; // d is a std::initializer_list<double>
+</pre>
+
+<pre>auto d = double{1.23}; // Good -- d is a double, not a std::initializer_list.
+</pre>
+
+<p>See <a href="#Braced_Initializer_List_Format">Braced_Initializer_List_Format</a> for formatting.</p>
+
+</div>
+
+<h3 id="Lambda_expressions">Lambda expressions</h3>
+
+<div class="summary">
+<p>Use lambda expressions where appropriate. Prefer explicit captures
+when the lambda will escape the current scope.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+
+<p> Lambda expressions are a concise way of creating anonymous
+function objects. They're often useful when passing
+functions as arguments. For example:</p>
+
+<pre>std::sort(v.begin(), v.end(), [](int x, int y) {
+ return Weight(x) < Weight(y);
+});
+</pre>
+
+<p> They further allow capturing variables from the enclosing scope either
+explicitly by name, or implicitly using a default capture. Explicit captures
+require each variable to be listed, as
+either a value or reference capture:</p>
+
+<pre>int weight = 3;
+int sum = 0;
+// Captures `weight` by value and `sum` by reference.
+std::for_each(v.begin(), v.end(), [weight, &sum](int x) {
+ sum += weight * x;
+});
+</pre>
+
+
+Default captures implicitly capture any variable referenced in the
+lambda body, including <code>this</code> if any members are used:
+
+<pre>const std::vector<int> lookup_table = ...;
+std::vector<int> indices = ...;
+// Captures `lookup_table` by reference, sorts `indices` by the value
+// of the associated element in `lookup_table`.
+std::sort(indices.begin(), indices.end(), [&](int a, int b) {
+ return lookup_table[a] < lookup_table[b];
+});
+</pre>
+
+<p>Lambdas were introduced in C++11 along with a set of utilities
+for working with function objects, such as the polymorphic
+wrapper <code>std::function</code>.
+</p>
+</div>
+
+<div class="pros">
+<ul>
+ <li>Lambdas are much more concise than other ways of
+ defining function objects to be passed to STL
+ algorithms, which can be a readability
+ improvement.</li>
+
+ <li>Appropriate use of default captures can remove
+ redundancy and highlight important exceptions from
+ the default.</li>
+
+ <li>Lambdas, <code>std::function</code>, and
+ <code>std::bind</code> can be used in combination as a
+ general purpose callback mechanism; they make it easy
+ to write functions that take bound functions as
+ arguments.</li>
+</ul>
+</div>
+
+<div class="cons">
+<ul>
+ <li>Variable capture in lambdas can be a source of dangling-pointer
+ bugs, particularly if a lambda escapes the current scope.</li>
+
+ <li>Default captures by value can be misleading because they do not prevent
+ dangling-pointer bugs. Capturing a pointer by value doesn't cause a deep
+ copy, so it often has the same lifetime issues as capture by reference.
+ This is especially confusing when capturing 'this' by value, since the use
+ of 'this' is often implicit.</li>
+
+ <li>It's possible for use of lambdas to get out of
+ hand; very long nested anonymous functions can make
+ code harder to understand.</li>
+
+</ul>
+</div>
+
+<div class="decision">
+<ul>
+<li>Use lambda expressions where appropriate, with formatting as
+described <a href="#Formatting_Lambda_Expressions">below</a>.</li>
+<li>Prefer explicit captures if the lambda may escape the current scope.
+For example, instead of:
+<pre class="badcode">{
+ Foo foo;
+ ...
+ executor->Schedule([&] { Frobnicate(foo); })
+ ...
+}
+// BAD! The fact that the lambda makes use of a reference to `foo` and
+// possibly `this` (if `Frobnicate` is a member function) may not be
+// apparent on a cursory inspection. If the lambda is invoked after
+// the function returns, that would be bad, because both `foo`
+// and the enclosing object could have been destroyed.
+</pre>
+prefer to write:
+<pre>{
+ Foo foo;
+ ...
+ executor->Schedule([&foo] { Frobnicate(foo); })
+ ...
+}
+// BETTER - The compile will fail if `Frobnicate` is a member
+// function, and it's clearer that `foo` is dangerously captured by
+// reference.
+</pre>
+</li>
+<li>Use default capture by reference ([&]) only when the
+lifetime of the lambda is obviously shorter than any potential
+captures.
+</li>
+<li>Use default capture by value ([=]) only as a means of binding a
+few variables for a short lambda, where the set of captured
+variables is obvious at a glance. Prefer not to write long or
+complex lambdas with default capture by value.
+</li>
+<li>Keep unnamed lambdas short. If a lambda body is more than
+maybe five lines long, prefer to give the lambda a name, or to
+use a named function instead of a lambda.</li>
+<li>Specify the return type of the lambda explicitly if that will
+make it more obvious to readers, as with
+<a href="#auto"><code>auto</code></a>.</li>
+
+</ul>
+</div>
+
+</div>
+
+<h3 id="Template_metaprogramming">Template metaprogramming</h3>
+<div class="summary">
+<p>Avoid complicated template programming.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p>Template metaprogramming refers to a family of techniques that
+exploit the fact that the C++ template instantiation mechanism is
+Turing complete and can be used to perform arbitrary compile-time
+computation in the type domain.</p>
+</div>
+
+<div class="pros">
+<p>Template metaprogramming allows extremely flexible interfaces that
+are type safe and high performance. Facilities like
+
+<a href="https://code.google.com/p/googletest/">Google Test</a>,
+<code>std::tuple</code>, <code>std::function</code>, and
+Boost.Spirit would be impossible without it.</p>
+</div>
+
+<div class="cons">
+<p>The techniques used in template metaprogramming are often obscure
+to anyone but language experts. Code that uses templates in
+complicated ways is often unreadable, and is hard to debug or
+maintain.</p>
+
+<p>Template metaprogramming often leads to extremely poor compiler
+time error messages: even if an interface is simple, the complicated
+implementation details become visible when the user does something
+wrong.</p>
+
+<p>Template metaprogramming interferes with large scale refactoring by
+making the job of refactoring tools harder. First, the template code
+is expanded in multiple contexts, and it's hard to verify that the
+transformation makes sense in all of them. Second, some refactoring
+tools work with an AST that only represents the structure of the code
+after template expansion. It can be difficult to automatically work
+back to the original source construct that needs to be
+rewritten.</p>
+</div>
+
+<div class="decision">
+<p>Template metaprogramming sometimes allows cleaner and easier-to-use
+interfaces than would be possible without it, but it's also often a
+temptation to be overly clever. It's best used in a small number of
+low level components where the extra maintenance burden is spread out
+over a large number of uses.</p>
+
+<p>Think twice before using template metaprogramming or other
+complicated template techniques; think about whether the average
+member of your team will be able to understand your code well enough
+to maintain it after you switch to another project, or whether a
+non-C++ programmer or someone casually browsing the code base will be
+able to understand the error messages or trace the flow of a function
+they want to call. If you're using recursive template instantiations
+or type lists or metafunctions or expression templates, or relying on
+SFINAE or on the <code>sizeof</code> trick for detecting function
+overload resolution, then there's a good chance you've gone too
+far.</p>
+
+<p>If you use template metaprogramming, you should expect to put
+considerable effort into minimizing and isolating the complexity. You
+should hide metaprogramming as an implementation detail whenever
+possible, so that user-facing headers are readable, and you should
+make sure that tricky code is especially well commented. You should
+carefully document how the code is used, and you should say something
+about what the "generated" code looks like. Pay extra attention to the
+error messages that the compiler emits when users make mistakes. The
+error messages are part of your user interface, and your code should
+be tweaked as necessary so that the error messages are understandable
+and actionable from a user point of view.</p>
+
+</div>
+</div>
+
+
+<h3 id="Boost">Boost</h3>
+
+<div class="summary">
+<p>Use only approved libraries from the Boost library
+collection.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p> The
+<a href="https://www.boost.org/">
+Boost library collection</a> is a popular collection of
+peer-reviewed, free, open-source C++ libraries.</p>
+</div>
+
+<div class="pros">
+<p>Boost code is generally very high-quality, is widely
+portable, and fills many important gaps in the C++
+standard library, such as type traits and better binders.</p>
+</div>
+
+<div class="cons">
+<p>Some Boost libraries encourage coding practices which can
+hamper readability, such as metaprogramming and other
+advanced template techniques, and an excessively
+"functional" style of programming. </p>
+</div>
+
+<div class="decision">
+
+
+
+<div>
+<p>In order to maintain a high level of readability for
+all contributors who might read and maintain code, we
+only allow an approved subset of Boost features.
+Currently, the following libraries are permitted:</p>
+
+<ul>
+ <li>
+ <a href="https://www.boost.org/libs/utility/call_traits.htm">
+ Call Traits</a> from <code>boost/call_traits.hpp</code></li>
+
+ <li><a href="https://www.boost.org/libs/utility/compressed_pair.htm">
+ Compressed Pair</a> from <code>boost/compressed_pair.hpp</code></li>
+
+ <li><a href="https://www.boost.org/libs/graph/">
+ The Boost Graph Library (BGL)</a> from <code>boost/graph</code>,
+ except serialization (<code>adj_list_serialize.hpp</code>) and
+ parallel/distributed algorithms and data structures
+ (<code>boost/graph/parallel/*</code> and
+ <code>boost/graph/distributed/*</code>).</li>
+
+ <li><a href="https://www.boost.org/libs/property_map/">
+ Property Map</a> from <code>boost/property_map</code>, except
+ parallel/distributed property maps (<code>boost/property_map/parallel/*</code>).</li>
+
+ <li><a href="https://www.boost.org/libs/iterator/">
+ Iterator</a> from <code>boost/iterator</code></li>
+
+ <li>The part of <a href="https://www.boost.org/libs/polygon/">
+ Polygon</a> that deals with Voronoi diagram
+ construction and doesn't depend on the rest of
+ Polygon:
+ <code>boost/polygon/voronoi_builder.hpp</code>,
+ <code>boost/polygon/voronoi_diagram.hpp</code>, and
+ <code>boost/polygon/voronoi_geometry_type.hpp</code></li>
+
+ <li><a href="https://www.boost.org/libs/bimap/">
+ Bimap</a> from <code>boost/bimap</code></li>
+
+ <li><a href="https://www.boost.org/libs/math/doc/html/dist.html">
+ Statistical Distributions and Functions</a> from
+ <code>boost/math/distributions</code></li>
+
+ <li><a href="https://www.boost.org/libs/math/doc/html/special.html">
+ Special Functions</a> from <code>boost/math/special_functions</code></li>
+
+ <li><a href="https://www.boost.org/libs/multi_index/">
+ Multi-index</a> from <code>boost/multi_index</code></li>
+
+ <li><a href="https://www.boost.org/libs/heap/">
+ Heap</a> from <code>boost/heap</code></li>
+
+ <li>The flat containers from
+ <a href="https://www.boost.org/libs/container/">Container</a>:
+ <code>boost/container/flat_map</code>, and
+ <code>boost/container/flat_set</code></li>
+
+ <li><a href="https://www.boost.org/libs/intrusive/">Intrusive</a>
+ from <code>boost/intrusive</code>.</li>
+
+ <li><a href="https://www.boost.org/libs/sort/">The
+ <code>boost/sort</code> library</a>.</li>
+
+ <li><a href="https://www.boost.org/libs/preprocessor/">Preprocessor</a>
+ from <code>boost/preprocessor</code>.</li>
+</ul>
+
+<p>We are actively considering adding other Boost
+features to the list, so this list may be expanded in
+the future.</p>
+</div>
+
+<p>The following libraries are permitted, but their use
+is discouraged because they've been superseded by
+standard libraries in C++11:</p>
+
+<ul>
+ <li><a href="https://www.boost.org/libs/array/">
+ Array</a> from <code>boost/array.hpp</code>: use
+ <a href="http://en.cppreference.com/w/cpp/container/array">
+ <code>std::array</code></a> instead.</li>
+
+ <li><a href="https://www.boost.org/libs/ptr_container/">
+ Pointer Container</a> from <code>boost/ptr_container</code>: use containers of
+ <a href="http://en.cppreference.com/w/cpp/memory/unique_ptr">
+ <code>std::unique_ptr</code></a> instead.</li>
+</ul>
+</div>
+
+</div>
+
+
+
+<h3 id="std_hash">std::hash</h3>
+
+<div class="summary">
+<p>Do not define specializations of <code>std::hash</code>.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p><code>std::hash<T></code> is the function object that the
+C++11 hash containers use to hash keys of type <code>T</code>,
+unless the user explicitly specifies a different hash function. For
+example, <code>std::unordered_map<int, string></code> is a hash
+map that uses <code>std::hash<int></code> to hash its keys,
+whereas <code>std::unordered_map<int, string, MyIntHash></code>
+uses <code>MyIntHash</code>.</p>
+
+<p><code>std::hash</code> is defined for all integral, floating-point,
+pointer, and <code>enum</code> types, as well as some standard library
+types such as <code>string</code> and <code>unique_ptr</code>. Users
+can enable it to work for their own types by defining specializations
+of it for those types.</p>
+</div>
+
+<div class="pros">
+<p><code>std::hash</code> is easy to use, and simplifies the code
+since you don't have to name it explicitly. Specializing
+<code>std::hash</code> is the standard way of specifying how to
+hash a type, so it's what outside resources will teach, and what
+new engineers will expect.</p>
+</div>
+
+<div class="cons">
+<p><code>std::hash</code> is hard to specialize. It requires a lot
+of boilerplate code, and more importantly, it combines responsibility
+for identifying the hash inputs with responsibility for executing the
+hashing algorithm itself. The type author has to be responsible for
+the former, but the latter requires expertise that a type author
+usually doesn't have, and shouldn't need. The stakes here are high
+because low-quality hash functions can be security vulnerabilities,
+due to the emergence of
+<a href="https://emboss.github.io/blog/2012/12/14/breaking-murmur-hash-flooding-dos-reloaded/">
+hash flooding attacks</a>.</p>
+
+<p>Even for experts, <code>std::hash</code> specializations are
+inordinately difficult to implement correctly for compound types,
+because the implementation cannot recursively call <code>std::hash</code>
+on data members. High-quality hash algorithms maintain large
+amounts of internal state, and reducing that state to the
+<code>size_t</code> bytes that <code>std::hash</code>
+returns is usually the slowest part of the computation, so it
+should not be done more than once.</p>
+
+<p>Due to exactly that issue, <code>std::hash</code> does not work
+with <code>std::pair</code> or <code>std::tuple</code>, and the
+language does not allow us to extend it to support them.</p>
+</div>
+
+<div class="decision">
+<p>You can use <code>std::hash</code> with the types that it supports
+"out of the box", but do not specialize it to support additional types.
+If you need a hash table with a key type that <code>std::hash</code>
+does not support, consider using legacy hash containers (e.g.
+<code>hash_map</code>) for now; they use a different default hasher,
+which is unaffected by this prohibition.</p>
+
+<p>If you want to use the standard hash containers anyway, you will
+need to specify a custom hasher for the key type, e.g.</p>
+<pre>std::unordered_map<MyKeyType, Value, MyKeyTypeHasher> my_map;
+</pre><p>
+Consult with the type's owners to see if there is an existing hasher
+that you can use; otherwise work with them to provide one,
+ or roll your own.</p>
+
+<p>We are planning to provide a hash function that can work with any type,
+using a new customization mechanism that doesn't have the drawbacks of
+<code>std::hash</code>.</p>
+</div>
+
+</div>
+
+<h3 id="C++11">C++11</h3>
+
+<div class="summary">
+<p>Use libraries and language extensions from C++11 when appropriate.
+Consider portability to other environments
+before using C++11 features in your
+project. </p>
+
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p> C++11 contains <a href="https://en.wikipedia.org/wiki/C%2B%2B11">
+significant changes</a> both to the language and
+libraries. </p>
+</div>
+
+<div class="pros">
+<p>C++11 was the official standard until august 2014, and
+is supported by most C++ compilers. It standardizes
+some common C++ extensions that we use already, allows
+shorthands for some operations, and has some performance
+and safety improvements.</p>
+</div>
+
+<div class="cons">
+<p>The C++11 standard is substantially more complex than
+its predecessor (1,300 pages versus 800 pages), and is
+unfamiliar to many developers. The long-term effects of
+some features on code readability and maintenance are
+unknown. We cannot predict when its various features will
+be implemented uniformly by tools that may be of
+interest, particularly in the case of projects that are
+forced to use older versions of tools.</p>
+
+<p>As with <a href="#Boost">Boost</a>, some C++11
+extensions encourage coding practices that hamper
+readability—for example by removing
+checked redundancy (such as type names) that may be
+helpful to readers, or by encouraging template
+metaprogramming. Other extensions duplicate functionality
+available through existing mechanisms, which may lead to confusion
+and conversion costs.</p>
+
+
+</div>
+
+<div class="decision">
+
+<p>C++11 features may be used unless specified otherwise.
+In addition to what's described in the rest of the style
+guide, the following C++11 features may not be used:</p>
+
+<ul>
+
+
+
+
+
+
+
+
+ <li>Compile-time rational numbers
+ (<code><ratio></code>), because of concerns that
+ it's tied to a more template-heavy interface
+ style.</li>
+
+ <li>The <code><cfenv></code> and
+ <code><fenv.h></code> headers, because many
+ compilers do not support those features reliably.</li>
+
+ <li>Ref-qualifiers on member functions, such as <code>void X::Foo()
+ &</code> or <code>void X::Foo() &&</code>, because of concerns
+ that they're an overly obscure feature.</li>
+
+
+
+
+</ul>
+</div>
+
+</div>
+
+<h3 id="Nonstandard_Extensions">Nonstandard Extensions</h3>
+
+<div class="summary">
+<p>Nonstandard extensions to C++ may not be used unless otherwise specified.</p>
+</div>
+<div class="stylebody">
+<div class="definition">
+<p>Compilers support various extensions that are not part of standard C++. Such
+ extensions include GCC's <code>__attribute__</code>, intrinsic functions such
+ as <code>__builtin_prefetch</code>, designated initializers (e.g.
+ <code>Foo f = {.field = 3}</code>), inline assembly, <code>__COUNTER__</code>,
+ <code>__PRETTY_FUNCTION__</code>, compound statement expressions (e.g.
+ <code>foo = ({ int x; Bar(&x); x })</code>, variable-length arrays and
+ <code>alloca()</code>, and the <code>a?:b</code> syntax.</p>
+</div>
+
+<div class="pros">
+ <ul>
+ <li>Nonstandard extensions may provide useful features that do not exist
+ in standard C++. For example, some people think that designated
+ initializers are more readable than standard C++ features like
+ constructors.</li>
+ <li>Important performance guidance to the compiler can only be specified
+ using extensions.</li>
+ </ul>
+</div>
+
+<div class="cons">
+ <ul>
+ <li>Nonstandard extensions do not work in all compilers. Use of nonstandard
+ extensions reduces portability of code.</li>
+ <li>Even if they are supported in all targeted compilers, the extensions
+ are often not well-specified, and there may be subtle behavior differences
+ between compilers.</li>
+ <li>Nonstandard extensions add to the language features that a reader must
+ know to understand the code.</li>
+ </ul>
+</div>
+
+<div class="decision">
+<p>Do not use nonstandard extensions. You may use portability wrappers that
+ are implemented using nonstandard extensions, so long as those wrappers
+
+ are provided by a designated project-wide
+ portability header.</p>
+</div>
+</div>
+
+<h3 id="Aliases">Aliases</h3>
+
+<div class="summary">
+<p>Public aliases are for the benefit of an API's user, and should be clearly documented.</p>
+</div>
+<div class="stylebody">
+<div class="definition">
+<p>There are several ways to create names that are aliases of other entities:</p>
+<pre>typedef Foo Bar;
+using Bar = Foo;
+using other_namespace::Foo;
+</pre>
+
+ <p>Like other declarations, aliases declared in a header file are part of that
+ header's public API unless they're in a function definition, in the private portion of a class,
+ or in an explicitly-marked internal namespace. Aliases in such areas or in .cc files are
+ implementation details (because client code can't refer to them), and are not restricted by this
+ rule.</p>
+</div>
+
+<div class="pros">
+ <ul>
+ <li>Aliases can improve readability by simplifying a long or complicated name.</li>
+ <li>Aliases can reduce duplication by naming in one place a type used repeatedly in an API,
+ which <em>might</em> make it easier to change the type later.
+ </li>
+ </ul>
+</div>
+
+<div class="cons">
+ <ul>
+ <li>When placed in a header where client code can refer to them, aliases increase the
+ number of entities in that header's API, increasing its complexity.</li>
+ <li>Clients can easily rely on unintended details of public aliases, making
+ changes difficult.</li>
+ <li>It can be tempting to create a public alias that is only intended for use
+ in the implementation, without considering its impact on the API, or on maintainability.</li>
+ <li>Aliases can create risk of name collisions</li>
+ <li>Aliases can reduce readability by giving a familiar construct an unfamiliar name</li>
+ <li>Type aliases can create an unclear API contract:
+ it is unclear whether the alias is guaranteed to be identical to the type it aliases,
+ to have the same API, or only to be usable in specified narrow ways</li>
+ </ul>
+</div>
+
+<div class="decision">
+<p>Don't put an alias in your public API just to save typing in the implementation;
+ do so only if you intend it to be used by your clients.</p>
+<p>When defining a public alias, document the intent of
+the new name, including whether it is guaranteed to always be the same as the type
+it's currently aliased to, or whether a more limited compatibility is
+intended. This lets the user know whether they can treat the types as
+substitutable or whether more specific rules must be followed, and can help the
+implementation retain some degree of freedom to change the alias.</p>
+<p>Don't put namespace aliases in your public API. (See also <a href="#Namespaces">Namespaces</a>).
+</p>
+
+<p>For example, these aliases document how they are intended to be used in client code:</p>
+<pre>namespace a {
+// Used to store field measurements. DataPoint may change from Bar* to some internal type.
+// Client code should treat it as an opaque pointer.
+using DataPoint = foo::bar::Bar*;
+
+// A set of measurements. Just an alias for user convenience.
+using TimeSeries = std::unordered_set<DataPoint, std::hash<DataPoint>, DataPointComparator>;
+} // namespace a
+</pre>
+
+<p>These aliases don't document intended use, and half of them aren't meant for client use:</p>
+
+<pre class="badcode">namespace a {
+// Bad: none of these say how they should be used.
+using DataPoint = foo::bar::Bar*;
+using std::unordered_set; // Bad: just for local convenience
+using std::hash; // Bad: just for local convenience
+typedef unordered_set<DataPoint, hash<DataPoint>, DataPointComparator> TimeSeries;
+} // namespace a
+</pre>
+
+<p>However, local convenience aliases are fine in function definitions, private sections of
+ classes, explicitly marked internal namespaces, and in .cc files:</p>
+
+<pre>// In a .cc file
+using std::unordered_set;
+</pre>
+
+</div>
+</div>
+
+<h2 id="Naming">Naming</h2>
+
+<p>The most important consistency rules are those that govern
+naming. The style of a name immediately informs us what sort of
+thing the named entity is: a type, a variable, a function, a
+constant, a macro, etc., without requiring us to search for the
+declaration of that entity. The pattern-matching engine in our
+brains relies a great deal on these naming rules.
+</p>
+
+<p>Naming rules are pretty arbitrary, but
+ we feel that
+consistency is more important than individual preferences in this
+area, so regardless of whether you find them sensible or not,
+the rules are the rules.</p>
+
+<h3 id="General_Naming_Rules">General Naming Rules</h3>
+
+<div class="summary">
+<p>Names should be descriptive; avoid abbreviation.</p>
+</div>
+
+<div class="stylebody">
+<p>Give as descriptive a name as possible, within reason.
+Do not worry about saving horizontal space as it is far
+more important to make your code immediately
+understandable by a new reader. Do not use abbreviations
+that are ambiguous or unfamiliar to readers outside your
+project, and do not abbreviate by deleting letters within
+a word.</p>
+
+<pre>int price_count_reader; // No abbreviation.
+int num_errors; // "num" is a widespread convention.
+int num_dns_connections; // Most people know what "DNS" stands for.
+</pre>
+
+<pre class="badcode">int n; // Meaningless.
+int nerr; // Ambiguous abbreviation.
+int n_comp_conns; // Ambiguous abbreviation.
+int wgc_connections; // Only your group knows what this stands for.
+int pc_reader; // Lots of things can be abbreviated "pc".
+int cstmr_id; // Deletes internal letters.
+</pre>
+
+<p>Note that certain universally-known abbreviations are OK, such as
+<code>i</code> for an iteration variable and <code>T</code> for a
+template parameter.</p>
+
+<p>Template parameters should follow the naming style for their
+category: type template parameters should follow the rules for
+<a href="#Type_Names">type names</a>, and non-type template
+parameters should follow the rules for <a href="#Variable_Names">
+variable names</a>.
+
+</p></div>
+
+<h3 id="File_Names">File Names</h3>
+
+<div class="summary">
+<p>Filenames should be all lowercase and can include
+underscores (<code>_</code>) or dashes (<code>-</code>).
+Follow the convention that your
+
+project uses. If there is no consistent
+local pattern to follow, prefer "_".</p>
+</div>
+
+<div class="stylebody">
+
+<p>Examples of acceptable file names:</p>
+
+<ul>
+ <li><code>my_useful_class.cc</code></li>
+ <li><code>my-useful-class.cc</code></li>
+ <li><code>myusefulclass.cc</code></li>
+ <li><code>myusefulclass_test.cc // _unittest and _regtest are deprecated.</code></li>
+</ul>
+
+<p>C++ files should end in <code>.cc</code> and header files should end in
+<code>.h</code>. Files that rely on being textually included at specific points
+should end in <code>.inc</code> (see also the section on
+<a href="#Self_contained_Headers">self-contained headers</a>).</p>
+
+<p>Do not use filenames that already exist in
+<code>/usr/include</code>, such as <code>db.h</code>.</p>
+
+<p>In general, make your filenames very specific. For
+example, use <code>http_server_logs.h</code> rather than
+<code>logs.h</code>. A very common case is to have a pair
+of files called, e.g., <code>foo_bar.h</code> and
+<code>foo_bar.cc</code>, defining a class called
+<code>FooBar</code>.</p>
+
+<p>Inline functions must be in a <code>.h</code> file. If
+your inline functions are very short, they should go
+directly into your <code>.h</code> file. </p>
+
+</div>
+
+<h3 id="Type_Names">Type Names</h3>
+
+<div class="summary">
+<p>Type names start with a capital letter and have a capital
+letter for each new word, with no underscores:
+<code>MyExcitingClass</code>, <code>MyExcitingEnum</code>.</p>
+</div>
+
+<div class="stylebody">
+
+<p>The names of all types — classes, structs, type aliases,
+enums, and type template parameters — have the same naming convention.
+Type names should start with a capital letter and have a capital letter
+for each new word. No underscores. For example:</p>
+
+<pre>// classes and structs
+class UrlTable { ...
+class UrlTableTester { ...
+struct UrlTableProperties { ...
+
+// typedefs
+typedef hash_map<UrlTableProperties *, string> PropertiesMap;
+
+// using aliases
+using PropertiesMap = hash_map<UrlTableProperties *, string>;
+
+// enums
+enum UrlTableErrors { ...
+</pre>
+
+</div>
+
+<h3 id="Variable_Names">Variable Names</h3>
+
+<div class="summary">
+<p>The names of variables (including function parameters) and data members are
+all lowercase, with underscores between words. Data members of classes (but not
+structs) additionally have trailing underscores. For instance:
+<code>a_local_variable</code>, <code>a_struct_data_member</code>,
+<code>a_class_data_member_</code>.</p>
+</div>
+
+<div class="stylebody">
+
+<h4 class="stylepoint_subsection">Common Variable names</h4>
+
+<p>For example:</p>
+
+<pre>string table_name; // OK - uses underscore.
+string tablename; // OK - all lowercase.
+</pre>
+
+<pre class="badcode">string tableName; // Bad - mixed case.
+</pre>
+
+<h4 class="stylepoint_subsection">Class Data Members</h4>
+
+<p>Data members of classes, both static and non-static, are
+named like ordinary nonmember variables, but with a
+trailing underscore.</p>
+
+<pre>class TableInfo {
+ ...
+ private:
+ string table_name_; // OK - underscore at end.
+ string tablename_; // OK.
+ static Pool<TableInfo>* pool_; // OK.
+};
+</pre>
+
+<h4 class="stylepoint_subsection">Struct Data Members</h4>
+
+<p>Data members of structs, both static and non-static,
+are named like ordinary nonmember variables. They do not have
+the trailing underscores that data members in classes have.</p>
+
+<pre>struct UrlTableProperties {
+ string name;
+ int num_entries;
+ static Pool<UrlTableProperties>* pool;
+};
+</pre>
+
+
+<p>See <a href="#Structs_vs._Classes">Structs vs.
+Classes</a> for a discussion of when to use a struct
+versus a class.</p>
+
+</div>
+
+<h3 id="Constant_Names">Constant Names</h3>
+
+<div class="summary">
+ <p>Variables declared constexpr or const, and whose value is fixed for
+ the duration of the program, are named with a leading "k" followed
+ by mixed case. For example:</p>
+</div>
+
+<pre>const int kDaysInAWeek = 7;
+</pre>
+
+<div class="stylebody">
+
+ <p>All such variables with static storage duration (i.e. statics and globals,
+ see <a href="http://en.cppreference.com/w/cpp/language/storage_duration#Storage_duration">
+ Storage Duration</a> for details) should be named this way. This
+ convention is optional for variables of other storage classes, e.g. automatic
+ variables, otherwise the usual variable naming rules apply.</p><p>
+
+</p></div>
+
+<h3 id="Function_Names">Function Names</h3>
+
+<div class="summary">
+<p>Regular functions have mixed case; accessors and mutators may be named
+like variables.</p>
+</div>
+
+<div class="stylebody">
+
+<p>Ordinarily, functions should start with a capital letter and have a
+capital letter for each new word
+(a.k.a. "<a href="https://en.wikipedia.org/wiki/Camel_case">Camel
+Case</a>" or "Pascal case"). Such names should not have
+underscores. Prefer to capitalize acronyms as single words
+(i.e. <code>StartRpc()</code>, not <code>StartRPC()</code>).</p>
+
+<pre>AddTableEntry()
+DeleteUrl()
+OpenFileOrDie()
+</pre>
+
+<p>(The same naming rule applies to class- and namespace-scope
+constants that are exposed as part of an API and that are intended to look
+like functions, because the fact that they're
+objects rather than functions is an unimportant implementation detail.)</p>
+
+<p>Accessors and mutators (get and set functions) may be named like
+variables. These often correspond to actual member variables, but this is
+not required. For example, <code>int count()</code> and <code>void
+set_count(int count)</code>.</p>
+
+</div>
+
+<h3 id="Namespace_Names">Namespace Names</h3>
+
+<div class="summary">
+Namespace names are all lower-case. Top-level namespace names are
+based on the project name
+. Avoid collisions
+between nested namespaces and well-known top-level namespaces.
+</div>
+
+<div class="stylebody">
+<p>The name of a top-level namespace should usually be the
+name of the project or team whose code is contained in that
+namespace. The code in that namespace should usually be in
+a directory whose basename matches the namespace name (or
+subdirectories thereof).</p>
+
+
+
+
+
+<p>Keep in mind that the <a href="#General_Naming_Rules">rule
+against abbreviated names</a> applies to namespaces just as much
+as variable names. Code inside the namespace seldom needs to
+mention the namespace name, so there's usually no particular need
+for abbreviation anyway.</p>
+
+<p>Avoid nested namespaces that match well-known top-level
+namespaces. Collisions between namespace names can lead to surprising
+build breaks because of name lookup rules. In particular, do not
+create any nested <code>std</code> namespaces. Prefer unique project
+identifiers
+(<code>websearch::index</code>, <code>websearch::index_util</code>)
+over collision-prone names like <code>websearch::util</code>.</p>
+
+<p>For <code>internal</code> namespaces, be wary of other code being
+added to the same <code>internal</code> namespace causing a collision
+(internal helpers within a team tend to be related and may lead to
+collisions). In such a situation, using the filename to make a unique
+internal name is helpful
+(<code>websearch::index::frobber_internal</code> for use
+in <code>frobber.h</code>)</p>
+
+</div>
+
+<h3 id="Enumerator_Names">Enumerator Names</h3>
+
+<div class="summary">
+<p>Enumerators (for both scoped and unscoped enums) should be named <i>either</i> like
+<a href="#Constant_Names">constants</a> or like
+<a href="#Macro_Names">macros</a>: either <code>kEnumName</code> or
+<code>ENUM_NAME</code>.</p>
+</div>
+
+<div class="stylebody">
+
+<p>Preferably, the individual enumerators should be named
+like <a href="#Constant_Names">constants</a>. However, it
+is also acceptable to name them like
+<a href="#Macro_Names">macros</a>. The enumeration name,
+<code>UrlTableErrors</code> (and
+<code>AlternateUrlTableErrors</code>), is a type, and
+therefore mixed case.</p>
+
+<pre>enum UrlTableErrors {
+ kOK = 0,
+ kErrorOutOfMemory,
+ kErrorMalformedInput,
+};
+enum AlternateUrlTableErrors {
+ OK = 0,
+ OUT_OF_MEMORY = 1,
+ MALFORMED_INPUT = 2,
+};
+</pre>
+
+<p>Until January 2009, the style was to name enum values
+like <a href="#Macro_Names">macros</a>. This caused
+problems with name collisions between enum values and
+macros. Hence, the change to prefer constant-style naming
+was put in place. New code should prefer constant-style
+naming if possible. However, there is no reason to change
+old code to use constant-style names, unless the old
+names are actually causing a compile-time problem.</p>
+
+
+
+</div>
+
+<h3 id="Macro_Names">Macro Names</h3>
+
+<div class="summary">
+<p>You're not really going to <a href="#Preprocessor_Macros">
+define a macro</a>, are you? If you do, they're like this:
+<code>MY_MACRO_THAT_SCARES_SMALL_CHILDREN</code>.</p>
+</div>
+
+<div class="stylebody">
+
+<p>Please see the <a href="#Preprocessor_Macros">description
+of macros</a>; in general macros should <em>not</em> be used.
+However, if they are absolutely needed, then they should be
+named with all capitals and underscores.</p>
+
+<pre>#define ROUND(x) ...
+#define PI_ROUNDED 3.0
+</pre>
+
+</div>
+
+<h3 id="Exceptions_to_Naming_Rules">Exceptions to Naming Rules</h3>
+
+<div class="summary">
+<p>If you are naming something that is analogous to an
+existing C or C++ entity then you can follow the existing
+naming convention scheme.</p>
+</div>
+
+<div class="stylebody">
+
+<dl>
+ <dt><code>bigopen()</code></dt>
+ <dd>function name, follows form of <code>open()</code></dd>
+
+ <dt><code>uint</code></dt>
+ <dd><code>typedef</code></dd>
+
+ <dt><code>bigpos</code></dt>
+ <dd><code>struct</code> or <code>class</code>, follows
+ form of <code>pos</code></dd>
+
+ <dt><code>sparse_hash_map</code></dt>
+ <dd>STL-like entity; follows STL naming conventions</dd>
+
+ <dt><code>LONGLONG_MAX</code></dt>
+ <dd>a constant, as in <code>INT_MAX</code></dd>
+</dl>
+
+</div>
+
+<h2 id="Comments">Comments</h2>
+
+<p>Though a pain to write, comments are absolutely vital to
+keeping our code readable. The following rules describe what
+you should comment and where. But remember: while comments are
+very important, the best code is self-documenting. Giving
+sensible names to types and variables is much better than using
+obscure names that you must then explain through comments.</p>
+
+<p>When writing your comments, write for your audience: the
+next
+contributor who will need to
+understand your code. Be generous — the next
+one may be you!</p>
+
+<h3 id="Comment_Style">Comment Style</h3>
+
+<div class="summary">
+<p>Use either the <code>//</code> or <code>/* */</code>
+syntax, as long as you are consistent.</p>
+</div>
+
+<div class="stylebody">
+
+<p>You can use either the <code>//</code> or the <code>/*
+*/</code> syntax; however, <code>//</code> is
+<em>much</em> more common. Be consistent with how you
+comment and what style you use where.</p>
+
+</div>
+
+<h3 id="File_Comments">File Comments</h3>
+
+<div class="summary">
+<p>Start each file with license boilerplate.</p>
+
+<p>File comments describe the contents of a file. If a file declares,
+implements, or tests exactly one abstraction that is documented by a comment
+at the point of declaration, file comments are not required. All other files
+must have file comments.</p>
+
+</div>
+
+<div class="stylebody">
+
+<h4 class="stylepoint_subsection">Legal Notice and Author
+Line</h4>
+
+
+
+<p>Every file should contain license
+boilerplate. Choose the appropriate boilerplate for the
+license used by the project (for example, Apache 2.0,
+BSD, LGPL, GPL).</p>
+
+<p>If you make significant changes to a file with an
+author line, consider deleting the author line.</p>
+
+<h4 class="stylepoint_subsection">File Contents</h4>
+
+<p>If a <code>.h</code> declares multiple abstractions, the file-level comment
+should broadly describe the contents of the file, and how the abstractions are
+related. A 1 or 2 sentence file-level comment may be sufficient. The detailed
+documentation about individual abstractions belongs with those abstractions,
+not at the file level.</p>
+
+<p>Do not duplicate comments in both the <code>.h</code> and the
+<code>.cc</code>. Duplicated comments diverge.</p>
+
+</div>
+
+<h3 id="Class_Comments">Class Comments</h3>
+
+<div class="summary">
+<p>Every non-obvious class declaration should have an accompanying
+comment that describes what it is for and how it should be used.</p>
+</div>
+
+<div class="stylebody">
+
+<pre>// Iterates over the contents of a GargantuanTable.
+// Example:
+// GargantuanTableIterator* iter = table->NewIterator();
+// for (iter->Seek("foo"); !iter->done(); iter->Next()) {
+// process(iter->key(), iter->value());
+// }
+// delete iter;
+class GargantuanTableIterator {
+ ...
+};
+</pre>
+
+<p>The class comment should provide the reader with enough information to know
+how and when to use the class, as well as any additional considerations
+necessary to correctly use the class. Document the synchronization assumptions
+the class makes, if any. If an instance of the class can be accessed by
+multiple threads, take extra care to document the rules and invariants
+surrounding multithreaded use.</p>
+
+<p>The class comment is often a good place for a small example code snippet
+demonstrating a simple and focused usage of the class.</p>
+
+<p>When sufficiently separated (e.g. <code>.h</code> and <code>.cc</code>
+files), comments describing the use of the class should go together with its
+interface definition; comments about the class operation and implementation
+should accompany the implementation of the class's methods.</p>
+
+</div>
+
+<h3 id="Function_Comments">Function Comments</h3>
+
+<div class="summary">
+<p>Declaration comments describe use of the function (when it is
+non-obvious); comments at the definition of a function describe
+operation.</p>
+</div>
+
+<div class="stylebody">
+
+<h4 class="stylepoint_subsection">Function Declarations</h4>
+
+<p>Almost every function declaration should have comments immediately
+preceding it that describe what the function does and how to use
+it. These comments may be omitted only if the function is simple and
+obvious (e.g. simple accessors for obvious properties of the
+class). These comments should be descriptive ("Opens the file")
+rather than imperative ("Open the file"); the comment describes the
+function, it does not tell the function what to do. In general, these
+comments do not describe how the function performs its task. Instead,
+that should be left to comments in the function definition.</p>
+
+<p>Types of things to mention in comments at the function
+declaration:</p>
+
+<ul>
+ <li>What the inputs and outputs are.</li>
+
+ <li>For class member functions: whether the object
+ remembers reference arguments beyond the duration of
+ the method call, and whether it will free them or
+ not.</li>
+
+ <li>If the function allocates memory that the caller
+ must free.</li>
+
+ <li>Whether any of the arguments can be a null
+ pointer.</li>
+
+ <li>If there are any performance implications of how a
+ function is used.</li>
+
+ <li>If the function is re-entrant. What are its
+ synchronization assumptions?</li>
+ </ul>
+
+<p>Here is an example:</p>
+
+<pre>// Returns an iterator for this table. It is the client's
+// responsibility to delete the iterator when it is done with it,
+// and it must not use the iterator once the GargantuanTable object
+// on which the iterator was created has been deleted.
+//
+// The iterator is initially positioned at the beginning of the table.
+//
+// This method is equivalent to:
+// Iterator* iter = table->NewIterator();
+// iter->Seek("");
+// return iter;
+// If you are going to immediately seek to another place in the
+// returned iterator, it will be faster to use NewIterator()
+// and avoid the extra seek.
+Iterator* GetIterator() const;
+</pre>
+
+<p>However, do not be unnecessarily verbose or state the
+completely obvious. Notice below that it is not necessary
+ to say "returns false otherwise" because this is
+implied.</p>
+
+<pre>// Returns true if the table cannot hold any more entries.
+bool IsTableFull();
+</pre>
+
+<p>When documenting function overrides, focus on the
+specifics of the override itself, rather than repeating
+the comment from the overridden function. In many of these
+cases, the override needs no additional documentation and
+thus no comment is required.</p>
+
+<p>When commenting constructors and destructors, remember
+that the person reading your code knows what constructors
+and destructors are for, so comments that just say
+something like "destroys this object" are not useful.
+Document what constructors do with their arguments (for
+example, if they take ownership of pointers), and what
+cleanup the destructor does. If this is trivial, just
+skip the comment. It is quite common for destructors not
+to have a header comment.</p>
+
+<h4 class="stylepoint_subsection">Function Definitions</h4>
+
+<p>If there is anything tricky about how a function does
+its job, the function definition should have an
+explanatory comment. For example, in the definition
+comment you might describe any coding tricks you use,
+give an overview of the steps you go through, or explain
+why you chose to implement the function in the way you
+did rather than using a viable alternative. For instance,
+you might mention why it must acquire a lock for the
+first half of the function but why it is not needed for
+the second half.</p>
+
+<p>Note you should <em>not</em> just repeat the comments
+given with the function declaration, in the
+<code>.h</code> file or wherever. It's okay to
+recapitulate briefly what the function does, but the
+focus of the comments should be on how it does it.</p>
+
+</div>
+
+<h3 id="Variable_Comments">Variable Comments</h3>
+
+<div class="summary">
+<p>In general the actual name of the variable should be
+descriptive enough to give a good idea of what the variable
+is used for. In certain cases, more comments are required.</p>
+</div>
+
+<div class="stylebody">
+
+<h4 class="stylepoint_subsection">Class Data Members</h4>
+
+<p>The purpose of each class data member (also called an instance
+variable or member variable) must be clear. If there are any
+invariants (special values, relationships between members, lifetime
+requirements) not clearly expressed by the type and name, they must be
+commented. However, if the type and name suffice (<code>int
+num_events_;</code>), no comment is needed.</p>
+
+<p>In particular, add comments to describe the existence and meaning
+of sentinel values, such as nullptr or -1, when they are not
+obvious. For example:</p>
+
+<pre>private:
+ // Used to bounds-check table accesses. -1 means
+ // that we don't yet know how many entries the table has.
+ int num_total_entries_;
+</pre>
+
+<h4 class="stylepoint_subsection">Global Variables</h4>
+
+<p>All global variables should have a comment describing what they
+are, what they are used for, and (if unclear) why it needs to be
+global. For example:</p>
+
+<pre>// The total number of tests cases that we run through in this regression test.
+const int kNumTestCases = 6;
+</pre>
+
+</div>
+
+<h3 id="Implementation_Comments">Implementation Comments</h3>
+
+<div class="summary">
+<p>In your implementation you should have comments in tricky,
+non-obvious, interesting, or important parts of your code.</p>
+</div>
+
+<div class="stylebody">
+
+<h4 class="stylepoint_subsection">Explanatory Comments</h4>
+
+<p>Tricky or complicated code blocks should have comments
+before them. Example:</p>
+
+<pre>// Divide result by two, taking into account that x
+// contains the carry from the add.
+for (int i = 0; i < result->size(); i++) {
+ x = (x << 8) + (*result)[i];
+ (*result)[i] = x >> 1;
+ x &= 1;
+}
+</pre>
+
+<h4 class="stylepoint_subsection">Line Comments</h4>
+
+<p>Also, lines that are non-obvious should get a comment
+at the end of the line. These end-of-line comments should
+be separated from the code by 2 spaces. Example:</p>
+
+<pre>// If we have enough memory, mmap the data portion too.
+mmap_budget = max<int64>(0, mmap_budget - index_->length());
+if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock))
+ return; // Error already logged.
+</pre>
+
+<p>Note that there are both comments that describe what
+the code is doing, and comments that mention that an
+error has already been logged when the function
+returns.</p>
+
+<p>If you have several comments on subsequent lines, it
+can often be more readable to line them up:</p>
+
+<pre>DoSomething(); // Comment here so the comments line up.
+DoSomethingElseThatIsLonger(); // Two spaces between the code and the comment.
+{ // One space before comment when opening a new scope is allowed,
+ // thus the comment lines up with the following comments and code.
+ DoSomethingElse(); // Two spaces before line comments normally.
+}
+std::vector<string> list{
+ // Comments in braced lists describe the next element...
+ "First item",
+ // .. and should be aligned appropriately.
+ "Second item"};
+DoSomething(); /* For trailing block comments, one space is fine. */
+</pre>
+
+<h4 class="stylepoint_subsection">Function Argument Comments</h4>
+
+<p>When the meaning of a function argument is nonobvious, consider
+one of the following remedies:</p>
+
+<ul>
+ <li>If the argument is a literal constant, and the same constant is
+ used in multiple function calls in a way that tacitly assumes they're
+ the same, you should use a named constant to make that constraint
+ explicit, and to guarantee that it holds.</li>
+
+ <li>Consider changing the function signature to replace a <code>bool</code>
+ argument with an <code>enum</code> argument. This will make the argument
+ values self-describing.</li>
+
+ <li>For functions that have several configuration options, consider
+ defining a single class or struct to hold all the options
+ ,
+ and pass an instance of that.
+ This approach has several advantages. Options are referenced by name
+ at the call site, which clarifies their meaning. It also reduces
+ function argument count, which makes function calls easier to read and
+ write. As an added benefit, you don't have to change call sites when
+ you add another option.
+ </li>
+
+ <li>Replace large or complex nested expressions with named variables.</li>
+
+ <li>As a last resort, use comments to clarify argument meanings at the
+ call site.</li>
+</ul>
+
+Consider the following example:
+
+<pre class="badcode">// What are these arguments?
+const DecimalNumber product = CalculateProduct(values, 7, false, nullptr);
+</pre>
+
+<p>versus:</p>
+
+<pre>ProductOptions options;
+options.set_precision_decimals(7);
+options.set_use_cache(ProductOptions::kDontUseCache);
+const DecimalNumber product =
+ CalculateProduct(values, options, /*completion_callback=*/nullptr);
+</pre>
+
+<h4 class="stylepoint_subsection">Don'ts</h4>
+
+<p>Do not state the obvious. In particular, don't literally describe what
+code does, unless the behavior is nonobvious to a reader who understands
+C++ well. Instead, provide higher level comments that describe <i>why</i>
+the code does what it does, or make the code self describing.</p>
+
+Compare this:
+
+<pre class="badcode">// Find the element in the vector. <-- Bad: obvious!
+auto iter = std::find(v.begin(), v.end(), element);
+if (iter != v.end()) {
+ Process(element);
+}
+</pre>
+
+To this:
+
+<pre>// Process "element" unless it was already processed.
+auto iter = std::find(v.begin(), v.end(), element);
+if (iter != v.end()) {
+ Process(element);
+}
+</pre>
+
+Self-describing code doesn't need a comment. The comment from
+the example above would be obvious:
+
+<pre>if (!IsAlreadyProcessed(element)) {
+ Process(element);
+}
+</pre>
+
+</div>
+
+<h3 id="Punctuation,_Spelling_and_Grammar">Punctuation, Spelling and Grammar</h3>
+
+<div class="summary">
+<p>Pay attention to punctuation, spelling, and grammar; it is
+easier to read well-written comments than badly written
+ones.</p>
+</div>
+
+<div class="stylebody">
+
+<p>Comments should be as readable as narrative text, with
+proper capitalization and punctuation. In many cases,
+complete sentences are more readable than sentence
+fragments. Shorter comments, such as comments at the end
+of a line of code, can sometimes be less formal, but you
+should be consistent with your style.</p>
+
+<p>Although it can be frustrating to have a code reviewer
+point out that you are using a comma when you should be
+using a semicolon, it is very important that source code
+maintain a high level of clarity and readability. Proper
+punctuation, spelling, and grammar help with that
+goal.</p>
+
+</div>
+
+<h3 id="TODO_Comments">TODO Comments</h3>
+
+<div class="summary">
+<p>Use <code>TODO</code> comments for code that is temporary,
+a short-term solution, or good-enough but not perfect.</p>
+</div>
+
+<div class="stylebody">
+
+<p><code>TODO</code>s should include the string
+<code>TODO</code> in all caps, followed by the
+
+name, e-mail address, bug ID, or other
+identifier
+of the person or issue with the best context
+about the problem referenced by the <code>TODO</code>. The
+main purpose is to have a consistent <code>TODO</code> that
+can be searched to find out how to get more details upon
+request. A <code>TODO</code> is not a commitment that the
+person referenced will fix the problem. Thus when you create
+a <code>TODO</code> with a name, it is almost always your
+name that is given.</p>
+
+
+
+<div>
+<pre>// TODO(kl@gmail.com): Use a "*" here for concatenation operator.
+// TODO(Zeke) change this to use relations.
+// TODO(bug 12345): remove the "Last visitors" feature
+</pre>
+</div>
+
+<p>If your <code>TODO</code> is of the form "At a future
+date do something" make sure that you either include a
+very specific date ("Fix by November 2005") or a very
+specific event ("Remove this code when all clients can
+handle XML responses.").</p>
+
+</div>
+
+<h3 id="Deprecation_Comments">Deprecation Comments</h3>
+
+<div class="summary">
+<p>Mark deprecated interface points with <code>DEPRECATED</code>
+comments.</p>
+</div>
+
+<div class="stylebody">
+
+<p>You can mark an interface as deprecated by writing a
+comment containing the word <code>DEPRECATED</code> in
+all caps. The comment goes either before the declaration
+of the interface or on the same line as the
+declaration.</p>
+
+
+
+<p>After the word
+<code>DEPRECATED</code>, write your name, e-mail address,
+or other identifier in parentheses.</p>
+
+<p>A deprecation comment must include simple, clear
+directions for people to fix their callsites. In C++, you
+can implement a deprecated function as an inline function
+that calls the new interface point.</p>
+
+<p>Marking an interface point <code>DEPRECATED</code>
+will not magically cause any callsites to change. If you
+want people to actually stop using the deprecated
+facility, you will have to fix the callsites yourself or
+recruit a crew to help you.</p>
+
+<p>New code should not contain calls to deprecated
+interface points. Use the new interface point instead. If
+you cannot understand the directions, find the person who
+created the deprecation and ask them for help using the
+new interface point.</p>
+
+
+
+</div>
+
+<h2 id="Formatting">Formatting</h2>
+
+<p>Coding style and formatting are pretty arbitrary, but a
+
+project is much easier to follow
+if everyone uses the same style. Individuals may not agree with every
+aspect of the formatting rules, and some of the rules may take
+some getting used to, but it is important that all
+
+project contributors follow the
+style rules so that
+they can all read and understand
+everyone's code easily.</p>
+
+
+
+<p>To help you format code correctly, we've
+created a
+<a href="https://raw.githubusercontent.com/google/styleguide/gh-pages/google-c-style.el">
+settings file for emacs</a>.</p>
+
+<h3 id="Line_Length">Line Length</h3>
+
+<div class="summary">
+<p>Each line of text in your code should be at most 80
+characters long.</p>
+</div>
+
+<div class="stylebody">
+
+
+
+ <p>We recognize that this rule is
+controversial, but so much existing code already adheres
+to it, and we feel that consistency is important.</p>
+
+<div class="pros">
+<p>Those who favor this rule
+argue that it is rude to force them to resize
+their windows and there is no need for anything longer.
+Some folks are used to having several code windows
+side-by-side, and thus don't have room to widen their
+windows in any case. People set up their work environment
+assuming a particular maximum window width, and 80
+columns has been the traditional standard. Why change
+it?</p>
+</div>
+
+<div class="cons">
+<p>Proponents of change argue that a wider line can make
+code more readable. The 80-column limit is an hidebound
+throwback to 1960s mainframes; modern equipment has wide screens that
+can easily show longer lines.</p>
+</div>
+
+<div class="decision">
+<p> 80 characters is the maximum.</p>
+
+<p class="exception">Comment lines can be longer than 80
+characters if it is not feasible to split them without
+harming readability, ease of cut and paste or auto-linking
+-- e.g. if a line contains an example command or a literal
+URL longer than 80 characters.</p>
+
+<p class="exception">A raw-string literal may have content
+that exceeds 80 characters. Except for test code, such literals
+should appear near the top of a file.</p>
+
+<p class="exception">An <code>#include</code> statement with a
+long path may exceed 80 columns.</p>
+
+<p class="exception">You needn't be concerned about
+<a href="#The__define_Guard">header guards</a> that exceed
+the maximum length. </p>
+</div>
+
+</div>
+
+<h3 id="Non-ASCII_Characters">Non-ASCII Characters</h3>
+
+<div class="summary">
+<p>Non-ASCII characters should be rare, and must use UTF-8
+formatting.</p>
+</div>
+
+<div class="stylebody">
+
+<p>You shouldn't hard-code user-facing text in source,
+even English, so use of non-ASCII characters should be
+rare. However, in certain cases it is appropriate to
+include such words in your code. For example, if your
+code parses data files from foreign sources, it may be
+appropriate to hard-code the non-ASCII string(s) used in
+those data files as delimiters. More commonly, unittest
+code (which does not need to be localized) might
+contain non-ASCII strings. In such cases, you should use
+UTF-8, since that is an encoding
+understood by most tools able to handle more than just
+ASCII.</p>
+
+<p>Hex encoding is also OK, and encouraged where it
+enhances readability — for example,
+<code>"\xEF\xBB\xBF"</code>, or, even more simply,
+<code>u8"\uFEFF"</code>, is the Unicode zero-width
+no-break space character, which would be invisible if
+included in the source as straight UTF-8.</p>
+
+<p>Use the <code>u8</code> prefix
+to guarantee that a string literal containing
+<code>\uXXXX</code> escape sequences is encoded as UTF-8.
+Do not use it for strings containing non-ASCII characters
+encoded as UTF-8, because that will produce incorrect
+output if the compiler does not interpret the source file
+as UTF-8. </p>
+
+<p>You shouldn't use the C++11 <code>char16_t</code> and
+<code>char32_t</code> character types, since they're for
+non-UTF-8 text. For similar reasons you also shouldn't
+use <code>wchar_t</code> (unless you're writing code that
+interacts with the Windows API, which uses
+<code>wchar_t</code> extensively).</p>
+
+</div>
+
+<h3 id="Spaces_vs._Tabs">Spaces vs. Tabs</h3>
+
+<div class="summary">
+<p>Use only spaces, and indent 2 spaces at a time.</p>
+</div>
+
+<div class="stylebody">
+
+<p>We use spaces for indentation. Do not use tabs in your
+code. You should set your editor to emit spaces when you
+hit the tab key.</p>
+
+</div>
+
+<h3 id="Function_Declarations_and_Definitions">Function Declarations and Definitions</h3>
+
+<div class="summary">
+<p>Return type on the same line as function name, parameters
+on the same line if they fit. Wrap parameter lists which do
+not fit on a single line as you would wrap arguments in a
+<a href="#Function_Calls">function call</a>.</p>
+</div>
+
+<div class="stylebody">
+
+<p>Functions look like this:</p>
+
+
+<pre>ReturnType ClassName::FunctionName(Type par_name1, Type par_name2) {
+ DoSomething();
+ ...
+}
+</pre>
+
+<p>If you have too much text to fit on one line:</p>
+
+<pre>ReturnType ClassName::ReallyLongFunctionName(Type par_name1, Type par_name2,
+ Type par_name3) {
+ DoSomething();
+ ...
+}
+</pre>
+
+<p>or if you cannot fit even the first parameter:</p>
+
+<pre>ReturnType LongClassName::ReallyReallyReallyLongFunctionName(
+ Type par_name1, // 4 space indent
+ Type par_name2,
+ Type par_name3) {
+ DoSomething(); // 2 space indent
+ ...
+}
+</pre>
+
+<p>Some points to note:</p>
+
+<ul>
+ <li>Choose good parameter names.</li>
+
+ <li>Parameter names may be omitted only if the parameter is unused and its
+ purpose is obvious.</li>
+
+ <li>If you cannot fit the return type and the function
+ name on a single line, break between them.</li>
+
+ <li>If you break after the return type of a function
+ declaration or definition, do not indent.</li>
+
+ <li>The open parenthesis is always on the same line as
+ the function name.</li>
+
+ <li>There is never a space between the function name
+ and the open parenthesis.</li>
+
+ <li>There is never a space between the parentheses and
+ the parameters.</li>
+
+ <li>The open curly brace is always on the end of the last line of the function
+ declaration, not the start of the next line.</li>
+
+ <li>The close curly brace is either on the last line by
+ itself or on the same line as the open curly brace.</li>
+
+ <li>There should be a space between the close
+ parenthesis and the open curly brace.</li>
+
+ <li>All parameters should be aligned if possible.</li>
+
+ <li>Default indentation is 2 spaces.</li>
+
+ <li>Wrapped parameters have a 4 space indent.</li>
+</ul>
+
+<p>Unused parameters that are obvious from context may be omitted:</p>
+
+<pre>class Foo {
+ public:
+ Foo(Foo&&);
+ Foo(const Foo&);
+ Foo& operator=(Foo&&);
+ Foo& operator=(const Foo&);
+};
+</pre>
+
+<p>Unused parameters that might not be obvious should comment out the variable
+name in the function definition:</p>
+
+<pre>class Shape {
+ public:
+ virtual void Rotate(double radians) = 0;
+};
+
+class Circle : public Shape {
+ public:
+ void Rotate(double radians) override;
+};
+
+void Circle::Rotate(double /*radians*/) {}
+</pre>
+
+<pre class="badcode">// Bad - if someone wants to implement later, it's not clear what the
+// variable means.
+void Circle::Rotate(double) {}
+</pre>
+
+<p>Attributes, and macros that expand to attributes, appear at the very
+beginning of the function declaration or definition, before the
+return type:</p>
+<pre>MUST_USE_RESULT bool IsOK();
+</pre>
+
+</div>
+
+<h3 id="Formatting_Lambda_Expressions">Lambda Expressions</h3>
+
+<div class="summary">
+<p>Format parameters and bodies as for any other function, and capture
+lists like other comma-separated lists.</p>
+</div>
+
+<div class="stylebody">
+<p>For by-reference captures, do not leave a space between the
+ampersand (&) and the variable name.</p>
+<pre>int x = 0;
+auto x_plus_n = [&x](int n) -> int { return x + n; }
+</pre>
+<p>Short lambdas may be written inline as function arguments.</p>
+<pre>std::set<int> blacklist = {7, 8, 9};
+std::vector<int> digits = {3, 9, 1, 8, 4, 7, 1};
+digits.erase(std::remove_if(digits.begin(), digits.end(), [&blacklist](int i) {
+ return blacklist.find(i) != blacklist.end();
+ }),
+ digits.end());
+</pre>
+
+</div>
+
+<h3 id="Function_Calls">Function Calls</h3>
+
+<div class="summary">
+<p>Either write the call all on a single line, wrap the
+arguments at the parenthesis, or start the arguments on a new
+line indented by four spaces and continue at that 4 space
+indent. In the absence of other considerations, use the
+minimum number of lines, including placing multiple arguments
+on each line where appropriate.</p>
+</div>
+
+<div class="stylebody">
+
+<p>Function calls have the following format:</p>
+<pre>bool result = DoSomething(argument1, argument2, argument3);
+</pre>
+
+<p>If the arguments do not all fit on one line, they
+should be broken up onto multiple lines, with each
+subsequent line aligned with the first argument. Do not
+add spaces after the open paren or before the close
+paren:</p>
+<pre>bool result = DoSomething(averyveryveryverylongargument1,
+ argument2, argument3);
+</pre>
+
+<p>Arguments may optionally all be placed on subsequent
+lines with a four space indent:</p>
+<pre>if (...) {
+ ...
+ ...
+ if (...) {
+ bool result = DoSomething(
+ argument1, argument2, // 4 space indent
+ argument3, argument4);
+ ...
+ }
+</pre>
+
+<p>Put multiple arguments on a single line to reduce the
+number of lines necessary for calling a function unless
+there is a specific readability problem. Some find that
+formatting with strictly one argument on each line is
+more readable and simplifies editing of the arguments.
+However, we prioritize for the reader over the ease of
+editing arguments, and most readability problems are
+better addressed with the following techniques.</p>
+
+<p>If having multiple arguments in a single line decreases
+readability due to the complexity or confusing nature of the
+expressions that make up some arguments, try creating
+variables that capture those arguments in a descriptive name:</p>
+<pre>int my_heuristic = scores[x] * y + bases[x];
+bool result = DoSomething(my_heuristic, x, y, z);
+</pre>
+
+<p>Or put the confusing argument on its own line with
+an explanatory comment:</p>
+<pre>bool result = DoSomething(scores[x] * y + bases[x], // Score heuristic.
+ x, y, z);
+</pre>
+
+<p>If there is still a case where one argument is
+significantly more readable on its own line, then put it on
+its own line. The decision should be specific to the argument
+which is made more readable rather than a general policy.</p>
+
+<p>Sometimes arguments form a structure that is important
+for readability. In those cases, feel free to format the
+arguments according to that structure:</p>
+<pre>// Transform the widget by a 3x3 matrix.
+my_widget.Transform(x1, x2, x3,
+ y1, y2, y3,
+ z1, z2, z3);
+</pre>
+
+</div>
+
+<h3 id="Braced_Initializer_List_Format">Braced Initializer List Format</h3>
+
+<div class="summary">
+<p>Format a <a href="#Braced_Initializer_List">braced initializer list</a>
+exactly like you would format a function call in its place.</p>
+</div>
+
+<div class="stylebody">
+
+<p>If the braced list follows a name (e.g. a type or
+variable name), format as if the <code>{}</code> were the
+parentheses of a function call with that name. If there
+is no name, assume a zero-length name.</p>
+
+<pre>// Examples of braced init list on a single line.
+return {foo, bar};
+functioncall({foo, bar});
+std::pair<int, int> p{foo, bar};
+
+// When you have to wrap.
+SomeFunction(
+ {"assume a zero-length name before {"},
+ some_other_function_parameter);
+SomeType variable{
+ some, other, values,
+ {"assume a zero-length name before {"},
+ SomeOtherType{
+ "Very long string requiring the surrounding breaks.",
+ some, other values},
+ SomeOtherType{"Slightly shorter string",
+ some, other, values}};
+SomeType variable{
+ "This is too long to fit all in one line"};
+MyType m = { // Here, you could also break before {.
+ superlongvariablename1,
+ superlongvariablename2,
+ {short, interior, list},
+ {interiorwrappinglist,
+ interiorwrappinglist2}};
+</pre>
+
+</div>
+
+<h3 id="Conditionals">Conditionals</h3>
+
+<div class="summary">
+<p>Prefer no spaces inside parentheses. The <code>if</code>
+and <code>else</code> keywords belong on separate lines.</p>
+</div>
+
+<div class="stylebody">
+
+<p>There are two acceptable formats for a basic
+conditional statement. One includes spaces between the
+parentheses and the condition, and one does not.</p>
+
+<p>The most common form is without spaces. Either is
+fine, but <em>be consistent</em>. If you are modifying a
+file, use the format that is already present. If you are
+writing new code, use the format that the other files in
+that directory or project use. If in doubt and you have
+no personal preference, do not add the spaces.</p>
+
+<pre>if (condition) { // no spaces inside parentheses
+ ... // 2 space indent.
+} else if (...) { // The else goes on the same line as the closing brace.
+ ...
+} else {
+ ...
+}
+</pre>
+
+<p>If you prefer you may add spaces inside the
+parentheses:</p>
+
+<pre>if ( condition ) { // spaces inside parentheses - rare
+ ... // 2 space indent.
+} else { // The else goes on the same line as the closing brace.
+ ...
+}
+</pre>
+
+<p>Note that in all cases you must have a space between
+the <code>if</code> and the open parenthesis. You must
+also have a space between the close parenthesis and the
+curly brace, if you're using one.</p>
+
+<pre class="badcode">if(condition) { // Bad - space missing after IF.
+if (condition){ // Bad - space missing before {.
+if(condition){ // Doubly bad.
+</pre>
+
+<pre>if (condition) { // Good - proper space after IF and before {.
+</pre>
+
+<p>Short conditional statements may be written on one
+line if this enhances readability. You may use this only
+when the line is brief and the statement does not use the
+<code>else</code> clause.</p>
+
+<pre>if (x == kFoo) return new Foo();
+if (x == kBar) return new Bar();
+</pre>
+
+<p>This is not allowed when the if statement has an
+<code>else</code>:</p>
+
+<pre class="badcode">// Not allowed - IF statement on one line when there is an ELSE clause
+if (x) DoThis();
+else DoThat();
+</pre>
+
+<p>In general, curly braces are not required for
+single-line statements, but they are allowed if you like
+them; conditional or loop statements with complex
+conditions or statements may be more readable with curly
+braces. Some
+projects require that an
+<code>if</code> must always always have an accompanying
+brace.</p>
+
+<pre>if (condition)
+ DoSomething(); // 2 space indent.
+
+if (condition) {
+ DoSomething(); // 2 space indent.
+}
+</pre>
+
+<p>However, if one part of an
+<code>if</code>-<code>else</code> statement uses curly
+braces, the other part must too:</p>
+
+<pre class="badcode">// Not allowed - curly on IF but not ELSE
+if (condition) {
+ foo;
+} else
+ bar;
+
+// Not allowed - curly on ELSE but not IF
+if (condition)
+ foo;
+else {
+ bar;
+}
+</pre>
+
+<pre>// Curly braces around both IF and ELSE required because
+// one of the clauses used braces.
+if (condition) {
+ foo;
+} else {
+ bar;
+}
+</pre>
+
+</div>
+
+<h3 id="Loops_and_Switch_Statements">Loops and Switch Statements</h3>
+
+<div class="summary">
+<p>Switch statements may use braces for blocks. Annotate
+non-trivial fall-through between cases.
+Braces are optional for single-statement loops.
+Empty loop bodies should use empty braces or <code>continue</code>.</p>
+</div>
+
+<div class="stylebody">
+
+<p><code>case</code> blocks in <code>switch</code>
+statements can have curly braces or not, depending on
+your preference. If you do include curly braces they
+should be placed as shown below.</p>
+
+<p>If not conditional on an enumerated value, switch
+statements should always have a <code>default</code> case
+(in the case of an enumerated value, the compiler will
+warn you if any values are not handled). If the default
+case should never execute, simply
+<code>assert</code>:</p>
+
+
+
+<div>
+<pre>switch (var) {
+ case 0: { // 2 space indent
+ ... // 4 space indent
+ break;
+ }
+ case 1: {
+ ...
+ break;
+ }
+ default: {
+ assert(false);
+ }
+}
+</pre>
+</div>
+
+
+
+
+
+<p> Braces are optional for single-statement loops.</p>
+
+<pre>for (int i = 0; i < kSomeNumber; ++i)
+ printf("I love you\n");
+
+for (int i = 0; i < kSomeNumber; ++i) {
+ printf("I take it back\n");
+}
+</pre>
+
+
+<p>Empty loop bodies should use an empty pair of braces or <code>continue</code>,
+but not a single semicolon.</p>
+
+<pre>while (condition) {
+ // Repeat test until it returns false.
+}
+for (int i = 0; i < kSomeNumber; ++i) {} // Good - one newline is also OK.
+while (condition) continue; // Good - continue indicates no logic.
+</pre>
+
+<pre class="badcode">while (condition); // Bad - looks like part of do/while loop.
+</pre>
+
+</div>
+
+<h3 id="Pointer_and_Reference_Expressions">Pointer and Reference Expressions</h3>
+
+<div class="summary">
+<p>No spaces around period or arrow. Pointer operators do not
+have trailing spaces.</p>
+</div>
+
+<div class="stylebody">
+
+<p>The following are examples of correctly-formatted
+pointer and reference expressions:</p>
+
+<pre>x = *p;
+p = &x;
+x = r.y;
+x = r->y;
+</pre>
+
+<p>Note that:</p>
+
+<ul>
+ <li>There are no spaces around the period or arrow when
+ accessing a member.</li>
+
+ <li>Pointer operators have no space after the
+ <code>*</code> or <code>&</code>.</li>
+</ul>
+
+<p>When declaring a pointer variable or argument, you may
+place the asterisk adjacent to either the type or to the
+variable name:</p>
+
+<pre>// These are fine, space preceding.
+char *c;
+const string &str;
+
+// These are fine, space following.
+char* c;
+const string& str;
+</pre>
+
+It is allowed (if unusual) to declare multiple variables in the same
+declaration, but it is disallowed if any of those have pointer or
+reference decorations. Such declarations are easily misread.
+<pre>// Fine if helpful for readability.
+int x, y;
+</pre>
+<pre class="badcode">int x, *y; // Disallowed - no & or * in multiple declaration
+char * c; // Bad - spaces on both sides of *
+const string & str; // Bad - spaces on both sides of &
+</pre>
+
+<p>You should do this consistently within a single
+file,
+so, when modifying an existing file, use the style in
+that file.</p>
+
+</div>
+
+<h3 id="Boolean_Expressions">Boolean Expressions</h3>
+
+<div class="summary">
+<p>When you have a boolean expression that is longer than the
+<a href="#Line_Length">standard line length</a>, be
+consistent in how you break up the lines.</p>
+</div>
+
+<div class="stylebody">
+
+<p>In this example, the logical AND operator is always at
+the end of the lines:</p>
+
+<pre>if (this_one_thing > this_other_thing &&
+ a_third_thing == a_fourth_thing &&
+ yet_another && last_one) {
+ ...
+}
+</pre>
+
+<p>Note that when the code wraps in this example, both of
+the <code>&&</code> logical AND operators are at
+the end of the line. This is more common in Google code,
+though wrapping all operators at the beginning of the
+line is also allowed. Feel free to insert extra
+parentheses judiciously because they can be very helpful
+in increasing readability when used
+appropriately. Also note that you should always use
+the punctuation operators, such as
+<code>&&</code> and <code>~</code>, rather than
+the word operators, such as <code>and</code> and
+<code>compl</code>.</p>
+
+</div>
+
+<h3 id="Return_Values">Return Values</h3>
+
+<div class="summary">
+<p>Do not needlessly surround the <code>return</code>
+expression with parentheses.</p>
+</div>
+
+<div class="stylebody">
+
+<p>Use parentheses in <code>return expr;</code> only
+where you would use them in <code>x = expr;</code>.</p>
+
+<pre>return result; // No parentheses in the simple case.
+// Parentheses OK to make a complex expression more readable.
+return (some_long_condition &&
+ another_condition);
+</pre>
+
+<pre class="badcode">return (value); // You wouldn't write var = (value);
+return(result); // return is not a function!
+</pre>
+
+</div>
+
+
+
+<h3 id="Variable_and_Array_Initialization">Variable and Array Initialization</h3>
+
+<div class="summary">
+<p>Your choice of <code>=</code>, <code>()</code>, or
+<code>{}</code>.</p>
+</div>
+
+<div class="stylebody">
+
+<p>You may choose between <code>=</code>,
+<code>()</code>, and <code>{}</code>; the following are
+all correct:</p>
+
+<pre>int x = 3;
+int x(3);
+int x{3};
+string name = "Some Name";
+string name("Some Name");
+string name{"Some Name"};
+</pre>
+
+<p>Be careful when using a braced initialization list <code>{...}</code>
+on a type with an <code>std::initializer_list</code> constructor.
+A nonempty <i>braced-init-list</i> prefers the
+<code>std::initializer_list</code> constructor whenever
+possible. Note that empty braces <code>{}</code> are special, and
+will call a default constructor if available. To force the
+non-<code>std::initializer_list</code> constructor, use parentheses
+instead of braces.</p>
+
+<pre>std::vector<int> v(100, 1); // A vector of 100 1s.
+std::vector<int> v{100, 1}; // A vector of 100, 1.
+</pre>
+
+<p>Also, the brace form prevents narrowing of integral
+types. This can prevent some types of programming
+errors.</p>
+
+<pre>int pi(3.14); // OK -- pi == 3.
+int pi{3.14}; // Compile error: narrowing conversion.
+</pre>
+
+</div>
+
+<h3 id="Preprocessor_Directives">Preprocessor Directives</h3>
+
+<div class="summary">
+<p>The hash mark that starts a preprocessor directive should
+always be at the beginning of the line.</p>
+</div>
+
+<div class="stylebody">
+
+<p>Even when preprocessor directives are within the body
+of indented code, the directives should start at the
+beginning of the line.</p>
+
+<pre>// Good - directives at beginning of line
+ if (lopsided_score) {
+#if DISASTER_PENDING // Correct -- Starts at beginning of line
+ DropEverything();
+# if NOTIFY // OK but not required -- Spaces after #
+ NotifyClient();
+# endif
+#endif
+ BackToNormal();
+ }
+</pre>
+
+<pre class="badcode">// Bad - indented directives
+ if (lopsided_score) {
+ #if DISASTER_PENDING // Wrong! The "#if" should be at beginning of line
+ DropEverything();
+ #endif // Wrong! Do not indent "#endif"
+ BackToNormal();
+ }
+</pre>
+
+</div>
+
+<h3 id="Class_Format">Class Format</h3>
+
+<div class="summary">
+<p>Sections in <code>public</code>, <code>protected</code> and
+<code>private</code> order, each indented one space.</p>
+</div>
+
+<div class="stylebody">
+
+<p>The basic format for a class definition (lacking the
+comments, see <a href="#Class_Comments">Class
+Comments</a> for a discussion of what comments are
+needed) is:</p>
+
+<pre>class MyClass : public OtherClass {
+ public: // Note the 1 space indent!
+ MyClass(); // Regular 2 space indent.
+ explicit MyClass(int var);
+ ~MyClass() {}
+
+ void SomeFunction();
+ void SomeFunctionThatDoesNothing() {
+ }
+
+ void set_some_var(int var) { some_var_ = var; }
+ int some_var() const { return some_var_; }
+
+ private:
+ bool SomeInternalFunction();
+
+ int some_var_;
+ int some_other_var_;
+};
+</pre>
+
+<p>Things to note:</p>
+
+<ul>
+ <li>Any base class name should be on the same line as
+ the subclass name, subject to the 80-column limit.</li>
+
+ <li>The <code>public:</code>, <code>protected:</code>,
+ and <code>private:</code> keywords should be indented
+ one space.</li>
+
+ <li>Except for the first instance, these keywords
+ should be preceded by a blank line. This rule is
+ optional in small classes.</li>
+
+ <li>Do not leave a blank line after these
+ keywords.</li>
+
+ <li>The <code>public</code> section should be first,
+ followed by the <code>protected</code> and finally the
+ <code>private</code> section.</li>
+
+ <li>See <a href="#Declaration_Order">Declaration
+ Order</a> for rules on ordering declarations within
+ each of these sections.</li>
+</ul>
+
+</div>
+
+<h3 id="Constructor_Initializer_Lists">Constructor Initializer Lists</h3>
+
+<div class="summary">
+<p>Constructor initializer lists can be all on one line or
+with subsequent lines indented four spaces.</p>
+</div>
+
+<div class="stylebody">
+
+<p>The acceptable formats for initializer lists are:</p>
+
+<pre>// When everything fits on one line:
+MyClass::MyClass(int var) : some_var_(var) {
+ DoSomething();
+}
+
+// If the signature and initializer list are not all on one line,
+// you must wrap before the colon and indent 4 spaces:
+MyClass::MyClass(int var)
+ : some_var_(var), some_other_var_(var + 1) {
+ DoSomething();
+}
+
+// When the list spans multiple lines, put each member on its own line
+// and align them:
+MyClass::MyClass(int var)
+ : some_var_(var), // 4 space indent
+ some_other_var_(var + 1) { // lined up
+ DoSomething();
+}
+
+// As with any other code block, the close curly can be on the same
+// line as the open curly, if it fits.
+MyClass::MyClass(int var)
+ : some_var_(var) {}
+</pre>
+
+</div>
+
+<h3 id="Namespace_Formatting">Namespace Formatting</h3>
+
+<div class="summary">
+<p>The contents of namespaces are not indented.</p>
+</div>
+
+<div class="stylebody">
+
+<p><a href="#Namespaces">Namespaces</a> do not add an
+extra level of indentation. For example, use:</p>
+
+<pre>namespace {
+
+void foo() { // Correct. No extra indentation within namespace.
+ ...
+}
+
+} // namespace
+</pre>
+
+<p>Do not indent within a namespace:</p>
+
+<pre class="badcode">namespace {
+
+ // Wrong. Indented when it should not be.
+ void foo() {
+ ...
+ }
+
+} // namespace
+</pre>
+
+<p>When declaring nested namespaces, put each namespace
+on its own line.</p>
+
+<pre>namespace foo {
+namespace bar {
+</pre>
+
+</div>
+
+<h3 id="Horizontal_Whitespace">Horizontal Whitespace</h3>
+
+<div class="summary">
+<p>Use of horizontal whitespace depends on location. Never put
+trailing whitespace at the end of a line.</p>
+</div>
+
+<div class="stylebody">
+
+<h4 class="stylepoint_subsection">General</h4>
+
+<pre>void f(bool b) { // Open braces should always have a space before them.
+ ...
+int i = 0; // Semicolons usually have no space before them.
+// Spaces inside braces for braced-init-list are optional. If you use them,
+// put them on both sides!
+int x[] = { 0 };
+int x[] = {0};
+
+// Spaces around the colon in inheritance and initializer lists.
+class Foo : public Bar {
+ public:
+ // For inline function implementations, put spaces between the braces
+ // and the implementation itself.
+ Foo(int b) : Bar(), baz_(b) {} // No spaces inside empty braces.
+ void Reset() { baz_ = 0; } // Spaces separating braces from implementation.
+ ...
+</pre>
+
+<p>Adding trailing whitespace can cause extra work for
+others editing the same file, when they merge, as can
+removing existing trailing whitespace. So: Don't
+introduce trailing whitespace. Remove it if you're
+already changing that line, or do it in a separate
+clean-up
+operation (preferably when no-one
+else is working on the file).</p>
+
+<h4 class="stylepoint_subsection">Loops and Conditionals</h4>
+
+<pre>if (b) { // Space after the keyword in conditions and loops.
+} else { // Spaces around else.
+}
+while (test) {} // There is usually no space inside parentheses.
+switch (i) {
+for (int i = 0; i < 5; ++i) {
+// Loops and conditions may have spaces inside parentheses, but this
+// is rare. Be consistent.
+switch ( i ) {
+if ( test ) {
+for ( int i = 0; i < 5; ++i ) {
+// For loops always have a space after the semicolon. They may have a space
+// before the semicolon, but this is rare.
+for ( ; i < 5 ; ++i) {
+ ...
+
+// Range-based for loops always have a space before and after the colon.
+for (auto x : counts) {
+ ...
+}
+switch (i) {
+ case 1: // No space before colon in a switch case.
+ ...
+ case 2: break; // Use a space after a colon if there's code after it.
+</pre>
+
+<h4 class="stylepoint_subsection">Operators</h4>
+
+<pre>// Assignment operators always have spaces around them.
+x = 0;
+
+// Other binary operators usually have spaces around them, but it's
+// OK to remove spaces around factors. Parentheses should have no
+// internal padding.
+v = w * x + y / z;
+v = w*x + y/z;
+v = w * (x + z);
+
+// No spaces separating unary operators and their arguments.
+x = -5;
+++x;
+if (x && !y)
+ ...
+</pre>
+
+<h4 class="stylepoint_subsection">Templates and Casts</h4>
+
+<pre>// No spaces inside the angle brackets (< and >), before
+// <, or between >( in a cast
+std::vector<string> x;
+y = static_cast<char*>(x);
+
+// Spaces between type and pointer are OK, but be consistent.
+std::vector<char *> x;
+</pre>
+
+</div>
+
+<h3 id="Vertical_Whitespace">Vertical Whitespace</h3>
+
+<div class="summary">
+<p>Minimize use of vertical whitespace.</p>
+</div>
+
+<div class="stylebody">
+
+<p>This is more a principle than a rule: don't use blank
+lines when you don't have to. In particular, don't put
+more than one or two blank lines between functions,
+resist starting functions with a blank line, don't end
+functions with a blank line, and be discriminating with
+your use of blank lines inside functions.</p>
+
+<p>The basic principle is: The more code that fits on one
+screen, the easier it is to follow and understand the
+control flow of the program. Of course, readability can
+suffer from code being too dense as well as too spread
+out, so use your judgement. But in general, minimize use
+of vertical whitespace.</p>
+
+<p>Some rules of thumb to help when blank lines may be
+useful:</p>
+
+<ul>
+ <li>Blank lines at the beginning or end of a function
+ very rarely help readability.</li>
+
+ <li>Blank lines inside a chain of if-else blocks may
+ well help readability.</li>
+</ul>
+
+</div>
+
+<h2 id="Exceptions_to_the_Rules">Exceptions to the Rules</h2>
+
+<p>The coding conventions described above are mandatory.
+However, like all good rules, these sometimes have exceptions,
+which we discuss here.</p>
+
+
+
+<div>
+<h3 id="Existing_Non-conformant_Code">Existing Non-conformant Code</h3>
+
+<div class="summary">
+<p>You may diverge from the rules when dealing with code that
+does not conform to this style guide.</p>
+</div>
+
+<div class="stylebody">
+
+<p>If you find yourself modifying code that was written
+to specifications other than those presented by this
+guide, you may have to diverge from these rules in order
+to stay consistent with the local conventions in that
+code. If you are in doubt about how to do this, ask the
+original author or the person currently responsible for
+the code. Remember that <em>consistency</em> includes
+local consistency, too.</p>
+
+</div>
+</div>
+
+
+
+<h3 id="Windows_Code">Windows Code</h3>
+
+<div class="summary">
+<p> Windows
+programmers have developed their own set of coding
+conventions, mainly derived from the conventions in Windows
+headers and other Microsoft code. We want to make it easy
+for anyone to understand your code, so we have a single set
+of guidelines for everyone writing C++ on any platform.</p>
+</div>
+
+<div class="stylebody">
+<p>It is worth reiterating a few of the guidelines that
+you might forget if you are used to the prevalent Windows
+style:</p>
+
+<ul>
+ <li>Do not use Hungarian notation (for example, naming
+ an integer <code>iNum</code>). Use the Google naming
+ conventions, including the <code>.cc</code> extension
+ for source files.</li>
+
+ <li>Windows defines many of its own synonyms for
+ primitive types, such as <code>DWORD</code>,
+ <code>HANDLE</code>, etc. It is perfectly acceptable,
+ and encouraged, that you use these types when calling
+ Windows API functions. Even so, keep as close as you
+ can to the underlying C++ types. For example, use
+ <code>const TCHAR *</code> instead of
+ <code>LPCTSTR</code>.</li>
+
+ <li>When compiling with Microsoft Visual C++, set the
+ compiler to warning level 3 or higher, and treat all
+ warnings as errors.</li>
+
+ <li>Do not use <code>#pragma once</code>; instead use
+ the standard Google include guards. The path in the
+ include guards should be relative to the top of your
+ project tree.</li>
+
+ <li>In fact, do not use any nonstandard extensions,
+ like <code>#pragma</code> and <code>__declspec</code>,
+ unless you absolutely must. Using
+ <code>__declspec(dllimport)</code> and
+ <code>__declspec(dllexport)</code> is allowed; however,
+ you must use them through macros such as
+ <code>DLLIMPORT</code> and <code>DLLEXPORT</code>, so
+ that someone can easily disable the extensions if they
+ share the code.</li>
+</ul>
+
+<p>However, there are just a few rules that we
+occasionally need to break on Windows:</p>
+
+<ul>
+ <li>Normally we <a href="#Multiple_Inheritance">forbid
+ the use of multiple implementation inheritance</a>;
+ however, it is required when using COM and some ATL/WTL
+ classes. You may use multiple implementation
+ inheritance to implement COM or ATL/WTL classes and
+ interfaces.</li>
+
+ <li>Although you should not use exceptions in your own
+ code, they are used extensively in the ATL and some
+ STLs, including the one that comes with Visual C++.
+ When using the ATL, you should define
+ <code>_ATL_NO_EXCEPTIONS</code> to disable exceptions.
+ You should investigate whether you can also disable
+ exceptions in your STL, but if not, it is OK to turn on
+ exceptions in the compiler. (Note that this is only to
+ get the STL to compile. You should still not write
+ exception handling code yourself.)</li>
+
+ <li>The usual way of working with precompiled headers
+ is to include a header file at the top of each source
+ file, typically with a name like <code>StdAfx.h</code>
+ or <code>precompile.h</code>. To make your code easier
+ to share with other projects, avoid including this file
+ explicitly (except in <code>precompile.cc</code>), and
+ use the <code>/FI</code> compiler option to include the
+ file automatically.</li>
+
+ <li>Resource headers, which are usually named
+ <code>resource.h</code> and contain only macros, do not
+ need to conform to these style guidelines.</li>
+</ul>
+
+</div>
+
+<h2 class="ignoreLink">Parting Words</h2>
+
+<p>Use common sense and <em>BE CONSISTENT</em>.</p>
+
+<p>If you are editing code, take a few minutes to look at the
+code around you and determine its style. If they use spaces
+around their <code>if</code> clauses, you should, too. If their
+comments have little boxes of stars around them, make your
+comments have little boxes of stars around them too.</p>
+
+<p>The point of having style guidelines is to have a common
+vocabulary of coding so people can concentrate on what you are
+saying, rather than on how you are saying it. We present global
+style rules here so people know the vocabulary. But local style
+is also important. If code you add to a file looks drastically
+different from the existing code around it, the discontinuity
+throws readers out of their rhythm when they go to read it. Try
+to avoid this.</p>
+
+
+
+<p>OK, enough writing about writing code; the code itself is much
+more interesting. Have fun!</p>
+
+<hr>
+
+</div>
+</div>
+</body>
+</html>
diff --git a/cppguide.xml b/cppguide.xml
new file mode 100644
index 0000000..8efc102
--- /dev/null
+++ b/cppguide.xml
@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html>
+<head>
+ <meta charset="utf8">
+ <meta http-equiv="content-type" content="text/html;charset=utf-8">
+ <meta http-equiv="refresh" content="1; url=cppguide.html">
+ <title>Redirecting</title>
+</head>
+<!-- The BODY onLoad redirect is the best: it preserves #fragments and
+ ?queries. But it requires javascript. If that fails, the
+ meta-refresh kicks in; it works more generally, but loses fragments
+ and queries, takes a second, and pollutes the browser history.
+ If they both fail, we let the user manually click on the new link.
+-->
+ <body onload="location.replace(location.href.replace('.xml', '.html'))">
+ Redirecting you to <a href="cppguide.html">cppguide.html</a>.
+</body>
+</html>
diff --git a/cpplint/README b/cpplint/README
new file mode 100644
index 0000000..ee6b9de
--- /dev/null
+++ b/cpplint/README
@@ -0,0 +1,45 @@
+This is automated checker to make sure a C++ file follows Google's C++ style
+guide (https://google.github.io/styleguide/cppguide.html). As it
+heavily relies on regular expressions, cpplint.py won't catch all violations of
+the style guide and will very occasionally report a false positive. There is a
+list of things we currently don't handle very well at the top of cpplint.py,
+and we welcome patches to improve it.
+
+The linting tool takes a list of files as input. For full usage instructions,
+please see the output of:
+
+ ./cpplint.py --help
+
+Unit tests are provided in cpplint_unittest.py. This file can safely be ignored
+by end users who have downloaded this package and only want to run the lint
+tool.
+
+---
+
+cpplint.py and its corresponding unit tests are Copyright (C) 2009 Google Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+ * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+ * Neither the name of Google Inc. nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/cpplint/cpplint.py b/cpplint/cpplint.py
new file mode 100755
index 0000000..53dbe81
--- /dev/null
+++ b/cpplint/cpplint.py
@@ -0,0 +1,6228 @@
+#!/usr/bin/env python
+#
+# Copyright (c) 2009 Google Inc. All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+# * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+"""Does google-lint on c++ files.
+
+The goal of this script is to identify places in the code that *may*
+be in non-compliance with google style. It does not attempt to fix
+up these problems -- the point is to educate. It does also not
+attempt to find all problems, or to ensure that everything it does
+find is legitimately a problem.
+
+In particular, we can get very confused by /* and // inside strings!
+We do a small hack, which is to ignore //'s with "'s after them on the
+same line, but it is far from perfect (in either direction).
+"""
+
+import codecs
+import copy
+import getopt
+import math # for log
+import os
+import re
+import sre_compile
+import string
+import sys
+import unicodedata
+
+
+_USAGE = """
+Syntax: cpplint.py [--verbose=#] [--output=vs7] [--filter=-x,+y,...]
+ [--counting=total|toplevel|detailed] [--root=subdir]
+ [--linelength=digits] [--headers=x,y,...]
+ [--quiet]
+ <file> [file] ...
+
+ The style guidelines this tries to follow are those in
+ https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
+
+ Every problem is given a confidence score from 1-5, with 5 meaning we are
+ certain of the problem, and 1 meaning it could be a legitimate construct.
+ This will miss some errors, and is not a substitute for a code review.
+
+ To suppress false-positive errors of a certain category, add a
+ 'NOLINT(category)' comment to the line. NOLINT or NOLINT(*)
+ suppresses errors of all categories on that line.
+
+ The files passed in will be linted; at least one file must be provided.
+ Default linted extensions are .cc, .cpp, .cu, .cuh and .h. Change the
+ extensions with the --extensions flag.
+
+ Flags:
+
+ output=vs7
+ By default, the output is formatted to ease emacs parsing. Visual Studio
+ compatible output (vs7) may also be used. Other formats are unsupported.
+
+ verbose=#
+ Specify a number 0-5 to restrict errors to certain verbosity levels.
+
+ quiet
+ Don't print anything if no errors are found.
+
+ filter=-x,+y,...
+ Specify a comma-separated list of category-filters to apply: only
+ error messages whose category names pass the filters will be printed.
+ (Category names are printed with the message and look like
+ "[whitespace/indent]".) Filters are evaluated left to right.
+ "-FOO" and "FOO" means "do not print categories that start with FOO".
+ "+FOO" means "do print categories that start with FOO".
+
+ Examples: --filter=-whitespace,+whitespace/braces
+ --filter=whitespace,runtime/printf,+runtime/printf_format
+ --filter=-,+build/include_what_you_use
+
+ To see a list of all the categories used in cpplint, pass no arg:
+ --filter=
+
+ counting=total|toplevel|detailed
+ The total number of errors found is always printed. If
+ 'toplevel' is provided, then the count of errors in each of
+ the top-level categories like 'build' and 'whitespace' will
+ also be printed. If 'detailed' is provided, then a count
+ is provided for each category like 'build/class'.
+
+ root=subdir
+ The root directory used for deriving header guard CPP variable.
+ By default, the header guard CPP variable is calculated as the relative
+ path to the directory that contains .git, .hg, or .svn. When this flag
+ is specified, the relative path is calculated from the specified
+ directory. If the specified directory does not exist, this flag is
+ ignored.
+
+ Examples:
+ Assuming that top/src/.git exists (and cwd=top/src), the header guard
+ CPP variables for top/src/chrome/browser/ui/browser.h are:
+
+ No flag => CHROME_BROWSER_UI_BROWSER_H_
+ --root=chrome => BROWSER_UI_BROWSER_H_
+ --root=chrome/browser => UI_BROWSER_H_
+ --root=.. => SRC_CHROME_BROWSER_UI_BROWSER_H_
+
+ linelength=digits
+ This is the allowed line length for the project. The default value is
+ 80 characters.
+
+ Examples:
+ --linelength=120
+
+ extensions=extension,extension,...
+ The allowed file extensions that cpplint will check
+
+ Examples:
+ --extensions=hpp,cpp
+
+ headers=x,y,...
+ The header extensions that cpplint will treat as .h in checks. Values are
+ automatically added to --extensions list.
+
+ Examples:
+ --headers=hpp,hxx
+ --headers=hpp
+
+ cpplint.py supports per-directory configurations specified in CPPLINT.cfg
+ files. CPPLINT.cfg file can contain a number of key=value pairs.
+ Currently the following options are supported:
+
+ set noparent
+ filter=+filter1,-filter2,...
+ exclude_files=regex
+ linelength=80
+ root=subdir
+ headers=x,y,...
+
+ "set noparent" option prevents cpplint from traversing directory tree
+ upwards looking for more .cfg files in parent directories. This option
+ is usually placed in the top-level project directory.
+
+ The "filter" option is similar in function to --filter flag. It specifies
+ message filters in addition to the |_DEFAULT_FILTERS| and those specified
+ through --filter command-line flag.
+
+ "exclude_files" allows to specify a regular expression to be matched against
+ a file name. If the expression matches, the file is skipped and not run
+ through liner.
+
+ "linelength" allows to specify the allowed line length for the project.
+
+ The "root" option is similar in function to the --root flag (see example
+ above). Paths are relative to the directory of the CPPLINT.cfg.
+
+ The "headers" option is similar in function to the --headers flag
+ (see example above).
+
+ CPPLINT.cfg has an effect on files in the same directory and all
+ sub-directories, unless overridden by a nested configuration file.
+
+ Example file:
+ filter=-build/include_order,+build/include_alpha
+ exclude_files=.*\.cc
+
+ The above example disables build/include_order warning and enables
+ build/include_alpha as well as excludes all .cc from being
+ processed by linter, in the current directory (where the .cfg
+ file is located) and all sub-directories.
+"""
+
+# We categorize each error message we print. Here are the categories.
+# We want an explicit list so we can list them all in cpplint --filter=.
+# If you add a new error message with a new category, add it to the list
+# here! cpplint_unittest.py should tell you if you forget to do this.
+_ERROR_CATEGORIES = [
+ 'build/class',
+ 'build/c++11',
+ 'build/c++14',
+ 'build/c++tr1',
+ 'build/deprecated',
+ 'build/endif_comment',
+ 'build/explicit_make_pair',
+ 'build/forward_decl',
+ 'build/header_guard',
+ 'build/include',
+ 'build/include_alpha',
+ 'build/include_order',
+ 'build/include_what_you_use',
+ 'build/namespaces',
+ 'build/printf_format',
+ 'build/storage_class',
+ 'legal/copyright',
+ 'readability/alt_tokens',
+ 'readability/braces',
+ 'readability/casting',
+ 'readability/check',
+ 'readability/constructors',
+ 'readability/fn_size',
+ 'readability/inheritance',
+ 'readability/multiline_comment',
+ 'readability/multiline_string',
+ 'readability/namespace',
+ 'readability/nolint',
+ 'readability/nul',
+ 'readability/strings',
+ 'readability/todo',
+ 'readability/utf8',
+ 'runtime/arrays',
+ 'runtime/casting',
+ 'runtime/explicit',
+ 'runtime/int',
+ 'runtime/init',
+ 'runtime/invalid_increment',
+ 'runtime/member_string_references',
+ 'runtime/memset',
+ 'runtime/indentation_namespace',
+ 'runtime/operator',
+ 'runtime/printf',
+ 'runtime/printf_format',
+ 'runtime/references',
+ 'runtime/string',
+ 'runtime/threadsafe_fn',
+ 'runtime/vlog',
+ 'whitespace/blank_line',
+ 'whitespace/braces',
+ 'whitespace/comma',
+ 'whitespace/comments',
+ 'whitespace/empty_conditional_body',
+ 'whitespace/empty_if_body',
+ 'whitespace/empty_loop_body',
+ 'whitespace/end_of_line',
+ 'whitespace/ending_newline',
+ 'whitespace/forcolon',
+ 'whitespace/indent',
+ 'whitespace/line_length',
+ 'whitespace/newline',
+ 'whitespace/operators',
+ 'whitespace/parens',
+ 'whitespace/semicolon',
+ 'whitespace/tab',
+ 'whitespace/todo',
+ ]
+
+# These error categories are no longer enforced by cpplint, but for backwards-
+# compatibility they may still appear in NOLINT comments.
+_LEGACY_ERROR_CATEGORIES = [
+ 'readability/streams',
+ 'readability/function',
+ ]
+
+# The default state of the category filter. This is overridden by the --filter=
+# flag. By default all errors are on, so only add here categories that should be
+# off by default (i.e., categories that must be enabled by the --filter= flags).
+# All entries here should start with a '-' or '+', as in the --filter= flag.
+_DEFAULT_FILTERS = ['-build/include_alpha']
+
+# The default list of categories suppressed for C (not C++) files.
+_DEFAULT_C_SUPPRESSED_CATEGORIES = [
+ 'readability/casting',
+ ]
+
+# The default list of categories suppressed for Linux Kernel files.
+_DEFAULT_KERNEL_SUPPRESSED_CATEGORIES = [
+ 'whitespace/tab',
+ ]
+
+# We used to check for high-bit characters, but after much discussion we
+# decided those were OK, as long as they were in UTF-8 and didn't represent
+# hard-coded international strings, which belong in a separate i18n file.
+
+# C++ headers
+_CPP_HEADERS = frozenset([
+ # Legacy
+ 'algobase.h',
+ 'algo.h',
+ 'alloc.h',
+ 'builtinbuf.h',
+ 'bvector.h',
+ 'complex.h',
+ 'defalloc.h',
+ 'deque.h',
+ 'editbuf.h',
+ 'fstream.h',
+ 'function.h',
+ 'hash_map',
+ 'hash_map.h',
+ 'hash_set',
+ 'hash_set.h',
+ 'hashtable.h',
+ 'heap.h',
+ 'indstream.h',
+ 'iomanip.h',
+ 'iostream.h',
+ 'istream.h',
+ 'iterator.h',
+ 'list.h',
+ 'map.h',
+ 'multimap.h',
+ 'multiset.h',
+ 'ostream.h',
+ 'pair.h',
+ 'parsestream.h',
+ 'pfstream.h',
+ 'procbuf.h',
+ 'pthread_alloc',
+ 'pthread_alloc.h',
+ 'rope',
+ 'rope.h',
+ 'ropeimpl.h',
+ 'set.h',
+ 'slist',
+ 'slist.h',
+ 'stack.h',
+ 'stdiostream.h',
+ 'stl_alloc.h',
+ 'stl_relops.h',
+ 'streambuf.h',
+ 'stream.h',
+ 'strfile.h',
+ 'strstream.h',
+ 'tempbuf.h',
+ 'tree.h',
+ 'type_traits.h',
+ 'vector.h',
+ # 17.6.1.2 C++ library headers
+ 'algorithm',
+ 'array',
+ 'atomic',
+ 'bitset',
+ 'chrono',
+ 'codecvt',
+ 'complex',
+ 'condition_variable',
+ 'deque',
+ 'exception',
+ 'forward_list',
+ 'fstream',
+ 'functional',
+ 'future',
+ 'initializer_list',
+ 'iomanip',
+ 'ios',
+ 'iosfwd',
+ 'iostream',
+ 'istream',
+ 'iterator',
+ 'limits',
+ 'list',
+ 'locale',
+ 'map',
+ 'memory',
+ 'mutex',
+ 'new',
+ 'numeric',
+ 'ostream',
+ 'queue',
+ 'random',
+ 'ratio',
+ 'regex',
+ 'scoped_allocator',
+ 'set',
+ 'sstream',
+ 'stack',
+ 'stdexcept',
+ 'streambuf',
+ 'string',
+ 'strstream',
+ 'system_error',
+ 'thread',
+ 'tuple',
+ 'typeindex',
+ 'typeinfo',
+ 'type_traits',
+ 'unordered_map',
+ 'unordered_set',
+ 'utility',
+ 'valarray',
+ 'vector',
+ # 17.6.1.2 C++ headers for C library facilities
+ 'cassert',
+ 'ccomplex',
+ 'cctype',
+ 'cerrno',
+ 'cfenv',
+ 'cfloat',
+ 'cinttypes',
+ 'ciso646',
+ 'climits',
+ 'clocale',
+ 'cmath',
+ 'csetjmp',
+ 'csignal',
+ 'cstdalign',
+ 'cstdarg',
+ 'cstdbool',
+ 'cstddef',
+ 'cstdint',
+ 'cstdio',
+ 'cstdlib',
+ 'cstring',
+ 'ctgmath',
+ 'ctime',
+ 'cuchar',
+ 'cwchar',
+ 'cwctype',
+ ])
+
+# Type names
+_TYPES = re.compile(
+ r'^(?:'
+ # [dcl.type.simple]
+ r'(char(16_t|32_t)?)|wchar_t|'
+ r'bool|short|int|long|signed|unsigned|float|double|'
+ # [support.types]
+ r'(ptrdiff_t|size_t|max_align_t|nullptr_t)|'
+ # [cstdint.syn]
+ r'(u?int(_fast|_least)?(8|16|32|64)_t)|'
+ r'(u?int(max|ptr)_t)|'
+ r')$')
+
+
+# These headers are excluded from [build/include] and [build/include_order]
+# checks:
+# - Anything not following google file name conventions (containing an
+# uppercase character, such as Python.h or nsStringAPI.h, for example).
+# - Lua headers.
+_THIRD_PARTY_HEADERS_PATTERN = re.compile(
+ r'^(?:[^/]*[A-Z][^/]*\.h|lua\.h|lauxlib\.h|lualib\.h)$')
+
+# Pattern for matching FileInfo.BaseName() against test file name
+_TEST_FILE_SUFFIX = r'(_test|_unittest|_regtest)$'
+
+# Pattern that matches only complete whitespace, possibly across multiple lines.
+_EMPTY_CONDITIONAL_BODY_PATTERN = re.compile(r'^\s*$', re.DOTALL)
+
+# Assertion macros. These are defined in base/logging.h and
+# testing/base/public/gunit.h.
+_CHECK_MACROS = [
+ 'DCHECK', 'CHECK',
+ 'EXPECT_TRUE', 'ASSERT_TRUE',
+ 'EXPECT_FALSE', 'ASSERT_FALSE',
+ ]
+
+# Replacement macros for CHECK/DCHECK/EXPECT_TRUE/EXPECT_FALSE
+_CHECK_REPLACEMENT = dict([(m, {}) for m in _CHECK_MACROS])
+
+for op, replacement in [('==', 'EQ'), ('!=', 'NE'),
+ ('>=', 'GE'), ('>', 'GT'),
+ ('<=', 'LE'), ('<', 'LT')]:
+ _CHECK_REPLACEMENT['DCHECK'][op] = 'DCHECK_%s' % replacement
+ _CHECK_REPLACEMENT['CHECK'][op] = 'CHECK_%s' % replacement
+ _CHECK_REPLACEMENT['EXPECT_TRUE'][op] = 'EXPECT_%s' % replacement
+ _CHECK_REPLACEMENT['ASSERT_TRUE'][op] = 'ASSERT_%s' % replacement
+
+for op, inv_replacement in [('==', 'NE'), ('!=', 'EQ'),
+ ('>=', 'LT'), ('>', 'LE'),
+ ('<=', 'GT'), ('<', 'GE')]:
+ _CHECK_REPLACEMENT['EXPECT_FALSE'][op] = 'EXPECT_%s' % inv_replacement
+ _CHECK_REPLACEMENT['ASSERT_FALSE'][op] = 'ASSERT_%s' % inv_replacement
+
+# Alternative tokens and their replacements. For full list, see section 2.5
+# Alternative tokens [lex.digraph] in the C++ standard.
+#
+# Digraphs (such as '%:') are not included here since it's a mess to
+# match those on a word boundary.
+_ALT_TOKEN_REPLACEMENT = {
+ 'and': '&&',
+ 'bitor': '|',
+ 'or': '||',
+ 'xor': '^',
+ 'compl': '~',
+ 'bitand': '&',
+ 'and_eq': '&=',
+ 'or_eq': '|=',
+ 'xor_eq': '^=',
+ 'not': '!',
+ 'not_eq': '!='
+ }
+
+# Compile regular expression that matches all the above keywords. The "[ =()]"
+# bit is meant to avoid matching these keywords outside of boolean expressions.
+#
+# False positives include C-style multi-line comments and multi-line strings
+# but those have always been troublesome for cpplint.
+_ALT_TOKEN_REPLACEMENT_PATTERN = re.compile(
+ r'[ =()](' + ('|'.join(_ALT_TOKEN_REPLACEMENT.keys())) + r')(?=[ (]|$)')
+
+
+# These constants define types of headers for use with
+# _IncludeState.CheckNextIncludeOrder().
+_C_SYS_HEADER = 1
+_CPP_SYS_HEADER = 2
+_LIKELY_MY_HEADER = 3
+_POSSIBLE_MY_HEADER = 4
+_OTHER_HEADER = 5
+
+# These constants define the current inline assembly state
+_NO_ASM = 0 # Outside of inline assembly block
+_INSIDE_ASM = 1 # Inside inline assembly block
+_END_ASM = 2 # Last line of inline assembly block
+_BLOCK_ASM = 3 # The whole block is an inline assembly block
+
+# Match start of assembly blocks
+_MATCH_ASM = re.compile(r'^\s*(?:asm|_asm|__asm|__asm__)'
+ r'(?:\s+(volatile|__volatile__))?'
+ r'\s*[{(]')
+
+# Match strings that indicate we're working on a C (not C++) file.
+_SEARCH_C_FILE = re.compile(r'\b(?:LINT_C_FILE|'
+ r'vim?:\s*.*(\s*|:)filetype=c(\s*|:|$))')
+
+# Match string that indicates we're working on a Linux Kernel file.
+_SEARCH_KERNEL_FILE = re.compile(r'\b(?:LINT_KERNEL_FILE)')
+
+_regexp_compile_cache = {}
+
+# {str, set(int)}: a map from error categories to sets of linenumbers
+# on which those errors are expected and should be suppressed.
+_error_suppressions = {}
+
+# The root directory used for deriving header guard CPP variable.
+# This is set by --root flag.
+_root = None
+_root_debug = False
+
+# The allowed line length of files.
+# This is set by --linelength flag.
+_line_length = 80
+
+# The allowed extensions for file names
+# This is set by --extensions flag.
+_valid_extensions = set(['cc', 'h', 'cpp', 'cu', 'cuh'])
+
+# Treat all headers starting with 'h' equally: .h, .hpp, .hxx etc.
+# This is set by --headers flag.
+_hpp_headers = set(['h'])
+
+# {str, bool}: a map from error categories to booleans which indicate if the
+# category should be suppressed for every line.
+_global_error_suppressions = {}
+
+def ProcessHppHeadersOption(val):
+ global _hpp_headers
+ try:
+ _hpp_headers = set(val.split(','))
+ # Automatically append to extensions list so it does not have to be set 2 times
+ _valid_extensions.update(_hpp_headers)
+ except ValueError:
+ PrintUsage('Header extensions must be comma seperated list.')
+
+def IsHeaderExtension(file_extension):
+ return file_extension in _hpp_headers
+
+def ParseNolintSuppressions(filename, raw_line, linenum, error):
+ """Updates the global list of line error-suppressions.
+
+ Parses any NOLINT comments on the current line, updating the global
+ error_suppressions store. Reports an error if the NOLINT comment
+ was malformed.
+
+ Args:
+ filename: str, the name of the input file.
+ raw_line: str, the line of input text, with comments.
+ linenum: int, the number of the current line.
+ error: function, an error handler.
+ """
+ matched = Search(r'\bNOLINT(NEXTLINE)?\b(\([^)]+\))?', raw_line)
+ if matched:
+ if matched.group(1):
+ suppressed_line = linenum + 1
+ else:
+ suppressed_line = linenum
+ category = matched.group(2)
+ if category in (None, '(*)'): # => "suppress all"
+ _error_suppressions.setdefault(None, set()).add(suppressed_line)
+ else:
+ if category.startswith('(') and category.endswith(')'):
+ category = category[1:-1]
+ if category in _ERROR_CATEGORIES:
+ _error_suppressions.setdefault(category, set()).add(suppressed_line)
+ elif category not in _LEGACY_ERROR_CATEGORIES:
+ error(filename, linenum, 'readability/nolint', 5,
+ 'Unknown NOLINT error category: %s' % category)
+
+
+def ProcessGlobalSuppresions(lines):
+ """Updates the list of global error suppressions.
+
+ Parses any lint directives in the file that have global effect.
+
+ Args:
+ lines: An array of strings, each representing a line of the file, with the
+ last element being empty if the file is terminated with a newline.
+ """
+ for line in lines:
+ if _SEARCH_C_FILE.search(line):
+ for category in _DEFAULT_C_SUPPRESSED_CATEGORIES:
+ _global_error_suppressions[category] = True
+ if _SEARCH_KERNEL_FILE.search(line):
+ for category in _DEFAULT_KERNEL_SUPPRESSED_CATEGORIES:
+ _global_error_suppressions[category] = True
+
+
+def ResetNolintSuppressions():
+ """Resets the set of NOLINT suppressions to empty."""
+ _error_suppressions.clear()
+ _global_error_suppressions.clear()
+
+
+def IsErrorSuppressedByNolint(category, linenum):
+ """Returns true if the specified error category is suppressed on this line.
+
+ Consults the global error_suppressions map populated by
+ ParseNolintSuppressions/ProcessGlobalSuppresions/ResetNolintSuppressions.
+
+ Args:
+ category: str, the category of the error.
+ linenum: int, the current line number.
+ Returns:
+ bool, True iff the error should be suppressed due to a NOLINT comment or
+ global suppression.
+ """
+ return (_global_error_suppressions.get(category, False) or
+ linenum in _error_suppressions.get(category, set()) or
+ linenum in _error_suppressions.get(None, set()))
+
+
+def Match(pattern, s):
+ """Matches the string with the pattern, caching the compiled regexp."""
+ # The regexp compilation caching is inlined in both Match and Search for
+ # performance reasons; factoring it out into a separate function turns out
+ # to be noticeably expensive.
+ if pattern not in _regexp_compile_cache:
+ _regexp_compile_cache[pattern] = sre_compile.compile(pattern)
+ return _regexp_compile_cache[pattern].match(s)
+
+
+def ReplaceAll(pattern, rep, s):
+ """Replaces instances of pattern in a string with a replacement.
+
+ The compiled regex is kept in a cache shared by Match and Search.
+
+ Args:
+ pattern: regex pattern
+ rep: replacement text
+ s: search string
+
+ Returns:
+ string with replacements made (or original string if no replacements)
+ """
+ if pattern not in _regexp_compile_cache:
+ _regexp_compile_cache[pattern] = sre_compile.compile(pattern)
+ return _regexp_compile_cache[pattern].sub(rep, s)
+
+
+def Search(pattern, s):
+ """Searches the string for the pattern, caching the compiled regexp."""
+ if pattern not in _regexp_compile_cache:
+ _regexp_compile_cache[pattern] = sre_compile.compile(pattern)
+ return _regexp_compile_cache[pattern].search(s)
+
+
+def _IsSourceExtension(s):
+ """File extension (excluding dot) matches a source file extension."""
+ return s in ('c', 'cc', 'cpp', 'cxx')
+
+
+class _IncludeState(object):
+ """Tracks line numbers for includes, and the order in which includes appear.
+
+ include_list contains list of lists of (header, line number) pairs.
+ It's a lists of lists rather than just one flat list to make it
+ easier to update across preprocessor boundaries.
+
+ Call CheckNextIncludeOrder() once for each header in the file, passing
+ in the type constants defined above. Calls in an illegal order will
+ raise an _IncludeError with an appropriate error message.
+
+ """
+ # self._section will move monotonically through this set. If it ever
+ # needs to move backwards, CheckNextIncludeOrder will raise an error.
+ _INITIAL_SECTION = 0
+ _MY_H_SECTION = 1
+ _C_SECTION = 2
+ _CPP_SECTION = 3
+ _OTHER_H_SECTION = 4
+
+ _TYPE_NAMES = {
+ _C_SYS_HEADER: 'C system header',
+ _CPP_SYS_HEADER: 'C++ system header',
+ _LIKELY_MY_HEADER: 'header this file implements',
+ _POSSIBLE_MY_HEADER: 'header this file may implement',
+ _OTHER_HEADER: 'other header',
+ }
+ _SECTION_NAMES = {
+ _INITIAL_SECTION: "... nothing. (This can't be an error.)",
+ _MY_H_SECTION: 'a header this file implements',
+ _C_SECTION: 'C system header',
+ _CPP_SECTION: 'C++ system header',
+ _OTHER_H_SECTION: 'other header',
+ }
+
+ def __init__(self):
+ self.include_list = [[]]
+ self.ResetSection('')
+
+ def FindHeader(self, header):
+ """Check if a header has already been included.
+
+ Args:
+ header: header to check.
+ Returns:
+ Line number of previous occurrence, or -1 if the header has not
+ been seen before.
+ """
+ for section_list in self.include_list:
+ for f in section_list:
+ if f[0] == header:
+ return f[1]
+ return -1
+
+ def ResetSection(self, directive):
+ """Reset section checking for preprocessor directive.
+
+ Args:
+ directive: preprocessor directive (e.g. "if", "else").
+ """
+ # The name of the current section.
+ self._section = self._INITIAL_SECTION
+ # The path of last found header.
+ self._last_header = ''
+
+ # Update list of includes. Note that we never pop from the
+ # include list.
+ if directive in ('if', 'ifdef', 'ifndef'):
+ self.include_list.append([])
+ elif directive in ('else', 'elif'):
+ self.include_list[-1] = []
+
+ def SetLastHeader(self, header_path):
+ self._last_header = header_path
+
+ def CanonicalizeAlphabeticalOrder(self, header_path):
+ """Returns a path canonicalized for alphabetical comparison.
+
+ - replaces "-" with "_" so they both cmp the same.
+ - removes '-inl' since we don't require them to be after the main header.
+ - lowercase everything, just in case.
+
+ Args:
+ header_path: Path to be canonicalized.
+
+ Returns:
+ Canonicalized path.
+ """
+ return header_path.replace('-inl.h', '.h').replace('-', '_').lower()
+
+ def IsInAlphabeticalOrder(self, clean_lines, linenum, header_path):
+ """Check if a header is in alphabetical order with the previous header.
+
+ Args:
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ header_path: Canonicalized header to be checked.
+
+ Returns:
+ Returns true if the header is in alphabetical order.
+ """
+ # If previous section is different from current section, _last_header will
+ # be reset to empty string, so it's always less than current header.
+ #
+ # If previous line was a blank line, assume that the headers are
+ # intentionally sorted the way they are.
+ if (self._last_header > header_path and
+ Match(r'^\s*#\s*include\b', clean_lines.elided[linenum - 1])):
+ return False
+ return True
+
+ def CheckNextIncludeOrder(self, header_type):
+ """Returns a non-empty error message if the next header is out of order.
+
+ This function also updates the internal state to be ready to check
+ the next include.
+
+ Args:
+ header_type: One of the _XXX_HEADER constants defined above.
+
+ Returns:
+ The empty string if the header is in the right order, or an
+ error message describing what's wrong.
+
+ """
+ error_message = ('Found %s after %s' %
+ (self._TYPE_NAMES[header_type],
+ self._SECTION_NAMES[self._section]))
+
+ last_section = self._section
+
+ if header_type == _C_SYS_HEADER:
+ if self._section <= self._C_SECTION:
+ self._section = self._C_SECTION
+ else:
+ self._last_header = ''
+ return error_message
+ elif header_type == _CPP_SYS_HEADER:
+ if self._section <= self._CPP_SECTION:
+ self._section = self._CPP_SECTION
+ else:
+ self._last_header = ''
+ return error_message
+ elif header_type == _LIKELY_MY_HEADER:
+ if self._section <= self._MY_H_SECTION:
+ self._section = self._MY_H_SECTION
+ else:
+ self._section = self._OTHER_H_SECTION
+ elif header_type == _POSSIBLE_MY_HEADER:
+ if self._section <= self._MY_H_SECTION:
+ self._section = self._MY_H_SECTION
+ else:
+ # This will always be the fallback because we're not sure
+ # enough that the header is associated with this file.
+ self._section = self._OTHER_H_SECTION
+ else:
+ assert header_type == _OTHER_HEADER
+ self._section = self._OTHER_H_SECTION
+
+ if last_section != self._section:
+ self._last_header = ''
+
+ return ''
+
+
+class _CppLintState(object):
+ """Maintains module-wide state.."""
+
+ def __init__(self):
+ self.verbose_level = 1 # global setting.
+ self.error_count = 0 # global count of reported errors
+ # filters to apply when emitting error messages
+ self.filters = _DEFAULT_FILTERS[:]
+ # backup of filter list. Used to restore the state after each file.
+ self._filters_backup = self.filters[:]
+ self.counting = 'total' # In what way are we counting errors?
+ self.errors_by_category = {} # string to int dict storing error counts
+ self.quiet = False # Suppress non-error messagess?
+
+ # output format:
+ # "emacs" - format that emacs can parse (default)
+ # "vs7" - format that Microsoft Visual Studio 7 can parse
+ self.output_format = 'emacs'
+
+ def SetOutputFormat(self, output_format):
+ """Sets the output format for errors."""
+ self.output_format = output_format
+
+ def SetQuiet(self, quiet):
+ """Sets the module's quiet settings, and returns the previous setting."""
+ last_quiet = self.quiet
+ self.quiet = quiet
+ return last_quiet
+
+ def SetVerboseLevel(self, level):
+ """Sets the module's verbosity, and returns the previous setting."""
+ last_verbose_level = self.verbose_level
+ self.verbose_level = level
+ return last_verbose_level
+
+ def SetCountingStyle(self, counting_style):
+ """Sets the module's counting options."""
+ self.counting = counting_style
+
+ def SetFilters(self, filters):
+ """Sets the error-message filters.
+
+ These filters are applied when deciding whether to emit a given
+ error message.
+
+ Args:
+ filters: A string of comma-separated filters (eg "+whitespace/indent").
+ Each filter should start with + or -; else we die.
+
+ Raises:
+ ValueError: The comma-separated filters did not all start with '+' or '-'.
+ E.g. "-,+whitespace,-whitespace/indent,whitespace/badfilter"
+ """
+ # Default filters always have less priority than the flag ones.
+ self.filters = _DEFAULT_FILTERS[:]
+ self.AddFilters(filters)
+
+ def AddFilters(self, filters):
+ """ Adds more filters to the existing list of error-message filters. """
+ for filt in filters.split(','):
+ clean_filt = filt.strip()
+ if clean_filt:
+ self.filters.append(clean_filt)
+ for filt in self.filters:
+ if not (filt.startswith('+') or filt.startswith('-')):
+ raise ValueError('Every filter in --filters must start with + or -'
+ ' (%s does not)' % filt)
+
+ def BackupFilters(self):
+ """ Saves the current filter list to backup storage."""
+ self._filters_backup = self.filters[:]
+
+ def RestoreFilters(self):
+ """ Restores filters previously backed up."""
+ self.filters = self._filters_backup[:]
+
+ def ResetErrorCounts(self):
+ """Sets the module's error statistic back to zero."""
+ self.error_count = 0
+ self.errors_by_category = {}
+
+ def IncrementErrorCount(self, category):
+ """Bumps the module's error statistic."""
+ self.error_count += 1
+ if self.counting in ('toplevel', 'detailed'):
+ if self.counting != 'detailed':
+ category = category.split('/')[0]
+ if category not in self.errors_by_category:
+ self.errors_by_category[category] = 0
+ self.errors_by_category[category] += 1
+
+ def PrintErrorCounts(self):
+ """Print a summary of errors by category, and the total."""
+ for category, count in self.errors_by_category.iteritems():
+ sys.stderr.write('Category \'%s\' errors found: %d\n' %
+ (category, count))
+ sys.stdout.write('Total errors found: %d\n' % self.error_count)
+
+_cpplint_state = _CppLintState()
+
+
+def _OutputFormat():
+ """Gets the module's output format."""
+ return _cpplint_state.output_format
+
+
+def _SetOutputFormat(output_format):
+ """Sets the module's output format."""
+ _cpplint_state.SetOutputFormat(output_format)
+
+def _Quiet():
+ """Return's the module's quiet setting."""
+ return _cpplint_state.quiet
+
+def _SetQuiet(quiet):
+ """Set the module's quiet status, and return previous setting."""
+ return _cpplint_state.SetQuiet(quiet)
+
+
+def _VerboseLevel():
+ """Returns the module's verbosity setting."""
+ return _cpplint_state.verbose_level
+
+
+def _SetVerboseLevel(level):
+ """Sets the module's verbosity, and returns the previous setting."""
+ return _cpplint_state.SetVerboseLevel(level)
+
+
+def _SetCountingStyle(level):
+ """Sets the module's counting options."""
+ _cpplint_state.SetCountingStyle(level)
+
+
+def _Filters():
+ """Returns the module's list of output filters, as a list."""
+ return _cpplint_state.filters
+
+
+def _SetFilters(filters):
+ """Sets the module's error-message filters.
+
+ These filters are applied when deciding whether to emit a given
+ error message.
+
+ Args:
+ filters: A string of comma-separated filters (eg "whitespace/indent").
+ Each filter should start with + or -; else we die.
+ """
+ _cpplint_state.SetFilters(filters)
+
+def _AddFilters(filters):
+ """Adds more filter overrides.
+
+ Unlike _SetFilters, this function does not reset the current list of filters
+ available.
+
+ Args:
+ filters: A string of comma-separated filters (eg "whitespace/indent").
+ Each filter should start with + or -; else we die.
+ """
+ _cpplint_state.AddFilters(filters)
+
+def _BackupFilters():
+ """ Saves the current filter list to backup storage."""
+ _cpplint_state.BackupFilters()
+
+def _RestoreFilters():
+ """ Restores filters previously backed up."""
+ _cpplint_state.RestoreFilters()
+
+class _FunctionState(object):
+ """Tracks current function name and the number of lines in its body."""
+
+ _NORMAL_TRIGGER = 250 # for --v=0, 500 for --v=1, etc.
+ _TEST_TRIGGER = 400 # about 50% more than _NORMAL_TRIGGER.
+
+ def __init__(self):
+ self.in_a_function = False
+ self.lines_in_function = 0
+ self.current_function = ''
+
+ def Begin(self, function_name):
+ """Start analyzing function body.
+
+ Args:
+ function_name: The name of the function being tracked.
+ """
+ self.in_a_function = True
+ self.lines_in_function = 0
+ self.current_function = function_name
+
+ def Count(self):
+ """Count line in current function body."""
+ if self.in_a_function:
+ self.lines_in_function += 1
+
+ def Check(self, error, filename, linenum):
+ """Report if too many lines in function body.
+
+ Args:
+ error: The function to call with any errors found.
+ filename: The name of the current file.
+ linenum: The number of the line to check.
+ """
+ if not self.in_a_function:
+ return
+
+ if Match(r'T(EST|est)', self.current_function):
+ base_trigger = self._TEST_TRIGGER
+ else:
+ base_trigger = self._NORMAL_TRIGGER
+ trigger = base_trigger * 2**_VerboseLevel()
+
+ if self.lines_in_function > trigger:
+ error_level = int(math.log(self.lines_in_function / base_trigger, 2))
+ # 50 => 0, 100 => 1, 200 => 2, 400 => 3, 800 => 4, 1600 => 5, ...
+ if error_level > 5:
+ error_level = 5
+ error(filename, linenum, 'readability/fn_size', error_level,
+ 'Small and focused functions are preferred:'
+ ' %s has %d non-comment lines'
+ ' (error triggered by exceeding %d lines).' % (
+ self.current_function, self.lines_in_function, trigger))
+
+ def End(self):
+ """Stop analyzing function body."""
+ self.in_a_function = False
+
+
+class _IncludeError(Exception):
+ """Indicates a problem with the include order in a file."""
+ pass
+
+
+class FileInfo(object):
+ """Provides utility functions for filenames.
+
+ FileInfo provides easy access to the components of a file's path
+ relative to the project root.
+ """
+
+ def __init__(self, filename):
+ self._filename = filename
+
+ def FullName(self):
+ """Make Windows paths like Unix."""
+ return os.path.abspath(self._filename).replace('\\', '/')
+
+ def RepositoryName(self):
+ """FullName after removing the local path to the repository.
+
+ If we have a real absolute path name here we can try to do something smart:
+ detecting the root of the checkout and truncating /path/to/checkout from
+ the name so that we get header guards that don't include things like
+ "C:\Documents and Settings\..." or "/home/username/..." in them and thus
+ people on different computers who have checked the source out to different
+ locations won't see bogus errors.
+ """
+ fullname = self.FullName()
+
+ if os.path.exists(fullname):
+ project_dir = os.path.dirname(fullname)
+
+ if os.path.exists(os.path.join(project_dir, ".svn")):
+ # If there's a .svn file in the current directory, we recursively look
+ # up the directory tree for the top of the SVN checkout
+ root_dir = project_dir
+ one_up_dir = os.path.dirname(root_dir)
+ while os.path.exists(os.path.join(one_up_dir, ".svn")):
+ root_dir = os.path.dirname(root_dir)
+ one_up_dir = os.path.dirname(one_up_dir)
+
+ prefix = os.path.commonprefix([root_dir, project_dir])
+ return fullname[len(prefix) + 1:]
+
+ # Not SVN <= 1.6? Try to find a git, hg, or svn top level directory by
+ # searching up from the current path.
+ root_dir = current_dir = os.path.dirname(fullname)
+ while current_dir != os.path.dirname(current_dir):
+ if (os.path.exists(os.path.join(current_dir, ".git")) or
+ os.path.exists(os.path.join(current_dir, ".hg")) or
+ os.path.exists(os.path.join(current_dir, ".svn"))):
+ root_dir = current_dir
+ current_dir = os.path.dirname(current_dir)
+
+ if (os.path.exists(os.path.join(root_dir, ".git")) or
+ os.path.exists(os.path.join(root_dir, ".hg")) or
+ os.path.exists(os.path.join(root_dir, ".svn"))):
+ prefix = os.path.commonprefix([root_dir, project_dir])
+ return fullname[len(prefix) + 1:]
+
+ # Don't know what to do; header guard warnings may be wrong...
+ return fullname
+
+ def Split(self):
+ """Splits the file into the directory, basename, and extension.
+
+ For 'chrome/browser/browser.cc', Split() would
+ return ('chrome/browser', 'browser', '.cc')
+
+ Returns:
+ A tuple of (directory, basename, extension).
+ """
+
+ googlename = self.RepositoryName()
+ project, rest = os.path.split(googlename)
+ return (project,) + os.path.splitext(rest)
+
+ def BaseName(self):
+ """File base name - text after the final slash, before the final period."""
+ return self.Split()[1]
+
+ def Extension(self):
+ """File extension - text following the final period."""
+ return self.Split()[2]
+
+ def NoExtension(self):
+ """File has no source file extension."""
+ return '/'.join(self.Split()[0:2])
+
+ def IsSource(self):
+ """File has a source file extension."""
+ return _IsSourceExtension(self.Extension()[1:])
+
+
+def _ShouldPrintError(category, confidence, linenum):
+ """If confidence >= verbose, category passes filter and is not suppressed."""
+
+ # There are three ways we might decide not to print an error message:
+ # a "NOLINT(category)" comment appears in the source,
+ # the verbosity level isn't high enough, or the filters filter it out.
+ if IsErrorSuppressedByNolint(category, linenum):
+ return False
+
+ if confidence < _cpplint_state.verbose_level:
+ return False
+
+ is_filtered = False
+ for one_filter in _Filters():
+ if one_filter.startswith('-'):
+ if category.startswith(one_filter[1:]):
+ is_filtered = True
+ elif one_filter.startswith('+'):
+ if category.startswith(one_filter[1:]):
+ is_filtered = False
+ else:
+ assert False # should have been checked for in SetFilter.
+ if is_filtered:
+ return False
+
+ return True
+
+
+def Error(filename, linenum, category, confidence, message):
+ """Logs the fact we've found a lint error.
+
+ We log where the error was found, and also our confidence in the error,
+ that is, how certain we are this is a legitimate style regression, and
+ not a misidentification or a use that's sometimes justified.
+
+ False positives can be suppressed by the use of
+ "cpplint(category)" comments on the offending line. These are
+ parsed into _error_suppressions.
+
+ Args:
+ filename: The name of the file containing the error.
+ linenum: The number of the line containing the error.
+ category: A string used to describe the "category" this bug
+ falls under: "whitespace", say, or "runtime". Categories
+ may have a hierarchy separated by slashes: "whitespace/indent".
+ confidence: A number from 1-5 representing a confidence score for
+ the error, with 5 meaning that we are certain of the problem,
+ and 1 meaning that it could be a legitimate construct.
+ message: The error message.
+ """
+ if _ShouldPrintError(category, confidence, linenum):
+ _cpplint_state.IncrementErrorCount(category)
+ if _cpplint_state.output_format == 'vs7':
+ sys.stderr.write('%s(%s): error cpplint: [%s] %s [%d]\n' % (
+ filename, linenum, category, message, confidence))
+ elif _cpplint_state.output_format == 'eclipse':
+ sys.stderr.write('%s:%s: warning: %s [%s] [%d]\n' % (
+ filename, linenum, message, category, confidence))
+ else:
+ sys.stderr.write('%s:%s: %s [%s] [%d]\n' % (
+ filename, linenum, message, category, confidence))
+
+
+# Matches standard C++ escape sequences per 2.13.2.3 of the C++ standard.
+_RE_PATTERN_CLEANSE_LINE_ESCAPES = re.compile(
+ r'\\([abfnrtv?"\\\']|\d+|x[0-9a-fA-F]+)')
+# Match a single C style comment on the same line.
+_RE_PATTERN_C_COMMENTS = r'/\*(?:[^*]|\*(?!/))*\*/'
+# Matches multi-line C style comments.
+# This RE is a little bit more complicated than one might expect, because we
+# have to take care of space removals tools so we can handle comments inside
+# statements better.
+# The current rule is: We only clear spaces from both sides when we're at the
+# end of the line. Otherwise, we try to remove spaces from the right side,
+# if this doesn't work we try on left side but only if there's a non-character
+# on the right.
+_RE_PATTERN_CLEANSE_LINE_C_COMMENTS = re.compile(
+ r'(\s*' + _RE_PATTERN_C_COMMENTS + r'\s*$|' +
+ _RE_PATTERN_C_COMMENTS + r'\s+|' +
+ r'\s+' + _RE_PATTERN_C_COMMENTS + r'(?=\W)|' +
+ _RE_PATTERN_C_COMMENTS + r')')
+
+
+def IsCppString(line):
+ """Does line terminate so, that the next symbol is in string constant.
+
+ This function does not consider single-line nor multi-line comments.
+
+ Args:
+ line: is a partial line of code starting from the 0..n.
+
+ Returns:
+ True, if next character appended to 'line' is inside a
+ string constant.
+ """
+
+ line = line.replace(r'\\', 'XX') # after this, \\" does not match to \"
+ return ((line.count('"') - line.count(r'\"') - line.count("'\"'")) & 1) == 1
+
+
+def CleanseRawStrings(raw_lines):
+ """Removes C++11 raw strings from lines.
+
+ Before:
+ static const char kData[] = R"(
+ multi-line string
+ )";
+
+ After:
+ static const char kData[] = ""
+ (replaced by blank line)
+ "";
+
+ Args:
+ raw_lines: list of raw lines.
+
+ Returns:
+ list of lines with C++11 raw strings replaced by empty strings.
+ """
+
+ delimiter = None
+ lines_without_raw_strings = []
+ for line in raw_lines:
+ if delimiter:
+ # Inside a raw string, look for the end
+ end = line.find(delimiter)
+ if end >= 0:
+ # Found the end of the string, match leading space for this
+ # line and resume copying the original lines, and also insert
+ # a "" on the last line.
+ leading_space = Match(r'^(\s*)\S', line)
+ line = leading_space.group(1) + '""' + line[end + len(delimiter):]
+ delimiter = None
+ else:
+ # Haven't found the end yet, append a blank line.
+ line = '""'
+
+ # Look for beginning of a raw string, and replace them with
+ # empty strings. This is done in a loop to handle multiple raw
+ # strings on the same line.
+ while delimiter is None:
+ # Look for beginning of a raw string.
+ # See 2.14.15 [lex.string] for syntax.
+ #
+ # Once we have matched a raw string, we check the prefix of the
+ # line to make sure that the line is not part of a single line
+ # comment. It's done this way because we remove raw strings
+ # before removing comments as opposed to removing comments
+ # before removing raw strings. This is because there are some
+ # cpplint checks that requires the comments to be preserved, but
+ # we don't want to check comments that are inside raw strings.
+ matched = Match(r'^(.*?)\b(?:R|u8R|uR|UR|LR)"([^\s\\()]*)\((.*)$', line)
+ if (matched and
+ not Match(r'^([^\'"]|\'(\\.|[^\'])*\'|"(\\.|[^"])*")*//',
+ matched.group(1))):
+ delimiter = ')' + matched.group(2) + '"'
+
+ end = matched.group(3).find(delimiter)
+ if end >= 0:
+ # Raw string ended on same line
+ line = (matched.group(1) + '""' +
+ matched.group(3)[end + len(delimiter):])
+ delimiter = None
+ else:
+ # Start of a multi-line raw string
+ line = matched.group(1) + '""'
+ else:
+ break
+
+ lines_without_raw_strings.append(line)
+
+ # TODO(unknown): if delimiter is not None here, we might want to
+ # emit a warning for unterminated string.
+ return lines_without_raw_strings
+
+
+def FindNextMultiLineCommentStart(lines, lineix):
+ """Find the beginning marker for a multiline comment."""
+ while lineix < len(lines):
+ if lines[lineix].strip().startswith('/*'):
+ # Only return this marker if the comment goes beyond this line
+ if lines[lineix].strip().find('*/', 2) < 0:
+ return lineix
+ lineix += 1
+ return len(lines)
+
+
+def FindNextMultiLineCommentEnd(lines, lineix):
+ """We are inside a comment, find the end marker."""
+ while lineix < len(lines):
+ if lines[lineix].strip().endswith('*/'):
+ return lineix
+ lineix += 1
+ return len(lines)
+
+
+def RemoveMultiLineCommentsFromRange(lines, begin, end):
+ """Clears a range of lines for multi-line comments."""
+ # Having // dummy comments makes the lines non-empty, so we will not get
+ # unnecessary blank line warnings later in the code.
+ for i in range(begin, end):
+ lines[i] = '/**/'
+
+
+def RemoveMultiLineComments(filename, lines, error):
+ """Removes multiline (c-style) comments from lines."""
+ lineix = 0
+ while lineix < len(lines):
+ lineix_begin = FindNextMultiLineCommentStart(lines, lineix)
+ if lineix_begin >= len(lines):
+ return
+ lineix_end = FindNextMultiLineCommentEnd(lines, lineix_begin)
+ if lineix_end >= len(lines):
+ error(filename, lineix_begin + 1, 'readability/multiline_comment', 5,
+ 'Could not find end of multi-line comment')
+ return
+ RemoveMultiLineCommentsFromRange(lines, lineix_begin, lineix_end + 1)
+ lineix = lineix_end + 1
+
+
+def CleanseComments(line):
+ """Removes //-comments and single-line C-style /* */ comments.
+
+ Args:
+ line: A line of C++ source.
+
+ Returns:
+ The line with single-line comments removed.
+ """
+ commentpos = line.find('//')
+ if commentpos != -1 and not IsCppString(line[:commentpos]):
+ line = line[:commentpos].rstrip()
+ # get rid of /* ... */
+ return _RE_PATTERN_CLEANSE_LINE_C_COMMENTS.sub('', line)
+
+
+class CleansedLines(object):
+ """Holds 4 copies of all lines with different preprocessing applied to them.
+
+ 1) elided member contains lines without strings and comments.
+ 2) lines member contains lines without comments.
+ 3) raw_lines member contains all the lines without processing.
+ 4) lines_without_raw_strings member is same as raw_lines, but with C++11 raw
+ strings removed.
+ All these members are of <type 'list'>, and of the same length.
+ """
+
+ def __init__(self, lines):
+ self.elided = []
+ self.lines = []
+ self.raw_lines = lines
+ self.num_lines = len(lines)
+ self.lines_without_raw_strings = CleanseRawStrings(lines)
+ for linenum in range(len(self.lines_without_raw_strings)):
+ self.lines.append(CleanseComments(
+ self.lines_without_raw_strings[linenum]))
+ elided = self._CollapseStrings(self.lines_without_raw_strings[linenum])
+ self.elided.append(CleanseComments(elided))
+
+ def NumLines(self):
+ """Returns the number of lines represented."""
+ return self.num_lines
+
+ @staticmethod
+ def _CollapseStrings(elided):
+ """Collapses strings and chars on a line to simple "" or '' blocks.
+
+ We nix strings first so we're not fooled by text like '"http://"'
+
+ Args:
+ elided: The line being processed.
+
+ Returns:
+ The line with collapsed strings.
+ """
+ if _RE_PATTERN_INCLUDE.match(elided):
+ return elided
+
+ # Remove escaped characters first to make quote/single quote collapsing
+ # basic. Things that look like escaped characters shouldn't occur
+ # outside of strings and chars.
+ elided = _RE_PATTERN_CLEANSE_LINE_ESCAPES.sub('', elided)
+
+ # Replace quoted strings and digit separators. Both single quotes
+ # and double quotes are processed in the same loop, otherwise
+ # nested quotes wouldn't work.
+ collapsed = ''
+ while True:
+ # Find the first quote character
+ match = Match(r'^([^\'"]*)([\'"])(.*)$', elided)
+ if not match:
+ collapsed += elided
+ break
+ head, quote, tail = match.groups()
+
+ if quote == '"':
+ # Collapse double quoted strings
+ second_quote = tail.find('"')
+ if second_quote >= 0:
+ collapsed += head + '""'
+ elided = tail[second_quote + 1:]
+ else:
+ # Unmatched double quote, don't bother processing the rest
+ # of the line since this is probably a multiline string.
+ collapsed += elided
+ break
+ else:
+ # Found single quote, check nearby text to eliminate digit separators.
+ #
+ # There is no special handling for floating point here, because
+ # the integer/fractional/exponent parts would all be parsed
+ # correctly as long as there are digits on both sides of the
+ # separator. So we are fine as long as we don't see something
+ # like "0.'3" (gcc 4.9.0 will not allow this literal).
+ if Search(r'\b(?:0[bBxX]?|[1-9])[0-9a-fA-F]*$', head):
+ match_literal = Match(r'^((?:\'?[0-9a-zA-Z_])*)(.*)$', "'" + tail)
+ collapsed += head + match_literal.group(1).replace("'", '')
+ elided = match_literal.group(2)
+ else:
+ second_quote = tail.find('\'')
+ if second_quote >= 0:
+ collapsed += head + "''"
+ elided = tail[second_quote + 1:]
+ else:
+ # Unmatched single quote
+ collapsed += elided
+ break
+
+ return collapsed
+
+
+def FindEndOfExpressionInLine(line, startpos, stack):
+ """Find the position just after the end of current parenthesized expression.
+
+ Args:
+ line: a CleansedLines line.
+ startpos: start searching at this position.
+ stack: nesting stack at startpos.
+
+ Returns:
+ On finding matching end: (index just after matching end, None)
+ On finding an unclosed expression: (-1, None)
+ Otherwise: (-1, new stack at end of this line)
+ """
+ for i in xrange(startpos, len(line)):
+ char = line[i]
+ if char in '([{':
+ # Found start of parenthesized expression, push to expression stack
+ stack.append(char)
+ elif char == '<':
+ # Found potential start of template argument list
+ if i > 0 and line[i - 1] == '<':
+ # Left shift operator
+ if stack and stack[-1] == '<':
+ stack.pop()
+ if not stack:
+ return (-1, None)
+ elif i > 0 and Search(r'\boperator\s*$', line[0:i]):
+ # operator<, don't add to stack
+ continue
+ else:
+ # Tentative start of template argument list
+ stack.append('<')
+ elif char in ')]}':
+ # Found end of parenthesized expression.
+ #
+ # If we are currently expecting a matching '>', the pending '<'
+ # must have been an operator. Remove them from expression stack.
+ while stack and stack[-1] == '<':
+ stack.pop()
+ if not stack:
+ return (-1, None)
+ if ((stack[-1] == '(' and char == ')') or
+ (stack[-1] == '[' and char == ']') or
+ (stack[-1] == '{' and char == '}')):
+ stack.pop()
+ if not stack:
+ return (i + 1, None)
+ else:
+ # Mismatched parentheses
+ return (-1, None)
+ elif char == '>':
+ # Found potential end of template argument list.
+
+ # Ignore "->" and operator functions
+ if (i > 0 and
+ (line[i - 1] == '-' or Search(r'\boperator\s*$', line[0:i - 1]))):
+ continue
+
+ # Pop the stack if there is a matching '<'. Otherwise, ignore
+ # this '>' since it must be an operator.
+ if stack:
+ if stack[-1] == '<':
+ stack.pop()
+ if not stack:
+ return (i + 1, None)
+ elif char == ';':
+ # Found something that look like end of statements. If we are currently
+ # expecting a '>', the matching '<' must have been an operator, since
+ # template argument list should not contain statements.
+ while stack and stack[-1] == '<':
+ stack.pop()
+ if not stack:
+ return (-1, None)
+
+ # Did not find end of expression or unbalanced parentheses on this line
+ return (-1, stack)
+
+
+def CloseExpression(clean_lines, linenum, pos):
+ """If input points to ( or { or [ or <, finds the position that closes it.
+
+ If lines[linenum][pos] points to a '(' or '{' or '[' or '<', finds the
+ linenum/pos that correspond to the closing of the expression.
+
+ TODO(unknown): cpplint spends a fair bit of time matching parentheses.
+ Ideally we would want to index all opening and closing parentheses once
+ and have CloseExpression be just a simple lookup, but due to preprocessor
+ tricks, this is not so easy.
+
+ Args:
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ pos: A position on the line.
+
+ Returns:
+ A tuple (line, linenum, pos) pointer *past* the closing brace, or
+ (line, len(lines), -1) if we never find a close. Note we ignore
+ strings and comments when matching; and the line we return is the
+ 'cleansed' line at linenum.
+ """
+
+ line = clean_lines.elided[linenum]
+ if (line[pos] not in '({[<') or Match(r'<[<=]', line[pos:]):
+ return (line, clean_lines.NumLines(), -1)
+
+ # Check first line
+ (end_pos, stack) = FindEndOfExpressionInLine(line, pos, [])
+ if end_pos > -1:
+ return (line, linenum, end_pos)
+
+ # Continue scanning forward
+ while stack and linenum < clean_lines.NumLines() - 1:
+ linenum += 1
+ line = clean_lines.elided[linenum]
+ (end_pos, stack) = FindEndOfExpressionInLine(line, 0, stack)
+ if end_pos > -1:
+ return (line, linenum, end_pos)
+
+ # Did not find end of expression before end of file, give up
+ return (line, clean_lines.NumLines(), -1)
+
+
+def FindStartOfExpressionInLine(line, endpos, stack):
+ """Find position at the matching start of current expression.
+
+ This is almost the reverse of FindEndOfExpressionInLine, but note
+ that the input position and returned position differs by 1.
+
+ Args:
+ line: a CleansedLines line.
+ endpos: start searching at this position.
+ stack: nesting stack at endpos.
+
+ Returns:
+ On finding matching start: (index at matching start, None)
+ On finding an unclosed expression: (-1, None)
+ Otherwise: (-1, new stack at beginning of this line)
+ """
+ i = endpos
+ while i >= 0:
+ char = line[i]
+ if char in ')]}':
+ # Found end of expression, push to expression stack
+ stack.append(char)
+ elif char == '>':
+ # Found potential end of template argument list.
+ #
+ # Ignore it if it's a "->" or ">=" or "operator>"
+ if (i > 0 and
+ (line[i - 1] == '-' or
+ Match(r'\s>=\s', line[i - 1:]) or
+ Search(r'\boperator\s*$', line[0:i]))):
+ i -= 1
+ else:
+ stack.append('>')
+ elif char == '<':
+ # Found potential start of template argument list
+ if i > 0 and line[i - 1] == '<':
+ # Left shift operator
+ i -= 1
+ else:
+ # If there is a matching '>', we can pop the expression stack.
+ # Otherwise, ignore this '<' since it must be an operator.
+ if stack and stack[-1] == '>':
+ stack.pop()
+ if not stack:
+ return (i, None)
+ elif char in '([{':
+ # Found start of expression.
+ #
+ # If there are any unmatched '>' on the stack, they must be
+ # operators. Remove those.
+ while stack and stack[-1] == '>':
+ stack.pop()
+ if not stack:
+ return (-1, None)
+ if ((char == '(' and stack[-1] == ')') or
+ (char == '[' and stack[-1] == ']') or
+ (char == '{' and stack[-1] == '}')):
+ stack.pop()
+ if not stack:
+ return (i, None)
+ else:
+ # Mismatched parentheses
+ return (-1, None)
+ elif char == ';':
+ # Found something that look like end of statements. If we are currently
+ # expecting a '<', the matching '>' must have been an operator, since
+ # template argument list should not contain statements.
+ while stack and stack[-1] == '>':
+ stack.pop()
+ if not stack:
+ return (-1, None)
+
+ i -= 1
+
+ return (-1, stack)
+
+
+def ReverseCloseExpression(clean_lines, linenum, pos):
+ """If input points to ) or } or ] or >, finds the position that opens it.
+
+ If lines[linenum][pos] points to a ')' or '}' or ']' or '>', finds the
+ linenum/pos that correspond to the opening of the expression.
+
+ Args:
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ pos: A position on the line.
+
+ Returns:
+ A tuple (line, linenum, pos) pointer *at* the opening brace, or
+ (line, 0, -1) if we never find the matching opening brace. Note
+ we ignore strings and comments when matching; and the line we
+ return is the 'cleansed' line at linenum.
+ """
+ line = clean_lines.elided[linenum]
+ if line[pos] not in ')}]>':
+ return (line, 0, -1)
+
+ # Check last line
+ (start_pos, stack) = FindStartOfExpressionInLine(line, pos, [])
+ if start_pos > -1:
+ return (line, linenum, start_pos)
+
+ # Continue scanning backward
+ while stack and linenum > 0:
+ linenum -= 1
+ line = clean_lines.elided[linenum]
+ (start_pos, stack) = FindStartOfExpressionInLine(line, len(line) - 1, stack)
+ if start_pos > -1:
+ return (line, linenum, start_pos)
+
+ # Did not find start of expression before beginning of file, give up
+ return (line, 0, -1)
+
+
+def CheckForCopyright(filename, lines, error):
+ """Logs an error if no Copyright message appears at the top of the file."""
+
+ # We'll say it should occur by line 10. Don't forget there's a
+ # dummy line at the front.
+ for line in xrange(1, min(len(lines), 11)):
+ if re.search(r'Copyright', lines[line], re.I): break
+ else: # means no copyright line was found
+ error(filename, 0, 'legal/copyright', 5,
+ 'No copyright message found. '
+ 'You should have a line: "Copyright [year] <Copyright Owner>"')
+
+
+def GetIndentLevel(line):
+ """Return the number of leading spaces in line.
+
+ Args:
+ line: A string to check.
+
+ Returns:
+ An integer count of leading spaces, possibly zero.
+ """
+ indent = Match(r'^( *)\S', line)
+ if indent:
+ return len(indent.group(1))
+ else:
+ return 0
+
+def PathSplitToList(path):
+ """Returns the path split into a list by the separator.
+
+ Args:
+ path: An absolute or relative path (e.g. '/a/b/c/' or '../a')
+
+ Returns:
+ A list of path components (e.g. ['a', 'b', 'c]).
+ """
+ lst = []
+ while True:
+ (head, tail) = os.path.split(path)
+ if head == path: # absolute paths end
+ lst.append(head)
+ break
+ if tail == path: # relative paths end
+ lst.append(tail)
+ break
+
+ path = head
+ lst.append(tail)
+
+ lst.reverse()
+ return lst
+
+def GetHeaderGuardCPPVariable(filename):
+ """Returns the CPP variable that should be used as a header guard.
+
+ Args:
+ filename: The name of a C++ header file.
+
+ Returns:
+ The CPP variable that should be used as a header guard in the
+ named file.
+
+ """
+
+ # Restores original filename in case that cpplint is invoked from Emacs's
+ # flymake.
+ filename = re.sub(r'_flymake\.h$', '.h', filename)
+ filename = re.sub(r'/\.flymake/([^/]*)$', r'/\1', filename)
+ # Replace 'c++' with 'cpp'.
+ filename = filename.replace('C++', 'cpp').replace('c++', 'cpp')
+
+ fileinfo = FileInfo(filename)
+ file_path_from_root = fileinfo.RepositoryName()
+
+ def FixupPathFromRoot():
+ if _root_debug:
+ sys.stderr.write("\n_root fixup, _root = '%s', repository name = '%s'\n"
+ %(_root, fileinfo.RepositoryName()))
+
+ # Process the file path with the --root flag if it was set.
+ if not _root:
+ if _root_debug:
+ sys.stderr.write("_root unspecified\n")
+ return file_path_from_root
+
+ def StripListPrefix(lst, prefix):
+ # f(['x', 'y'], ['w, z']) -> None (not a valid prefix)
+ if lst[:len(prefix)] != prefix:
+ return None
+ # f(['a, 'b', 'c', 'd'], ['a', 'b']) -> ['c', 'd']
+ return lst[(len(prefix)):]
+
+ # root behavior:
+ # --root=subdir , lstrips subdir from the header guard
+ maybe_path = StripListPrefix(PathSplitToList(file_path_from_root),
+ PathSplitToList(_root))
+
+ if _root_debug:
+ sys.stderr.write("_root lstrip (maybe_path=%s, file_path_from_root=%s," +
+ " _root=%s)\n" %(maybe_path, file_path_from_root, _root))
+
+ if maybe_path:
+ return os.path.join(*maybe_path)
+
+ # --root=.. , will prepend the outer directory to the header guard
+ full_path = fileinfo.FullName()
+ root_abspath = os.path.abspath(_root)
+
+ maybe_path = StripListPrefix(PathSplitToList(full_path),
+ PathSplitToList(root_abspath))
+
+ if _root_debug:
+ sys.stderr.write("_root prepend (maybe_path=%s, full_path=%s, " +
+ "root_abspath=%s)\n" %(maybe_path, full_path, root_abspath))
+
+ if maybe_path:
+ return os.path.join(*maybe_path)
+
+ if _root_debug:
+ sys.stderr.write("_root ignore, returning %s\n" %(file_path_from_root))
+
+ # --root=FAKE_DIR is ignored
+ return file_path_from_root
+
+ file_path_from_root = FixupPathFromRoot()
+ return re.sub(r'[^a-zA-Z0-9]', '_', file_path_from_root).upper() + '_'
+
+
+def CheckForHeaderGuard(filename, clean_lines, error):
+ """Checks that the file contains a header guard.
+
+ Logs an error if no #ifndef header guard is present. For other
+ headers, checks that the full pathname is used.
+
+ Args:
+ filename: The name of the C++ header file.
+ clean_lines: A CleansedLines instance containing the file.
+ error: The function to call with any errors found.
+ """
+
+ # Don't check for header guards if there are error suppression
+ # comments somewhere in this file.
+ #
+ # Because this is silencing a warning for a nonexistent line, we
+ # only support the very specific NOLINT(build/header_guard) syntax,
+ # and not the general NOLINT or NOLINT(*) syntax.
+ raw_lines = clean_lines.lines_without_raw_strings
+ for i in raw_lines:
+ if Search(r'//\s*NOLINT\(build/header_guard\)', i):
+ return
+
+ cppvar = GetHeaderGuardCPPVariable(filename)
+
+ ifndef = ''
+ ifndef_linenum = 0
+ define = ''
+ endif = ''
+ endif_linenum = 0
+ for linenum, line in enumerate(raw_lines):
+ linesplit = line.split()
+ if len(linesplit) >= 2:
+ # find the first occurrence of #ifndef and #define, save arg
+ if not ifndef and linesplit[0] == '#ifndef':
+ # set ifndef to the header guard presented on the #ifndef line.
+ ifndef = linesplit[1]
+ ifndef_linenum = linenum
+ if not define and linesplit[0] == '#define':
+ define = linesplit[1]
+ # find the last occurrence of #endif, save entire line
+ if line.startswith('#endif'):
+ endif = line
+ endif_linenum = linenum
+
+ if not ifndef or not define or ifndef != define:
+ error(filename, 0, 'build/header_guard', 5,
+ 'No #ifndef header guard found, suggested CPP variable is: %s' %
+ cppvar)
+ return
+
+ # The guard should be PATH_FILE_H_, but we also allow PATH_FILE_H__
+ # for backward compatibility.
+ if ifndef != cppvar:
+ error_level = 0
+ if ifndef != cppvar + '_':
+ error_level = 5
+
+ ParseNolintSuppressions(filename, raw_lines[ifndef_linenum], ifndef_linenum,
+ error)
+ error(filename, ifndef_linenum, 'build/header_guard', error_level,
+ '#ifndef header guard has wrong style, please use: %s' % cppvar)
+
+ # Check for "//" comments on endif line.
+ ParseNolintSuppressions(filename, raw_lines[endif_linenum], endif_linenum,
+ error)
+ match = Match(r'#endif\s*//\s*' + cppvar + r'(_)?\b', endif)
+ if match:
+ if match.group(1) == '_':
+ # Issue low severity warning for deprecated double trailing underscore
+ error(filename, endif_linenum, 'build/header_guard', 0,
+ '#endif line should be "#endif // %s"' % cppvar)
+ return
+
+ # Didn't find the corresponding "//" comment. If this file does not
+ # contain any "//" comments at all, it could be that the compiler
+ # only wants "/**/" comments, look for those instead.
+ no_single_line_comments = True
+ for i in xrange(1, len(raw_lines) - 1):
+ line = raw_lines[i]
+ if Match(r'^(?:(?:\'(?:\.|[^\'])*\')|(?:"(?:\.|[^"])*")|[^\'"])*//', line):
+ no_single_line_comments = False
+ break
+
+ if no_single_line_comments:
+ match = Match(r'#endif\s*/\*\s*' + cppvar + r'(_)?\s*\*/', endif)
+ if match:
+ if match.group(1) == '_':
+ # Low severity warning for double trailing underscore
+ error(filename, endif_linenum, 'build/header_guard', 0,
+ '#endif line should be "#endif /* %s */"' % cppvar)
+ return
+
+ # Didn't find anything
+ error(filename, endif_linenum, 'build/header_guard', 5,
+ '#endif line should be "#endif // %s"' % cppvar)
+
+
+def CheckHeaderFileIncluded(filename, include_state, error):
+ """Logs an error if a .cc file does not include its header."""
+
+ # Do not check test files
+ fileinfo = FileInfo(filename)
+ if Search(_TEST_FILE_SUFFIX, fileinfo.BaseName()):
+ return
+
+ headerfile = filename[0:len(filename) - len(fileinfo.Extension())] + '.h'
+ if not os.path.exists(headerfile):
+ return
+ headername = FileInfo(headerfile).RepositoryName()
+ first_include = 0
+ for section_list in include_state.include_list:
+ for f in section_list:
+ if headername in f[0] or f[0] in headername:
+ return
+ if not first_include:
+ first_include = f[1]
+
+ error(filename, first_include, 'build/include', 5,
+ '%s should include its header file %s' % (fileinfo.RepositoryName(),
+ headername))
+
+
+def CheckForBadCharacters(filename, lines, error):
+ """Logs an error for each line containing bad characters.
+
+ Two kinds of bad characters:
+
+ 1. Unicode replacement characters: These indicate that either the file
+ contained invalid UTF-8 (likely) or Unicode replacement characters (which
+ it shouldn't). Note that it's possible for this to throw off line
+ numbering if the invalid UTF-8 occurred adjacent to a newline.
+
+ 2. NUL bytes. These are problematic for some tools.
+
+ Args:
+ filename: The name of the current file.
+ lines: An array of strings, each representing a line of the file.
+ error: The function to call with any errors found.
+ """
+ for linenum, line in enumerate(lines):
+ if u'\ufffd' in line:
+ error(filename, linenum, 'readability/utf8', 5,
+ 'Line contains invalid UTF-8 (or Unicode replacement character).')
+ if '\0' in line:
+ error(filename, linenum, 'readability/nul', 5, 'Line contains NUL byte.')
+
+
+def CheckForNewlineAtEOF(filename, lines, error):
+ """Logs an error if there is no newline char at the end of the file.
+
+ Args:
+ filename: The name of the current file.
+ lines: An array of strings, each representing a line of the file.
+ error: The function to call with any errors found.
+ """
+
+ # The array lines() was created by adding two newlines to the
+ # original file (go figure), then splitting on \n.
+ # To verify that the file ends in \n, we just have to make sure the
+ # last-but-two element of lines() exists and is empty.
+ if len(lines) < 3 or lines[-2]:
+ error(filename, len(lines) - 2, 'whitespace/ending_newline', 5,
+ 'Could not find a newline character at the end of the file.')
+
+
+def CheckForMultilineCommentsAndStrings(filename, clean_lines, linenum, error):
+ """Logs an error if we see /* ... */ or "..." that extend past one line.
+
+ /* ... */ comments are legit inside macros, for one line.
+ Otherwise, we prefer // comments, so it's ok to warn about the
+ other. Likewise, it's ok for strings to extend across multiple
+ lines, as long as a line continuation character (backslash)
+ terminates each line. Although not currently prohibited by the C++
+ style guide, it's ugly and unnecessary. We don't do well with either
+ in this lint program, so we warn about both.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ line = clean_lines.elided[linenum]
+
+ # Remove all \\ (escaped backslashes) from the line. They are OK, and the
+ # second (escaped) slash may trigger later \" detection erroneously.
+ line = line.replace('\\\\', '')
+
+ if line.count('/*') > line.count('*/'):
+ error(filename, linenum, 'readability/multiline_comment', 5,
+ 'Complex multi-line /*...*/-style comment found. '
+ 'Lint may give bogus warnings. '
+ 'Consider replacing these with //-style comments, '
+ 'with #if 0...#endif, '
+ 'or with more clearly structured multi-line comments.')
+
+ if (line.count('"') - line.count('\\"')) % 2:
+ error(filename, linenum, 'readability/multiline_string', 5,
+ 'Multi-line string ("...") found. This lint script doesn\'t '
+ 'do well with such strings, and may give bogus warnings. '
+ 'Use C++11 raw strings or concatenation instead.')
+
+
+# (non-threadsafe name, thread-safe alternative, validation pattern)
+#
+# The validation pattern is used to eliminate false positives such as:
+# _rand(); // false positive due to substring match.
+# ->rand(); // some member function rand().
+# ACMRandom rand(seed); // some variable named rand.
+# ISAACRandom rand(); // another variable named rand.
+#
+# Basically we require the return value of these functions to be used
+# in some expression context on the same line by matching on some
+# operator before the function name. This eliminates constructors and
+# member function calls.
+_UNSAFE_FUNC_PREFIX = r'(?:[-+*/=%^&|(<]\s*|>\s+)'
+_THREADING_LIST = (
+ ('asctime(', 'asctime_r(', _UNSAFE_FUNC_PREFIX + r'asctime\([^)]+\)'),
+ ('ctime(', 'ctime_r(', _UNSAFE_FUNC_PREFIX + r'ctime\([^)]+\)'),
+ ('getgrgid(', 'getgrgid_r(', _UNSAFE_FUNC_PREFIX + r'getgrgid\([^)]+\)'),
+ ('getgrnam(', 'getgrnam_r(', _UNSAFE_FUNC_PREFIX + r'getgrnam\([^)]+\)'),
+ ('getlogin(', 'getlogin_r(', _UNSAFE_FUNC_PREFIX + r'getlogin\(\)'),
+ ('getpwnam(', 'getpwnam_r(', _UNSAFE_FUNC_PREFIX + r'getpwnam\([^)]+\)'),
+ ('getpwuid(', 'getpwuid_r(', _UNSAFE_FUNC_PREFIX + r'getpwuid\([^)]+\)'),
+ ('gmtime(', 'gmtime_r(', _UNSAFE_FUNC_PREFIX + r'gmtime\([^)]+\)'),
+ ('localtime(', 'localtime_r(', _UNSAFE_FUNC_PREFIX + r'localtime\([^)]+\)'),
+ ('rand(', 'rand_r(', _UNSAFE_FUNC_PREFIX + r'rand\(\)'),
+ ('strtok(', 'strtok_r(',
+ _UNSAFE_FUNC_PREFIX + r'strtok\([^)]+\)'),
+ ('ttyname(', 'ttyname_r(', _UNSAFE_FUNC_PREFIX + r'ttyname\([^)]+\)'),
+ )
+
+
+def CheckPosixThreading(filename, clean_lines, linenum, error):
+ """Checks for calls to thread-unsafe functions.
+
+ Much code has been originally written without consideration of
+ multi-threading. Also, engineers are relying on their old experience;
+ they have learned posix before threading extensions were added. These
+ tests guide the engineers to use thread-safe functions (when using
+ posix directly).
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ line = clean_lines.elided[linenum]
+ for single_thread_func, multithread_safe_func, pattern in _THREADING_LIST:
+ # Additional pattern matching check to confirm that this is the
+ # function we are looking for
+ if Search(pattern, line):
+ error(filename, linenum, 'runtime/threadsafe_fn', 2,
+ 'Consider using ' + multithread_safe_func +
+ '...) instead of ' + single_thread_func +
+ '...) for improved thread safety.')
+
+
+def CheckVlogArguments(filename, clean_lines, linenum, error):
+ """Checks that VLOG() is only used for defining a logging level.
+
+ For example, VLOG(2) is correct. VLOG(INFO), VLOG(WARNING), VLOG(ERROR), and
+ VLOG(FATAL) are not.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ line = clean_lines.elided[linenum]
+ if Search(r'\bVLOG\((INFO|ERROR|WARNING|DFATAL|FATAL)\)', line):
+ error(filename, linenum, 'runtime/vlog', 5,
+ 'VLOG() should be used with numeric verbosity level. '
+ 'Use LOG() if you want symbolic severity levels.')
+
+# Matches invalid increment: *count++, which moves pointer instead of
+# incrementing a value.
+_RE_PATTERN_INVALID_INCREMENT = re.compile(
+ r'^\s*\*\w+(\+\+|--);')
+
+
+def CheckInvalidIncrement(filename, clean_lines, linenum, error):
+ """Checks for invalid increment *count++.
+
+ For example following function:
+ void increment_counter(int* count) {
+ *count++;
+ }
+ is invalid, because it effectively does count++, moving pointer, and should
+ be replaced with ++*count, (*count)++ or *count += 1.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ line = clean_lines.elided[linenum]
+ if _RE_PATTERN_INVALID_INCREMENT.match(line):
+ error(filename, linenum, 'runtime/invalid_increment', 5,
+ 'Changing pointer instead of value (or unused value of operator*).')
+
+
+def IsMacroDefinition(clean_lines, linenum):
+ if Search(r'^#define', clean_lines[linenum]):
+ return True
+
+ if linenum > 0 and Search(r'\\$', clean_lines[linenum - 1]):
+ return True
+
+ return False
+
+
+def IsForwardClassDeclaration(clean_lines, linenum):
+ return Match(r'^\s*(\btemplate\b)*.*class\s+\w+;\s*$', clean_lines[linenum])
+
+
+class _BlockInfo(object):
+ """Stores information about a generic block of code."""
+
+ def __init__(self, linenum, seen_open_brace):
+ self.starting_linenum = linenum
+ self.seen_open_brace = seen_open_brace
+ self.open_parentheses = 0
+ self.inline_asm = _NO_ASM
+ self.check_namespace_indentation = False
+
+ def CheckBegin(self, filename, clean_lines, linenum, error):
+ """Run checks that applies to text up to the opening brace.
+
+ This is mostly for checking the text after the class identifier
+ and the "{", usually where the base class is specified. For other
+ blocks, there isn't much to check, so we always pass.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ pass
+
+ def CheckEnd(self, filename, clean_lines, linenum, error):
+ """Run checks that applies to text after the closing brace.
+
+ This is mostly used for checking end of namespace comments.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ pass
+
+ def IsBlockInfo(self):
+ """Returns true if this block is a _BlockInfo.
+
+ This is convenient for verifying that an object is an instance of
+ a _BlockInfo, but not an instance of any of the derived classes.
+
+ Returns:
+ True for this class, False for derived classes.
+ """
+ return self.__class__ == _BlockInfo
+
+
+class _ExternCInfo(_BlockInfo):
+ """Stores information about an 'extern "C"' block."""
+
+ def __init__(self, linenum):
+ _BlockInfo.__init__(self, linenum, True)
+
+
+class _ClassInfo(_BlockInfo):
+ """Stores information about a class."""
+
+ def __init__(self, name, class_or_struct, clean_lines, linenum):
+ _BlockInfo.__init__(self, linenum, False)
+ self.name = name
+ self.is_derived = False
+ self.check_namespace_indentation = True
+ if class_or_struct == 'struct':
+ self.access = 'public'
+ self.is_struct = True
+ else:
+ self.access = 'private'
+ self.is_struct = False
+
+ # Remember initial indentation level for this class. Using raw_lines here
+ # instead of elided to account for leading comments.
+ self.class_indent = GetIndentLevel(clean_lines.raw_lines[linenum])
+
+ # Try to find the end of the class. This will be confused by things like:
+ # class A {
+ # } *x = { ...
+ #
+ # But it's still good enough for CheckSectionSpacing.
+ self.last_line = 0
+ depth = 0
+ for i in range(linenum, clean_lines.NumLines()):
+ line = clean_lines.elided[i]
+ depth += line.count('{') - line.count('}')
+ if not depth:
+ self.last_line = i
+ break
+
+ def CheckBegin(self, filename, clean_lines, linenum, error):
+ # Look for a bare ':'
+ if Search('(^|[^:]):($|[^:])', clean_lines.elided[linenum]):
+ self.is_derived = True
+
+ def CheckEnd(self, filename, clean_lines, linenum, error):
+ # If there is a DISALLOW macro, it should appear near the end of
+ # the class.
+ seen_last_thing_in_class = False
+ for i in xrange(linenum - 1, self.starting_linenum, -1):
+ match = Search(
+ r'\b(DISALLOW_COPY_AND_ASSIGN|DISALLOW_IMPLICIT_CONSTRUCTORS)\(' +
+ self.name + r'\)',
+ clean_lines.elided[i])
+ if match:
+ if seen_last_thing_in_class:
+ error(filename, i, 'readability/constructors', 3,
+ match.group(1) + ' should be the last thing in the class')
+ break
+
+ if not Match(r'^\s*$', clean_lines.elided[i]):
+ seen_last_thing_in_class = True
+
+ # Check that closing brace is aligned with beginning of the class.
+ # Only do this if the closing brace is indented by only whitespaces.
+ # This means we will not check single-line class definitions.
+ indent = Match(r'^( *)\}', clean_lines.elided[linenum])
+ if indent and len(indent.group(1)) != self.class_indent:
+ if self.is_struct:
+ parent = 'struct ' + self.name
+ else:
+ parent = 'class ' + self.name
+ error(filename, linenum, 'whitespace/indent', 3,
+ 'Closing brace should be aligned with beginning of %s' % parent)
+
+
+class _NamespaceInfo(_BlockInfo):
+ """Stores information about a namespace."""
+
+ def __init__(self, name, linenum):
+ _BlockInfo.__init__(self, linenum, False)
+ self.name = name or ''
+ self.check_namespace_indentation = True
+
+ def CheckEnd(self, filename, clean_lines, linenum, error):
+ """Check end of namespace comments."""
+ line = clean_lines.raw_lines[linenum]
+
+ # Check how many lines is enclosed in this namespace. Don't issue
+ # warning for missing namespace comments if there aren't enough
+ # lines. However, do apply checks if there is already an end of
+ # namespace comment and it's incorrect.
+ #
+ # TODO(unknown): We always want to check end of namespace comments
+ # if a namespace is large, but sometimes we also want to apply the
+ # check if a short namespace contained nontrivial things (something
+ # other than forward declarations). There is currently no logic on
+ # deciding what these nontrivial things are, so this check is
+ # triggered by namespace size only, which works most of the time.
+ if (linenum - self.starting_linenum < 10
+ and not Match(r'^\s*};*\s*(//|/\*).*\bnamespace\b', line)):
+ return
+
+ # Look for matching comment at end of namespace.
+ #
+ # Note that we accept C style "/* */" comments for terminating
+ # namespaces, so that code that terminate namespaces inside
+ # preprocessor macros can be cpplint clean.
+ #
+ # We also accept stuff like "// end of namespace <name>." with the
+ # period at the end.
+ #
+ # Besides these, we don't accept anything else, otherwise we might
+ # get false negatives when existing comment is a substring of the
+ # expected namespace.
+ if self.name:
+ # Named namespace
+ if not Match((r'^\s*};*\s*(//|/\*).*\bnamespace\s+' +
+ re.escape(self.name) + r'[\*/\.\\\s]*$'),
+ line):
+ error(filename, linenum, 'readability/namespace', 5,
+ 'Namespace should be terminated with "// namespace %s"' %
+ self.name)
+ else:
+ # Anonymous namespace
+ if not Match(r'^\s*};*\s*(//|/\*).*\bnamespace[\*/\.\\\s]*$', line):
+ # If "// namespace anonymous" or "// anonymous namespace (more text)",
+ # mention "// anonymous namespace" as an acceptable form
+ if Match(r'^\s*}.*\b(namespace anonymous|anonymous namespace)\b', line):
+ error(filename, linenum, 'readability/namespace', 5,
+ 'Anonymous namespace should be terminated with "// namespace"'
+ ' or "// anonymous namespace"')
+ else:
+ error(filename, linenum, 'readability/namespace', 5,
+ 'Anonymous namespace should be terminated with "// namespace"')
+
+
+class _PreprocessorInfo(object):
+ """Stores checkpoints of nesting stacks when #if/#else is seen."""
+
+ def __init__(self, stack_before_if):
+ # The entire nesting stack before #if
+ self.stack_before_if = stack_before_if
+
+ # The entire nesting stack up to #else
+ self.stack_before_else = []
+
+ # Whether we have already seen #else or #elif
+ self.seen_else = False
+
+
+class NestingState(object):
+ """Holds states related to parsing braces."""
+
+ def __init__(self):
+ # Stack for tracking all braces. An object is pushed whenever we
+ # see a "{", and popped when we see a "}". Only 3 types of
+ # objects are possible:
+ # - _ClassInfo: a class or struct.
+ # - _NamespaceInfo: a namespace.
+ # - _BlockInfo: some other type of block.
+ self.stack = []
+
+ # Top of the previous stack before each Update().
+ #
+ # Because the nesting_stack is updated at the end of each line, we
+ # had to do some convoluted checks to find out what is the current
+ # scope at the beginning of the line. This check is simplified by
+ # saving the previous top of nesting stack.
+ #
+ # We could save the full stack, but we only need the top. Copying
+ # the full nesting stack would slow down cpplint by ~10%.
+ self.previous_stack_top = []
+
+ # Stack of _PreprocessorInfo objects.
+ self.pp_stack = []
+
+ def SeenOpenBrace(self):
+ """Check if we have seen the opening brace for the innermost block.
+
+ Returns:
+ True if we have seen the opening brace, False if the innermost
+ block is still expecting an opening brace.
+ """
+ return (not self.stack) or self.stack[-1].seen_open_brace
+
+ def InNamespaceBody(self):
+ """Check if we are currently one level inside a namespace body.
+
+ Returns:
+ True if top of the stack is a namespace block, False otherwise.
+ """
+ return self.stack and isinstance(self.stack[-1], _NamespaceInfo)
+
+ def InExternC(self):
+ """Check if we are currently one level inside an 'extern "C"' block.
+
+ Returns:
+ True if top of the stack is an extern block, False otherwise.
+ """
+ return self.stack and isinstance(self.stack[-1], _ExternCInfo)
+
+ def InClassDeclaration(self):
+ """Check if we are currently one level inside a class or struct declaration.
+
+ Returns:
+ True if top of the stack is a class/struct, False otherwise.
+ """
+ return self.stack and isinstance(self.stack[-1], _ClassInfo)
+
+ def InAsmBlock(self):
+ """Check if we are currently one level inside an inline ASM block.
+
+ Returns:
+ True if the top of the stack is a block containing inline ASM.
+ """
+ return self.stack and self.stack[-1].inline_asm != _NO_ASM
+
+ def InTemplateArgumentList(self, clean_lines, linenum, pos):
+ """Check if current position is inside template argument list.
+
+ Args:
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ pos: position just after the suspected template argument.
+ Returns:
+ True if (linenum, pos) is inside template arguments.
+ """
+ while linenum < clean_lines.NumLines():
+ # Find the earliest character that might indicate a template argument
+ line = clean_lines.elided[linenum]
+ match = Match(r'^[^{};=\[\]\.<>]*(.)', line[pos:])
+ if not match:
+ linenum += 1
+ pos = 0
+ continue
+ token = match.group(1)
+ pos += len(match.group(0))
+
+ # These things do not look like template argument list:
+ # class Suspect {
+ # class Suspect x; }
+ if token in ('{', '}', ';'): return False
+
+ # These things look like template argument list:
+ # template <class Suspect>
+ # template <class Suspect = default_value>
+ # template <class Suspect[]>
+ # template <class Suspect...>
+ if token in ('>', '=', '[', ']', '.'): return True
+
+ # Check if token is an unmatched '<'.
+ # If not, move on to the next character.
+ if token != '<':
+ pos += 1
+ if pos >= len(line):
+ linenum += 1
+ pos = 0
+ continue
+
+ # We can't be sure if we just find a single '<', and need to
+ # find the matching '>'.
+ (_, end_line, end_pos) = CloseExpression(clean_lines, linenum, pos - 1)
+ if end_pos < 0:
+ # Not sure if template argument list or syntax error in file
+ return False
+ linenum = end_line
+ pos = end_pos
+ return False
+
+ def UpdatePreprocessor(self, line):
+ """Update preprocessor stack.
+
+ We need to handle preprocessors due to classes like this:
+ #ifdef SWIG
+ struct ResultDetailsPageElementExtensionPoint {
+ #else
+ struct ResultDetailsPageElementExtensionPoint : public Extension {
+ #endif
+
+ We make the following assumptions (good enough for most files):
+ - Preprocessor condition evaluates to true from #if up to first
+ #else/#elif/#endif.
+
+ - Preprocessor condition evaluates to false from #else/#elif up
+ to #endif. We still perform lint checks on these lines, but
+ these do not affect nesting stack.
+
+ Args:
+ line: current line to check.
+ """
+ if Match(r'^\s*#\s*(if|ifdef|ifndef)\b', line):
+ # Beginning of #if block, save the nesting stack here. The saved
+ # stack will allow us to restore the parsing state in the #else case.
+ self.pp_stack.append(_PreprocessorInfo(copy.deepcopy(self.stack)))
+ elif Match(r'^\s*#\s*(else|elif)\b', line):
+ # Beginning of #else block
+ if self.pp_stack:
+ if not self.pp_stack[-1].seen_else:
+ # This is the first #else or #elif block. Remember the
+ # whole nesting stack up to this point. This is what we
+ # keep after the #endif.
+ self.pp_stack[-1].seen_else = True
+ self.pp_stack[-1].stack_before_else = copy.deepcopy(self.stack)
+
+ # Restore the stack to how it was before the #if
+ self.stack = copy.deepcopy(self.pp_stack[-1].stack_before_if)
+ else:
+ # TODO(unknown): unexpected #else, issue warning?
+ pass
+ elif Match(r'^\s*#\s*endif\b', line):
+ # End of #if or #else blocks.
+ if self.pp_stack:
+ # If we saw an #else, we will need to restore the nesting
+ # stack to its former state before the #else, otherwise we
+ # will just continue from where we left off.
+ if self.pp_stack[-1].seen_else:
+ # Here we can just use a shallow copy since we are the last
+ # reference to it.
+ self.stack = self.pp_stack[-1].stack_before_else
+ # Drop the corresponding #if
+ self.pp_stack.pop()
+ else:
+ # TODO(unknown): unexpected #endif, issue warning?
+ pass
+
+ # TODO(unknown): Update() is too long, but we will refactor later.
+ def Update(self, filename, clean_lines, linenum, error):
+ """Update nesting state with current line.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ line = clean_lines.elided[linenum]
+
+ # Remember top of the previous nesting stack.
+ #
+ # The stack is always pushed/popped and not modified in place, so
+ # we can just do a shallow copy instead of copy.deepcopy. Using
+ # deepcopy would slow down cpplint by ~28%.
+ if self.stack:
+ self.previous_stack_top = self.stack[-1]
+ else:
+ self.previous_stack_top = None
+
+ # Update pp_stack
+ self.UpdatePreprocessor(line)
+
+ # Count parentheses. This is to avoid adding struct arguments to
+ # the nesting stack.
+ if self.stack:
+ inner_block = self.stack[-1]
+ depth_change = line.count('(') - line.count(')')
+ inner_block.open_parentheses += depth_change
+
+ # Also check if we are starting or ending an inline assembly block.
+ if inner_block.inline_asm in (_NO_ASM, _END_ASM):
+ if (depth_change != 0 and
+ inner_block.open_parentheses == 1 and
+ _MATCH_ASM.match(line)):
+ # Enter assembly block
+ inner_block.inline_asm = _INSIDE_ASM
+ else:
+ # Not entering assembly block. If previous line was _END_ASM,
+ # we will now shift to _NO_ASM state.
+ inner_block.inline_asm = _NO_ASM
+ elif (inner_block.inline_asm == _INSIDE_ASM and
+ inner_block.open_parentheses == 0):
+ # Exit assembly block
+ inner_block.inline_asm = _END_ASM
+
+ # Consume namespace declaration at the beginning of the line. Do
+ # this in a loop so that we catch same line declarations like this:
+ # namespace proto2 { namespace bridge { class MessageSet; } }
+ while True:
+ # Match start of namespace. The "\b\s*" below catches namespace
+ # declarations even if it weren't followed by a whitespace, this
+ # is so that we don't confuse our namespace checker. The
+ # missing spaces will be flagged by CheckSpacing.
+ namespace_decl_match = Match(r'^\s*namespace\b\s*([:\w]+)?(.*)$', line)
+ if not namespace_decl_match:
+ break
+
+ new_namespace = _NamespaceInfo(namespace_decl_match.group(1), linenum)
+ self.stack.append(new_namespace)
+
+ line = namespace_decl_match.group(2)
+ if line.find('{') != -1:
+ new_namespace.seen_open_brace = True
+ line = line[line.find('{') + 1:]
+
+ # Look for a class declaration in whatever is left of the line
+ # after parsing namespaces. The regexp accounts for decorated classes
+ # such as in:
+ # class LOCKABLE API Object {
+ # };
+ class_decl_match = Match(
+ r'^(\s*(?:template\s*<[\w\s<>,:]*>\s*)?'
+ r'(class|struct)\s+(?:[A-Z_]+\s+)*(\w+(?:::\w+)*))'
+ r'(.*)$', line)
+ if (class_decl_match and
+ (not self.stack or self.stack[-1].open_parentheses == 0)):
+ # We do not want to accept classes that are actually template arguments:
+ # template <class Ignore1,
+ # class Ignore2 = Default<Args>,
+ # template <Args> class Ignore3>
+ # void Function() {};
+ #
+ # To avoid template argument cases, we scan forward and look for
+ # an unmatched '>'. If we see one, assume we are inside a
+ # template argument list.
+ end_declaration = len(class_decl_match.group(1))
+ if not self.InTemplateArgumentList(clean_lines, linenum, end_declaration):
+ self.stack.append(_ClassInfo(
+ class_decl_match.group(3), class_decl_match.group(2),
+ clean_lines, linenum))
+ line = class_decl_match.group(4)
+
+ # If we have not yet seen the opening brace for the innermost block,
+ # run checks here.
+ if not self.SeenOpenBrace():
+ self.stack[-1].CheckBegin(filename, clean_lines, linenum, error)
+
+ # Update access control if we are inside a class/struct
+ if self.stack and isinstance(self.stack[-1], _ClassInfo):
+ classinfo = self.stack[-1]
+ access_match = Match(
+ r'^(.*)\b(public|private|protected|signals)(\s+(?:slots\s*)?)?'
+ r':(?:[^:]|$)',
+ line)
+ if access_match:
+ classinfo.access = access_match.group(2)
+
+ # Check that access keywords are indented +1 space. Skip this
+ # check if the keywords are not preceded by whitespaces.
+ indent = access_match.group(1)
+ if (len(indent) != classinfo.class_indent + 1 and
+ Match(r'^\s*$', indent)):
+ if classinfo.is_struct:
+ parent = 'struct ' + classinfo.name
+ else:
+ parent = 'class ' + classinfo.name
+ slots = ''
+ if access_match.group(3):
+ slots = access_match.group(3)
+ error(filename, linenum, 'whitespace/indent', 3,
+ '%s%s: should be indented +1 space inside %s' % (
+ access_match.group(2), slots, parent))
+
+ # Consume braces or semicolons from what's left of the line
+ while True:
+ # Match first brace, semicolon, or closed parenthesis.
+ matched = Match(r'^[^{;)}]*([{;)}])(.*)$', line)
+ if not matched:
+ break
+
+ token = matched.group(1)
+ if token == '{':
+ # If namespace or class hasn't seen a opening brace yet, mark
+ # namespace/class head as complete. Push a new block onto the
+ # stack otherwise.
+ if not self.SeenOpenBrace():
+ self.stack[-1].seen_open_brace = True
+ elif Match(r'^extern\s*"[^"]*"\s*\{', line):
+ self.stack.append(_ExternCInfo(linenum))
+ else:
+ self.stack.append(_BlockInfo(linenum, True))
+ if _MATCH_ASM.match(line):
+ self.stack[-1].inline_asm = _BLOCK_ASM
+
+ elif token == ';' or token == ')':
+ # If we haven't seen an opening brace yet, but we already saw
+ # a semicolon, this is probably a forward declaration. Pop
+ # the stack for these.
+ #
+ # Similarly, if we haven't seen an opening brace yet, but we
+ # already saw a closing parenthesis, then these are probably
+ # function arguments with extra "class" or "struct" keywords.
+ # Also pop these stack for these.
+ if not self.SeenOpenBrace():
+ self.stack.pop()
+ else: # token == '}'
+ # Perform end of block checks and pop the stack.
+ if self.stack:
+ self.stack[-1].CheckEnd(filename, clean_lines, linenum, error)
+ self.stack.pop()
+ line = matched.group(2)
+
+ def InnermostClass(self):
+ """Get class info on the top of the stack.
+
+ Returns:
+ A _ClassInfo object if we are inside a class, or None otherwise.
+ """
+ for i in range(len(self.stack), 0, -1):
+ classinfo = self.stack[i - 1]
+ if isinstance(classinfo, _ClassInfo):
+ return classinfo
+ return None
+
+ def CheckCompletedBlocks(self, filename, error):
+ """Checks that all classes and namespaces have been completely parsed.
+
+ Call this when all lines in a file have been processed.
+ Args:
+ filename: The name of the current file.
+ error: The function to call with any errors found.
+ """
+ # Note: This test can result in false positives if #ifdef constructs
+ # get in the way of brace matching. See the testBuildClass test in
+ # cpplint_unittest.py for an example of this.
+ for obj in self.stack:
+ if isinstance(obj, _ClassInfo):
+ error(filename, obj.starting_linenum, 'build/class', 5,
+ 'Failed to find complete declaration of class %s' %
+ obj.name)
+ elif isinstance(obj, _NamespaceInfo):
+ error(filename, obj.starting_linenum, 'build/namespaces', 5,
+ 'Failed to find complete declaration of namespace %s' %
+ obj.name)
+
+
+def CheckForNonStandardConstructs(filename, clean_lines, linenum,
+ nesting_state, error):
+ r"""Logs an error if we see certain non-ANSI constructs ignored by gcc-2.
+
+ Complain about several constructs which gcc-2 accepts, but which are
+ not standard C++. Warning about these in lint is one way to ease the
+ transition to new compilers.
+ - put storage class first (e.g. "static const" instead of "const static").
+ - "%lld" instead of %qd" in printf-type functions.
+ - "%1$d" is non-standard in printf-type functions.
+ - "\%" is an undefined character escape sequence.
+ - text after #endif is not allowed.
+ - invalid inner-style forward declaration.
+ - >? and <? operators, and their >?= and <?= cousins.
+
+ Additionally, check for constructor/destructor style violations and reference
+ members, as it is very convenient to do so while checking for
+ gcc-2 compliance.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ nesting_state: A NestingState instance which maintains information about
+ the current stack of nested blocks being parsed.
+ error: A callable to which errors are reported, which takes 4 arguments:
+ filename, line number, error level, and message
+ """
+
+ # Remove comments from the line, but leave in strings for now.
+ line = clean_lines.lines[linenum]
+
+ if Search(r'printf\s*\(.*".*%[-+ ]?\d*q', line):
+ error(filename, linenum, 'runtime/printf_format', 3,
+ '%q in format strings is deprecated. Use %ll instead.')
+
+ if Search(r'printf\s*\(.*".*%\d+\$', line):
+ error(filename, linenum, 'runtime/printf_format', 2,
+ '%N$ formats are unconventional. Try rewriting to avoid them.')
+
+ # Remove escaped backslashes before looking for undefined escapes.
+ line = line.replace('\\\\', '')
+
+ if Search(r'("|\').*\\(%|\[|\(|{)', line):
+ error(filename, linenum, 'build/printf_format', 3,
+ '%, [, (, and { are undefined character escapes. Unescape them.')
+
+ # For the rest, work with both comments and strings removed.
+ line = clean_lines.elided[linenum]
+
+ if Search(r'\b(const|volatile|void|char|short|int|long'
+ r'|float|double|signed|unsigned'
+ r'|schar|u?int8|u?int16|u?int32|u?int64)'
+ r'\s+(register|static|extern|typedef)\b',
+ line):
+ error(filename, linenum, 'build/storage_class', 5,
+ 'Storage-class specifier (static, extern, typedef, etc) should be '
+ 'at the beginning of the declaration.')
+
+ if Match(r'\s*#\s*endif\s*[^/\s]+', line):
+ error(filename, linenum, 'build/endif_comment', 5,
+ 'Uncommented text after #endif is non-standard. Use a comment.')
+
+ if Match(r'\s*class\s+(\w+\s*::\s*)+\w+\s*;', line):
+ error(filename, linenum, 'build/forward_decl', 5,
+ 'Inner-style forward declarations are invalid. Remove this line.')
+
+ if Search(r'(\w+|[+-]?\d+(\.\d*)?)\s*(<|>)\?=?\s*(\w+|[+-]?\d+)(\.\d*)?',
+ line):
+ error(filename, linenum, 'build/deprecated', 3,
+ '>? and <? (max and min) operators are non-standard and deprecated.')
+
+ if Search(r'^\s*const\s*string\s*&\s*\w+\s*;', line):
+ # TODO(unknown): Could it be expanded safely to arbitrary references,
+ # without triggering too many false positives? The first
+ # attempt triggered 5 warnings for mostly benign code in the regtest, hence
+ # the restriction.
+ # Here's the original regexp, for the reference:
+ # type_name = r'\w+((\s*::\s*\w+)|(\s*<\s*\w+?\s*>))?'
+ # r'\s*const\s*' + type_name + '\s*&\s*\w+\s*;'
+ error(filename, linenum, 'runtime/member_string_references', 2,
+ 'const string& members are dangerous. It is much better to use '
+ 'alternatives, such as pointers or simple constants.')
+
+ # Everything else in this function operates on class declarations.
+ # Return early if the top of the nesting stack is not a class, or if
+ # the class head is not completed yet.
+ classinfo = nesting_state.InnermostClass()
+ if not classinfo or not classinfo.seen_open_brace:
+ return
+
+ # The class may have been declared with namespace or classname qualifiers.
+ # The constructor and destructor will not have those qualifiers.
+ base_classname = classinfo.name.split('::')[-1]
+
+ # Look for single-argument constructors that aren't marked explicit.
+ # Technically a valid construct, but against style.
+ explicit_constructor_match = Match(
+ r'\s+(?:(?:inline|constexpr)\s+)*(explicit\s+)?'
+ r'(?:(?:inline|constexpr)\s+)*%s\s*'
+ r'\(((?:[^()]|\([^()]*\))*)\)'
+ % re.escape(base_classname),
+ line)
+
+ if explicit_constructor_match:
+ is_marked_explicit = explicit_constructor_match.group(1)
+
+ if not explicit_constructor_match.group(2):
+ constructor_args = []
+ else:
+ constructor_args = explicit_constructor_match.group(2).split(',')
+
+ # collapse arguments so that commas in template parameter lists and function
+ # argument parameter lists don't split arguments in two
+ i = 0
+ while i < len(constructor_args):
+ constructor_arg = constructor_args[i]
+ while (constructor_arg.count('<') > constructor_arg.count('>') or
+ constructor_arg.count('(') > constructor_arg.count(')')):
+ constructor_arg += ',' + constructor_args[i + 1]
+ del constructor_args[i + 1]
+ constructor_args[i] = constructor_arg
+ i += 1
+
+ defaulted_args = [arg for arg in constructor_args if '=' in arg]
+ noarg_constructor = (not constructor_args or # empty arg list
+ # 'void' arg specifier
+ (len(constructor_args) == 1 and
+ constructor_args[0].strip() == 'void'))
+ onearg_constructor = ((len(constructor_args) == 1 and # exactly one arg
+ not noarg_constructor) or
+ # all but at most one arg defaulted
+ (len(constructor_args) >= 1 and
+ not noarg_constructor and
+ len(defaulted_args) >= len(constructor_args) - 1))
+ initializer_list_constructor = bool(
+ onearg_constructor and
+ Search(r'\bstd\s*::\s*initializer_list\b', constructor_args[0]))
+ copy_constructor = bool(
+ onearg_constructor and
+ Match(r'(const\s+)?%s(\s*<[^>]*>)?(\s+const)?\s*(?:<\w+>\s*)?&'
+ % re.escape(base_classname), constructor_args[0].strip()))
+
+ if (not is_marked_explicit and
+ onearg_constructor and
+ not initializer_list_constructor and
+ not copy_constructor):
+ if defaulted_args:
+ error(filename, linenum, 'runtime/explicit', 5,
+ 'Constructors callable with one argument '
+ 'should be marked explicit.')
+ else:
+ error(filename, linenum, 'runtime/explicit', 5,
+ 'Single-parameter constructors should be marked explicit.')
+ elif is_marked_explicit and not onearg_constructor:
+ if noarg_constructor:
+ error(filename, linenum, 'runtime/explicit', 5,
+ 'Zero-parameter constructors should not be marked explicit.')
+
+
+def CheckSpacingForFunctionCall(filename, clean_lines, linenum, error):
+ """Checks for the correctness of various spacing around function calls.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ line = clean_lines.elided[linenum]
+
+ # Since function calls often occur inside if/for/while/switch
+ # expressions - which have their own, more liberal conventions - we
+ # first see if we should be looking inside such an expression for a
+ # function call, to which we can apply more strict standards.
+ fncall = line # if there's no control flow construct, look at whole line
+ for pattern in (r'\bif\s*\((.*)\)\s*{',
+ r'\bfor\s*\((.*)\)\s*{',
+ r'\bwhile\s*\((.*)\)\s*[{;]',
+ r'\bswitch\s*\((.*)\)\s*{'):
+ match = Search(pattern, line)
+ if match:
+ fncall = match.group(1) # look inside the parens for function calls
+ break
+
+ # Except in if/for/while/switch, there should never be space
+ # immediately inside parens (eg "f( 3, 4 )"). We make an exception
+ # for nested parens ( (a+b) + c ). Likewise, there should never be
+ # a space before a ( when it's a function argument. I assume it's a
+ # function argument when the char before the whitespace is legal in
+ # a function name (alnum + _) and we're not starting a macro. Also ignore
+ # pointers and references to arrays and functions coz they're too tricky:
+ # we use a very simple way to recognize these:
+ # " (something)(maybe-something)" or
+ # " (something)(maybe-something," or
+ # " (something)[something]"
+ # Note that we assume the contents of [] to be short enough that
+ # they'll never need to wrap.
+ if ( # Ignore control structures.
+ not Search(r'\b(if|for|while|switch|return|new|delete|catch|sizeof)\b',
+ fncall) and
+ # Ignore pointers/references to functions.
+ not Search(r' \([^)]+\)\([^)]*(\)|,$)', fncall) and
+ # Ignore pointers/references to arrays.
+ not Search(r' \([^)]+\)\[[^\]]+\]', fncall)):
+ if Search(r'\w\s*\(\s(?!\s*\\$)', fncall): # a ( used for a fn call
+ error(filename, linenum, 'whitespace/parens', 4,
+ 'Extra space after ( in function call')
+ elif Search(r'\(\s+(?!(\s*\\)|\()', fncall):
+ error(filename, linenum, 'whitespace/parens', 2,
+ 'Extra space after (')
+ if (Search(r'\w\s+\(', fncall) and
+ not Search(r'_{0,2}asm_{0,2}\s+_{0,2}volatile_{0,2}\s+\(', fncall) and
+ not Search(r'#\s*define|typedef|using\s+\w+\s*=', fncall) and
+ not Search(r'\w\s+\((\w+::)*\*\w+\)\(', fncall) and
+ not Search(r'\bcase\s+\(', fncall)):
+ # TODO(unknown): Space after an operator function seem to be a common
+ # error, silence those for now by restricting them to highest verbosity.
+ if Search(r'\boperator_*\b', line):
+ error(filename, linenum, 'whitespace/parens', 0,
+ 'Extra space before ( in function call')
+ else:
+ error(filename, linenum, 'whitespace/parens', 4,
+ 'Extra space before ( in function call')
+ # If the ) is followed only by a newline or a { + newline, assume it's
+ # part of a control statement (if/while/etc), and don't complain
+ if Search(r'[^)]\s+\)\s*[^{\s]', fncall):
+ # If the closing parenthesis is preceded by only whitespaces,
+ # try to give a more descriptive error message.
+ if Search(r'^\s+\)', fncall):
+ error(filename, linenum, 'whitespace/parens', 2,
+ 'Closing ) should be moved to the previous line')
+ else:
+ error(filename, linenum, 'whitespace/parens', 2,
+ 'Extra space before )')
+
+
+def IsBlankLine(line):
+ """Returns true if the given line is blank.
+
+ We consider a line to be blank if the line is empty or consists of
+ only white spaces.
+
+ Args:
+ line: A line of a string.
+
+ Returns:
+ True, if the given line is blank.
+ """
+ return not line or line.isspace()
+
+
+def CheckForNamespaceIndentation(filename, nesting_state, clean_lines, line,
+ error):
+ is_namespace_indent_item = (
+ len(nesting_state.stack) > 1 and
+ nesting_state.stack[-1].check_namespace_indentation and
+ isinstance(nesting_state.previous_stack_top, _NamespaceInfo) and
+ nesting_state.previous_stack_top == nesting_state.stack[-2])
+
+ if ShouldCheckNamespaceIndentation(nesting_state, is_namespace_indent_item,
+ clean_lines.elided, line):
+ CheckItemIndentationInNamespace(filename, clean_lines.elided,
+ line, error)
+
+
+def CheckForFunctionLengths(filename, clean_lines, linenum,
+ function_state, error):
+ """Reports for long function bodies.
+
+ For an overview why this is done, see:
+ https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Write_Short_Functions
+
+ Uses a simplistic algorithm assuming other style guidelines
+ (especially spacing) are followed.
+ Only checks unindented functions, so class members are unchecked.
+ Trivial bodies are unchecked, so constructors with huge initializer lists
+ may be missed.
+ Blank/comment lines are not counted so as to avoid encouraging the removal
+ of vertical space and comments just to get through a lint check.
+ NOLINT *on the last line of a function* disables this check.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ function_state: Current function name and lines in body so far.
+ error: The function to call with any errors found.
+ """
+ lines = clean_lines.lines
+ line = lines[linenum]
+ joined_line = ''
+
+ starting_func = False
+ regexp = r'(\w(\w|::|\*|\&|\s)*)\(' # decls * & space::name( ...
+ match_result = Match(regexp, line)
+ if match_result:
+ # If the name is all caps and underscores, figure it's a macro and
+ # ignore it, unless it's TEST or TEST_F.
+ function_name = match_result.group(1).split()[-1]
+ if function_name == 'TEST' or function_name == 'TEST_F' or (
+ not Match(r'[A-Z_]+$', function_name)):
+ starting_func = True
+
+ if starting_func:
+ body_found = False
+ for start_linenum in xrange(linenum, clean_lines.NumLines()):
+ start_line = lines[start_linenum]
+ joined_line += ' ' + start_line.lstrip()
+ if Search(r'(;|})', start_line): # Declarations and trivial functions
+ body_found = True
+ break # ... ignore
+ elif Search(r'{', start_line):
+ body_found = True
+ function = Search(r'((\w|:)*)\(', line).group(1)
+ if Match(r'TEST', function): # Handle TEST... macros
+ parameter_regexp = Search(r'(\(.*\))', joined_line)
+ if parameter_regexp: # Ignore bad syntax
+ function += parameter_regexp.group(1)
+ else:
+ function += '()'
+ function_state.Begin(function)
+ break
+ if not body_found:
+ # No body for the function (or evidence of a non-function) was found.
+ error(filename, linenum, 'readability/fn_size', 5,
+ 'Lint failed to find start of function body.')
+ elif Match(r'^\}\s*$', line): # function end
+ function_state.Check(error, filename, linenum)
+ function_state.End()
+ elif not Match(r'^\s*$', line):
+ function_state.Count() # Count non-blank/non-comment lines.
+
+
+_RE_PATTERN_TODO = re.compile(r'^//(\s*)TODO(\(.+?\))?:?(\s|$)?')
+
+
+def CheckComment(line, filename, linenum, next_line_start, error):
+ """Checks for common mistakes in comments.
+
+ Args:
+ line: The line in question.
+ filename: The name of the current file.
+ linenum: The number of the line to check.
+ next_line_start: The first non-whitespace column of the next line.
+ error: The function to call with any errors found.
+ """
+ commentpos = line.find('//')
+ if commentpos != -1:
+ # Check if the // may be in quotes. If so, ignore it
+ if re.sub(r'\\.', '', line[0:commentpos]).count('"') % 2 == 0:
+ # Allow one space for new scopes, two spaces otherwise:
+ if (not (Match(r'^.*{ *//', line) and next_line_start == commentpos) and
+ ((commentpos >= 1 and
+ line[commentpos-1] not in string.whitespace) or
+ (commentpos >= 2 and
+ line[commentpos-2] not in string.whitespace))):
+ error(filename, linenum, 'whitespace/comments', 2,
+ 'At least two spaces is best between code and comments')
+
+ # Checks for common mistakes in TODO comments.
+ comment = line[commentpos:]
+ match = _RE_PATTERN_TODO.match(comment)
+ if match:
+ # One whitespace is correct; zero whitespace is handled elsewhere.
+ leading_whitespace = match.group(1)
+ if len(leading_whitespace) > 1:
+ error(filename, linenum, 'whitespace/todo', 2,
+ 'Too many spaces before TODO')
+
+ username = match.group(2)
+ if not username:
+ error(filename, linenum, 'readability/todo', 2,
+ 'Missing username in TODO; it should look like '
+ '"// TODO(my_username): Stuff."')
+
+ middle_whitespace = match.group(3)
+ # Comparisons made explicit for correctness -- pylint: disable=g-explicit-bool-comparison
+ if middle_whitespace != ' ' and middle_whitespace != '':
+ error(filename, linenum, 'whitespace/todo', 2,
+ 'TODO(my_username) should be followed by a space')
+
+ # If the comment contains an alphanumeric character, there
+ # should be a space somewhere between it and the // unless
+ # it's a /// or //! Doxygen comment.
+ if (Match(r'//[^ ]*\w', comment) and
+ not Match(r'(///|//\!)(\s+|$)', comment)):
+ error(filename, linenum, 'whitespace/comments', 4,
+ 'Should have a space between // and comment')
+
+
+def CheckSpacing(filename, clean_lines, linenum, nesting_state, error):
+ """Checks for the correctness of various spacing issues in the code.
+
+ Things we check for: spaces around operators, spaces after
+ if/for/while/switch, no spaces around parens in function calls, two
+ spaces between code and comment, don't start a block with a blank
+ line, don't end a function with a blank line, don't add a blank line
+ after public/protected/private, don't have too many blank lines in a row.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ nesting_state: A NestingState instance which maintains information about
+ the current stack of nested blocks being parsed.
+ error: The function to call with any errors found.
+ """
+
+ # Don't use "elided" lines here, otherwise we can't check commented lines.
+ # Don't want to use "raw" either, because we don't want to check inside C++11
+ # raw strings,
+ raw = clean_lines.lines_without_raw_strings
+ line = raw[linenum]
+
+ # Before nixing comments, check if the line is blank for no good
+ # reason. This includes the first line after a block is opened, and
+ # blank lines at the end of a function (ie, right before a line like '}'
+ #
+ # Skip all the blank line checks if we are immediately inside a
+ # namespace body. In other words, don't issue blank line warnings
+ # for this block:
+ # namespace {
+ #
+ # }
+ #
+ # A warning about missing end of namespace comments will be issued instead.
+ #
+ # Also skip blank line checks for 'extern "C"' blocks, which are formatted
+ # like namespaces.
+ if (IsBlankLine(line) and
+ not nesting_state.InNamespaceBody() and
+ not nesting_state.InExternC()):
+ elided = clean_lines.elided
+ prev_line = elided[linenum - 1]
+ prevbrace = prev_line.rfind('{')
+ # TODO(unknown): Don't complain if line before blank line, and line after,
+ # both start with alnums and are indented the same amount.
+ # This ignores whitespace at the start of a namespace block
+ # because those are not usually indented.
+ if prevbrace != -1 and prev_line[prevbrace:].find('}') == -1:
+ # OK, we have a blank line at the start of a code block. Before we
+ # complain, we check if it is an exception to the rule: The previous
+ # non-empty line has the parameters of a function header that are indented
+ # 4 spaces (because they did not fit in a 80 column line when placed on
+ # the same line as the function name). We also check for the case where
+ # the previous line is indented 6 spaces, which may happen when the
+ # initializers of a constructor do not fit into a 80 column line.
+ exception = False
+ if Match(r' {6}\w', prev_line): # Initializer list?
+ # We are looking for the opening column of initializer list, which
+ # should be indented 4 spaces to cause 6 space indentation afterwards.
+ search_position = linenum-2
+ while (search_position >= 0
+ and Match(r' {6}\w', elided[search_position])):
+ search_position -= 1
+ exception = (search_position >= 0
+ and elided[search_position][:5] == ' :')
+ else:
+ # Search for the function arguments or an initializer list. We use a
+ # simple heuristic here: If the line is indented 4 spaces; and we have a
+ # closing paren, without the opening paren, followed by an opening brace
+ # or colon (for initializer lists) we assume that it is the last line of
+ # a function header. If we have a colon indented 4 spaces, it is an
+ # initializer list.
+ exception = (Match(r' {4}\w[^\(]*\)\s*(const\s*)?(\{\s*$|:)',
+ prev_line)
+ or Match(r' {4}:', prev_line))
+
+ if not exception:
+ error(filename, linenum, 'whitespace/blank_line', 2,
+ 'Redundant blank line at the start of a code block '
+ 'should be deleted.')
+ # Ignore blank lines at the end of a block in a long if-else
+ # chain, like this:
+ # if (condition1) {
+ # // Something followed by a blank line
+ #
+ # } else if (condition2) {
+ # // Something else
+ # }
+ if linenum + 1 < clean_lines.NumLines():
+ next_line = raw[linenum + 1]
+ if (next_line
+ and Match(r'\s*}', next_line)
+ and next_line.find('} else ') == -1):
+ error(filename, linenum, 'whitespace/blank_line', 3,
+ 'Redundant blank line at the end of a code block '
+ 'should be deleted.')
+
+ matched = Match(r'\s*(public|protected|private):', prev_line)
+ if matched:
+ error(filename, linenum, 'whitespace/blank_line', 3,
+ 'Do not leave a blank line after "%s:"' % matched.group(1))
+
+ # Next, check comments
+ next_line_start = 0
+ if linenum + 1 < clean_lines.NumLines():
+ next_line = raw[linenum + 1]
+ next_line_start = len(next_line) - len(next_line.lstrip())
+ CheckComment(line, filename, linenum, next_line_start, error)
+
+ # get rid of comments and strings
+ line = clean_lines.elided[linenum]
+
+ # You shouldn't have spaces before your brackets, except maybe after
+ # 'delete []' or 'return []() {};'
+ if Search(r'\w\s+\[', line) and not Search(r'(?:delete|return)\s+\[', line):
+ error(filename, linenum, 'whitespace/braces', 5,
+ 'Extra space before [')
+
+ # In range-based for, we wanted spaces before and after the colon, but
+ # not around "::" tokens that might appear.
+ if (Search(r'for *\(.*[^:]:[^: ]', line) or
+ Search(r'for *\(.*[^: ]:[^:]', line)):
+ error(filename, linenum, 'whitespace/forcolon', 2,
+ 'Missing space around colon in range-based for loop')
+
+
+def CheckOperatorSpacing(filename, clean_lines, linenum, error):
+ """Checks for horizontal spacing around operators.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ line = clean_lines.elided[linenum]
+
+ # Don't try to do spacing checks for operator methods. Do this by
+ # replacing the troublesome characters with something else,
+ # preserving column position for all other characters.
+ #
+ # The replacement is done repeatedly to avoid false positives from
+ # operators that call operators.
+ while True:
+ match = Match(r'^(.*\boperator\b)(\S+)(\s*\(.*)$', line)
+ if match:
+ line = match.group(1) + ('_' * len(match.group(2))) + match.group(3)
+ else:
+ break
+
+ # We allow no-spaces around = within an if: "if ( (a=Foo()) == 0 )".
+ # Otherwise not. Note we only check for non-spaces on *both* sides;
+ # sometimes people put non-spaces on one side when aligning ='s among
+ # many lines (not that this is behavior that I approve of...)
+ if ((Search(r'[\w.]=', line) or
+ Search(r'=[\w.]', line))
+ and not Search(r'\b(if|while|for) ', line)
+ # Operators taken from [lex.operators] in C++11 standard.
+ and not Search(r'(>=|<=|==|!=|&=|\^=|\|=|\+=|\*=|\/=|\%=)', line)
+ and not Search(r'operator=', line)):
+ error(filename, linenum, 'whitespace/operators', 4,
+ 'Missing spaces around =')
+
+ # It's ok not to have spaces around binary operators like + - * /, but if
+ # there's too little whitespace, we get concerned. It's hard to tell,
+ # though, so we punt on this one for now. TODO.
+
+ # You should always have whitespace around binary operators.
+ #
+ # Check <= and >= first to avoid false positives with < and >, then
+ # check non-include lines for spacing around < and >.
+ #
+ # If the operator is followed by a comma, assume it's be used in a
+ # macro context and don't do any checks. This avoids false
+ # positives.
+ #
+ # Note that && is not included here. This is because there are too
+ # many false positives due to RValue references.
+ match = Search(r'[^<>=!\s](==|!=|<=|>=|\|\|)[^<>=!\s,;\)]', line)
+ if match:
+ error(filename, linenum, 'whitespace/operators', 3,
+ 'Missing spaces around %s' % match.group(1))
+ elif not Match(r'#.*include', line):
+ # Look for < that is not surrounded by spaces. This is only
+ # triggered if both sides are missing spaces, even though
+ # technically should should flag if at least one side is missing a
+ # space. This is done to avoid some false positives with shifts.
+ match = Match(r'^(.*[^\s<])<[^\s=<,]', line)
+ if match:
+ (_, _, end_pos) = CloseExpression(
+ clean_lines, linenum, len(match.group(1)))
+ if end_pos <= -1:
+ error(filename, linenum, 'whitespace/operators', 3,
+ 'Missing spaces around <')
+
+ # Look for > that is not surrounded by spaces. Similar to the
+ # above, we only trigger if both sides are missing spaces to avoid
+ # false positives with shifts.
+ match = Match(r'^(.*[^-\s>])>[^\s=>,]', line)
+ if match:
+ (_, _, start_pos) = ReverseCloseExpression(
+ clean_lines, linenum, len(match.group(1)))
+ if start_pos <= -1:
+ error(filename, linenum, 'whitespace/operators', 3,
+ 'Missing spaces around >')
+
+ # We allow no-spaces around << when used like this: 10<<20, but
+ # not otherwise (particularly, not when used as streams)
+ #
+ # We also allow operators following an opening parenthesis, since
+ # those tend to be macros that deal with operators.
+ match = Search(r'(operator|[^\s(<])(?:L|UL|LL|ULL|l|ul|ll|ull)?<<([^\s,=<])', line)
+ if (match and not (match.group(1).isdigit() and match.group(2).isdigit()) and
+ not (match.group(1) == 'operator' and match.group(2) == ';')):
+ error(filename, linenum, 'whitespace/operators', 3,
+ 'Missing spaces around <<')
+
+ # We allow no-spaces around >> for almost anything. This is because
+ # C++11 allows ">>" to close nested templates, which accounts for
+ # most cases when ">>" is not followed by a space.
+ #
+ # We still warn on ">>" followed by alpha character, because that is
+ # likely due to ">>" being used for right shifts, e.g.:
+ # value >> alpha
+ #
+ # When ">>" is used to close templates, the alphanumeric letter that
+ # follows would be part of an identifier, and there should still be
+ # a space separating the template type and the identifier.
+ # type<type<type>> alpha
+ match = Search(r'>>[a-zA-Z_]', line)
+ if match:
+ error(filename, linenum, 'whitespace/operators', 3,
+ 'Missing spaces around >>')
+
+ # There shouldn't be space around unary operators
+ match = Search(r'(!\s|~\s|[\s]--[\s;]|[\s]\+\+[\s;])', line)
+ if match:
+ error(filename, linenum, 'whitespace/operators', 4,
+ 'Extra space for operator %s' % match.group(1))
+
+
+def CheckParenthesisSpacing(filename, clean_lines, linenum, error):
+ """Checks for horizontal spacing around parentheses.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ line = clean_lines.elided[linenum]
+
+ # No spaces after an if, while, switch, or for
+ match = Search(r' (if\(|for\(|while\(|switch\()', line)
+ if match:
+ error(filename, linenum, 'whitespace/parens', 5,
+ 'Missing space before ( in %s' % match.group(1))
+
+ # For if/for/while/switch, the left and right parens should be
+ # consistent about how many spaces are inside the parens, and
+ # there should either be zero or one spaces inside the parens.
+ # We don't want: "if ( foo)" or "if ( foo )".
+ # Exception: "for ( ; foo; bar)" and "for (foo; bar; )" are allowed.
+ match = Search(r'\b(if|for|while|switch)\s*'
+ r'\(([ ]*)(.).*[^ ]+([ ]*)\)\s*{\s*$',
+ line)
+ if match:
+ if len(match.group(2)) != len(match.group(4)):
+ if not (match.group(3) == ';' and
+ len(match.group(2)) == 1 + len(match.group(4)) or
+ not match.group(2) and Search(r'\bfor\s*\(.*; \)', line)):
+ error(filename, linenum, 'whitespace/parens', 5,
+ 'Mismatching spaces inside () in %s' % match.group(1))
+ if len(match.group(2)) not in [0, 1]:
+ error(filename, linenum, 'whitespace/parens', 5,
+ 'Should have zero or one spaces inside ( and ) in %s' %
+ match.group(1))
+
+
+def CheckCommaSpacing(filename, clean_lines, linenum, error):
+ """Checks for horizontal spacing near commas and semicolons.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ raw = clean_lines.lines_without_raw_strings
+ line = clean_lines.elided[linenum]
+
+ # You should always have a space after a comma (either as fn arg or operator)
+ #
+ # This does not apply when the non-space character following the
+ # comma is another comma, since the only time when that happens is
+ # for empty macro arguments.
+ #
+ # We run this check in two passes: first pass on elided lines to
+ # verify that lines contain missing whitespaces, second pass on raw
+ # lines to confirm that those missing whitespaces are not due to
+ # elided comments.
+ if (Search(r',[^,\s]', ReplaceAll(r'\boperator\s*,\s*\(', 'F(', line)) and
+ Search(r',[^,\s]', raw[linenum])):
+ error(filename, linenum, 'whitespace/comma', 3,
+ 'Missing space after ,')
+
+ # You should always have a space after a semicolon
+ # except for few corner cases
+ # TODO(unknown): clarify if 'if (1) { return 1;}' is requires one more
+ # space after ;
+ if Search(r';[^\s};\\)/]', line):
+ error(filename, linenum, 'whitespace/semicolon', 3,
+ 'Missing space after ;')
+
+
+def _IsType(clean_lines, nesting_state, expr):
+ """Check if expression looks like a type name, returns true if so.
+
+ Args:
+ clean_lines: A CleansedLines instance containing the file.
+ nesting_state: A NestingState instance which maintains information about
+ the current stack of nested blocks being parsed.
+ expr: The expression to check.
+ Returns:
+ True, if token looks like a type.
+ """
+ # Keep only the last token in the expression
+ last_word = Match(r'^.*(\b\S+)$', expr)
+ if last_word:
+ token = last_word.group(1)
+ else:
+ token = expr
+
+ # Match native types and stdint types
+ if _TYPES.match(token):
+ return True
+
+ # Try a bit harder to match templated types. Walk up the nesting
+ # stack until we find something that resembles a typename
+ # declaration for what we are looking for.
+ typename_pattern = (r'\b(?:typename|class|struct)\s+' + re.escape(token) +
+ r'\b')
+ block_index = len(nesting_state.stack) - 1
+ while block_index >= 0:
+ if isinstance(nesting_state.stack[block_index], _NamespaceInfo):
+ return False
+
+ # Found where the opening brace is. We want to scan from this
+ # line up to the beginning of the function, minus a few lines.
+ # template <typename Type1, // stop scanning here
+ # ...>
+ # class C
+ # : public ... { // start scanning here
+ last_line = nesting_state.stack[block_index].starting_linenum
+
+ next_block_start = 0
+ if block_index > 0:
+ next_block_start = nesting_state.stack[block_index - 1].starting_linenum
+ first_line = last_line
+ while first_line >= next_block_start:
+ if clean_lines.elided[first_line].find('template') >= 0:
+ break
+ first_line -= 1
+ if first_line < next_block_start:
+ # Didn't find any "template" keyword before reaching the next block,
+ # there are probably no template things to check for this block
+ block_index -= 1
+ continue
+
+ # Look for typename in the specified range
+ for i in xrange(first_line, last_line + 1, 1):
+ if Search(typename_pattern, clean_lines.elided[i]):
+ return True
+ block_index -= 1
+
+ return False
+
+
+def CheckBracesSpacing(filename, clean_lines, linenum, nesting_state, error):
+ """Checks for horizontal spacing near commas.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ nesting_state: A NestingState instance which maintains information about
+ the current stack of nested blocks being parsed.
+ error: The function to call with any errors found.
+ """
+ line = clean_lines.elided[linenum]
+
+ # Except after an opening paren, or after another opening brace (in case of
+ # an initializer list, for instance), you should have spaces before your
+ # braces when they are delimiting blocks, classes, namespaces etc.
+ # And since you should never have braces at the beginning of a line,
+ # this is an easy test. Except that braces used for initialization don't
+ # follow the same rule; we often don't want spaces before those.
+ match = Match(r'^(.*[^ ({>]){', line)
+
+ if match:
+ # Try a bit harder to check for brace initialization. This
+ # happens in one of the following forms:
+ # Constructor() : initializer_list_{} { ... }
+ # Constructor{}.MemberFunction()
+ # Type variable{};
+ # FunctionCall(type{}, ...);
+ # LastArgument(..., type{});
+ # LOG(INFO) << type{} << " ...";
+ # map_of_type[{...}] = ...;
+ # ternary = expr ? new type{} : nullptr;
+ # OuterTemplate<InnerTemplateConstructor<Type>{}>
+ #
+ # We check for the character following the closing brace, and
+ # silence the warning if it's one of those listed above, i.e.
+ # "{.;,)<>]:".
+ #
+ # To account for nested initializer list, we allow any number of
+ # closing braces up to "{;,)<". We can't simply silence the
+ # warning on first sight of closing brace, because that would
+ # cause false negatives for things that are not initializer lists.
+ # Silence this: But not this:
+ # Outer{ if (...) {
+ # Inner{...} if (...){ // Missing space before {
+ # }; }
+ #
+ # There is a false negative with this approach if people inserted
+ # spurious semicolons, e.g. "if (cond){};", but we will catch the
+ # spurious semicolon with a separate check.
+ leading_text = match.group(1)
+ (endline, endlinenum, endpos) = CloseExpression(
+ clean_lines, linenum, len(match.group(1)))
+ trailing_text = ''
+ if endpos > -1:
+ trailing_text = endline[endpos:]
+ for offset in xrange(endlinenum + 1,
+ min(endlinenum + 3, clean_lines.NumLines() - 1)):
+ trailing_text += clean_lines.elided[offset]
+ # We also suppress warnings for `uint64_t{expression}` etc., as the style
+ # guide recommends brace initialization for integral types to avoid
+ # overflow/truncation.
+ if (not Match(r'^[\s}]*[{.;,)<>\]:]', trailing_text)
+ and not _IsType(clean_lines, nesting_state, leading_text)):
+ error(filename, linenum, 'whitespace/braces', 5,
+ 'Missing space before {')
+
+ # Make sure '} else {' has spaces.
+ if Search(r'}else', line):
+ error(filename, linenum, 'whitespace/braces', 5,
+ 'Missing space before else')
+
+ # You shouldn't have a space before a semicolon at the end of the line.
+ # There's a special case for "for" since the style guide allows space before
+ # the semicolon there.
+ if Search(r':\s*;\s*$', line):
+ error(filename, linenum, 'whitespace/semicolon', 5,
+ 'Semicolon defining empty statement. Use {} instead.')
+ elif Search(r'^\s*;\s*$', line):
+ error(filename, linenum, 'whitespace/semicolon', 5,
+ 'Line contains only semicolon. If this should be an empty statement, '
+ 'use {} instead.')
+ elif (Search(r'\s+;\s*$', line) and
+ not Search(r'\bfor\b', line)):
+ error(filename, linenum, 'whitespace/semicolon', 5,
+ 'Extra space before last semicolon. If this should be an empty '
+ 'statement, use {} instead.')
+
+
+def IsDecltype(clean_lines, linenum, column):
+ """Check if the token ending on (linenum, column) is decltype().
+
+ Args:
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: the number of the line to check.
+ column: end column of the token to check.
+ Returns:
+ True if this token is decltype() expression, False otherwise.
+ """
+ (text, _, start_col) = ReverseCloseExpression(clean_lines, linenum, column)
+ if start_col < 0:
+ return False
+ if Search(r'\bdecltype\s*$', text[0:start_col]):
+ return True
+ return False
+
+
+def CheckSectionSpacing(filename, clean_lines, class_info, linenum, error):
+ """Checks for additional blank line issues related to sections.
+
+ Currently the only thing checked here is blank line before protected/private.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ class_info: A _ClassInfo objects.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ # Skip checks if the class is small, where small means 25 lines or less.
+ # 25 lines seems like a good cutoff since that's the usual height of
+ # terminals, and any class that can't fit in one screen can't really
+ # be considered "small".
+ #
+ # Also skip checks if we are on the first line. This accounts for
+ # classes that look like
+ # class Foo { public: ... };
+ #
+ # If we didn't find the end of the class, last_line would be zero,
+ # and the check will be skipped by the first condition.
+ if (class_info.last_line - class_info.starting_linenum <= 24 or
+ linenum <= class_info.starting_linenum):
+ return
+
+ matched = Match(r'\s*(public|protected|private):', clean_lines.lines[linenum])
+ if matched:
+ # Issue warning if the line before public/protected/private was
+ # not a blank line, but don't do this if the previous line contains
+ # "class" or "struct". This can happen two ways:
+ # - We are at the beginning of the class.
+ # - We are forward-declaring an inner class that is semantically
+ # private, but needed to be public for implementation reasons.
+ # Also ignores cases where the previous line ends with a backslash as can be
+ # common when defining classes in C macros.
+ prev_line = clean_lines.lines[linenum - 1]
+ if (not IsBlankLine(prev_line) and
+ not Search(r'\b(class|struct)\b', prev_line) and
+ not Search(r'\\$', prev_line)):
+ # Try a bit harder to find the beginning of the class. This is to
+ # account for multi-line base-specifier lists, e.g.:
+ # class Derived
+ # : public Base {
+ end_class_head = class_info.starting_linenum
+ for i in range(class_info.starting_linenum, linenum):
+ if Search(r'\{\s*$', clean_lines.lines[i]):
+ end_class_head = i
+ break
+ if end_class_head < linenum - 1:
+ error(filename, linenum, 'whitespace/blank_line', 3,
+ '"%s:" should be preceded by a blank line' % matched.group(1))
+
+
+def GetPreviousNonBlankLine(clean_lines, linenum):
+ """Return the most recent non-blank line and its line number.
+
+ Args:
+ clean_lines: A CleansedLines instance containing the file contents.
+ linenum: The number of the line to check.
+
+ Returns:
+ A tuple with two elements. The first element is the contents of the last
+ non-blank line before the current line, or the empty string if this is the
+ first non-blank line. The second is the line number of that line, or -1
+ if this is the first non-blank line.
+ """
+
+ prevlinenum = linenum - 1
+ while prevlinenum >= 0:
+ prevline = clean_lines.elided[prevlinenum]
+ if not IsBlankLine(prevline): # if not a blank line...
+ return (prevline, prevlinenum)
+ prevlinenum -= 1
+ return ('', -1)
+
+
+def CheckBraces(filename, clean_lines, linenum, error):
+ """Looks for misplaced braces (e.g. at the end of line).
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+
+ line = clean_lines.elided[linenum] # get rid of comments and strings
+
+ if Match(r'\s*{\s*$', line):
+ # We allow an open brace to start a line in the case where someone is using
+ # braces in a block to explicitly create a new scope, which is commonly used
+ # to control the lifetime of stack-allocated variables. Braces are also
+ # used for brace initializers inside function calls. We don't detect this
+ # perfectly: we just don't complain if the last non-whitespace character on
+ # the previous non-blank line is ',', ';', ':', '(', '{', or '}', or if the
+ # previous line starts a preprocessor block. We also allow a brace on the
+ # following line if it is part of an array initialization and would not fit
+ # within the 80 character limit of the preceding line.
+ prevline = GetPreviousNonBlankLine(clean_lines, linenum)[0]
+ if (not Search(r'[,;:}{(]\s*$', prevline) and
+ not Match(r'\s*#', prevline) and
+ not (GetLineWidth(prevline) > _line_length - 2 and '[]' in prevline)):
+ error(filename, linenum, 'whitespace/braces', 4,
+ '{ should almost always be at the end of the previous line')
+
+ # An else clause should be on the same line as the preceding closing brace.
+ if Match(r'\s*else\b\s*(?:if\b|\{|$)', line):
+ prevline = GetPreviousNonBlankLine(clean_lines, linenum)[0]
+ if Match(r'\s*}\s*$', prevline):
+ error(filename, linenum, 'whitespace/newline', 4,
+ 'An else should appear on the same line as the preceding }')
+
+ # If braces come on one side of an else, they should be on both.
+ # However, we have to worry about "else if" that spans multiple lines!
+ if Search(r'else if\s*\(', line): # could be multi-line if
+ brace_on_left = bool(Search(r'}\s*else if\s*\(', line))
+ # find the ( after the if
+ pos = line.find('else if')
+ pos = line.find('(', pos)
+ if pos > 0:
+ (endline, _, endpos) = CloseExpression(clean_lines, linenum, pos)
+ brace_on_right = endline[endpos:].find('{') != -1
+ if brace_on_left != brace_on_right: # must be brace after if
+ error(filename, linenum, 'readability/braces', 5,
+ 'If an else has a brace on one side, it should have it on both')
+ elif Search(r'}\s*else[^{]*$', line) or Match(r'[^}]*else\s*{', line):
+ error(filename, linenum, 'readability/braces', 5,
+ 'If an else has a brace on one side, it should have it on both')
+
+ # Likewise, an else should never have the else clause on the same line
+ if Search(r'\belse [^\s{]', line) and not Search(r'\belse if\b', line):
+ error(filename, linenum, 'whitespace/newline', 4,
+ 'Else clause should never be on same line as else (use 2 lines)')
+
+ # In the same way, a do/while should never be on one line
+ if Match(r'\s*do [^\s{]', line):
+ error(filename, linenum, 'whitespace/newline', 4,
+ 'do/while clauses should not be on a single line')
+
+ # Check single-line if/else bodies. The style guide says 'curly braces are not
+ # required for single-line statements'. We additionally allow multi-line,
+ # single statements, but we reject anything with more than one semicolon in
+ # it. This means that the first semicolon after the if should be at the end of
+ # its line, and the line after that should have an indent level equal to or
+ # lower than the if. We also check for ambiguous if/else nesting without
+ # braces.
+ if_else_match = Search(r'\b(if\s*\(|else\b)', line)
+ if if_else_match and not Match(r'\s*#', line):
+ if_indent = GetIndentLevel(line)
+ endline, endlinenum, endpos = line, linenum, if_else_match.end()
+ if_match = Search(r'\bif\s*\(', line)
+ if if_match:
+ # This could be a multiline if condition, so find the end first.
+ pos = if_match.end() - 1
+ (endline, endlinenum, endpos) = CloseExpression(clean_lines, linenum, pos)
+ # Check for an opening brace, either directly after the if or on the next
+ # line. If found, this isn't a single-statement conditional.
+ if (not Match(r'\s*{', endline[endpos:])
+ and not (Match(r'\s*$', endline[endpos:])
+ and endlinenum < (len(clean_lines.elided) - 1)
+ and Match(r'\s*{', clean_lines.elided[endlinenum + 1]))):
+ while (endlinenum < len(clean_lines.elided)
+ and ';' not in clean_lines.elided[endlinenum][endpos:]):
+ endlinenum += 1
+ endpos = 0
+ if endlinenum < len(clean_lines.elided):
+ endline = clean_lines.elided[endlinenum]
+ # We allow a mix of whitespace and closing braces (e.g. for one-liner
+ # methods) and a single \ after the semicolon (for macros)
+ endpos = endline.find(';')
+ if not Match(r';[\s}]*(\\?)$', endline[endpos:]):
+ # Semicolon isn't the last character, there's something trailing.
+ # Output a warning if the semicolon is not contained inside
+ # a lambda expression.
+ if not Match(r'^[^{};]*\[[^\[\]]*\][^{}]*\{[^{}]*\}\s*\)*[;,]\s*$',
+ endline):
+ error(filename, linenum, 'readability/braces', 4,
+ 'If/else bodies with multiple statements require braces')
+ elif endlinenum < len(clean_lines.elided) - 1:
+ # Make sure the next line is dedented
+ next_line = clean_lines.elided[endlinenum + 1]
+ next_indent = GetIndentLevel(next_line)
+ # With ambiguous nested if statements, this will error out on the
+ # if that *doesn't* match the else, regardless of whether it's the
+ # inner one or outer one.
+ if (if_match and Match(r'\s*else\b', next_line)
+ and next_indent != if_indent):
+ error(filename, linenum, 'readability/braces', 4,
+ 'Else clause should be indented at the same level as if. '
+ 'Ambiguous nested if/else chains require braces.')
+ elif next_indent > if_indent:
+ error(filename, linenum, 'readability/braces', 4,
+ 'If/else bodies with multiple statements require braces')
+
+
+def CheckTrailingSemicolon(filename, clean_lines, linenum, error):
+ """Looks for redundant trailing semicolon.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+
+ line = clean_lines.elided[linenum]
+
+ # Block bodies should not be followed by a semicolon. Due to C++11
+ # brace initialization, there are more places where semicolons are
+ # required than not, so we use a whitelist approach to check these
+ # rather than a blacklist. These are the places where "};" should
+ # be replaced by just "}":
+ # 1. Some flavor of block following closing parenthesis:
+ # for (;;) {};
+ # while (...) {};
+ # switch (...) {};
+ # Function(...) {};
+ # if (...) {};
+ # if (...) else if (...) {};
+ #
+ # 2. else block:
+ # if (...) else {};
+ #
+ # 3. const member function:
+ # Function(...) const {};
+ #
+ # 4. Block following some statement:
+ # x = 42;
+ # {};
+ #
+ # 5. Block at the beginning of a function:
+ # Function(...) {
+ # {};
+ # }
+ #
+ # Note that naively checking for the preceding "{" will also match
+ # braces inside multi-dimensional arrays, but this is fine since
+ # that expression will not contain semicolons.
+ #
+ # 6. Block following another block:
+ # while (true) {}
+ # {};
+ #
+ # 7. End of namespaces:
+ # namespace {};
+ #
+ # These semicolons seems far more common than other kinds of
+ # redundant semicolons, possibly due to people converting classes
+ # to namespaces. For now we do not warn for this case.
+ #
+ # Try matching case 1 first.
+ match = Match(r'^(.*\)\s*)\{', line)
+ if match:
+ # Matched closing parenthesis (case 1). Check the token before the
+ # matching opening parenthesis, and don't warn if it looks like a
+ # macro. This avoids these false positives:
+ # - macro that defines a base class
+ # - multi-line macro that defines a base class
+ # - macro that defines the whole class-head
+ #
+ # But we still issue warnings for macros that we know are safe to
+ # warn, specifically:
+ # - TEST, TEST_F, TEST_P, MATCHER, MATCHER_P
+ # - TYPED_TEST
+ # - INTERFACE_DEF
+ # - EXCLUSIVE_LOCKS_REQUIRED, SHARED_LOCKS_REQUIRED, LOCKS_EXCLUDED:
+ #
+ # We implement a whitelist of safe macros instead of a blacklist of
+ # unsafe macros, even though the latter appears less frequently in
+ # google code and would have been easier to implement. This is because
+ # the downside for getting the whitelist wrong means some extra
+ # semicolons, while the downside for getting the blacklist wrong
+ # would result in compile errors.
+ #
+ # In addition to macros, we also don't want to warn on
+ # - Compound literals
+ # - Lambdas
+ # - alignas specifier with anonymous structs
+ # - decltype
+ closing_brace_pos = match.group(1).rfind(')')
+ opening_parenthesis = ReverseCloseExpression(
+ clean_lines, linenum, closing_brace_pos)
+ if opening_parenthesis[2] > -1:
+ line_prefix = opening_parenthesis[0][0:opening_parenthesis[2]]
+ macro = Search(r'\b([A-Z_][A-Z0-9_]*)\s*$', line_prefix)
+ func = Match(r'^(.*\])\s*$', line_prefix)
+ if ((macro and
+ macro.group(1) not in (
+ 'TEST', 'TEST_F', 'MATCHER', 'MATCHER_P', 'TYPED_TEST',
+ 'EXCLUSIVE_LOCKS_REQUIRED', 'SHARED_LOCKS_REQUIRED',
+ 'LOCKS_EXCLUDED', 'INTERFACE_DEF')) or
+ (func and not Search(r'\boperator\s*\[\s*\]', func.group(1))) or
+ Search(r'\b(?:struct|union)\s+alignas\s*$', line_prefix) or
+ Search(r'\bdecltype$', line_prefix) or
+ Search(r'\s+=\s*$', line_prefix)):
+ match = None
+ if (match and
+ opening_parenthesis[1] > 1 and
+ Search(r'\]\s*$', clean_lines.elided[opening_parenthesis[1] - 1])):
+ # Multi-line lambda-expression
+ match = None
+
+ else:
+ # Try matching cases 2-3.
+ match = Match(r'^(.*(?:else|\)\s*const)\s*)\{', line)
+ if not match:
+ # Try matching cases 4-6. These are always matched on separate lines.
+ #
+ # Note that we can't simply concatenate the previous line to the
+ # current line and do a single match, otherwise we may output
+ # duplicate warnings for the blank line case:
+ # if (cond) {
+ # // blank line
+ # }
+ prevline = GetPreviousNonBlankLine(clean_lines, linenum)[0]
+ if prevline and Search(r'[;{}]\s*$', prevline):
+ match = Match(r'^(\s*)\{', line)
+
+ # Check matching closing brace
+ if match:
+ (endline, endlinenum, endpos) = CloseExpression(
+ clean_lines, linenum, len(match.group(1)))
+ if endpos > -1 and Match(r'^\s*;', endline[endpos:]):
+ # Current {} pair is eligible for semicolon check, and we have found
+ # the redundant semicolon, output warning here.
+ #
+ # Note: because we are scanning forward for opening braces, and
+ # outputting warnings for the matching closing brace, if there are
+ # nested blocks with trailing semicolons, we will get the error
+ # messages in reversed order.
+
+ # We need to check the line forward for NOLINT
+ raw_lines = clean_lines.raw_lines
+ ParseNolintSuppressions(filename, raw_lines[endlinenum-1], endlinenum-1,
+ error)
+ ParseNolintSuppressions(filename, raw_lines[endlinenum], endlinenum,
+ error)
+
+ error(filename, endlinenum, 'readability/braces', 4,
+ "You don't need a ; after a }")
+
+
+def CheckEmptyBlockBody(filename, clean_lines, linenum, error):
+ """Look for empty loop/conditional body with only a single semicolon.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+
+ # Search for loop keywords at the beginning of the line. Because only
+ # whitespaces are allowed before the keywords, this will also ignore most
+ # do-while-loops, since those lines should start with closing brace.
+ #
+ # We also check "if" blocks here, since an empty conditional block
+ # is likely an error.
+ line = clean_lines.elided[linenum]
+ matched = Match(r'\s*(for|while|if)\s*\(', line)
+ if matched:
+ # Find the end of the conditional expression.
+ (end_line, end_linenum, end_pos) = CloseExpression(
+ clean_lines, linenum, line.find('('))
+
+ # Output warning if what follows the condition expression is a semicolon.
+ # No warning for all other cases, including whitespace or newline, since we
+ # have a separate check for semicolons preceded by whitespace.
+ if end_pos >= 0 and Match(r';', end_line[end_pos:]):
+ if matched.group(1) == 'if':
+ error(filename, end_linenum, 'whitespace/empty_conditional_body', 5,
+ 'Empty conditional bodies should use {}')
+ else:
+ error(filename, end_linenum, 'whitespace/empty_loop_body', 5,
+ 'Empty loop bodies should use {} or continue')
+
+ # Check for if statements that have completely empty bodies (no comments)
+ # and no else clauses.
+ if end_pos >= 0 and matched.group(1) == 'if':
+ # Find the position of the opening { for the if statement.
+ # Return without logging an error if it has no brackets.
+ opening_linenum = end_linenum
+ opening_line_fragment = end_line[end_pos:]
+ # Loop until EOF or find anything that's not whitespace or opening {.
+ while not Search(r'^\s*\{', opening_line_fragment):
+ if Search(r'^(?!\s*$)', opening_line_fragment):
+ # Conditional has no brackets.
+ return
+ opening_linenum += 1
+ if opening_linenum == len(clean_lines.elided):
+ # Couldn't find conditional's opening { or any code before EOF.
+ return
+ opening_line_fragment = clean_lines.elided[opening_linenum]
+ # Set opening_line (opening_line_fragment may not be entire opening line).
+ opening_line = clean_lines.elided[opening_linenum]
+
+ # Find the position of the closing }.
+ opening_pos = opening_line_fragment.find('{')
+ if opening_linenum == end_linenum:
+ # We need to make opening_pos relative to the start of the entire line.
+ opening_pos += end_pos
+ (closing_line, closing_linenum, closing_pos) = CloseExpression(
+ clean_lines, opening_linenum, opening_pos)
+ if closing_pos < 0:
+ return
+
+ # Now construct the body of the conditional. This consists of the portion
+ # of the opening line after the {, all lines until the closing line,
+ # and the portion of the closing line before the }.
+ if (clean_lines.raw_lines[opening_linenum] !=
+ CleanseComments(clean_lines.raw_lines[opening_linenum])):
+ # Opening line ends with a comment, so conditional isn't empty.
+ return
+ if closing_linenum > opening_linenum:
+ # Opening line after the {. Ignore comments here since we checked above.
+ body = list(opening_line[opening_pos+1:])
+ # All lines until closing line, excluding closing line, with comments.
+ body.extend(clean_lines.raw_lines[opening_linenum+1:closing_linenum])
+ # Closing line before the }. Won't (and can't) have comments.
+ body.append(clean_lines.elided[closing_linenum][:closing_pos-1])
+ body = '\n'.join(body)
+ else:
+ # If statement has brackets and fits on a single line.
+ body = opening_line[opening_pos+1:closing_pos-1]
+
+ # Check if the body is empty
+ if not _EMPTY_CONDITIONAL_BODY_PATTERN.search(body):
+ return
+ # The body is empty. Now make sure there's not an else clause.
+ current_linenum = closing_linenum
+ current_line_fragment = closing_line[closing_pos:]
+ # Loop until EOF or find anything that's not whitespace or else clause.
+ while Search(r'^\s*$|^(?=\s*else)', current_line_fragment):
+ if Search(r'^(?=\s*else)', current_line_fragment):
+ # Found an else clause, so don't log an error.
+ return
+ current_linenum += 1
+ if current_linenum == len(clean_lines.elided):
+ break
+ current_line_fragment = clean_lines.elided[current_linenum]
+
+ # The body is empty and there's no else clause until EOF or other code.
+ error(filename, end_linenum, 'whitespace/empty_if_body', 4,
+ ('If statement had no body and no else clause'))
+
+
+def FindCheckMacro(line):
+ """Find a replaceable CHECK-like macro.
+
+ Args:
+ line: line to search on.
+ Returns:
+ (macro name, start position), or (None, -1) if no replaceable
+ macro is found.
+ """
+ for macro in _CHECK_MACROS:
+ i = line.find(macro)
+ if i >= 0:
+ # Find opening parenthesis. Do a regular expression match here
+ # to make sure that we are matching the expected CHECK macro, as
+ # opposed to some other macro that happens to contain the CHECK
+ # substring.
+ matched = Match(r'^(.*\b' + macro + r'\s*)\(', line)
+ if not matched:
+ continue
+ return (macro, len(matched.group(1)))
+ return (None, -1)
+
+
+def CheckCheck(filename, clean_lines, linenum, error):
+ """Checks the use of CHECK and EXPECT macros.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+
+ # Decide the set of replacement macros that should be suggested
+ lines = clean_lines.elided
+ (check_macro, start_pos) = FindCheckMacro(lines[linenum])
+ if not check_macro:
+ return
+
+ # Find end of the boolean expression by matching parentheses
+ (last_line, end_line, end_pos) = CloseExpression(
+ clean_lines, linenum, start_pos)
+ if end_pos < 0:
+ return
+
+ # If the check macro is followed by something other than a
+ # semicolon, assume users will log their own custom error messages
+ # and don't suggest any replacements.
+ if not Match(r'\s*;', last_line[end_pos:]):
+ return
+
+ if linenum == end_line:
+ expression = lines[linenum][start_pos + 1:end_pos - 1]
+ else:
+ expression = lines[linenum][start_pos + 1:]
+ for i in xrange(linenum + 1, end_line):
+ expression += lines[i]
+ expression += last_line[0:end_pos - 1]
+
+ # Parse expression so that we can take parentheses into account.
+ # This avoids false positives for inputs like "CHECK((a < 4) == b)",
+ # which is not replaceable by CHECK_LE.
+ lhs = ''
+ rhs = ''
+ operator = None
+ while expression:
+ matched = Match(r'^\s*(<<|<<=|>>|>>=|->\*|->|&&|\|\||'
+ r'==|!=|>=|>|<=|<|\()(.*)$', expression)
+ if matched:
+ token = matched.group(1)
+ if token == '(':
+ # Parenthesized operand
+ expression = matched.group(2)
+ (end, _) = FindEndOfExpressionInLine(expression, 0, ['('])
+ if end < 0:
+ return # Unmatched parenthesis
+ lhs += '(' + expression[0:end]
+ expression = expression[end:]
+ elif token in ('&&', '||'):
+ # Logical and/or operators. This means the expression
+ # contains more than one term, for example:
+ # CHECK(42 < a && a < b);
+ #
+ # These are not replaceable with CHECK_LE, so bail out early.
+ return
+ elif token in ('<<', '<<=', '>>', '>>=', '->*', '->'):
+ # Non-relational operator
+ lhs += token
+ expression = matched.group(2)
+ else:
+ # Relational operator
+ operator = token
+ rhs = matched.group(2)
+ break
+ else:
+ # Unparenthesized operand. Instead of appending to lhs one character
+ # at a time, we do another regular expression match to consume several
+ # characters at once if possible. Trivial benchmark shows that this
+ # is more efficient when the operands are longer than a single
+ # character, which is generally the case.
+ matched = Match(r'^([^-=!<>()&|]+)(.*)$', expression)
+ if not matched:
+ matched = Match(r'^(\s*\S)(.*)$', expression)
+ if not matched:
+ break
+ lhs += matched.group(1)
+ expression = matched.group(2)
+
+ # Only apply checks if we got all parts of the boolean expression
+ if not (lhs and operator and rhs):
+ return
+
+ # Check that rhs do not contain logical operators. We already know
+ # that lhs is fine since the loop above parses out && and ||.
+ if rhs.find('&&') > -1 or rhs.find('||') > -1:
+ return
+
+ # At least one of the operands must be a constant literal. This is
+ # to avoid suggesting replacements for unprintable things like
+ # CHECK(variable != iterator)
+ #
+ # The following pattern matches decimal, hex integers, strings, and
+ # characters (in that order).
+ lhs = lhs.strip()
+ rhs = rhs.strip()
+ match_constant = r'^([-+]?(\d+|0[xX][0-9a-fA-F]+)[lLuU]{0,3}|".*"|\'.*\')$'
+ if Match(match_constant, lhs) or Match(match_constant, rhs):
+ # Note: since we know both lhs and rhs, we can provide a more
+ # descriptive error message like:
+ # Consider using CHECK_EQ(x, 42) instead of CHECK(x == 42)
+ # Instead of:
+ # Consider using CHECK_EQ instead of CHECK(a == b)
+ #
+ # We are still keeping the less descriptive message because if lhs
+ # or rhs gets long, the error message might become unreadable.
+ error(filename, linenum, 'readability/check', 2,
+ 'Consider using %s instead of %s(a %s b)' % (
+ _CHECK_REPLACEMENT[check_macro][operator],
+ check_macro, operator))
+
+
+def CheckAltTokens(filename, clean_lines, linenum, error):
+ """Check alternative keywords being used in boolean expressions.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ line = clean_lines.elided[linenum]
+
+ # Avoid preprocessor lines
+ if Match(r'^\s*#', line):
+ return
+
+ # Last ditch effort to avoid multi-line comments. This will not help
+ # if the comment started before the current line or ended after the
+ # current line, but it catches most of the false positives. At least,
+ # it provides a way to workaround this warning for people who use
+ # multi-line comments in preprocessor macros.
+ #
+ # TODO(unknown): remove this once cpplint has better support for
+ # multi-line comments.
+ if line.find('/*') >= 0 or line.find('*/') >= 0:
+ return
+
+ for match in _ALT_TOKEN_REPLACEMENT_PATTERN.finditer(line):
+ error(filename, linenum, 'readability/alt_tokens', 2,
+ 'Use operator %s instead of %s' % (
+ _ALT_TOKEN_REPLACEMENT[match.group(1)], match.group(1)))
+
+
+def GetLineWidth(line):
+ """Determines the width of the line in column positions.
+
+ Args:
+ line: A string, which may be a Unicode string.
+
+ Returns:
+ The width of the line in column positions, accounting for Unicode
+ combining characters and wide characters.
+ """
+ if isinstance(line, unicode):
+ width = 0
+ for uc in unicodedata.normalize('NFC', line):
+ if unicodedata.east_asian_width(uc) in ('W', 'F'):
+ width += 2
+ elif not unicodedata.combining(uc):
+ width += 1
+ return width
+ else:
+ return len(line)
+
+
+def CheckStyle(filename, clean_lines, linenum, file_extension, nesting_state,
+ error):
+ """Checks rules from the 'C++ style rules' section of cppguide.html.
+
+ Most of these rules are hard to test (naming, comment style), but we
+ do what we can. In particular we check for 2-space indents, line lengths,
+ tab usage, spaces inside code, etc.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ file_extension: The extension (without the dot) of the filename.
+ nesting_state: A NestingState instance which maintains information about
+ the current stack of nested blocks being parsed.
+ error: The function to call with any errors found.
+ """
+
+ # Don't use "elided" lines here, otherwise we can't check commented lines.
+ # Don't want to use "raw" either, because we don't want to check inside C++11
+ # raw strings,
+ raw_lines = clean_lines.lines_without_raw_strings
+ line = raw_lines[linenum]
+ prev = raw_lines[linenum - 1] if linenum > 0 else ''
+
+ if line.find('\t') != -1:
+ error(filename, linenum, 'whitespace/tab', 1,
+ 'Tab found; better to use spaces')
+
+ # One or three blank spaces at the beginning of the line is weird; it's
+ # hard to reconcile that with 2-space indents.
+ # NOTE: here are the conditions rob pike used for his tests. Mine aren't
+ # as sophisticated, but it may be worth becoming so: RLENGTH==initial_spaces
+ # if(RLENGTH > 20) complain = 0;
+ # if(match($0, " +(error|private|public|protected):")) complain = 0;
+ # if(match(prev, "&& *$")) complain = 0;
+ # if(match(prev, "\\|\\| *$")) complain = 0;
+ # if(match(prev, "[\",=><] *$")) complain = 0;
+ # if(match($0, " <<")) complain = 0;
+ # if(match(prev, " +for \\(")) complain = 0;
+ # if(prevodd && match(prevprev, " +for \\(")) complain = 0;
+ scope_or_label_pattern = r'\s*\w+\s*:\s*\\?$'
+ classinfo = nesting_state.InnermostClass()
+ initial_spaces = 0
+ cleansed_line = clean_lines.elided[linenum]
+ while initial_spaces < len(line) and line[initial_spaces] == ' ':
+ initial_spaces += 1
+ # There are certain situations we allow one space, notably for
+ # section labels, and also lines containing multi-line raw strings.
+ # We also don't check for lines that look like continuation lines
+ # (of lines ending in double quotes, commas, equals, or angle brackets)
+ # because the rules for how to indent those are non-trivial.
+ if (not Search(r'[",=><] *$', prev) and
+ (initial_spaces == 1 or initial_spaces == 3) and
+ not Match(scope_or_label_pattern, cleansed_line) and
+ not (clean_lines.raw_lines[linenum] != line and
+ Match(r'^\s*""', line))):
+ error(filename, linenum, 'whitespace/indent', 3,
+ 'Weird number of spaces at line-start. '
+ 'Are you using a 2-space indent?')
+
+ if line and line[-1].isspace():
+ error(filename, linenum, 'whitespace/end_of_line', 4,
+ 'Line ends in whitespace. Consider deleting these extra spaces.')
+
+ # Check if the line is a header guard.
+ is_header_guard = False
+ if IsHeaderExtension(file_extension):
+ cppvar = GetHeaderGuardCPPVariable(filename)
+ if (line.startswith('#ifndef %s' % cppvar) or
+ line.startswith('#define %s' % cppvar) or
+ line.startswith('#endif // %s' % cppvar)):
+ is_header_guard = True
+ # #include lines and header guards can be long, since there's no clean way to
+ # split them.
+ #
+ # URLs can be long too. It's possible to split these, but it makes them
+ # harder to cut&paste.
+ #
+ # The "$Id:...$" comment may also get very long without it being the
+ # developers fault.
+ if (not line.startswith('#include') and not is_header_guard and
+ not Match(r'^\s*//.*http(s?)://\S*$', line) and
+ not Match(r'^\s*//\s*[^\s]*$', line) and
+ not Match(r'^// \$Id:.*#[0-9]+ \$$', line)):
+ line_width = GetLineWidth(line)
+ if line_width > _line_length:
+ error(filename, linenum, 'whitespace/line_length', 2,
+ 'Lines should be <= %i characters long' % _line_length)
+
+ if (cleansed_line.count(';') > 1 and
+ # for loops are allowed two ;'s (and may run over two lines).
+ cleansed_line.find('for') == -1 and
+ (GetPreviousNonBlankLine(clean_lines, linenum)[0].find('for') == -1 or
+ GetPreviousNonBlankLine(clean_lines, linenum)[0].find(';') != -1) and
+ # It's ok to have many commands in a switch case that fits in 1 line
+ not ((cleansed_line.find('case ') != -1 or
+ cleansed_line.find('default:') != -1) and
+ cleansed_line.find('break;') != -1)):
+ error(filename, linenum, 'whitespace/newline', 0,
+ 'More than one command on the same line')
+
+ # Some more style checks
+ CheckBraces(filename, clean_lines, linenum, error)
+ CheckTrailingSemicolon(filename, clean_lines, linenum, error)
+ CheckEmptyBlockBody(filename, clean_lines, linenum, error)
+ CheckSpacing(filename, clean_lines, linenum, nesting_state, error)
+ CheckOperatorSpacing(filename, clean_lines, linenum, error)
+ CheckParenthesisSpacing(filename, clean_lines, linenum, error)
+ CheckCommaSpacing(filename, clean_lines, linenum, error)
+ CheckBracesSpacing(filename, clean_lines, linenum, nesting_state, error)
+ CheckSpacingForFunctionCall(filename, clean_lines, linenum, error)
+ CheckCheck(filename, clean_lines, linenum, error)
+ CheckAltTokens(filename, clean_lines, linenum, error)
+ classinfo = nesting_state.InnermostClass()
+ if classinfo:
+ CheckSectionSpacing(filename, clean_lines, classinfo, linenum, error)
+
+
+_RE_PATTERN_INCLUDE = re.compile(r'^\s*#\s*include\s*([<"])([^>"]*)[>"].*$')
+# Matches the first component of a filename delimited by -s and _s. That is:
+# _RE_FIRST_COMPONENT.match('foo').group(0) == 'foo'
+# _RE_FIRST_COMPONENT.match('foo.cc').group(0) == 'foo'
+# _RE_FIRST_COMPONENT.match('foo-bar_baz.cc').group(0) == 'foo'
+# _RE_FIRST_COMPONENT.match('foo_bar-baz.cc').group(0) == 'foo'
+_RE_FIRST_COMPONENT = re.compile(r'^[^-_.]+')
+
+
+def _DropCommonSuffixes(filename):
+ """Drops common suffixes like _test.cc or -inl.h from filename.
+
+ For example:
+ >>> _DropCommonSuffixes('foo/foo-inl.h')
+ 'foo/foo'
+ >>> _DropCommonSuffixes('foo/bar/foo.cc')
+ 'foo/bar/foo'
+ >>> _DropCommonSuffixes('foo/foo_internal.h')
+ 'foo/foo'
+ >>> _DropCommonSuffixes('foo/foo_unusualinternal.h')
+ 'foo/foo_unusualinternal'
+
+ Args:
+ filename: The input filename.
+
+ Returns:
+ The filename with the common suffix removed.
+ """
+ for suffix in ('test.cc', 'regtest.cc', 'unittest.cc',
+ 'inl.h', 'impl.h', 'internal.h'):
+ if (filename.endswith(suffix) and len(filename) > len(suffix) and
+ filename[-len(suffix) - 1] in ('-', '_')):
+ return filename[:-len(suffix) - 1]
+ return os.path.splitext(filename)[0]
+
+
+def _ClassifyInclude(fileinfo, include, is_system):
+ """Figures out what kind of header 'include' is.
+
+ Args:
+ fileinfo: The current file cpplint is running over. A FileInfo instance.
+ include: The path to a #included file.
+ is_system: True if the #include used <> rather than "".
+
+ Returns:
+ One of the _XXX_HEADER constants.
+
+ For example:
+ >>> _ClassifyInclude(FileInfo('foo/foo.cc'), 'stdio.h', True)
+ _C_SYS_HEADER
+ >>> _ClassifyInclude(FileInfo('foo/foo.cc'), 'string', True)
+ _CPP_SYS_HEADER
+ >>> _ClassifyInclude(FileInfo('foo/foo.cc'), 'foo/foo.h', False)
+ _LIKELY_MY_HEADER
+ >>> _ClassifyInclude(FileInfo('foo/foo_unknown_extension.cc'),
+ ... 'bar/foo_other_ext.h', False)
+ _POSSIBLE_MY_HEADER
+ >>> _ClassifyInclude(FileInfo('foo/foo.cc'), 'foo/bar.h', False)
+ _OTHER_HEADER
+ """
+ # This is a list of all standard c++ header files, except
+ # those already checked for above.
+ is_cpp_h = include in _CPP_HEADERS
+
+ if is_system:
+ if is_cpp_h:
+ return _CPP_SYS_HEADER
+ else:
+ return _C_SYS_HEADER
+
+ # If the target file and the include we're checking share a
+ # basename when we drop common extensions, and the include
+ # lives in . , then it's likely to be owned by the target file.
+ target_dir, target_base = (
+ os.path.split(_DropCommonSuffixes(fileinfo.RepositoryName())))
+ include_dir, include_base = os.path.split(_DropCommonSuffixes(include))
+ if target_base == include_base and (
+ include_dir == target_dir or
+ include_dir == os.path.normpath(target_dir + '/../public')):
+ return _LIKELY_MY_HEADER
+
+ # If the target and include share some initial basename
+ # component, it's possible the target is implementing the
+ # include, so it's allowed to be first, but we'll never
+ # complain if it's not there.
+ target_first_component = _RE_FIRST_COMPONENT.match(target_base)
+ include_first_component = _RE_FIRST_COMPONENT.match(include_base)
+ if (target_first_component and include_first_component and
+ target_first_component.group(0) ==
+ include_first_component.group(0)):
+ return _POSSIBLE_MY_HEADER
+
+ return _OTHER_HEADER
+
+
+
+def CheckIncludeLine(filename, clean_lines, linenum, include_state, error):
+ """Check rules that are applicable to #include lines.
+
+ Strings on #include lines are NOT removed from elided line, to make
+ certain tasks easier. However, to prevent false positives, checks
+ applicable to #include lines in CheckLanguage must be put here.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ include_state: An _IncludeState instance in which the headers are inserted.
+ error: The function to call with any errors found.
+ """
+ fileinfo = FileInfo(filename)
+ line = clean_lines.lines[linenum]
+
+ # "include" should use the new style "foo/bar.h" instead of just "bar.h"
+ # Only do this check if the included header follows google naming
+ # conventions. If not, assume that it's a 3rd party API that
+ # requires special include conventions.
+ #
+ # We also make an exception for Lua headers, which follow google
+ # naming convention but not the include convention.
+ match = Match(r'#include\s*"([^/]+\.h)"', line)
+ if match and not _THIRD_PARTY_HEADERS_PATTERN.match(match.group(1)):
+ error(filename, linenum, 'build/include', 4,
+ 'Include the directory when naming .h files')
+
+ # we shouldn't include a file more than once. actually, there are a
+ # handful of instances where doing so is okay, but in general it's
+ # not.
+ match = _RE_PATTERN_INCLUDE.search(line)
+ if match:
+ include = match.group(2)
+ is_system = (match.group(1) == '<')
+ duplicate_line = include_state.FindHeader(include)
+ if duplicate_line >= 0:
+ error(filename, linenum, 'build/include', 4,
+ '"%s" already included at %s:%s' %
+ (include, filename, duplicate_line))
+ elif (include.endswith('.cc') and
+ os.path.dirname(fileinfo.RepositoryName()) != os.path.dirname(include)):
+ error(filename, linenum, 'build/include', 4,
+ 'Do not include .cc files from other packages')
+ elif not _THIRD_PARTY_HEADERS_PATTERN.match(include):
+ include_state.include_list[-1].append((include, linenum))
+
+ # We want to ensure that headers appear in the right order:
+ # 1) for foo.cc, foo.h (preferred location)
+ # 2) c system files
+ # 3) cpp system files
+ # 4) for foo.cc, foo.h (deprecated location)
+ # 5) other google headers
+ #
+ # We classify each include statement as one of those 5 types
+ # using a number of techniques. The include_state object keeps
+ # track of the highest type seen, and complains if we see a
+ # lower type after that.
+ error_message = include_state.CheckNextIncludeOrder(
+ _ClassifyInclude(fileinfo, include, is_system))
+ if error_message:
+ error(filename, linenum, 'build/include_order', 4,
+ '%s. Should be: %s.h, c system, c++ system, other.' %
+ (error_message, fileinfo.BaseName()))
+ canonical_include = include_state.CanonicalizeAlphabeticalOrder(include)
+ if not include_state.IsInAlphabeticalOrder(
+ clean_lines, linenum, canonical_include):
+ error(filename, linenum, 'build/include_alpha', 4,
+ 'Include "%s" not in alphabetical order' % include)
+ include_state.SetLastHeader(canonical_include)
+
+
+
+def _GetTextInside(text, start_pattern):
+ r"""Retrieves all the text between matching open and close parentheses.
+
+ Given a string of lines and a regular expression string, retrieve all the text
+ following the expression and between opening punctuation symbols like
+ (, [, or {, and the matching close-punctuation symbol. This properly nested
+ occurrences of the punctuations, so for the text like
+ printf(a(), b(c()));
+ a call to _GetTextInside(text, r'printf\(') will return 'a(), b(c())'.
+ start_pattern must match string having an open punctuation symbol at the end.
+
+ Args:
+ text: The lines to extract text. Its comments and strings must be elided.
+ It can be single line and can span multiple lines.
+ start_pattern: The regexp string indicating where to start extracting
+ the text.
+ Returns:
+ The extracted text.
+ None if either the opening string or ending punctuation could not be found.
+ """
+ # TODO(unknown): Audit cpplint.py to see what places could be profitably
+ # rewritten to use _GetTextInside (and use inferior regexp matching today).
+
+ # Give opening punctuations to get the matching close-punctuations.
+ matching_punctuation = {'(': ')', '{': '}', '[': ']'}
+ closing_punctuation = set(matching_punctuation.itervalues())
+
+ # Find the position to start extracting text.
+ match = re.search(start_pattern, text, re.M)
+ if not match: # start_pattern not found in text.
+ return None
+ start_position = match.end(0)
+
+ assert start_position > 0, (
+ 'start_pattern must ends with an opening punctuation.')
+ assert text[start_position - 1] in matching_punctuation, (
+ 'start_pattern must ends with an opening punctuation.')
+ # Stack of closing punctuations we expect to have in text after position.
+ punctuation_stack = [matching_punctuation[text[start_position - 1]]]
+ position = start_position
+ while punctuation_stack and position < len(text):
+ if text[position] == punctuation_stack[-1]:
+ punctuation_stack.pop()
+ elif text[position] in closing_punctuation:
+ # A closing punctuation without matching opening punctuations.
+ return None
+ elif text[position] in matching_punctuation:
+ punctuation_stack.append(matching_punctuation[text[position]])
+ position += 1
+ if punctuation_stack:
+ # Opening punctuations left without matching close-punctuations.
+ return None
+ # punctuations match.
+ return text[start_position:position - 1]
+
+
+# Patterns for matching call-by-reference parameters.
+#
+# Supports nested templates up to 2 levels deep using this messy pattern:
+# < (?: < (?: < [^<>]*
+# >
+# | [^<>] )*
+# >
+# | [^<>] )*
+# >
+_RE_PATTERN_IDENT = r'[_a-zA-Z]\w*' # =~ [[:alpha:]][[:alnum:]]*
+_RE_PATTERN_TYPE = (
+ r'(?:const\s+)?(?:typename\s+|class\s+|struct\s+|union\s+|enum\s+)?'
+ r'(?:\w|'
+ r'\s*<(?:<(?:<[^<>]*>|[^<>])*>|[^<>])*>|'
+ r'::)+')
+# A call-by-reference parameter ends with '& identifier'.
+_RE_PATTERN_REF_PARAM = re.compile(
+ r'(' + _RE_PATTERN_TYPE + r'(?:\s*(?:\bconst\b|[*]))*\s*'
+ r'&\s*' + _RE_PATTERN_IDENT + r')\s*(?:=[^,()]+)?[,)]')
+# A call-by-const-reference parameter either ends with 'const& identifier'
+# or looks like 'const type& identifier' when 'type' is atomic.
+_RE_PATTERN_CONST_REF_PARAM = (
+ r'(?:.*\s*\bconst\s*&\s*' + _RE_PATTERN_IDENT +
+ r'|const\s+' + _RE_PATTERN_TYPE + r'\s*&\s*' + _RE_PATTERN_IDENT + r')')
+# Stream types.
+_RE_PATTERN_REF_STREAM_PARAM = (
+ r'(?:.*stream\s*&\s*' + _RE_PATTERN_IDENT + r')')
+
+
+def CheckLanguage(filename, clean_lines, linenum, file_extension,
+ include_state, nesting_state, error):
+ """Checks rules from the 'C++ language rules' section of cppguide.html.
+
+ Some of these rules are hard to test (function overloading, using
+ uint32 inappropriately), but we do the best we can.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ file_extension: The extension (without the dot) of the filename.
+ include_state: An _IncludeState instance in which the headers are inserted.
+ nesting_state: A NestingState instance which maintains information about
+ the current stack of nested blocks being parsed.
+ error: The function to call with any errors found.
+ """
+ # If the line is empty or consists of entirely a comment, no need to
+ # check it.
+ line = clean_lines.elided[linenum]
+ if not line:
+ return
+
+ match = _RE_PATTERN_INCLUDE.search(line)
+ if match:
+ CheckIncludeLine(filename, clean_lines, linenum, include_state, error)
+ return
+
+ # Reset include state across preprocessor directives. This is meant
+ # to silence warnings for conditional includes.
+ match = Match(r'^\s*#\s*(if|ifdef|ifndef|elif|else|endif)\b', line)
+ if match:
+ include_state.ResetSection(match.group(1))
+
+ # Make Windows paths like Unix.
+ fullname = os.path.abspath(filename).replace('\\', '/')
+
+ # Perform other checks now that we are sure that this is not an include line
+ CheckCasts(filename, clean_lines, linenum, error)
+ CheckGlobalStatic(filename, clean_lines, linenum, error)
+ CheckPrintf(filename, clean_lines, linenum, error)
+
+ if IsHeaderExtension(file_extension):
+ # TODO(unknown): check that 1-arg constructors are explicit.
+ # How to tell it's a constructor?
+ # (handled in CheckForNonStandardConstructs for now)
+ # TODO(unknown): check that classes declare or disable copy/assign
+ # (level 1 error)
+ pass
+
+ # Check if people are using the verboten C basic types. The only exception
+ # we regularly allow is "unsigned short port" for port.
+ if Search(r'\bshort port\b', line):
+ if not Search(r'\bunsigned short port\b', line):
+ error(filename, linenum, 'runtime/int', 4,
+ 'Use "unsigned short" for ports, not "short"')
+ else:
+ match = Search(r'\b(short|long(?! +double)|long long)\b', line)
+ if match:
+ error(filename, linenum, 'runtime/int', 4,
+ 'Use int16/int64/etc, rather than the C type %s' % match.group(1))
+
+ # Check if some verboten operator overloading is going on
+ # TODO(unknown): catch out-of-line unary operator&:
+ # class X {};
+ # int operator&(const X& x) { return 42; } // unary operator&
+ # The trick is it's hard to tell apart from binary operator&:
+ # class Y { int operator&(const Y& x) { return 23; } }; // binary operator&
+ if Search(r'\boperator\s*&\s*\(\s*\)', line):
+ error(filename, linenum, 'runtime/operator', 4,
+ 'Unary operator& is dangerous. Do not use it.')
+
+ # Check for suspicious usage of "if" like
+ # } if (a == b) {
+ if Search(r'\}\s*if\s*\(', line):
+ error(filename, linenum, 'readability/braces', 4,
+ 'Did you mean "else if"? If not, start a new line for "if".')
+
+ # Check for potential format string bugs like printf(foo).
+ # We constrain the pattern not to pick things like DocidForPrintf(foo).
+ # Not perfect but it can catch printf(foo.c_str()) and printf(foo->c_str())
+ # TODO(unknown): Catch the following case. Need to change the calling
+ # convention of the whole function to process multiple line to handle it.
+ # printf(
+ # boy_this_is_a_really_long_variable_that_cannot_fit_on_the_prev_line);
+ printf_args = _GetTextInside(line, r'(?i)\b(string)?printf\s*\(')
+ if printf_args:
+ match = Match(r'([\w.\->()]+)$', printf_args)
+ if match and match.group(1) != '__VA_ARGS__':
+ function_name = re.search(r'\b((?:string)?printf)\s*\(',
+ line, re.I).group(1)
+ error(filename, linenum, 'runtime/printf', 4,
+ 'Potential format string bug. Do %s("%%s", %s) instead.'
+ % (function_name, match.group(1)))
+
+ # Check for potential memset bugs like memset(buf, sizeof(buf), 0).
+ match = Search(r'memset\s*\(([^,]*),\s*([^,]*),\s*0\s*\)', line)
+ if match and not Match(r"^''|-?[0-9]+|0x[0-9A-Fa-f]$", match.group(2)):
+ error(filename, linenum, 'runtime/memset', 4,
+ 'Did you mean "memset(%s, 0, %s)"?'
+ % (match.group(1), match.group(2)))
+
+ if Search(r'\busing namespace\b', line):
+ error(filename, linenum, 'build/namespaces', 5,
+ 'Do not use namespace using-directives. '
+ 'Use using-declarations instead.')
+
+ # Detect variable-length arrays.
+ match = Match(r'\s*(.+::)?(\w+) [a-z]\w*\[(.+)];', line)
+ if (match and match.group(2) != 'return' and match.group(2) != 'delete' and
+ match.group(3).find(']') == -1):
+ # Split the size using space and arithmetic operators as delimiters.
+ # If any of the resulting tokens are not compile time constants then
+ # report the error.
+ tokens = re.split(r'\s|\+|\-|\*|\/|<<|>>]', match.group(3))
+ is_const = True
+ skip_next = False
+ for tok in tokens:
+ if skip_next:
+ skip_next = False
+ continue
+
+ if Search(r'sizeof\(.+\)', tok): continue
+ if Search(r'arraysize\(\w+\)', tok): continue
+
+ tok = tok.lstrip('(')
+ tok = tok.rstrip(')')
+ if not tok: continue
+ if Match(r'\d+', tok): continue
+ if Match(r'0[xX][0-9a-fA-F]+', tok): continue
+ if Match(r'k[A-Z0-9]\w*', tok): continue
+ if Match(r'(.+::)?k[A-Z0-9]\w*', tok): continue
+ if Match(r'(.+::)?[A-Z][A-Z0-9_]*', tok): continue
+ # A catch all for tricky sizeof cases, including 'sizeof expression',
+ # 'sizeof(*type)', 'sizeof(const type)', 'sizeof(struct StructName)'
+ # requires skipping the next token because we split on ' ' and '*'.
+ if tok.startswith('sizeof'):
+ skip_next = True
+ continue
+ is_const = False
+ break
+ if not is_const:
+ error(filename, linenum, 'runtime/arrays', 1,
+ 'Do not use variable-length arrays. Use an appropriately named '
+ "('k' followed by CamelCase) compile-time constant for the size.")
+
+ # Check for use of unnamed namespaces in header files. Registration
+ # macros are typically OK, so we allow use of "namespace {" on lines
+ # that end with backslashes.
+ if (IsHeaderExtension(file_extension)
+ and Search(r'\bnamespace\s*{', line)
+ and line[-1] != '\\'):
+ error(filename, linenum, 'build/namespaces', 4,
+ 'Do not use unnamed namespaces in header files. See '
+ 'https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Namespaces'
+ ' for more information.')
+
+
+def CheckGlobalStatic(filename, clean_lines, linenum, error):
+ """Check for unsafe global or static objects.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ line = clean_lines.elided[linenum]
+
+ # Match two lines at a time to support multiline declarations
+ if linenum + 1 < clean_lines.NumLines() and not Search(r'[;({]', line):
+ line += clean_lines.elided[linenum + 1].strip()
+
+ # Check for people declaring static/global STL strings at the top level.
+ # This is dangerous because the C++ language does not guarantee that
+ # globals with constructors are initialized before the first access, and
+ # also because globals can be destroyed when some threads are still running.
+ # TODO(unknown): Generalize this to also find static unique_ptr instances.
+ # TODO(unknown): File bugs for clang-tidy to find these.
+ match = Match(
+ r'((?:|static +)(?:|const +))(?::*std::)?string( +const)? +'
+ r'([a-zA-Z0-9_:]+)\b(.*)',
+ line)
+
+ # Remove false positives:
+ # - String pointers (as opposed to values).
+ # string *pointer
+ # const string *pointer
+ # string const *pointer
+ # string *const pointer
+ #
+ # - Functions and template specializations.
+ # string Function<Type>(...
+ # string Class<Type>::Method(...
+ #
+ # - Operators. These are matched separately because operator names
+ # cross non-word boundaries, and trying to match both operators
+ # and functions at the same time would decrease accuracy of
+ # matching identifiers.
+ # string Class::operator*()
+ if (match and
+ not Search(r'\bstring\b(\s+const)?\s*[\*\&]\s*(const\s+)?\w', line) and
+ not Search(r'\boperator\W', line) and
+ not Match(r'\s*(<.*>)?(::[a-zA-Z0-9_]+)*\s*\(([^"]|$)', match.group(4))):
+ if Search(r'\bconst\b', line):
+ error(filename, linenum, 'runtime/string', 4,
+ 'For a static/global string constant, use a C style string '
+ 'instead: "%schar%s %s[]".' %
+ (match.group(1), match.group(2) or '', match.group(3)))
+ else:
+ error(filename, linenum, 'runtime/string', 4,
+ 'Static/global string variables are not permitted.')
+
+ if (Search(r'\b([A-Za-z0-9_]*_)\(\1\)', line) or
+ Search(r'\b([A-Za-z0-9_]*_)\(CHECK_NOTNULL\(\1\)\)', line)):
+ error(filename, linenum, 'runtime/init', 4,
+ 'You seem to be initializing a member variable with itself.')
+
+
+def CheckPrintf(filename, clean_lines, linenum, error):
+ """Check for printf related issues.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ line = clean_lines.elided[linenum]
+
+ # When snprintf is used, the second argument shouldn't be a literal.
+ match = Search(r'snprintf\s*\(([^,]*),\s*([0-9]*)\s*,', line)
+ if match and match.group(2) != '0':
+ # If 2nd arg is zero, snprintf is used to calculate size.
+ error(filename, linenum, 'runtime/printf', 3,
+ 'If you can, use sizeof(%s) instead of %s as the 2nd arg '
+ 'to snprintf.' % (match.group(1), match.group(2)))
+
+ # Check if some verboten C functions are being used.
+ if Search(r'\bsprintf\s*\(', line):
+ error(filename, linenum, 'runtime/printf', 5,
+ 'Never use sprintf. Use snprintf instead.')
+ match = Search(r'\b(strcpy|strcat)\s*\(', line)
+ if match:
+ error(filename, linenum, 'runtime/printf', 4,
+ 'Almost always, snprintf is better than %s' % match.group(1))
+
+
+def IsDerivedFunction(clean_lines, linenum):
+ """Check if current line contains an inherited function.
+
+ Args:
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ Returns:
+ True if current line contains a function with "override"
+ virt-specifier.
+ """
+ # Scan back a few lines for start of current function
+ for i in xrange(linenum, max(-1, linenum - 10), -1):
+ match = Match(r'^([^()]*\w+)\(', clean_lines.elided[i])
+ if match:
+ # Look for "override" after the matching closing parenthesis
+ line, _, closing_paren = CloseExpression(
+ clean_lines, i, len(match.group(1)))
+ return (closing_paren >= 0 and
+ Search(r'\boverride\b', line[closing_paren:]))
+ return False
+
+
+def IsOutOfLineMethodDefinition(clean_lines, linenum):
+ """Check if current line contains an out-of-line method definition.
+
+ Args:
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ Returns:
+ True if current line contains an out-of-line method definition.
+ """
+ # Scan back a few lines for start of current function
+ for i in xrange(linenum, max(-1, linenum - 10), -1):
+ if Match(r'^([^()]*\w+)\(', clean_lines.elided[i]):
+ return Match(r'^[^()]*\w+::\w+\(', clean_lines.elided[i]) is not None
+ return False
+
+
+def IsInitializerList(clean_lines, linenum):
+ """Check if current line is inside constructor initializer list.
+
+ Args:
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ Returns:
+ True if current line appears to be inside constructor initializer
+ list, False otherwise.
+ """
+ for i in xrange(linenum, 1, -1):
+ line = clean_lines.elided[i]
+ if i == linenum:
+ remove_function_body = Match(r'^(.*)\{\s*$', line)
+ if remove_function_body:
+ line = remove_function_body.group(1)
+
+ if Search(r'\s:\s*\w+[({]', line):
+ # A lone colon tend to indicate the start of a constructor
+ # initializer list. It could also be a ternary operator, which
+ # also tend to appear in constructor initializer lists as
+ # opposed to parameter lists.
+ return True
+ if Search(r'\}\s*,\s*$', line):
+ # A closing brace followed by a comma is probably the end of a
+ # brace-initialized member in constructor initializer list.
+ return True
+ if Search(r'[{};]\s*$', line):
+ # Found one of the following:
+ # - A closing brace or semicolon, probably the end of the previous
+ # function.
+ # - An opening brace, probably the start of current class or namespace.
+ #
+ # Current line is probably not inside an initializer list since
+ # we saw one of those things without seeing the starting colon.
+ return False
+
+ # Got to the beginning of the file without seeing the start of
+ # constructor initializer list.
+ return False
+
+
+def CheckForNonConstReference(filename, clean_lines, linenum,
+ nesting_state, error):
+ """Check for non-const references.
+
+ Separate from CheckLanguage since it scans backwards from current
+ line, instead of scanning forward.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ nesting_state: A NestingState instance which maintains information about
+ the current stack of nested blocks being parsed.
+ error: The function to call with any errors found.
+ """
+ # Do nothing if there is no '&' on current line.
+ line = clean_lines.elided[linenum]
+ if '&' not in line:
+ return
+
+ # If a function is inherited, current function doesn't have much of
+ # a choice, so any non-const references should not be blamed on
+ # derived function.
+ if IsDerivedFunction(clean_lines, linenum):
+ return
+
+ # Don't warn on out-of-line method definitions, as we would warn on the
+ # in-line declaration, if it isn't marked with 'override'.
+ if IsOutOfLineMethodDefinition(clean_lines, linenum):
+ return
+
+ # Long type names may be broken across multiple lines, usually in one
+ # of these forms:
+ # LongType
+ # ::LongTypeContinued &identifier
+ # LongType::
+ # LongTypeContinued &identifier
+ # LongType<
+ # ...>::LongTypeContinued &identifier
+ #
+ # If we detected a type split across two lines, join the previous
+ # line to current line so that we can match const references
+ # accordingly.
+ #
+ # Note that this only scans back one line, since scanning back
+ # arbitrary number of lines would be expensive. If you have a type
+ # that spans more than 2 lines, please use a typedef.
+ if linenum > 1:
+ previous = None
+ if Match(r'\s*::(?:[\w<>]|::)+\s*&\s*\S', line):
+ # previous_line\n + ::current_line
+ previous = Search(r'\b((?:const\s*)?(?:[\w<>]|::)+[\w<>])\s*$',
+ clean_lines.elided[linenum - 1])
+ elif Match(r'\s*[a-zA-Z_]([\w<>]|::)+\s*&\s*\S', line):
+ # previous_line::\n + current_line
+ previous = Search(r'\b((?:const\s*)?(?:[\w<>]|::)+::)\s*$',
+ clean_lines.elided[linenum - 1])
+ if previous:
+ line = previous.group(1) + line.lstrip()
+ else:
+ # Check for templated parameter that is split across multiple lines
+ endpos = line.rfind('>')
+ if endpos > -1:
+ (_, startline, startpos) = ReverseCloseExpression(
+ clean_lines, linenum, endpos)
+ if startpos > -1 and startline < linenum:
+ # Found the matching < on an earlier line, collect all
+ # pieces up to current line.
+ line = ''
+ for i in xrange(startline, linenum + 1):
+ line += clean_lines.elided[i].strip()
+
+ # Check for non-const references in function parameters. A single '&' may
+ # found in the following places:
+ # inside expression: binary & for bitwise AND
+ # inside expression: unary & for taking the address of something
+ # inside declarators: reference parameter
+ # We will exclude the first two cases by checking that we are not inside a
+ # function body, including one that was just introduced by a trailing '{'.
+ # TODO(unknown): Doesn't account for 'catch(Exception& e)' [rare].
+ if (nesting_state.previous_stack_top and
+ not (isinstance(nesting_state.previous_stack_top, _ClassInfo) or
+ isinstance(nesting_state.previous_stack_top, _NamespaceInfo))):
+ # Not at toplevel, not within a class, and not within a namespace
+ return
+
+ # Avoid initializer lists. We only need to scan back from the
+ # current line for something that starts with ':'.
+ #
+ # We don't need to check the current line, since the '&' would
+ # appear inside the second set of parentheses on the current line as
+ # opposed to the first set.
+ if linenum > 0:
+ for i in xrange(linenum - 1, max(0, linenum - 10), -1):
+ previous_line = clean_lines.elided[i]
+ if not Search(r'[),]\s*$', previous_line):
+ break
+ if Match(r'^\s*:\s+\S', previous_line):
+ return
+
+ # Avoid preprocessors
+ if Search(r'\\\s*$', line):
+ return
+
+ # Avoid constructor initializer lists
+ if IsInitializerList(clean_lines, linenum):
+ return
+
+ # We allow non-const references in a few standard places, like functions
+ # called "swap()" or iostream operators like "<<" or ">>". Do not check
+ # those function parameters.
+ #
+ # We also accept & in static_assert, which looks like a function but
+ # it's actually a declaration expression.
+ whitelisted_functions = (r'(?:[sS]wap(?:<\w:+>)?|'
+ r'operator\s*[<>][<>]|'
+ r'static_assert|COMPILE_ASSERT'
+ r')\s*\(')
+ if Search(whitelisted_functions, line):
+ return
+ elif not Search(r'\S+\([^)]*$', line):
+ # Don't see a whitelisted function on this line. Actually we
+ # didn't see any function name on this line, so this is likely a
+ # multi-line parameter list. Try a bit harder to catch this case.
+ for i in xrange(2):
+ if (linenum > i and
+ Search(whitelisted_functions, clean_lines.elided[linenum - i - 1])):
+ return
+
+ decls = ReplaceAll(r'{[^}]*}', ' ', line) # exclude function body
+ for parameter in re.findall(_RE_PATTERN_REF_PARAM, decls):
+ if (not Match(_RE_PATTERN_CONST_REF_PARAM, parameter) and
+ not Match(_RE_PATTERN_REF_STREAM_PARAM, parameter)):
+ error(filename, linenum, 'runtime/references', 2,
+ 'Is this a non-const reference? '
+ 'If so, make const or use a pointer: ' +
+ ReplaceAll(' *<', '<', parameter))
+
+
+def CheckCasts(filename, clean_lines, linenum, error):
+ """Various cast related checks.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ line = clean_lines.elided[linenum]
+
+ # Check to see if they're using an conversion function cast.
+ # I just try to capture the most common basic types, though there are more.
+ # Parameterless conversion functions, such as bool(), are allowed as they are
+ # probably a member operator declaration or default constructor.
+ match = Search(
+ r'(\bnew\s+(?:const\s+)?|\S<\s*(?:const\s+)?)?\b'
+ r'(int|float|double|bool|char|int32|uint32|int64|uint64)'
+ r'(\([^)].*)', line)
+ expecting_function = ExpectingFunctionArgs(clean_lines, linenum)
+ if match and not expecting_function:
+ matched_type = match.group(2)
+
+ # matched_new_or_template is used to silence two false positives:
+ # - New operators
+ # - Template arguments with function types
+ #
+ # For template arguments, we match on types immediately following
+ # an opening bracket without any spaces. This is a fast way to
+ # silence the common case where the function type is the first
+ # template argument. False negative with less-than comparison is
+ # avoided because those operators are usually followed by a space.
+ #
+ # function<double(double)> // bracket + no space = false positive
+ # value < double(42) // bracket + space = true positive
+ matched_new_or_template = match.group(1)
+
+ # Avoid arrays by looking for brackets that come after the closing
+ # parenthesis.
+ if Match(r'\([^()]+\)\s*\[', match.group(3)):
+ return
+
+ # Other things to ignore:
+ # - Function pointers
+ # - Casts to pointer types
+ # - Placement new
+ # - Alias declarations
+ matched_funcptr = match.group(3)
+ if (matched_new_or_template is None and
+ not (matched_funcptr and
+ (Match(r'\((?:[^() ]+::\s*\*\s*)?[^() ]+\)\s*\(',
+ matched_funcptr) or
+ matched_funcptr.startswith('(*)'))) and
+ not Match(r'\s*using\s+\S+\s*=\s*' + matched_type, line) and
+ not Search(r'new\(\S+\)\s*' + matched_type, line)):
+ error(filename, linenum, 'readability/casting', 4,
+ 'Using deprecated casting style. '
+ 'Use static_cast<%s>(...) instead' %
+ matched_type)
+
+ if not expecting_function:
+ CheckCStyleCast(filename, clean_lines, linenum, 'static_cast',
+ r'\((int|float|double|bool|char|u?int(16|32|64))\)', error)
+
+ # This doesn't catch all cases. Consider (const char * const)"hello".
+ #
+ # (char *) "foo" should always be a const_cast (reinterpret_cast won't
+ # compile).
+ if CheckCStyleCast(filename, clean_lines, linenum, 'const_cast',
+ r'\((char\s?\*+\s?)\)\s*"', error):
+ pass
+ else:
+ # Check pointer casts for other than string constants
+ CheckCStyleCast(filename, clean_lines, linenum, 'reinterpret_cast',
+ r'\((\w+\s?\*+\s?)\)', error)
+
+ # In addition, we look for people taking the address of a cast. This
+ # is dangerous -- casts can assign to temporaries, so the pointer doesn't
+ # point where you think.
+ #
+ # Some non-identifier character is required before the '&' for the
+ # expression to be recognized as a cast. These are casts:
+ # expression = &static_cast<int*>(temporary());
+ # function(&(int*)(temporary()));
+ #
+ # This is not a cast:
+ # reference_type&(int* function_param);
+ match = Search(
+ r'(?:[^\w]&\(([^)*][^)]*)\)[\w(])|'
+ r'(?:[^\w]&(static|dynamic|down|reinterpret)_cast\b)', line)
+ if match:
+ # Try a better error message when the & is bound to something
+ # dereferenced by the casted pointer, as opposed to the casted
+ # pointer itself.
+ parenthesis_error = False
+ match = Match(r'^(.*&(?:static|dynamic|down|reinterpret)_cast\b)<', line)
+ if match:
+ _, y1, x1 = CloseExpression(clean_lines, linenum, len(match.group(1)))
+ if x1 >= 0 and clean_lines.elided[y1][x1] == '(':
+ _, y2, x2 = CloseExpression(clean_lines, y1, x1)
+ if x2 >= 0:
+ extended_line = clean_lines.elided[y2][x2:]
+ if y2 < clean_lines.NumLines() - 1:
+ extended_line += clean_lines.elided[y2 + 1]
+ if Match(r'\s*(?:->|\[)', extended_line):
+ parenthesis_error = True
+
+ if parenthesis_error:
+ error(filename, linenum, 'readability/casting', 4,
+ ('Are you taking an address of something dereferenced '
+ 'from a cast? Wrapping the dereferenced expression in '
+ 'parentheses will make the binding more obvious'))
+ else:
+ error(filename, linenum, 'runtime/casting', 4,
+ ('Are you taking an address of a cast? '
+ 'This is dangerous: could be a temp var. '
+ 'Take the address before doing the cast, rather than after'))
+
+
+def CheckCStyleCast(filename, clean_lines, linenum, cast_type, pattern, error):
+ """Checks for a C-style cast by looking for the pattern.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ cast_type: The string for the C++ cast to recommend. This is either
+ reinterpret_cast, static_cast, or const_cast, depending.
+ pattern: The regular expression used to find C-style casts.
+ error: The function to call with any errors found.
+
+ Returns:
+ True if an error was emitted.
+ False otherwise.
+ """
+ line = clean_lines.elided[linenum]
+ match = Search(pattern, line)
+ if not match:
+ return False
+
+ # Exclude lines with keywords that tend to look like casts
+ context = line[0:match.start(1) - 1]
+ if Match(r'.*\b(?:sizeof|alignof|alignas|[_A-Z][_A-Z0-9]*)\s*$', context):
+ return False
+
+ # Try expanding current context to see if we one level of
+ # parentheses inside a macro.
+ if linenum > 0:
+ for i in xrange(linenum - 1, max(0, linenum - 5), -1):
+ context = clean_lines.elided[i] + context
+ if Match(r'.*\b[_A-Z][_A-Z0-9]*\s*\((?:\([^()]*\)|[^()])*$', context):
+ return False
+
+ # operator++(int) and operator--(int)
+ if context.endswith(' operator++') or context.endswith(' operator--'):
+ return False
+
+ # A single unnamed argument for a function tends to look like old style cast.
+ # If we see those, don't issue warnings for deprecated casts.
+ remainder = line[match.end(0):]
+ if Match(r'^\s*(?:;|const\b|throw\b|final\b|override\b|[=>{),]|->)',
+ remainder):
+ return False
+
+ # At this point, all that should be left is actual casts.
+ error(filename, linenum, 'readability/casting', 4,
+ 'Using C-style cast. Use %s<%s>(...) instead' %
+ (cast_type, match.group(1)))
+
+ return True
+
+
+def ExpectingFunctionArgs(clean_lines, linenum):
+ """Checks whether where function type arguments are expected.
+
+ Args:
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+
+ Returns:
+ True if the line at 'linenum' is inside something that expects arguments
+ of function types.
+ """
+ line = clean_lines.elided[linenum]
+ return (Match(r'^\s*MOCK_(CONST_)?METHOD\d+(_T)?\(', line) or
+ (linenum >= 2 and
+ (Match(r'^\s*MOCK_(?:CONST_)?METHOD\d+(?:_T)?\((?:\S+,)?\s*$',
+ clean_lines.elided[linenum - 1]) or
+ Match(r'^\s*MOCK_(?:CONST_)?METHOD\d+(?:_T)?\(\s*$',
+ clean_lines.elided[linenum - 2]) or
+ Search(r'\bstd::m?function\s*\<\s*$',
+ clean_lines.elided[linenum - 1]))))
+
+
+_HEADERS_CONTAINING_TEMPLATES = (
+ ('<deque>', ('deque',)),
+ ('<functional>', ('unary_function', 'binary_function',
+ 'plus', 'minus', 'multiplies', 'divides', 'modulus',
+ 'negate',
+ 'equal_to', 'not_equal_to', 'greater', 'less',
+ 'greater_equal', 'less_equal',
+ 'logical_and', 'logical_or', 'logical_not',
+ 'unary_negate', 'not1', 'binary_negate', 'not2',
+ 'bind1st', 'bind2nd',
+ 'pointer_to_unary_function',
+ 'pointer_to_binary_function',
+ 'ptr_fun',
+ 'mem_fun_t', 'mem_fun', 'mem_fun1_t', 'mem_fun1_ref_t',
+ 'mem_fun_ref_t',
+ 'const_mem_fun_t', 'const_mem_fun1_t',
+ 'const_mem_fun_ref_t', 'const_mem_fun1_ref_t',
+ 'mem_fun_ref',
+ )),
+ ('<limits>', ('numeric_limits',)),
+ ('<list>', ('list',)),
+ ('<map>', ('map', 'multimap',)),
+ ('<memory>', ('allocator', 'make_shared', 'make_unique', 'shared_ptr',
+ 'unique_ptr', 'weak_ptr')),
+ ('<queue>', ('queue', 'priority_queue',)),
+ ('<set>', ('set', 'multiset',)),
+ ('<stack>', ('stack',)),
+ ('<string>', ('char_traits', 'basic_string',)),
+ ('<tuple>', ('tuple',)),
+ ('<unordered_map>', ('unordered_map', 'unordered_multimap')),
+ ('<unordered_set>', ('unordered_set', 'unordered_multiset')),
+ ('<utility>', ('pair',)),
+ ('<vector>', ('vector',)),
+
+ # gcc extensions.
+ # Note: std::hash is their hash, ::hash is our hash
+ ('<hash_map>', ('hash_map', 'hash_multimap',)),
+ ('<hash_set>', ('hash_set', 'hash_multiset',)),
+ ('<slist>', ('slist',)),
+ )
+
+_HEADERS_MAYBE_TEMPLATES = (
+ ('<algorithm>', ('copy', 'max', 'min', 'min_element', 'sort',
+ 'transform',
+ )),
+ ('<utility>', ('forward', 'make_pair', 'move', 'swap')),
+ )
+
+_RE_PATTERN_STRING = re.compile(r'\bstring\b')
+
+_re_pattern_headers_maybe_templates = []
+for _header, _templates in _HEADERS_MAYBE_TEMPLATES:
+ for _template in _templates:
+ # Match max<type>(..., ...), max(..., ...), but not foo->max, foo.max or
+ # type::max().
+ _re_pattern_headers_maybe_templates.append(
+ (re.compile(r'[^>.]\b' + _template + r'(<.*?>)?\([^\)]'),
+ _template,
+ _header))
+
+# Other scripts may reach in and modify this pattern.
+_re_pattern_templates = []
+for _header, _templates in _HEADERS_CONTAINING_TEMPLATES:
+ for _template in _templates:
+ _re_pattern_templates.append(
+ (re.compile(r'(\<|\b)' + _template + r'\s*\<'),
+ _template + '<>',
+ _header))
+
+
+def FilesBelongToSameModule(filename_cc, filename_h):
+ """Check if these two filenames belong to the same module.
+
+ The concept of a 'module' here is a as follows:
+ foo.h, foo-inl.h, foo.cc, foo_test.cc and foo_unittest.cc belong to the
+ same 'module' if they are in the same directory.
+ some/path/public/xyzzy and some/path/internal/xyzzy are also considered
+ to belong to the same module here.
+
+ If the filename_cc contains a longer path than the filename_h, for example,
+ '/absolute/path/to/base/sysinfo.cc', and this file would include
+ 'base/sysinfo.h', this function also produces the prefix needed to open the
+ header. This is used by the caller of this function to more robustly open the
+ header file. We don't have access to the real include paths in this context,
+ so we need this guesswork here.
+
+ Known bugs: tools/base/bar.cc and base/bar.h belong to the same module
+ according to this implementation. Because of this, this function gives
+ some false positives. This should be sufficiently rare in practice.
+
+ Args:
+ filename_cc: is the path for the .cc file
+ filename_h: is the path for the header path
+
+ Returns:
+ Tuple with a bool and a string:
+ bool: True if filename_cc and filename_h belong to the same module.
+ string: the additional prefix needed to open the header file.
+ """
+
+ fileinfo = FileInfo(filename_cc)
+ if not fileinfo.IsSource():
+ return (False, '')
+ filename_cc = filename_cc[:-len(fileinfo.Extension())]
+ matched_test_suffix = Search(_TEST_FILE_SUFFIX, fileinfo.BaseName())
+ if matched_test_suffix:
+ filename_cc = filename_cc[:-len(matched_test_suffix.group(1))]
+ filename_cc = filename_cc.replace('/public/', '/')
+ filename_cc = filename_cc.replace('/internal/', '/')
+
+ if not filename_h.endswith('.h'):
+ return (False, '')
+ filename_h = filename_h[:-len('.h')]
+ if filename_h.endswith('-inl'):
+ filename_h = filename_h[:-len('-inl')]
+ filename_h = filename_h.replace('/public/', '/')
+ filename_h = filename_h.replace('/internal/', '/')
+
+ files_belong_to_same_module = filename_cc.endswith(filename_h)
+ common_path = ''
+ if files_belong_to_same_module:
+ common_path = filename_cc[:-len(filename_h)]
+ return files_belong_to_same_module, common_path
+
+
+def UpdateIncludeState(filename, include_dict, io=codecs):
+ """Fill up the include_dict with new includes found from the file.
+
+ Args:
+ filename: the name of the header to read.
+ include_dict: a dictionary in which the headers are inserted.
+ io: The io factory to use to read the file. Provided for testability.
+
+ Returns:
+ True if a header was successfully added. False otherwise.
+ """
+ headerfile = None
+ try:
+ headerfile = io.open(filename, 'r', 'utf8', 'replace')
+ except IOError:
+ return False
+ linenum = 0
+ for line in headerfile:
+ linenum += 1
+ clean_line = CleanseComments(line)
+ match = _RE_PATTERN_INCLUDE.search(clean_line)
+ if match:
+ include = match.group(2)
+ include_dict.setdefault(include, linenum)
+ return True
+
+
+def CheckForIncludeWhatYouUse(filename, clean_lines, include_state, error,
+ io=codecs):
+ """Reports for missing stl includes.
+
+ This function will output warnings to make sure you are including the headers
+ necessary for the stl containers and functions that you use. We only give one
+ reason to include a header. For example, if you use both equal_to<> and
+ less<> in a .h file, only one (the latter in the file) of these will be
+ reported as a reason to include the <functional>.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ include_state: An _IncludeState instance.
+ error: The function to call with any errors found.
+ io: The IO factory to use to read the header file. Provided for unittest
+ injection.
+ """
+ required = {} # A map of header name to linenumber and the template entity.
+ # Example of required: { '<functional>': (1219, 'less<>') }
+
+ for linenum in xrange(clean_lines.NumLines()):
+ line = clean_lines.elided[linenum]
+ if not line or line[0] == '#':
+ continue
+
+ # String is special -- it is a non-templatized type in STL.
+ matched = _RE_PATTERN_STRING.search(line)
+ if matched:
+ # Don't warn about strings in non-STL namespaces:
+ # (We check only the first match per line; good enough.)
+ prefix = line[:matched.start()]
+ if prefix.endswith('std::') or not prefix.endswith('::'):
+ required['<string>'] = (linenum, 'string')
+
+ for pattern, template, header in _re_pattern_headers_maybe_templates:
+ if pattern.search(line):
+ required[header] = (linenum, template)
+
+ # The following function is just a speed up, no semantics are changed.
+ if not '<' in line: # Reduces the cpu time usage by skipping lines.
+ continue
+
+ for pattern, template, header in _re_pattern_templates:
+ matched = pattern.search(line)
+ if matched:
+ # Don't warn about IWYU in non-STL namespaces:
+ # (We check only the first match per line; good enough.)
+ prefix = line[:matched.start()]
+ if prefix.endswith('std::') or not prefix.endswith('::'):
+ required[header] = (linenum, template)
+
+ # The policy is that if you #include something in foo.h you don't need to
+ # include it again in foo.cc. Here, we will look at possible includes.
+ # Let's flatten the include_state include_list and copy it into a dictionary.
+ include_dict = dict([item for sublist in include_state.include_list
+ for item in sublist])
+
+ # Did we find the header for this file (if any) and successfully load it?
+ header_found = False
+
+ # Use the absolute path so that matching works properly.
+ abs_filename = FileInfo(filename).FullName()
+
+ # For Emacs's flymake.
+ # If cpplint is invoked from Emacs's flymake, a temporary file is generated
+ # by flymake and that file name might end with '_flymake.cc'. In that case,
+ # restore original file name here so that the corresponding header file can be
+ # found.
+ # e.g. If the file name is 'foo_flymake.cc', we should search for 'foo.h'
+ # instead of 'foo_flymake.h'
+ abs_filename = re.sub(r'_flymake\.cc$', '.cc', abs_filename)
+
+ # include_dict is modified during iteration, so we iterate over a copy of
+ # the keys.
+ header_keys = include_dict.keys()
+ for header in header_keys:
+ (same_module, common_path) = FilesBelongToSameModule(abs_filename, header)
+ fullpath = common_path + header
+ if same_module and UpdateIncludeState(fullpath, include_dict, io):
+ header_found = True
+
+ # If we can't find the header file for a .cc, assume it's because we don't
+ # know where to look. In that case we'll give up as we're not sure they
+ # didn't include it in the .h file.
+ # TODO(unknown): Do a better job of finding .h files so we are confident that
+ # not having the .h file means there isn't one.
+ if filename.endswith('.cc') and not header_found:
+ return
+
+ # All the lines have been processed, report the errors found.
+ for required_header_unstripped in required:
+ template = required[required_header_unstripped][1]
+ if required_header_unstripped.strip('<>"') not in include_dict:
+ error(filename, required[required_header_unstripped][0],
+ 'build/include_what_you_use', 4,
+ 'Add #include ' + required_header_unstripped + ' for ' + template)
+
+
+_RE_PATTERN_EXPLICIT_MAKEPAIR = re.compile(r'\bmake_pair\s*<')
+
+
+def CheckMakePairUsesDeduction(filename, clean_lines, linenum, error):
+ """Check that make_pair's template arguments are deduced.
+
+ G++ 4.6 in C++11 mode fails badly if make_pair's template arguments are
+ specified explicitly, and such use isn't intended in any case.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ line = clean_lines.elided[linenum]
+ match = _RE_PATTERN_EXPLICIT_MAKEPAIR.search(line)
+ if match:
+ error(filename, linenum, 'build/explicit_make_pair',
+ 4, # 4 = high confidence
+ 'For C++11-compatibility, omit template arguments from make_pair'
+ ' OR use pair directly OR if appropriate, construct a pair directly')
+
+
+def CheckRedundantVirtual(filename, clean_lines, linenum, error):
+ """Check if line contains a redundant "virtual" function-specifier.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ # Look for "virtual" on current line.
+ line = clean_lines.elided[linenum]
+ virtual = Match(r'^(.*)(\bvirtual\b)(.*)$', line)
+ if not virtual: return
+
+ # Ignore "virtual" keywords that are near access-specifiers. These
+ # are only used in class base-specifier and do not apply to member
+ # functions.
+ if (Search(r'\b(public|protected|private)\s+$', virtual.group(1)) or
+ Match(r'^\s+(public|protected|private)\b', virtual.group(3))):
+ return
+
+ # Ignore the "virtual" keyword from virtual base classes. Usually
+ # there is a column on the same line in these cases (virtual base
+ # classes are rare in google3 because multiple inheritance is rare).
+ if Match(r'^.*[^:]:[^:].*$', line): return
+
+ # Look for the next opening parenthesis. This is the start of the
+ # parameter list (possibly on the next line shortly after virtual).
+ # TODO(unknown): doesn't work if there are virtual functions with
+ # decltype() or other things that use parentheses, but csearch suggests
+ # that this is rare.
+ end_col = -1
+ end_line = -1
+ start_col = len(virtual.group(2))
+ for start_line in xrange(linenum, min(linenum + 3, clean_lines.NumLines())):
+ line = clean_lines.elided[start_line][start_col:]
+ parameter_list = Match(r'^([^(]*)\(', line)
+ if parameter_list:
+ # Match parentheses to find the end of the parameter list
+ (_, end_line, end_col) = CloseExpression(
+ clean_lines, start_line, start_col + len(parameter_list.group(1)))
+ break
+ start_col = 0
+
+ if end_col < 0:
+ return # Couldn't find end of parameter list, give up
+
+ # Look for "override" or "final" after the parameter list
+ # (possibly on the next few lines).
+ for i in xrange(end_line, min(end_line + 3, clean_lines.NumLines())):
+ line = clean_lines.elided[i][end_col:]
+ match = Search(r'\b(override|final)\b', line)
+ if match:
+ error(filename, linenum, 'readability/inheritance', 4,
+ ('"virtual" is redundant since function is '
+ 'already declared as "%s"' % match.group(1)))
+
+ # Set end_col to check whole lines after we are done with the
+ # first line.
+ end_col = 0
+ if Search(r'[^\w]\s*$', line):
+ break
+
+
+def CheckRedundantOverrideOrFinal(filename, clean_lines, linenum, error):
+ """Check if line contains a redundant "override" or "final" virt-specifier.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ # Look for closing parenthesis nearby. We need one to confirm where
+ # the declarator ends and where the virt-specifier starts to avoid
+ # false positives.
+ line = clean_lines.elided[linenum]
+ declarator_end = line.rfind(')')
+ if declarator_end >= 0:
+ fragment = line[declarator_end:]
+ else:
+ if linenum > 1 and clean_lines.elided[linenum - 1].rfind(')') >= 0:
+ fragment = line
+ else:
+ return
+
+ # Check that at most one of "override" or "final" is present, not both
+ if Search(r'\boverride\b', fragment) and Search(r'\bfinal\b', fragment):
+ error(filename, linenum, 'readability/inheritance', 4,
+ ('"override" is redundant since function is '
+ 'already declared as "final"'))
+
+
+
+
+# Returns true if we are at a new block, and it is directly
+# inside of a namespace.
+def IsBlockInNameSpace(nesting_state, is_forward_declaration):
+ """Checks that the new block is directly in a namespace.
+
+ Args:
+ nesting_state: The _NestingState object that contains info about our state.
+ is_forward_declaration: If the class is a forward declared class.
+ Returns:
+ Whether or not the new block is directly in a namespace.
+ """
+ if is_forward_declaration:
+ if len(nesting_state.stack) >= 1 and (
+ isinstance(nesting_state.stack[-1], _NamespaceInfo)):
+ return True
+ else:
+ return False
+
+ return (len(nesting_state.stack) > 1 and
+ nesting_state.stack[-1].check_namespace_indentation and
+ isinstance(nesting_state.stack[-2], _NamespaceInfo))
+
+
+def ShouldCheckNamespaceIndentation(nesting_state, is_namespace_indent_item,
+ raw_lines_no_comments, linenum):
+ """This method determines if we should apply our namespace indentation check.
+
+ Args:
+ nesting_state: The current nesting state.
+ is_namespace_indent_item: If we just put a new class on the stack, True.
+ If the top of the stack is not a class, or we did not recently
+ add the class, False.
+ raw_lines_no_comments: The lines without the comments.
+ linenum: The current line number we are processing.
+
+ Returns:
+ True if we should apply our namespace indentation check. Currently, it
+ only works for classes and namespaces inside of a namespace.
+ """
+
+ is_forward_declaration = IsForwardClassDeclaration(raw_lines_no_comments,
+ linenum)
+
+ if not (is_namespace_indent_item or is_forward_declaration):
+ return False
+
+ # If we are in a macro, we do not want to check the namespace indentation.
+ if IsMacroDefinition(raw_lines_no_comments, linenum):
+ return False
+
+ return IsBlockInNameSpace(nesting_state, is_forward_declaration)
+
+
+# Call this method if the line is directly inside of a namespace.
+# If the line above is blank (excluding comments) or the start of
+# an inner namespace, it cannot be indented.
+def CheckItemIndentationInNamespace(filename, raw_lines_no_comments, linenum,
+ error):
+ line = raw_lines_no_comments[linenum]
+ if Match(r'^\s+', line):
+ error(filename, linenum, 'runtime/indentation_namespace', 4,
+ 'Do not indent within a namespace')
+
+
+def ProcessLine(filename, file_extension, clean_lines, line,
+ include_state, function_state, nesting_state, error,
+ extra_check_functions=[]):
+ """Processes a single line in the file.
+
+ Args:
+ filename: Filename of the file that is being processed.
+ file_extension: The extension (dot not included) of the file.
+ clean_lines: An array of strings, each representing a line of the file,
+ with comments stripped.
+ line: Number of line being processed.
+ include_state: An _IncludeState instance in which the headers are inserted.
+ function_state: A _FunctionState instance which counts function lines, etc.
+ nesting_state: A NestingState instance which maintains information about
+ the current stack of nested blocks being parsed.
+ error: A callable to which errors are reported, which takes 4 arguments:
+ filename, line number, error level, and message
+ extra_check_functions: An array of additional check functions that will be
+ run on each source line. Each function takes 4
+ arguments: filename, clean_lines, line, error
+ """
+ raw_lines = clean_lines.raw_lines
+ ParseNolintSuppressions(filename, raw_lines[line], line, error)
+ nesting_state.Update(filename, clean_lines, line, error)
+ CheckForNamespaceIndentation(filename, nesting_state, clean_lines, line,
+ error)
+ if nesting_state.InAsmBlock(): return
+ CheckForFunctionLengths(filename, clean_lines, line, function_state, error)
+ CheckForMultilineCommentsAndStrings(filename, clean_lines, line, error)
+ CheckStyle(filename, clean_lines, line, file_extension, nesting_state, error)
+ CheckLanguage(filename, clean_lines, line, file_extension, include_state,
+ nesting_state, error)
+ CheckForNonConstReference(filename, clean_lines, line, nesting_state, error)
+ CheckForNonStandardConstructs(filename, clean_lines, line,
+ nesting_state, error)
+ CheckVlogArguments(filename, clean_lines, line, error)
+ CheckPosixThreading(filename, clean_lines, line, error)
+ CheckInvalidIncrement(filename, clean_lines, line, error)
+ CheckMakePairUsesDeduction(filename, clean_lines, line, error)
+ CheckRedundantVirtual(filename, clean_lines, line, error)
+ CheckRedundantOverrideOrFinal(filename, clean_lines, line, error)
+ for check_fn in extra_check_functions:
+ check_fn(filename, clean_lines, line, error)
+
+def FlagCxx11Features(filename, clean_lines, linenum, error):
+ """Flag those c++11 features that we only allow in certain places.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ line = clean_lines.elided[linenum]
+
+ include = Match(r'\s*#\s*include\s+[<"]([^<"]+)[">]', line)
+
+ # Flag unapproved C++ TR1 headers.
+ if include and include.group(1).startswith('tr1/'):
+ error(filename, linenum, 'build/c++tr1', 5,
+ ('C++ TR1 headers such as <%s> are unapproved.') % include.group(1))
+
+ # Flag unapproved C++11 headers.
+ if include and include.group(1) in ('cfenv',
+ 'condition_variable',
+ 'fenv.h',
+ 'future',
+ 'mutex',
+ 'thread',
+ 'chrono',
+ 'ratio',
+ 'regex',
+ 'system_error',
+ ):
+ error(filename, linenum, 'build/c++11', 5,
+ ('<%s> is an unapproved C++11 header.') % include.group(1))
+
+ # The only place where we need to worry about C++11 keywords and library
+ # features in preprocessor directives is in macro definitions.
+ if Match(r'\s*#', line) and not Match(r'\s*#\s*define\b', line): return
+
+ # These are classes and free functions. The classes are always
+ # mentioned as std::*, but we only catch the free functions if
+ # they're not found by ADL. They're alphabetical by header.
+ for top_name in (
+ # type_traits
+ 'alignment_of',
+ 'aligned_union',
+ ):
+ if Search(r'\bstd::%s\b' % top_name, line):
+ error(filename, linenum, 'build/c++11', 5,
+ ('std::%s is an unapproved C++11 class or function. Send c-style '
+ 'an example of where it would make your code more readable, and '
+ 'they may let you use it.') % top_name)
+
+
+def FlagCxx14Features(filename, clean_lines, linenum, error):
+ """Flag those C++14 features that we restrict.
+
+ Args:
+ filename: The name of the current file.
+ clean_lines: A CleansedLines instance containing the file.
+ linenum: The number of the line to check.
+ error: The function to call with any errors found.
+ """
+ line = clean_lines.elided[linenum]
+
+ include = Match(r'\s*#\s*include\s+[<"]([^<"]+)[">]', line)
+
+ # Flag unapproved C++14 headers.
+ if include and include.group(1) in ('scoped_allocator', 'shared_mutex'):
+ error(filename, linenum, 'build/c++14', 5,
+ ('<%s> is an unapproved C++14 header.') % include.group(1))
+
+
+def ProcessFileData(filename, file_extension, lines, error,
+ extra_check_functions=[]):
+ """Performs lint checks and reports any errors to the given error function.
+
+ Args:
+ filename: Filename of the file that is being processed.
+ file_extension: The extension (dot not included) of the file.
+ lines: An array of strings, each representing a line of the file, with the
+ last element being empty if the file is terminated with a newline.
+ error: A callable to which errors are reported, which takes 4 arguments:
+ filename, line number, error level, and message
+ extra_check_functions: An array of additional check functions that will be
+ run on each source line. Each function takes 4
+ arguments: filename, clean_lines, line, error
+ """
+ lines = (['// marker so line numbers and indices both start at 1'] + lines +
+ ['// marker so line numbers end in a known way'])
+
+ include_state = _IncludeState()
+ function_state = _FunctionState()
+ nesting_state = NestingState()
+
+ ResetNolintSuppressions()
+
+ CheckForCopyright(filename, lines, error)
+ ProcessGlobalSuppresions(lines)
+ RemoveMultiLineComments(filename, lines, error)
+ clean_lines = CleansedLines(lines)
+
+ if IsHeaderExtension(file_extension):
+ CheckForHeaderGuard(filename, clean_lines, error)
+
+ for line in xrange(clean_lines.NumLines()):
+ ProcessLine(filename, file_extension, clean_lines, line,
+ include_state, function_state, nesting_state, error,
+ extra_check_functions)
+ FlagCxx11Features(filename, clean_lines, line, error)
+ nesting_state.CheckCompletedBlocks(filename, error)
+
+ CheckForIncludeWhatYouUse(filename, clean_lines, include_state, error)
+
+ # Check that the .cc file has included its header if it exists.
+ if _IsSourceExtension(file_extension):
+ CheckHeaderFileIncluded(filename, include_state, error)
+
+ # We check here rather than inside ProcessLine so that we see raw
+ # lines rather than "cleaned" lines.
+ CheckForBadCharacters(filename, lines, error)
+
+ CheckForNewlineAtEOF(filename, lines, error)
+
+def ProcessConfigOverrides(filename):
+ """ Loads the configuration files and processes the config overrides.
+
+ Args:
+ filename: The name of the file being processed by the linter.
+
+ Returns:
+ False if the current |filename| should not be processed further.
+ """
+
+ abs_filename = os.path.abspath(filename)
+ cfg_filters = []
+ keep_looking = True
+ while keep_looking:
+ abs_path, base_name = os.path.split(abs_filename)
+ if not base_name:
+ break # Reached the root directory.
+
+ cfg_file = os.path.join(abs_path, "CPPLINT.cfg")
+ abs_filename = abs_path
+ if not os.path.isfile(cfg_file):
+ continue
+
+ try:
+ with open(cfg_file) as file_handle:
+ for line in file_handle:
+ line, _, _ = line.partition('#') # Remove comments.
+ if not line.strip():
+ continue
+
+ name, _, val = line.partition('=')
+ name = name.strip()
+ val = val.strip()
+ if name == 'set noparent':
+ keep_looking = False
+ elif name == 'filter':
+ cfg_filters.append(val)
+ elif name == 'exclude_files':
+ # When matching exclude_files pattern, use the base_name of
+ # the current file name or the directory name we are processing.
+ # For example, if we are checking for lint errors in /foo/bar/baz.cc
+ # and we found the .cfg file at /foo/CPPLINT.cfg, then the config
+ # file's "exclude_files" filter is meant to be checked against "bar"
+ # and not "baz" nor "bar/baz.cc".
+ if base_name:
+ pattern = re.compile(val)
+ if pattern.match(base_name):
+ if _cpplint_state.quiet:
+ # Suppress "Ignoring file" warning when using --quiet.
+ return False
+ sys.stderr.write('Ignoring "%s": file excluded by "%s". '
+ 'File path component "%s" matches '
+ 'pattern "%s"\n' %
+ (filename, cfg_file, base_name, val))
+ return False
+ elif name == 'linelength':
+ global _line_length
+ try:
+ _line_length = int(val)
+ except ValueError:
+ sys.stderr.write('Line length must be numeric.')
+ elif name == 'root':
+ global _root
+ # root directories are specified relative to CPPLINT.cfg dir.
+ _root = os.path.join(os.path.dirname(cfg_file), val)
+ elif name == 'headers':
+ ProcessHppHeadersOption(val)
+ else:
+ sys.stderr.write(
+ 'Invalid configuration option (%s) in file %s\n' %
+ (name, cfg_file))
+
+ except IOError:
+ sys.stderr.write(
+ "Skipping config file '%s': Can't open for reading\n" % cfg_file)
+ keep_looking = False
+
+ # Apply all the accumulated filters in reverse order (top-level directory
+ # config options having the least priority).
+ for filter in reversed(cfg_filters):
+ _AddFilters(filter)
+
+ return True
+
+
+def ProcessFile(filename, vlevel, extra_check_functions=[]):
+ """Does google-lint on a single file.
+
+ Args:
+ filename: The name of the file to parse.
+
+ vlevel: The level of errors to report. Every error of confidence
+ >= verbose_level will be reported. 0 is a good default.
+
+ extra_check_functions: An array of additional check functions that will be
+ run on each source line. Each function takes 4
+ arguments: filename, clean_lines, line, error
+ """
+
+ _SetVerboseLevel(vlevel)
+ _BackupFilters()
+ old_errors = _cpplint_state.error_count
+
+ if not ProcessConfigOverrides(filename):
+ _RestoreFilters()
+ return
+
+ lf_lines = []
+ crlf_lines = []
+ try:
+ # Support the UNIX convention of using "-" for stdin. Note that
+ # we are not opening the file with universal newline support
+ # (which codecs doesn't support anyway), so the resulting lines do
+ # contain trailing '\r' characters if we are reading a file that
+ # has CRLF endings.
+ # If after the split a trailing '\r' is present, it is removed
+ # below.
+ if filename == '-':
+ lines = codecs.StreamReaderWriter(sys.stdin,
+ codecs.getreader('utf8'),
+ codecs.getwriter('utf8'),
+ 'replace').read().split('\n')
+ else:
+ lines = codecs.open(filename, 'r', 'utf8', 'replace').read().split('\n')
+
+ # Remove trailing '\r'.
+ # The -1 accounts for the extra trailing blank line we get from split()
+ for linenum in range(len(lines) - 1):
+ if lines[linenum].endswith('\r'):
+ lines[linenum] = lines[linenum].rstrip('\r')
+ crlf_lines.append(linenum + 1)
+ else:
+ lf_lines.append(linenum + 1)
+
+ except IOError:
+ sys.stderr.write(
+ "Skipping input '%s': Can't open for reading\n" % filename)
+ _RestoreFilters()
+ return
+
+ # Note, if no dot is found, this will give the entire filename as the ext.
+ file_extension = filename[filename.rfind('.') + 1:]
+
+ # When reading from stdin, the extension is unknown, so no cpplint tests
+ # should rely on the extension.
+ if filename != '-' and file_extension not in _valid_extensions:
+ sys.stderr.write('Ignoring %s; not a valid file name '
+ '(%s)\n' % (filename, ', '.join(_valid_extensions)))
+ else:
+ ProcessFileData(filename, file_extension, lines, Error,
+ extra_check_functions)
+
+ # If end-of-line sequences are a mix of LF and CR-LF, issue
+ # warnings on the lines with CR.
+ #
+ # Don't issue any warnings if all lines are uniformly LF or CR-LF,
+ # since critique can handle these just fine, and the style guide
+ # doesn't dictate a particular end of line sequence.
+ #
+ # We can't depend on os.linesep to determine what the desired
+ # end-of-line sequence should be, since that will return the
+ # server-side end-of-line sequence.
+ if lf_lines and crlf_lines:
+ # Warn on every line with CR. An alternative approach might be to
+ # check whether the file is mostly CRLF or just LF, and warn on the
+ # minority, we bias toward LF here since most tools prefer LF.
+ for linenum in crlf_lines:
+ Error(filename, linenum, 'whitespace/newline', 1,
+ 'Unexpected \\r (^M) found; better to use only \\n')
+
+ # Suppress printing anything if --quiet was passed unless the error
+ # count has increased after processing this file.
+ if not _cpplint_state.quiet or old_errors != _cpplint_state.error_count:
+ sys.stdout.write('Done processing %s\n' % filename)
+ _RestoreFilters()
+
+
+def PrintUsage(message):
+ """Prints a brief usage string and exits, optionally with an error message.
+
+ Args:
+ message: The optional error message.
+ """
+ sys.stderr.write(_USAGE)
+ if message:
+ sys.exit('\nFATAL ERROR: ' + message)
+ else:
+ sys.exit(1)
+
+
+def PrintCategories():
+ """Prints a list of all the error-categories used by error messages.
+
+ These are the categories used to filter messages via --filter.
+ """
+ sys.stderr.write(''.join(' %s\n' % cat for cat in _ERROR_CATEGORIES))
+ sys.exit(0)
+
+
+def ParseArguments(args):
+ """Parses the command line arguments.
+
+ This may set the output format and verbosity level as side-effects.
+
+ Args:
+ args: The command line arguments:
+
+ Returns:
+ The list of filenames to lint.
+ """
+ try:
+ (opts, filenames) = getopt.getopt(args, '', ['help', 'output=', 'verbose=',
+ 'counting=',
+ 'filter=',
+ 'root=',
+ 'linelength=',
+ 'extensions=',
+ 'headers=',
+ 'quiet'])
+ except getopt.GetoptError:
+ PrintUsage('Invalid arguments.')
+
+ verbosity = _VerboseLevel()
+ output_format = _OutputFormat()
+ filters = ''
+ quiet = _Quiet()
+ counting_style = ''
+
+ for (opt, val) in opts:
+ if opt == '--help':
+ PrintUsage(None)
+ elif opt == '--output':
+ if val not in ('emacs', 'vs7', 'eclipse'):
+ PrintUsage('The only allowed output formats are emacs, vs7 and eclipse.')
+ output_format = val
+ elif opt == '--quiet':
+ quiet = True
+ elif opt == '--verbose':
+ verbosity = int(val)
+ elif opt == '--filter':
+ filters = val
+ if not filters:
+ PrintCategories()
+ elif opt == '--counting':
+ if val not in ('total', 'toplevel', 'detailed'):
+ PrintUsage('Valid counting options are total, toplevel, and detailed')
+ counting_style = val
+ elif opt == '--root':
+ global _root
+ _root = val
+ elif opt == '--linelength':
+ global _line_length
+ try:
+ _line_length = int(val)
+ except ValueError:
+ PrintUsage('Line length must be digits.')
+ elif opt == '--extensions':
+ global _valid_extensions
+ try:
+ _valid_extensions = set(val.split(','))
+ except ValueError:
+ PrintUsage('Extensions must be comma seperated list.')
+ elif opt == '--headers':
+ ProcessHppHeadersOption(val)
+
+ if not filenames:
+ PrintUsage('No files were specified.')
+
+ _SetOutputFormat(output_format)
+ _SetQuiet(quiet)
+ _SetVerboseLevel(verbosity)
+ _SetFilters(filters)
+ _SetCountingStyle(counting_style)
+
+ return filenames
+
+
+def main():
+ filenames = ParseArguments(sys.argv[1:])
+
+ # Change stderr to write with replacement characters so we don't die
+ # if we try to print something containing non-ASCII characters.
+ sys.stderr = codecs.StreamReaderWriter(sys.stderr,
+ codecs.getreader('utf8'),
+ codecs.getwriter('utf8'),
+ 'replace')
+
+ _cpplint_state.ResetErrorCounts()
+ for filename in filenames:
+ ProcessFile(filename, _cpplint_state.verbose_level)
+ # If --quiet is passed, suppress printing error count unless there are errors.
+ if not _cpplint_state.quiet or _cpplint_state.error_count > 0:
+ _cpplint_state.PrintErrorCounts()
+
+ sys.exit(_cpplint_state.error_count > 0)
+
+
+if __name__ == '__main__':
+ main()
diff --git a/cpplint/cpplint_test_header.h b/cpplint/cpplint_test_header.h
new file mode 100644
index 0000000..4307e80
--- /dev/null
+++ b/cpplint/cpplint_test_header.h
@@ -0,0 +1 @@
+// A test header for cpplint_unittest.py.
diff --git a/cpplint/cpplint_unittest.py b/cpplint/cpplint_unittest.py
new file mode 100755
index 0000000..a07ffd8
--- /dev/null
+++ b/cpplint/cpplint_unittest.py
@@ -0,0 +1,5803 @@
+#!/usr/bin/python
+# -*- coding: utf-8; -*-
+#
+# Copyright (c) 2009 Google Inc. All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+# * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+"""Unit test for cpplint.py."""
+
+# TODO(unknown): Add a good test that tests UpdateIncludeState.
+
+import codecs
+import os
+import random
+import re
+import subprocess
+import sys
+import unittest
+
+import cpplint
+
+
+# This class works as an error collector and replaces cpplint.Error
+# function for the unit tests. We also verify each category we see
+# is in cpplint._ERROR_CATEGORIES, to help keep that list up to date.
+class ErrorCollector(object):
+ # These are a global list, covering all categories seen ever.
+ _ERROR_CATEGORIES = cpplint._ERROR_CATEGORIES
+ _SEEN_ERROR_CATEGORIES = {}
+
+ def __init__(self, assert_fn):
+ """assert_fn: a function to call when we notice a problem."""
+ self._assert_fn = assert_fn
+ self._errors = []
+ cpplint.ResetNolintSuppressions()
+
+ def __call__(self, unused_filename, linenum,
+ category, confidence, message):
+ self._assert_fn(category in self._ERROR_CATEGORIES,
+ 'Message "%s" has category "%s",'
+ ' which is not in _ERROR_CATEGORIES' % (message, category))
+ self._SEEN_ERROR_CATEGORIES[category] = 1
+ if cpplint._ShouldPrintError(category, confidence, linenum):
+ self._errors.append('%s [%s] [%d]' % (message, category, confidence))
+
+ def Results(self):
+ if len(self._errors) < 2:
+ return ''.join(self._errors) # Most tests expect to have a string.
+ else:
+ return self._errors # Let's give a list if there is more than one.
+
+ def ResultList(self):
+ return self._errors
+
+ def VerifyAllCategoriesAreSeen(self):
+ """Fails if there's a category in _ERROR_CATEGORIES~_SEEN_ERROR_CATEGORIES.
+
+ This should only be called after all tests are run, so
+ _SEEN_ERROR_CATEGORIES has had a chance to fully populate. Since
+ this isn't called from within the normal unittest framework, we
+ can't use the normal unittest assert macros. Instead we just exit
+ when we see an error. Good thing this test is always run last!
+ """
+ for category in self._ERROR_CATEGORIES:
+ if category not in self._SEEN_ERROR_CATEGORIES:
+ sys.exit('FATAL ERROR: There are no tests for category "%s"' % category)
+
+ def RemoveIfPresent(self, substr):
+ for (index, error) in enumerate(self._errors):
+ if error.find(substr) != -1:
+ self._errors = self._errors[0:index] + self._errors[(index + 1):]
+ break
+
+
+# This class is a lame mock of codecs. We do not verify filename, mode, or
+# encoding, but for the current use case it is not needed.
+class MockIo(object):
+
+ def __init__(self, mock_file):
+ self.mock_file = mock_file
+
+ def open(self, # pylint: disable-msg=C6409
+ unused_filename, unused_mode, unused_encoding, _):
+ return self.mock_file
+
+
+class CpplintTestBase(unittest.TestCase):
+ """Provides some useful helper functions for cpplint tests."""
+
+ def setUp(self):
+ # Allow subclasses to cheat os.path.abspath called in FileInfo class.
+ self.os_path_abspath_orig = os.path.abspath
+
+ def tearDown(self):
+ os.path.abspath = self.os_path_abspath_orig
+
+ # Perform lint on single line of input and return the error message.
+ def PerformSingleLineLint(self, code):
+ error_collector = ErrorCollector(self.assert_)
+ lines = code.split('\n')
+ cpplint.RemoveMultiLineComments('foo.h', lines, error_collector)
+ clean_lines = cpplint.CleansedLines(lines)
+ include_state = cpplint._IncludeState()
+ function_state = cpplint._FunctionState()
+ nesting_state = cpplint.NestingState()
+ cpplint.ProcessLine('foo.cc', 'cc', clean_lines, 0,
+ include_state, function_state,
+ nesting_state, error_collector)
+ # Single-line lint tests are allowed to fail the 'unlintable function'
+ # check.
+ error_collector.RemoveIfPresent(
+ 'Lint failed to find start of function body.')
+ return error_collector.Results()
+
+ # Perform lint over multiple lines and return the error message.
+ def PerformMultiLineLint(self, code):
+ error_collector = ErrorCollector(self.assert_)
+ lines = code.split('\n')
+ cpplint.RemoveMultiLineComments('foo.h', lines, error_collector)
+ lines = cpplint.CleansedLines(lines)
+ nesting_state = cpplint.NestingState()
+ for i in xrange(lines.NumLines()):
+ nesting_state.Update('foo.h', lines, i, error_collector)
+ cpplint.CheckStyle('foo.h', lines, i, 'h', nesting_state,
+ error_collector)
+ cpplint.CheckForNonStandardConstructs('foo.h', lines, i,
+ nesting_state, error_collector)
+ nesting_state.CheckCompletedBlocks('foo.h', error_collector)
+ return error_collector.Results()
+
+ # Similar to PerformMultiLineLint, but calls CheckLanguage instead of
+ # CheckForNonStandardConstructs
+ def PerformLanguageRulesCheck(self, file_name, code):
+ error_collector = ErrorCollector(self.assert_)
+ include_state = cpplint._IncludeState()
+ nesting_state = cpplint.NestingState()
+ lines = code.split('\n')
+ cpplint.RemoveMultiLineComments(file_name, lines, error_collector)
+ lines = cpplint.CleansedLines(lines)
+ ext = file_name[file_name.rfind('.') + 1:]
+ for i in xrange(lines.NumLines()):
+ cpplint.CheckLanguage(file_name, lines, i, ext, include_state,
+ nesting_state, error_collector)
+ return error_collector.Results()
+
+ def PerformFunctionLengthsCheck(self, code):
+ """Perform Lint function length check on block of code and return warnings.
+
+ Builds up an array of lines corresponding to the code and strips comments
+ using cpplint functions.
+
+ Establishes an error collector and invokes the function length checking
+ function following cpplint's pattern.
+
+ Args:
+ code: C++ source code expected to generate a warning message.
+
+ Returns:
+ The accumulated errors.
+ """
+ file_name = 'foo.cc'
+ error_collector = ErrorCollector(self.assert_)
+ function_state = cpplint._FunctionState()
+ lines = code.split('\n')
+ cpplint.RemoveMultiLineComments(file_name, lines, error_collector)
+ lines = cpplint.CleansedLines(lines)
+ for i in xrange(lines.NumLines()):
+ cpplint.CheckForFunctionLengths(file_name, lines, i,
+ function_state, error_collector)
+ return error_collector.Results()
+
+ def PerformIncludeWhatYouUse(self, code, filename='foo.h', io=codecs):
+ # First, build up the include state.
+ error_collector = ErrorCollector(self.assert_)
+ include_state = cpplint._IncludeState()
+ nesting_state = cpplint.NestingState()
+ lines = code.split('\n')
+ cpplint.RemoveMultiLineComments(filename, lines, error_collector)
+ lines = cpplint.CleansedLines(lines)
+ for i in xrange(lines.NumLines()):
+ cpplint.CheckLanguage(filename, lines, i, '.h', include_state,
+ nesting_state, error_collector)
+ # We could clear the error_collector here, but this should
+ # also be fine, since our IncludeWhatYouUse unittests do not
+ # have language problems.
+
+ # Second, look for missing includes.
+ cpplint.CheckForIncludeWhatYouUse(filename, lines, include_state,
+ error_collector, io)
+ return error_collector.Results()
+
+ # Perform lint and compare the error message with "expected_message".
+ def TestLint(self, code, expected_message):
+ self.assertEquals(expected_message, self.PerformSingleLineLint(code))
+
+ def TestMultiLineLint(self, code, expected_message):
+ self.assertEquals(expected_message, self.PerformMultiLineLint(code))
+
+ def TestMultiLineLintRE(self, code, expected_message_re):
+ message = self.PerformMultiLineLint(code)
+ if not re.search(expected_message_re, message):
+ self.fail('Message was:\n' + message + 'Expected match to "' +
+ expected_message_re + '"')
+
+ def TestLanguageRulesCheck(self, file_name, code, expected_message):
+ self.assertEquals(expected_message,
+ self.PerformLanguageRulesCheck(file_name, code))
+
+ def TestIncludeWhatYouUse(self, code, expected_message):
+ self.assertEquals(expected_message,
+ self.PerformIncludeWhatYouUse(code))
+
+ def TestBlankLinesCheck(self, lines, start_errors, end_errors):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc', lines, error_collector)
+ self.assertEquals(
+ start_errors,
+ error_collector.Results().count(
+ 'Redundant blank line at the start of a code block '
+ 'should be deleted. [whitespace/blank_line] [2]'))
+ self.assertEquals(
+ end_errors,
+ error_collector.Results().count(
+ 'Redundant blank line at the end of a code block '
+ 'should be deleted. [whitespace/blank_line] [3]'))
+
+
+class CpplintTest(CpplintTestBase):
+
+ def GetNamespaceResults(self, lines):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.RemoveMultiLineComments('foo.h', lines, error_collector)
+ lines = cpplint.CleansedLines(lines)
+ nesting_state = cpplint.NestingState()
+ for i in xrange(lines.NumLines()):
+ nesting_state.Update('foo.h', lines, i, error_collector)
+ cpplint.CheckForNamespaceIndentation('foo.h', nesting_state,
+ lines, i, error_collector)
+
+ return error_collector.Results()
+
+ def testForwardDeclarationNameSpaceIndentation(self):
+ lines = ['namespace Test {',
+ ' class ForwardDeclaration;',
+ '} // namespace Test']
+
+ results = self.GetNamespaceResults(lines)
+ self.assertEquals(results, 'Do not indent within a namespace '
+ ' [runtime/indentation_namespace] [4]')
+
+ def testNameSpaceIndentationForClass(self):
+ lines = ['namespace Test {',
+ 'void foo() { }',
+ ' class Test {',
+ ' };',
+ '} // namespace Test']
+
+ results = self.GetNamespaceResults(lines)
+ self.assertEquals(results, 'Do not indent within a namespace '
+ ' [runtime/indentation_namespace] [4]')
+
+ def testNameSpaceIndentationNoError(self):
+ lines = ['namespace Test {',
+ 'void foo() { }',
+ '} // namespace Test']
+
+ results = self.GetNamespaceResults(lines)
+ self.assertEquals(results, '')
+
+ def testWhitespaceBeforeNamespace(self):
+ lines = [' namespace Test {',
+ ' void foo() { }',
+ ' } // namespace Test']
+
+ results = self.GetNamespaceResults(lines)
+ self.assertEquals(results, '')
+
+ def testFalsePositivesNoError(self):
+ lines = ['namespace Test {',
+ 'struct OuterClass {',
+ ' struct NoFalsePositivesHere;',
+ ' struct NoFalsePositivesHere member_variable;',
+ '};',
+ '} // namespace Test']
+
+ results = self.GetNamespaceResults(lines)
+ self.assertEquals(results, '')
+
+
+ # Test get line width.
+ def testGetLineWidth(self):
+ self.assertEquals(0, cpplint.GetLineWidth(''))
+ self.assertEquals(10, cpplint.GetLineWidth(u'x' * 10))
+ self.assertEquals(16, cpplint.GetLineWidth(u'都|道|府|県|支庁'))
+
+ def testGetTextInside(self):
+ self.assertEquals('', cpplint._GetTextInside('fun()', r'fun\('))
+ self.assertEquals('x, y', cpplint._GetTextInside('f(x, y)', r'f\('))
+ self.assertEquals('a(), b(c())', cpplint._GetTextInside(
+ 'printf(a(), b(c()))', r'printf\('))
+ self.assertEquals('x, y{}', cpplint._GetTextInside('f[x, y{}]', r'f\['))
+ self.assertEquals(None, cpplint._GetTextInside('f[a, b(}]', r'f\['))
+ self.assertEquals(None, cpplint._GetTextInside('f[x, y]', r'f\('))
+ self.assertEquals('y, h(z, (a + b))', cpplint._GetTextInside(
+ 'f(x, g(y, h(z, (a + b))))', r'g\('))
+ self.assertEquals('f(f(x))', cpplint._GetTextInside('f(f(f(x)))', r'f\('))
+ # Supports multiple lines.
+ self.assertEquals('\n return loop(x);\n',
+ cpplint._GetTextInside(
+ 'int loop(int x) {\n return loop(x);\n}\n', r'\{'))
+ # '^' matches the beginning of each line.
+ self.assertEquals('x, y',
+ cpplint._GetTextInside(
+ '#include "inl.h" // skip #define\n'
+ '#define A2(x, y) a_inl_(x, y, __LINE__)\n'
+ '#define A(x) a_inl_(x, "", __LINE__)\n',
+ r'^\s*#define\s*\w+\('))
+
+ def testFindNextMultiLineCommentStart(self):
+ self.assertEquals(1, cpplint.FindNextMultiLineCommentStart([''], 0))
+
+ lines = ['a', 'b', '/* c']
+ self.assertEquals(2, cpplint.FindNextMultiLineCommentStart(lines, 0))
+
+ lines = ['char a[] = "/*";'] # not recognized as comment.
+ self.assertEquals(1, cpplint.FindNextMultiLineCommentStart(lines, 0))
+
+ def testFindNextMultiLineCommentEnd(self):
+ self.assertEquals(1, cpplint.FindNextMultiLineCommentEnd([''], 0))
+ lines = ['a', 'b', ' c */']
+ self.assertEquals(2, cpplint.FindNextMultiLineCommentEnd(lines, 0))
+
+ def testRemoveMultiLineCommentsFromRange(self):
+ lines = ['a', ' /* comment ', ' * still comment', ' comment */ ', 'b']
+ cpplint.RemoveMultiLineCommentsFromRange(lines, 1, 4)
+ self.assertEquals(['a', '/**/', '/**/', '/**/', 'b'], lines)
+
+ def testSpacesAtEndOfLine(self):
+ self.TestLint(
+ '// Hello there ',
+ 'Line ends in whitespace. Consider deleting these extra spaces.'
+ ' [whitespace/end_of_line] [4]')
+
+ # Test line length check.
+ def testLineLengthCheck(self):
+ self.TestLint(
+ '// Hello',
+ '')
+ self.TestLint(
+ '// x' + ' x' * 40,
+ 'Lines should be <= 80 characters long'
+ ' [whitespace/line_length] [2]')
+ self.TestLint(
+ '// x' + ' x' * 50,
+ 'Lines should be <= 80 characters long'
+ ' [whitespace/line_length] [2]')
+ self.TestLint(
+ '// //some/path/to/f' + ('i' * 100) + 'le',
+ '')
+ self.TestLint(
+ '// //some/path/to/f' + ('i' * 100) + 'le',
+ '')
+ self.TestLint(
+ '// //some/path/to/f' + ('i' * 50) + 'le and some comments',
+ 'Lines should be <= 80 characters long'
+ ' [whitespace/line_length] [2]')
+ self.TestLint(
+ '// http://g' + ('o' * 100) + 'gle.com/',
+ '')
+ self.TestLint(
+ '// https://g' + ('o' * 100) + 'gle.com/',
+ '')
+ self.TestLint(
+ '// https://g' + ('o' * 60) + 'gle.com/ and some comments',
+ 'Lines should be <= 80 characters long'
+ ' [whitespace/line_length] [2]')
+ self.TestLint(
+ '// Read https://g' + ('o' * 60) + 'gle.com/',
+ '')
+ self.TestLint(
+ '// $Id: g' + ('o' * 80) + 'gle.cc#1 $',
+ '')
+ self.TestLint(
+ '// $Id: g' + ('o' * 80) + 'gle.cc#1',
+ 'Lines should be <= 80 characters long'
+ ' [whitespace/line_length] [2]')
+ self.TestMultiLineLint(
+ 'static const char kCStr[] = "g' + ('o' * 50) + 'gle";\n',
+ 'Lines should be <= 80 characters long'
+ ' [whitespace/line_length] [2]')
+ self.TestMultiLineLint(
+ 'static const char kRawStr[] = R"(g' + ('o' * 50) + 'gle)";\n',
+ '') # no warning because raw string content is elided
+ self.TestMultiLineLint(
+ 'static const char kMultiLineRawStr[] = R"(\n'
+ 'g' + ('o' * 80) + 'gle\n'
+ ')";',
+ '')
+ self.TestMultiLineLint(
+ 'static const char kL' + ('o' * 50) + 'ngIdentifier[] = R"()";\n',
+ 'Lines should be <= 80 characters long'
+ ' [whitespace/line_length] [2]')
+
+ # Test error suppression annotations.
+ def testErrorSuppression(self):
+ # Two errors on same line:
+ self.TestLint(
+ 'long a = (int64) 65;',
+ ['Using C-style cast. Use static_cast<int64>(...) instead'
+ ' [readability/casting] [4]',
+ 'Use int16/int64/etc, rather than the C type long'
+ ' [runtime/int] [4]',
+ ])
+ # One category of error suppressed:
+ self.TestLint(
+ 'long a = (int64) 65; // NOLINT(runtime/int)',
+ 'Using C-style cast. Use static_cast<int64>(...) instead'
+ ' [readability/casting] [4]')
+ # All categories suppressed: (two aliases)
+ self.TestLint('long a = (int64) 65; // NOLINT', '')
+ self.TestLint('long a = (int64) 65; // NOLINT(*)', '')
+ # Malformed NOLINT directive:
+ self.TestLint(
+ 'long a = 65; // NOLINT(foo)',
+ ['Unknown NOLINT error category: foo'
+ ' [readability/nolint] [5]',
+ 'Use int16/int64/etc, rather than the C type long [runtime/int] [4]',
+ ])
+ # Irrelevant NOLINT directive has no effect:
+ self.TestLint(
+ 'long a = 65; // NOLINT(readability/casting)',
+ 'Use int16/int64/etc, rather than the C type long'
+ ' [runtime/int] [4]')
+ # NOLINTNEXTLINE silences warning for the next line instead of current line
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('test.cc', 'cc',
+ ['// Copyright 2014 Your Company.',
+ '// NOLINTNEXTLINE(whitespace/line_length)',
+ '// ./command' + (' -verbose' * 80),
+ ''],
+ error_collector)
+ self.assertEquals('', error_collector.Results())
+ # LINT_C_FILE silences cast warnings for entire file.
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('test.h', 'h',
+ ['// Copyright 2014 Your Company.',
+ '// NOLINT(build/header_guard)',
+ 'int64 a = (uint64) 65;',
+ '// LINT_C_FILE',
+ ''],
+ error_collector)
+ self.assertEquals('', error_collector.Results())
+ # Vim modes silence cast warnings for entire file.
+ for modeline in ['vi:filetype=c',
+ 'vi:sw=8 filetype=c',
+ 'vi:sw=8 filetype=c ts=8',
+ 'vi: filetype=c',
+ 'vi: sw=8 filetype=c',
+ 'vi: sw=8 filetype=c ts=8',
+ 'vim:filetype=c',
+ 'vim:sw=8 filetype=c',
+ 'vim:sw=8 filetype=c ts=8',
+ 'vim: filetype=c',
+ 'vim: sw=8 filetype=c',
+ 'vim: sw=8 filetype=c ts=8',
+ 'vim: set filetype=c:',
+ 'vim: set sw=8 filetype=c:',
+ 'vim: set sw=8 filetype=c ts=8:',
+ 'vim: set filetype=c :',
+ 'vim: set sw=8 filetype=c :',
+ 'vim: set sw=8 filetype=c ts=8 :',
+ 'vim: se filetype=c:',
+ 'vim: se sw=8 filetype=c:',
+ 'vim: se sw=8 filetype=c ts=8:',
+ 'vim: se filetype=c :',
+ 'vim: se sw=8 filetype=c :',
+ 'vim: se sw=8 filetype=c ts=8 :']:
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('test.h', 'h',
+ ['// Copyright 2014 Your Company.',
+ '// NOLINT(build/header_guard)',
+ 'int64 a = (uint64) 65;',
+ '/* Prevent warnings about the modeline',
+ modeline,
+ '*/',
+ ''],
+ error_collector)
+ self.assertEquals('', error_collector.Results())
+ # LINT_KERNEL_FILE silences whitespace/tab warnings for entire file.
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('test.h', 'h',
+ ['// Copyright 2014 Your Company.',
+ '// NOLINT(build/header_guard)',
+ 'struct test {',
+ '\tint member;',
+ '};',
+ '// LINT_KERNEL_FILE',
+ ''],
+ error_collector)
+ self.assertEquals('', error_collector.Results())
+ # NOLINT, NOLINTNEXTLINE silences the readability/braces warning for "};".
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('test.cc', 'cc',
+ ['// Copyright 2014 Your Company.',
+ 'for (int i = 0; i != 100; ++i) {',
+ '\tstd::cout << i << std::endl;',
+ '}; // NOLINT',
+ 'for (int i = 0; i != 100; ++i) {',
+ '\tstd::cout << i << std::endl;',
+ '// NOLINTNEXTLINE',
+ '};',
+ '// LINT_KERNEL_FILE',
+ ''],
+ error_collector)
+ self.assertEquals('', error_collector.Results())
+
+ # Test Variable Declarations.
+ def testVariableDeclarations(self):
+ self.TestLint(
+ 'long a = 65;',
+ 'Use int16/int64/etc, rather than the C type long'
+ ' [runtime/int] [4]')
+ self.TestLint(
+ 'long double b = 65.0;',
+ '')
+ self.TestLint(
+ 'long long aa = 6565;',
+ 'Use int16/int64/etc, rather than the C type long'
+ ' [runtime/int] [4]')
+
+ # Test C-style cast cases.
+ def testCStyleCast(self):
+ self.TestLint(
+ 'int a = (int)1.0;',
+ 'Using C-style cast. Use static_cast<int>(...) instead'
+ ' [readability/casting] [4]')
+ self.TestLint(
+ 'int a = (int)-1.0;',
+ 'Using C-style cast. Use static_cast<int>(...) instead'
+ ' [readability/casting] [4]')
+ self.TestLint(
+ 'int *a = (int *)NULL;',
+ 'Using C-style cast. Use reinterpret_cast<int *>(...) instead'
+ ' [readability/casting] [4]')
+
+ self.TestLint(
+ 'uint16 a = (uint16)1.0;',
+ 'Using C-style cast. Use static_cast<uint16>(...) instead'
+ ' [readability/casting] [4]')
+ self.TestLint(
+ 'int32 a = (int32)1.0;',
+ 'Using C-style cast. Use static_cast<int32>(...) instead'
+ ' [readability/casting] [4]')
+ self.TestLint(
+ 'uint64 a = (uint64)1.0;',
+ 'Using C-style cast. Use static_cast<uint64>(...) instead'
+ ' [readability/casting] [4]')
+
+ # These shouldn't be recognized casts.
+ self.TestLint('u a = (u)NULL;', '')
+ self.TestLint('uint a = (uint)NULL;', '')
+ self.TestLint('typedef MockCallback<int(int)> CallbackType;', '')
+ self.TestLint('scoped_ptr< MockCallback<int(int)> > callback_value;', '')
+ self.TestLint('std::function<int(bool)>', '')
+ self.TestLint('x = sizeof(int)', '')
+ self.TestLint('x = alignof(int)', '')
+ self.TestLint('alignas(int) char x[42]', '')
+ self.TestLint('alignas(alignof(x)) char y[42]', '')
+ self.TestLint('void F(int (func)(int));', '')
+ self.TestLint('void F(int (func)(int*));', '')
+ self.TestLint('void F(int (Class::member)(int));', '')
+ self.TestLint('void F(int (Class::member)(int*));', '')
+ self.TestLint('void F(int (Class::member)(int), int param);', '')
+ self.TestLint('void F(int (Class::member)(int*), int param);', '')
+
+ # These should not be recognized (lambda functions without arg names).
+ self.TestLint('[](int/*unused*/) -> bool {', '')
+ self.TestLint('[](int /*unused*/) -> bool {', '')
+ self.TestLint('auto f = [](MyStruct* /*unused*/)->int {', '')
+ self.TestLint('[](int) -> bool {', '')
+ self.TestLint('auto f = [](MyStruct*)->int {', '')
+
+ # Cast with brace initializers
+ self.TestLint('int64_t{4096} * 1000 * 1000', '')
+ self.TestLint('size_t{4096} * 1000 * 1000', '')
+ self.TestLint('uint_fast16_t{4096} * 1000 * 1000', '')
+
+ # Brace initializer with templated type
+ self.TestMultiLineLint(
+ """
+ template <typename Type1,
+ typename Type2>
+ void Function(int arg1,
+ int arg2) {
+ variable &= ~Type1{0} - 1;
+ }""",
+ '')
+ self.TestMultiLineLint(
+ """
+ template <typename Type>
+ class Class {
+ void Function() {
+ variable &= ~Type{0} - 1;
+ }
+ };""",
+ '')
+ self.TestMultiLineLint(
+ """
+ template <typename Type>
+ class Class {
+ void Function() {
+ variable &= ~Type{0} - 1;
+ }
+ };""",
+ '')
+ self.TestMultiLineLint(
+ """
+ namespace {
+ template <typename Type>
+ class Class {
+ void Function() {
+ if (block) {
+ variable &= ~Type{0} - 1;
+ }
+ }
+ };
+ }""",
+ '')
+
+ # Test taking address of casts (runtime/casting)
+ def testRuntimeCasting(self):
+ error_msg = ('Are you taking an address of a cast? '
+ 'This is dangerous: could be a temp var. '
+ 'Take the address before doing the cast, rather than after'
+ ' [runtime/casting] [4]')
+ self.TestLint('int* x = &static_cast<int*>(foo);', error_msg)
+ self.TestLint('int* x = &reinterpret_cast<int *>(foo);', error_msg)
+ self.TestLint('int* x = &(int*)foo;',
+ ['Using C-style cast. Use reinterpret_cast<int*>(...) '
+ 'instead [readability/casting] [4]',
+ error_msg])
+ self.TestLint('BudgetBuckets&(BudgetWinHistory::*BucketFn)(void) const;',
+ '')
+ self.TestLint('&(*func_ptr)(arg)', '')
+ self.TestLint('Compute(arg, &(*func_ptr)(i, j));', '')
+
+ # Alternative error message
+ alt_error_msg = ('Are you taking an address of something dereferenced '
+ 'from a cast? Wrapping the dereferenced expression in '
+ 'parentheses will make the binding more obvious'
+ ' [readability/casting] [4]')
+ self.TestLint('int* x = &down_cast<Obj*>(obj)->member_;', alt_error_msg)
+ self.TestLint('int* x = &down_cast<Obj*>(obj)[index];', alt_error_msg)
+ self.TestLint('int* x = &(down_cast<Obj*>(obj)->member_);', '')
+ self.TestLint('int* x = &(down_cast<Obj*>(obj)[index]);', '')
+ self.TestLint('int* x = &down_cast<Obj*>(obj)\n->member_;', alt_error_msg)
+ self.TestLint('int* x = &(down_cast<Obj*>(obj)\n->member_);', '')
+
+ # It's OK to cast an address.
+ self.TestLint('int* x = reinterpret_cast<int *>(&foo);', '')
+
+ # Function pointers returning references should not be confused
+ # with taking address of old-style casts.
+ self.TestLint('auto x = implicit_cast<string &(*)(int)>(&foo);', '')
+
+ def testRuntimeSelfinit(self):
+ self.TestLint(
+ 'Foo::Foo(Bar r, Bel l) : r_(r_), l_(l_) { }',
+ 'You seem to be initializing a member variable with itself.'
+ ' [runtime/init] [4]')
+ self.TestLint(
+ 'Foo::Foo(Bar r, Bel l) : r_(CHECK_NOTNULL(r_)) { }',
+ 'You seem to be initializing a member variable with itself.'
+ ' [runtime/init] [4]')
+ self.TestLint(
+ 'Foo::Foo(Bar r, Bel l) : r_(r), l_(l) { }',
+ '')
+ self.TestLint(
+ 'Foo::Foo(Bar r) : r_(r), l_(r_), ll_(l_) { }',
+ '')
+
+ # Test for unnamed arguments in a method.
+ def testCheckForUnnamedParams(self):
+ self.TestLint('virtual void Func(int*) const;', '')
+ self.TestLint('virtual void Func(int*);', '')
+ self.TestLint('void Method(char*) {', '')
+ self.TestLint('void Method(char*);', '')
+ self.TestLint('static void operator delete[](void*) throw();', '')
+ self.TestLint('int Method(int);', '')
+
+ self.TestLint('virtual void Func(int* p);', '')
+ self.TestLint('void operator delete(void* x) throw();', '')
+ self.TestLint('void Method(char* x) {', '')
+ self.TestLint('void Method(char* /*x*/) {', '')
+ self.TestLint('void Method(char* x);', '')
+ self.TestLint('typedef void (*Method)(int32 x);', '')
+ self.TestLint('static void operator delete[](void* x) throw();', '')
+ self.TestLint('static void operator delete[](void* /*x*/) throw();', '')
+
+ self.TestLint('X operator++(int);', '')
+ self.TestLint('X operator++(int) {', '')
+ self.TestLint('X operator--(int);', '')
+ self.TestLint('X operator--(int /*unused*/) {', '')
+ self.TestLint('MACRO(int);', '')
+ self.TestLint('MACRO(func(int));', '')
+ self.TestLint('MACRO(arg, func(int));', '')
+
+ self.TestLint('void (*func)(void*);', '')
+ self.TestLint('void Func((*func)(void*)) {}', '')
+ self.TestLint('template <void Func(void*)> void func();', '')
+ self.TestLint('virtual void f(int /*unused*/) {', '')
+ self.TestLint('void f(int /*unused*/) override {', '')
+ self.TestLint('void f(int /*unused*/) final {', '')
+
+ # Test deprecated casts such as int(d)
+ def testDeprecatedCast(self):
+ self.TestLint(
+ 'int a = int(2.2);',
+ 'Using deprecated casting style. '
+ 'Use static_cast<int>(...) instead'
+ ' [readability/casting] [4]')
+
+ self.TestLint(
+ '(char *) "foo"',
+ 'Using C-style cast. '
+ 'Use const_cast<char *>(...) instead'
+ ' [readability/casting] [4]')
+
+ self.TestLint(
+ '(int*)foo',
+ 'Using C-style cast. '
+ 'Use reinterpret_cast<int*>(...) instead'
+ ' [readability/casting] [4]')
+
+ # Checks for false positives...
+ self.TestLint('int a = int();', '') # constructor
+ self.TestLint('X::X() : a(int()) {}', '') # default constructor
+ self.TestLint('operator bool();', '') # Conversion operator
+ self.TestLint('new int64(123);', '') # "new" operator on basic type
+ self.TestLint('new int64(123);', '') # "new" operator on basic type
+ self.TestLint('new const int(42);', '') # "new" on const-qualified type
+ self.TestLint('using a = bool(int arg);', '') # C++11 alias-declaration
+ self.TestLint('x = bit_cast<double(*)[3]>(y);', '') # array of array
+ self.TestLint('void F(const char(&src)[N]);', '') # array of references
+
+ # Placement new
+ self.TestLint(
+ 'new(field_ptr) int(field->default_value_enum()->number());',
+ '')
+
+ # C++11 function wrappers
+ self.TestLint('std::function<int(bool)>', '')
+ self.TestLint('std::function<const int(bool)>', '')
+ self.TestLint('std::function< int(bool) >', '')
+ self.TestLint('mfunction<int(bool)>', '')
+
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(
+ 'test.cc', 'cc',
+ ['// Copyright 2014 Your Company. All Rights Reserved.',
+ 'typedef std::function<',
+ ' bool(int)> F;',
+ ''],
+ error_collector)
+ self.assertEquals('', error_collector.Results())
+
+ # Return types for function pointers
+ self.TestLint('typedef bool(FunctionPointer)();', '')
+ self.TestLint('typedef bool(FunctionPointer)(int param);', '')
+ self.TestLint('typedef bool(MyClass::*MemberFunctionPointer)();', '')
+ self.TestLint('typedef bool(MyClass::* MemberFunctionPointer)();', '')
+ self.TestLint('typedef bool(MyClass::*MemberFunctionPointer)() const;', '')
+ self.TestLint('void Function(bool(FunctionPointerArg)());', '')
+ self.TestLint('void Function(bool(FunctionPointerArg)()) {}', '')
+ self.TestLint('typedef set<int64, bool(*)(int64, int64)> SortedIdSet', '')
+ self.TestLint(
+ 'bool TraverseNode(T *Node, bool(VisitorBase:: *traverse) (T *t)) {}',
+ '')
+
+ # The second parameter to a gMock method definition is a function signature
+ # that often looks like a bad cast but should not picked up by lint.
+ def testMockMethod(self):
+ self.TestLint(
+ 'MOCK_METHOD0(method, int());',
+ '')
+ self.TestLint(
+ 'MOCK_CONST_METHOD1(method, float(string));',
+ '')
+ self.TestLint(
+ 'MOCK_CONST_METHOD2_T(method, double(float, float));',
+ '')
+ self.TestLint(
+ 'MOCK_CONST_METHOD1(method, SomeType(int));',
+ '')
+
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('mock.cc', 'cc',
+ ['MOCK_METHOD1(method1,',
+ ' bool(int));',
+ 'MOCK_METHOD1(',
+ ' method2,',
+ ' bool(int));',
+ 'MOCK_CONST_METHOD2(',
+ ' method3, bool(int,',
+ ' int));',
+ 'MOCK_METHOD1(method4, int(bool));',
+ 'const int kConstant = int(42);'], # true positive
+ error_collector)
+ self.assertEquals(
+ 0,
+ error_collector.Results().count(
+ ('Using deprecated casting style. '
+ 'Use static_cast<bool>(...) instead '
+ '[readability/casting] [4]')))
+ self.assertEquals(
+ 1,
+ error_collector.Results().count(
+ ('Using deprecated casting style. '
+ 'Use static_cast<int>(...) instead '
+ '[readability/casting] [4]')))
+
+ # Like gMock method definitions, MockCallback instantiations look very similar
+ # to bad casts.
+ def testMockCallback(self):
+ self.TestLint(
+ 'MockCallback<bool(int)>',
+ '')
+ self.TestLint(
+ 'MockCallback<int(float, char)>',
+ '')
+
+ # Test false errors that happened with some include file names
+ def testIncludeFilenameFalseError(self):
+ self.TestLint(
+ '#include "foo/long-foo.h"',
+ '')
+ self.TestLint(
+ '#include "foo/sprintf.h"',
+ '')
+
+ # Test typedef cases. There was a bug that cpplint misidentified
+ # typedef for pointer to function as C-style cast and produced
+ # false-positive error messages.
+ def testTypedefForPointerToFunction(self):
+ self.TestLint(
+ 'typedef void (*Func)(int x);',
+ '')
+ self.TestLint(
+ 'typedef void (*Func)(int *x);',
+ '')
+ self.TestLint(
+ 'typedef void Func(int x);',
+ '')
+ self.TestLint(
+ 'typedef void Func(int *x);',
+ '')
+
+ def testIncludeWhatYouUseNoImplementationFiles(self):
+ code = 'std::vector<int> foo;'
+ self.assertEquals('Add #include <vector> for vector<>'
+ ' [build/include_what_you_use] [4]',
+ self.PerformIncludeWhatYouUse(code, 'foo.h'))
+ self.assertEquals('',
+ self.PerformIncludeWhatYouUse(code, 'foo.cc'))
+
+ def testIncludeWhatYouUse(self):
+ self.TestIncludeWhatYouUse(
+ """#include <vector>
+ std::vector<int> foo;
+ """,
+ '')
+ self.TestIncludeWhatYouUse(
+ """#include <map>
+ std::pair<int,int> foo;
+ """,
+ 'Add #include <utility> for pair<>'
+ ' [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include <multimap>
+ std::pair<int,int> foo;
+ """,
+ 'Add #include <utility> for pair<>'
+ ' [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include <hash_map>
+ std::pair<int,int> foo;
+ """,
+ 'Add #include <utility> for pair<>'
+ ' [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include <hash_map>
+ auto foo = std::make_pair(1, 2);
+ """,
+ 'Add #include <utility> for make_pair'
+ ' [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include <utility>
+ std::pair<int,int> foo;
+ """,
+ '')
+ self.TestIncludeWhatYouUse(
+ """#include <vector>
+ DECLARE_string(foobar);
+ """,
+ '')
+ self.TestIncludeWhatYouUse(
+ """#include <vector>
+ DEFINE_string(foobar, "", "");
+ """,
+ '')
+ self.TestIncludeWhatYouUse(
+ """#include <vector>
+ std::pair<int,int> foo;
+ """,
+ 'Add #include <utility> for pair<>'
+ ' [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include "base/foobar.h"
+ std::vector<int> foo;
+ """,
+ 'Add #include <vector> for vector<>'
+ ' [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include <vector>
+ std::set<int> foo;
+ """,
+ 'Add #include <set> for set<>'
+ ' [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include "base/foobar.h"
+ hash_map<int, int> foobar;
+ """,
+ 'Add #include <hash_map> for hash_map<>'
+ ' [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include "base/containers/hash_tables.h"
+ base::hash_map<int, int> foobar;
+ """,
+ '')
+ self.TestIncludeWhatYouUse(
+ """#include "base/foobar.h"
+ bool foobar = std::less<int>(0,1);
+ """,
+ 'Add #include <functional> for less<>'
+ ' [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include "base/foobar.h"
+ bool foobar = min<int>(0,1);
+ """,
+ 'Add #include <algorithm> for min [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ 'void a(const string &foobar);',
+ 'Add #include <string> for string [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ 'void a(const std::string &foobar);',
+ 'Add #include <string> for string [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ 'void a(const my::string &foobar);',
+ '') # Avoid false positives on strings in other namespaces.
+ self.TestIncludeWhatYouUse(
+ """#include "base/foobar.h"
+ bool foobar = swap(0,1);
+ """,
+ 'Add #include <utility> for swap [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include "base/foobar.h"
+ bool foobar = transform(a.begin(), a.end(), b.start(), Foo);
+ """,
+ 'Add #include <algorithm> for transform '
+ '[build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include "base/foobar.h"
+ bool foobar = min_element(a.begin(), a.end());
+ """,
+ 'Add #include <algorithm> for min_element '
+ '[build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """foo->swap(0,1);
+ foo.swap(0,1);
+ """,
+ '')
+ self.TestIncludeWhatYouUse(
+ """#include <string>
+ void a(const std::multimap<int,string> &foobar);
+ """,
+ 'Add #include <map> for multimap<>'
+ ' [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include <string>
+ void a(const std::unordered_map<int,string> &foobar);
+ """,
+ 'Add #include <unordered_map> for unordered_map<>'
+ ' [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include <string>
+ void a(const std::unordered_set<int> &foobar);
+ """,
+ 'Add #include <unordered_set> for unordered_set<>'
+ ' [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include <queue>
+ void a(const std::priority_queue<int> &foobar);
+ """,
+ '')
+ self.TestIncludeWhatYouUse(
+ """#include <assert.h>
+ #include <string>
+ #include <vector>
+ #include "base/basictypes.h"
+ #include "base/port.h"
+ vector<string> hajoa;""", '')
+ self.TestIncludeWhatYouUse(
+ """#include <string>
+ int i = numeric_limits<int>::max()
+ """,
+ 'Add #include <limits> for numeric_limits<>'
+ ' [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include <limits>
+ int i = numeric_limits<int>::max()
+ """,
+ '')
+ self.TestIncludeWhatYouUse(
+ """#include <string>
+ std::unique_ptr<int> x;
+ """,
+ 'Add #include <memory> for unique_ptr<>'
+ ' [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include <string>
+ auto x = std::make_unique<int>(0);
+ """,
+ 'Add #include <memory> for make_unique<>'
+ ' [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include <vector>
+ vector<int> foo(vector<int> x) { return std::move(x); }
+ """,
+ 'Add #include <utility> for move'
+ ' [build/include_what_you_use] [4]')
+ self.TestIncludeWhatYouUse(
+ """#include <string>
+ int a, b;
+ std::swap(a, b);
+ """,
+ 'Add #include <utility> for swap'
+ ' [build/include_what_you_use] [4]')
+
+ # Test the UpdateIncludeState code path.
+ mock_header_contents = ['#include "blah/foo.h"', '#include "blah/bar.h"']
+ message = self.PerformIncludeWhatYouUse(
+ '#include "blah/a.h"',
+ filename='blah/a.cc',
+ io=MockIo(mock_header_contents))
+ self.assertEquals(message, '')
+
+ mock_header_contents = ['#include <set>']
+ message = self.PerformIncludeWhatYouUse(
+ """#include "blah/a.h"
+ std::set<int> foo;""",
+ filename='blah/a.cc',
+ io=MockIo(mock_header_contents))
+ self.assertEquals(message, '')
+
+ # Make sure we can find the correct header file if the cc file seems to be
+ # a temporary file generated by Emacs's flymake.
+ mock_header_contents = ['']
+ message = self.PerformIncludeWhatYouUse(
+ """#include "blah/a.h"
+ std::set<int> foo;""",
+ filename='blah/a_flymake.cc',
+ io=MockIo(mock_header_contents))
+ self.assertEquals(message, 'Add #include <set> for set<> '
+ '[build/include_what_you_use] [4]')
+
+ # If there's just a cc and the header can't be found then it's ok.
+ message = self.PerformIncludeWhatYouUse(
+ """#include "blah/a.h"
+ std::set<int> foo;""",
+ filename='blah/a.cc')
+ self.assertEquals(message, '')
+
+ # Make sure we find the headers with relative paths.
+ mock_header_contents = ['']
+ message = self.PerformIncludeWhatYouUse(
+ """#include "%s/a.h"
+ std::set<int> foo;""" % os.path.basename(os.getcwd()),
+ filename='a.cc',
+ io=MockIo(mock_header_contents))
+ self.assertEquals(message, 'Add #include <set> for set<> '
+ '[build/include_what_you_use] [4]')
+
+ def testFilesBelongToSameModule(self):
+ f = cpplint.FilesBelongToSameModule
+ self.assertEquals((True, ''), f('a.cc', 'a.h'))
+ self.assertEquals((True, ''), f('base/google.cc', 'base/google.h'))
+ self.assertEquals((True, ''), f('base/google_test.cc', 'base/google.h'))
+ self.assertEquals((True, ''),
+ f('base/google_unittest.cc', 'base/google.h'))
+ self.assertEquals((True, ''),
+ f('base/internal/google_unittest.cc',
+ 'base/public/google.h'))
+ self.assertEquals((True, 'xxx/yyy/'),
+ f('xxx/yyy/base/internal/google_unittest.cc',
+ 'base/public/google.h'))
+ self.assertEquals((True, 'xxx/yyy/'),
+ f('xxx/yyy/base/google_unittest.cc',
+ 'base/public/google.h'))
+ self.assertEquals((True, ''),
+ f('base/google_unittest.cc', 'base/google-inl.h'))
+ self.assertEquals((True, '/home/build/google3/'),
+ f('/home/build/google3/base/google.cc', 'base/google.h'))
+
+ self.assertEquals((False, ''),
+ f('/home/build/google3/base/google.cc', 'basu/google.h'))
+ self.assertEquals((False, ''), f('a.cc', 'b.h'))
+
+ def testCleanseLine(self):
+ self.assertEquals('int foo = 0;',
+ cpplint.CleanseComments('int foo = 0; // danger!'))
+ self.assertEquals('int o = 0;',
+ cpplint.CleanseComments('int /* foo */ o = 0;'))
+ self.assertEquals('foo(int a, int b);',
+ cpplint.CleanseComments('foo(int a /* abc */, int b);'))
+ self.assertEqual('f(a, b);',
+ cpplint.CleanseComments('f(a, /* name */ b);'))
+ self.assertEqual('f(a, b);',
+ cpplint.CleanseComments('f(a /* name */, b);'))
+ self.assertEqual('f(a, b);',
+ cpplint.CleanseComments('f(a, /* name */b);'))
+ self.assertEqual('f(a, b, c);',
+ cpplint.CleanseComments('f(a, /**/b, /**/c);'))
+ self.assertEqual('f(a, b, c);',
+ cpplint.CleanseComments('f(a, /**/b/**/, c);'))
+
+ def testRawStrings(self):
+ self.TestMultiLineLint(
+ """
+ void Func() {
+ static const char kString[] = R"(
+ #endif <- invalid preprocessor should be ignored
+ */ <- invalid comment should be ignored too
+ )";
+ }""",
+ '')
+ self.TestMultiLineLint(
+ """
+ void Func() {
+ string s = R"TrueDelimiter(
+ )"
+ )FalseDelimiter"
+ )TrueDelimiter";
+ }""",
+ '')
+ self.TestMultiLineLint(
+ """
+ void Func() {
+ char char kString[] = R"( ";" )";
+ }""",
+ '')
+ self.TestMultiLineLint(
+ """
+ static const char kRawString[] = R"(
+ \tstatic const int kLineWithTab = 1;
+ static const int kLineWithTrailingWhiteSpace = 1;\x20
+
+ void WeirdNumberOfSpacesAtLineStart() {
+ string x;
+ x += StrCat("Use StrAppend instead");
+ }
+
+ void BlankLineAtEndOfBlock() {
+ // TODO incorrectly formatted
+ //Badly formatted comment
+
+ }
+
+ )";""",
+ '')
+ self.TestMultiLineLint(
+ """
+ void Func() {
+ string s = StrCat(R"TrueDelimiter(
+ )"
+ )FalseDelimiter"
+ )TrueDelimiter", R"TrueDelimiter2(
+ )"
+ )FalseDelimiter2"
+ )TrueDelimiter2");
+ }""",
+ '')
+ self.TestMultiLineLint(
+ """
+ static SomeStruct kData = {
+ {0, R"(line1
+ line2
+ )"}
+ };""",
+ '')
+
+ def testMultiLineComments(self):
+ # missing explicit is bad
+ self.TestMultiLineLint(
+ r"""int a = 0;
+ /* multi-liner
+ class Foo {
+ Foo(int f); // should cause a lint warning in code
+ }
+ */ """,
+ '')
+ self.TestMultiLineLint(
+ r"""/* int a = 0; multi-liner
+ static const int b = 0;""",
+ 'Could not find end of multi-line comment'
+ ' [readability/multiline_comment] [5]')
+ self.TestMultiLineLint(r""" /* multi-line comment""",
+ 'Could not find end of multi-line comment'
+ ' [readability/multiline_comment] [5]')
+ self.TestMultiLineLint(r""" // /* comment, but not multi-line""", '')
+ self.TestMultiLineLint(r"""/**********
+ */""", '')
+ self.TestMultiLineLint(r"""/**
+ * Doxygen comment
+ */""",
+ '')
+ self.TestMultiLineLint(r"""/*!
+ * Doxygen comment
+ */""",
+ '')
+
+ def testMultilineStrings(self):
+ multiline_string_error_message = (
+ 'Multi-line string ("...") found. This lint script doesn\'t '
+ 'do well with such strings, and may give bogus warnings. '
+ 'Use C++11 raw strings or concatenation instead.'
+ ' [readability/multiline_string] [5]')
+
+ file_path = 'mydir/foo.cc'
+
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'cc',
+ ['const char* str = "This is a\\',
+ ' multiline string.";'],
+ error_collector)
+ self.assertEquals(
+ 2, # One per line.
+ error_collector.ResultList().count(multiline_string_error_message))
+
+ # Test non-explicit single-argument constructors
+ def testExplicitSingleArgumentConstructors(self):
+ old_verbose_level = cpplint._cpplint_state.verbose_level
+ cpplint._cpplint_state.verbose_level = 0
+
+ try:
+ # missing explicit is bad
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ Foo(int f);
+ };""",
+ 'Single-parameter constructors should be marked explicit.'
+ ' [runtime/explicit] [5]')
+ # missing explicit is bad, even with whitespace
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ Foo (int f);
+ };""",
+ ['Extra space before ( in function call [whitespace/parens] [4]',
+ 'Single-parameter constructors should be marked explicit.'
+ ' [runtime/explicit] [5]'])
+ # missing explicit, with distracting comment, is still bad
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ Foo(int f); // simpler than Foo(blargh, blarg)
+ };""",
+ 'Single-parameter constructors should be marked explicit.'
+ ' [runtime/explicit] [5]')
+ # missing explicit, with qualified classname
+ self.TestMultiLineLint(
+ """
+ class Qualifier::AnotherOne::Foo {
+ Foo(int f);
+ };""",
+ 'Single-parameter constructors should be marked explicit.'
+ ' [runtime/explicit] [5]')
+ # missing explicit for inline constructors is bad as well
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ inline Foo(int f);
+ };""",
+ 'Single-parameter constructors should be marked explicit.'
+ ' [runtime/explicit] [5]')
+ # missing explicit for constexpr constructors is bad as well
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ constexpr Foo(int f);
+ };""",
+ 'Single-parameter constructors should be marked explicit.'
+ ' [runtime/explicit] [5]')
+ # missing explicit for constexpr+inline constructors is bad as well
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ constexpr inline Foo(int f);
+ };""",
+ 'Single-parameter constructors should be marked explicit.'
+ ' [runtime/explicit] [5]')
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ inline constexpr Foo(int f);
+ };""",
+ 'Single-parameter constructors should be marked explicit.'
+ ' [runtime/explicit] [5]')
+ # explicit with inline is accepted
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ inline explicit Foo(int f);
+ };""",
+ '')
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ explicit inline Foo(int f);
+ };""",
+ '')
+ # explicit with constexpr is accepted
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ constexpr explicit Foo(int f);
+ };""",
+ '')
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ explicit constexpr Foo(int f);
+ };""",
+ '')
+ # explicit with constexpr+inline is accepted
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ inline constexpr explicit Foo(int f);
+ };""",
+ '')
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ explicit inline constexpr Foo(int f);
+ };""",
+ '')
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ constexpr inline explicit Foo(int f);
+ };""",
+ '')
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ explicit constexpr inline Foo(int f);
+ };""",
+ '')
+ # structs are caught as well.
+ self.TestMultiLineLint(
+ """
+ struct Foo {
+ Foo(int f);
+ };""",
+ 'Single-parameter constructors should be marked explicit.'
+ ' [runtime/explicit] [5]')
+ # Templatized classes are caught as well.
+ self.TestMultiLineLint(
+ """
+ template<typename T> class Foo {
+ Foo(int f);
+ };""",
+ 'Single-parameter constructors should be marked explicit.'
+ ' [runtime/explicit] [5]')
+ # inline case for templatized classes.
+ self.TestMultiLineLint(
+ """
+ template<typename T> class Foo {
+ inline Foo(int f);
+ };""",
+ 'Single-parameter constructors should be marked explicit.'
+ ' [runtime/explicit] [5]')
+ # constructors with a default argument should still be marked explicit
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ Foo(int f = 0);
+ };""",
+ 'Constructors callable with one argument should be marked explicit.'
+ ' [runtime/explicit] [5]')
+ # multi-argument constructors with all but one default argument should be
+ # marked explicit
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ Foo(int f, int g = 0);
+ };""",
+ 'Constructors callable with one argument should be marked explicit.'
+ ' [runtime/explicit] [5]')
+ # multi-argument constructors with all default arguments should be marked
+ # explicit
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ Foo(int f = 0, int g = 0);
+ };""",
+ 'Constructors callable with one argument should be marked explicit.'
+ ' [runtime/explicit] [5]')
+ # explicit no-argument constructors are bad
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ explicit Foo();
+ };""",
+ 'Zero-parameter constructors should not be marked explicit.'
+ ' [runtime/explicit] [5]')
+ # void constructors are considered no-argument
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ explicit Foo(void);
+ };""",
+ 'Zero-parameter constructors should not be marked explicit.'
+ ' [runtime/explicit] [5]')
+ # No warning for multi-parameter constructors
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ explicit Foo(int f, int g);
+ };""",
+ '')
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ explicit Foo(int f, int g = 0);
+ };""",
+ '')
+ # single-argument constructors that take a function that takes multiple
+ # arguments should be explicit
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ Foo(void (*f)(int f, int g));
+ };""",
+ 'Single-parameter constructors should be marked explicit.'
+ ' [runtime/explicit] [5]')
+ # single-argument constructors that take a single template argument with
+ # multiple parameters should be explicit
+ self.TestMultiLineLint(
+ """
+ template <typename T, typename S>
+ class Foo {
+ Foo(Bar<T, S> b);
+ };""",
+ 'Single-parameter constructors should be marked explicit.'
+ ' [runtime/explicit] [5]')
+ # but copy constructors that take multiple template parameters are OK
+ self.TestMultiLineLint(
+ """
+ template <typename T, S>
+ class Foo {
+ Foo(Foo<T, S>& f);
+ };""",
+ '')
+ # proper style is okay
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ explicit Foo(int f);
+ };""",
+ '')
+ # two argument constructor is okay
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ Foo(int f, int b);
+ };""",
+ '')
+ # two argument constructor, across two lines, is okay
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ Foo(int f,
+ int b);
+ };""",
+ '')
+ # non-constructor (but similar name), is okay
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ aFoo(int f);
+ };""",
+ '')
+ # constructor with void argument is okay
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ Foo(void);
+ };""",
+ '')
+ # single argument method is okay
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ Bar(int b);
+ };""",
+ '')
+ # comments should be ignored
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ // Foo(int f);
+ };""",
+ '')
+ # single argument function following class definition is okay
+ # (okay, it's not actually valid, but we don't want a false positive)
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ Foo(int f, int b);
+ };
+ Foo(int f);""",
+ '')
+ # single argument function is okay
+ self.TestMultiLineLint(
+ """static Foo(int f);""",
+ '')
+ # single argument copy constructor is okay.
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ Foo(const Foo&);
+ };""",
+ '')
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ Foo(Foo const&);
+ };""",
+ '')
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ Foo(Foo&);
+ };""",
+ '')
+ # templatized copy constructor is okay.
+ self.TestMultiLineLint(
+ """
+ template<typename T> class Foo {
+ Foo(const Foo<T>&);
+ };""",
+ '')
+ # Special case for std::initializer_list
+ self.TestMultiLineLint(
+ """
+ class Foo {
+ Foo(std::initializer_list<T> &arg) {}
+ };""",
+ '')
+ # Anything goes inside an assembly block
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc',
+ ['void Func() {',
+ ' __asm__ (',
+ ' "hlt"',
+ ' );',
+ ' asm {',
+ ' movdqa [edx + 32], xmm2',
+ ' }',
+ '}'],
+ error_collector)
+ self.assertEquals(
+ 0,
+ error_collector.ResultList().count(
+ 'Extra space before ( in function call [whitespace/parens] [4]'))
+ self.assertEquals(
+ 0,
+ error_collector.ResultList().count(
+ 'Closing ) should be moved to the previous line '
+ '[whitespace/parens] [2]'))
+ self.assertEquals(
+ 0,
+ error_collector.ResultList().count(
+ 'Extra space before [ [whitespace/braces] [5]'))
+ finally:
+ cpplint._cpplint_state.verbose_level = old_verbose_level
+
+ def testSlashStarCommentOnSingleLine(self):
+ self.TestMultiLineLint(
+ """/* static */ Foo(int f);""",
+ '')
+ self.TestMultiLineLint(
+ """/*/ static */ Foo(int f);""",
+ '')
+ self.TestMultiLineLint(
+ """/*/ static Foo(int f);""",
+ 'Could not find end of multi-line comment'
+ ' [readability/multiline_comment] [5]')
+ self.TestMultiLineLint(
+ """ /*/ static Foo(int f);""",
+ 'Could not find end of multi-line comment'
+ ' [readability/multiline_comment] [5]')
+ self.TestMultiLineLint(
+ """ /**/ static Foo(int f);""",
+ '')
+
+ # Test suspicious usage of "if" like this:
+ # if (a == b) {
+ # DoSomething();
+ # } if (a == c) { // Should be "else if".
+ # DoSomething(); // This gets called twice if a == b && a == c.
+ # }
+ def testSuspiciousUsageOfIf(self):
+ self.TestLint(
+ ' if (a == b) {',
+ '')
+ self.TestLint(
+ ' } if (a == b) {',
+ 'Did you mean "else if"? If not, start a new line for "if".'
+ ' [readability/braces] [4]')
+
+ # Test suspicious usage of memset. Specifically, a 0
+ # as the final argument is almost certainly an error.
+ def testSuspiciousUsageOfMemset(self):
+ # Normal use is okay.
+ self.TestLint(
+ ' memset(buf, 0, sizeof(buf))',
+ '')
+
+ # A 0 as the final argument is almost certainly an error.
+ self.TestLint(
+ ' memset(buf, sizeof(buf), 0)',
+ 'Did you mean "memset(buf, 0, sizeof(buf))"?'
+ ' [runtime/memset] [4]')
+ self.TestLint(
+ ' memset(buf, xsize * ysize, 0)',
+ 'Did you mean "memset(buf, 0, xsize * ysize)"?'
+ ' [runtime/memset] [4]')
+
+ # There is legitimate test code that uses this form.
+ # This is okay since the second argument is a literal.
+ self.TestLint(
+ " memset(buf, 'y', 0)",
+ '')
+ self.TestLint(
+ ' memset(buf, 4, 0)',
+ '')
+ self.TestLint(
+ ' memset(buf, -1, 0)',
+ '')
+ self.TestLint(
+ ' memset(buf, 0xF1, 0)',
+ '')
+ self.TestLint(
+ ' memset(buf, 0xcd, 0)',
+ '')
+
+ def testRedundantVirtual(self):
+ self.TestLint('virtual void F()', '')
+ self.TestLint('virtual void F();', '')
+ self.TestLint('virtual void F() {}', '')
+
+ message_template = ('"%s" is redundant since function is already '
+ 'declared as "%s" [readability/inheritance] [4]')
+ for virt_specifier in ['override', 'final']:
+ error_message = message_template % ('virtual', virt_specifier)
+ self.TestLint('virtual int F() %s' % virt_specifier, error_message)
+ self.TestLint('virtual int F() %s;' % virt_specifier, error_message)
+ self.TestLint('virtual int F() %s {' % virt_specifier, error_message)
+
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(
+ 'foo.cc', 'cc',
+ ['// Copyright 2014 Your Company.',
+ 'virtual void F(int a,',
+ ' int b) ' + virt_specifier + ';',
+ 'virtual void F(int a,',
+ ' int b) LOCKS_EXCLUDED(lock) ' + virt_specifier + ';',
+ 'virtual void F(int a,',
+ ' int b)',
+ ' LOCKS_EXCLUDED(lock) ' + virt_specifier + ';',
+ ''],
+ error_collector)
+ self.assertEquals(
+ [error_message, error_message, error_message],
+ error_collector.Results())
+
+ error_message = message_template % ('override', 'final')
+ self.TestLint('int F() override final', error_message)
+ self.TestLint('int F() override final;', error_message)
+ self.TestLint('int F() override final {}', error_message)
+ self.TestLint('int F() final override', error_message)
+ self.TestLint('int F() final override;', error_message)
+ self.TestLint('int F() final override {}', error_message)
+
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(
+ 'foo.cc', 'cc',
+ ['// Copyright 2014 Your Company.',
+ 'struct A : virtual B {',
+ ' ~A() override;'
+ '};',
+ 'class C',
+ ' : public D,',
+ ' public virtual E {',
+ ' void Func() override;',
+ '}',
+ ''],
+ error_collector)
+ self.assertEquals('', error_collector.Results())
+
+ self.TestLint('void Finalize(AnnotationProto *final) override;', '')
+
+ def testCheckDeprecated(self):
+ self.TestLanguageRulesCheck('foo_test.cc', '#include <iostream>', '')
+ self.TestLanguageRulesCheck('foo_unittest.cc', '#include <iostream>', '')
+
+ def testCheckPosixThreading(self):
+ self.TestLint('var = sctime_r()', '')
+ self.TestLint('var = strtok_r()', '')
+ self.TestLint('var = strtok_r(foo, ba, r)', '')
+ self.TestLint('var = brand()', '')
+ self.TestLint('_rand()', '')
+ self.TestLint('.rand()', '')
+ self.TestLint('->rand()', '')
+ self.TestLint('ACMRandom rand(seed)', '')
+ self.TestLint('ISAACRandom rand()', '')
+ self.TestLint('var = rand()',
+ 'Consider using rand_r(...) instead of rand(...)'
+ ' for improved thread safety.'
+ ' [runtime/threadsafe_fn] [2]')
+ self.TestLint('var = strtok(str, delim)',
+ 'Consider using strtok_r(...) '
+ 'instead of strtok(...)'
+ ' for improved thread safety.'
+ ' [runtime/threadsafe_fn] [2]')
+
+ def testVlogMisuse(self):
+ self.TestLint('VLOG(1)', '')
+ self.TestLint('VLOG(99)', '')
+ self.TestLint('LOG(ERROR)', '')
+ self.TestLint('LOG(INFO)', '')
+ self.TestLint('LOG(WARNING)', '')
+ self.TestLint('LOG(FATAL)', '')
+ self.TestLint('LOG(DFATAL)', '')
+ self.TestLint('VLOG(SOMETHINGWEIRD)', '')
+ self.TestLint('MYOWNVLOG(ERROR)', '')
+ errmsg = ('VLOG() should be used with numeric verbosity level. '
+ 'Use LOG() if you want symbolic severity levels.'
+ ' [runtime/vlog] [5]')
+ self.TestLint('VLOG(ERROR)', errmsg)
+ self.TestLint('VLOG(INFO)', errmsg)
+ self.TestLint('VLOG(WARNING)', errmsg)
+ self.TestLint('VLOG(FATAL)', errmsg)
+ self.TestLint('VLOG(DFATAL)', errmsg)
+ self.TestLint(' VLOG(ERROR)', errmsg)
+ self.TestLint(' VLOG(INFO)', errmsg)
+ self.TestLint(' VLOG(WARNING)', errmsg)
+ self.TestLint(' VLOG(FATAL)', errmsg)
+ self.TestLint(' VLOG(DFATAL)', errmsg)
+
+
+ # Test potential format string bugs like printf(foo).
+ def testFormatStrings(self):
+ self.TestLint('printf("foo")', '')
+ self.TestLint('printf("foo: %s", foo)', '')
+ self.TestLint('DocidForPrintf(docid)', '') # Should not trigger.
+ self.TestLint('printf(format, value)', '') # Should not trigger.
+ self.TestLint('printf(__VA_ARGS__)', '') # Should not trigger.
+ self.TestLint('printf(format.c_str(), value)', '') # Should not trigger.
+ self.TestLint('printf(format(index).c_str(), value)', '')
+ self.TestLint(
+ 'printf(foo)',
+ 'Potential format string bug. Do printf("%s", foo) instead.'
+ ' [runtime/printf] [4]')
+ self.TestLint(
+ 'printf(foo.c_str())',
+ 'Potential format string bug. '
+ 'Do printf("%s", foo.c_str()) instead.'
+ ' [runtime/printf] [4]')
+ self.TestLint(
+ 'printf(foo->c_str())',
+ 'Potential format string bug. '
+ 'Do printf("%s", foo->c_str()) instead.'
+ ' [runtime/printf] [4]')
+ self.TestLint(
+ 'StringPrintf(foo)',
+ 'Potential format string bug. Do StringPrintf("%s", foo) instead.'
+ ''
+ ' [runtime/printf] [4]')
+
+ # Test disallowed use of operator& and other operators.
+ def testIllegalOperatorOverloading(self):
+ errmsg = ('Unary operator& is dangerous. Do not use it.'
+ ' [runtime/operator] [4]')
+ self.TestLint('void operator=(const Myclass&)', '')
+ self.TestLint('void operator&(int a, int b)', '') # binary operator& ok
+ self.TestLint('void operator&() { }', errmsg)
+ self.TestLint('void operator & ( ) { }',
+ ['Extra space after ( [whitespace/parens] [2]', errmsg])
+
+ # const string reference members are dangerous..
+ def testConstStringReferenceMembers(self):
+ errmsg = ('const string& members are dangerous. It is much better to use '
+ 'alternatives, such as pointers or simple constants.'
+ ' [runtime/member_string_references] [2]')
+
+ members_declarations = ['const string& church',
+ 'const string &turing',
+ 'const string & godel']
+ # TODO(unknown): Enable also these tests if and when we ever
+ # decide to check for arbitrary member references.
+ # "const Turing & a",
+ # "const Church& a",
+ # "const vector<int>& a",
+ # "const Kurt::Godel & godel",
+ # "const Kazimierz::Kuratowski& kk" ]
+
+ # The Good.
+
+ self.TestLint('void f(const string&)', '')
+ self.TestLint('const string& f(const string& a, const string& b)', '')
+ self.TestLint('typedef const string& A;', '')
+
+ for decl in members_declarations:
+ self.TestLint(decl + ' = b;', '')
+ self.TestLint(decl + ' =', '')
+
+ # The Bad.
+
+ for decl in members_declarations:
+ self.TestLint(decl + ';', errmsg)
+
+ # Variable-length arrays are not permitted.
+ def testVariableLengthArrayDetection(self):
+ errmsg = ('Do not use variable-length arrays. Use an appropriately named '
+ "('k' followed by CamelCase) compile-time constant for the size."
+ ' [runtime/arrays] [1]')
+
+ self.TestLint('int a[any_old_variable];', errmsg)
+ self.TestLint('int doublesize[some_var * 2];', errmsg)
+ self.TestLint('int a[afunction()];', errmsg)
+ self.TestLint('int a[function(kMaxFooBars)];', errmsg)
+ self.TestLint('bool a_list[items_->size()];', errmsg)
+ self.TestLint('namespace::Type buffer[len+1];', errmsg)
+
+ self.TestLint('int a[64];', '')
+ self.TestLint('int a[0xFF];', '')
+ self.TestLint('int first[256], second[256];', '')
+ self.TestLint('int array_name[kCompileTimeConstant];', '')
+ self.TestLint('char buf[somenamespace::kBufSize];', '')
+ self.TestLint('int array_name[ALL_CAPS];', '')
+ self.TestLint('AClass array1[foo::bar::ALL_CAPS];', '')
+ self.TestLint('int a[kMaxStrLen + 1];', '')
+ self.TestLint('int a[sizeof(foo)];', '')
+ self.TestLint('int a[sizeof(*foo)];', '')
+ self.TestLint('int a[sizeof foo];', '')
+ self.TestLint('int a[sizeof(struct Foo)];', '')
+ self.TestLint('int a[128 - sizeof(const bar)];', '')
+ self.TestLint('int a[(sizeof(foo) * 4)];', '')
+ self.TestLint('int a[(arraysize(fixed_size_array)/2) << 1];', '')
+ self.TestLint('delete a[some_var];', '')
+ self.TestLint('return a[some_var];', '')
+
+ # DISALLOW_COPY_AND_ASSIGN and DISALLOW_IMPLICIT_CONSTRUCTORS should be at
+ # end of class if present.
+ def testDisallowMacrosAtEnd(self):
+ for macro_name in (
+ 'DISALLOW_COPY_AND_ASSIGN',
+ 'DISALLOW_IMPLICIT_CONSTRUCTORS'):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(
+ 'foo.cc', 'cc',
+ ['// Copyright 2014 Your Company.',
+ 'class SomeClass {',
+ ' private:',
+ ' %s(SomeClass);' % macro_name,
+ ' int member_;',
+ '};',
+ ''],
+ error_collector)
+ self.assertEquals(
+ ('%s should be the last thing in the class' % macro_name) +
+ ' [readability/constructors] [3]',
+ error_collector.Results())
+
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(
+ 'foo.cc', 'cc',
+ ['// Copyright 2014 Your Company.',
+ 'class OuterClass {',
+ ' private:',
+ ' struct InnerClass {',
+ ' private:',
+ ' %s(InnerClass);' % macro_name,
+ ' int member;',
+ ' };',
+ '};',
+ ''],
+ error_collector)
+ self.assertEquals(
+ ('%s should be the last thing in the class' % macro_name) +
+ ' [readability/constructors] [3]',
+ error_collector.Results())
+
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(
+ 'foo.cc', 'cc',
+ ['// Copyright 2014 Your Company.',
+ 'class OuterClass1 {',
+ ' private:',
+ ' struct InnerClass1 {',
+ ' private:',
+ ' %s(InnerClass1);' % macro_name,
+ ' };',
+ ' %s(OuterClass1);' % macro_name,
+ '};',
+ 'struct OuterClass2 {',
+ ' private:',
+ ' class InnerClass2 {',
+ ' private:',
+ ' %s(InnerClass2);' % macro_name,
+ ' // comment',
+ ' };',
+ '',
+ ' %s(OuterClass2);' % macro_name,
+ '',
+ ' // comment',
+ '};',
+ 'void Func() {',
+ ' struct LocalClass {',
+ ' private:',
+ ' %s(LocalClass);' % macro_name,
+ ' } variable;',
+ '}',
+ ''],
+ error_collector)
+ self.assertEquals('', error_collector.Results())
+
+ # Brace usage
+ def testBraces(self):
+ # Braces shouldn't be followed by a ; unless they're defining a struct
+ # or initializing an array
+ self.TestLint('int a[3] = { 1, 2, 3 };', '')
+ self.TestLint(
+ """const int foo[] =
+ {1, 2, 3 };""",
+ '')
+ # For single line, unmatched '}' with a ';' is ignored (not enough context)
+ self.TestMultiLineLint(
+ """int a[3] = { 1,
+ 2,
+ 3 };""",
+ '')
+ self.TestMultiLineLint(
+ """int a[2][3] = { { 1, 2 },
+ { 3, 4 } };""",
+ '')
+ self.TestMultiLineLint(
+ """int a[2][3] =
+ { { 1, 2 },
+ { 3, 4 } };""",
+ '')
+
+ # CHECK/EXPECT_TRUE/EXPECT_FALSE replacements
+ def testCheckCheck(self):
+ self.TestLint('CHECK(x == 42);',
+ 'Consider using CHECK_EQ instead of CHECK(a == b)'
+ ' [readability/check] [2]')
+ self.TestLint('CHECK(x != 42);',
+ 'Consider using CHECK_NE instead of CHECK(a != b)'
+ ' [readability/check] [2]')
+ self.TestLint('CHECK(x >= 42);',
+ 'Consider using CHECK_GE instead of CHECK(a >= b)'
+ ' [readability/check] [2]')
+ self.TestLint('CHECK(x > 42);',
+ 'Consider using CHECK_GT instead of CHECK(a > b)'
+ ' [readability/check] [2]')
+ self.TestLint('CHECK(x <= 42);',
+ 'Consider using CHECK_LE instead of CHECK(a <= b)'
+ ' [readability/check] [2]')
+ self.TestLint('CHECK(x < 42);',
+ 'Consider using CHECK_LT instead of CHECK(a < b)'
+ ' [readability/check] [2]')
+
+ self.TestLint('DCHECK(x == 42);',
+ 'Consider using DCHECK_EQ instead of DCHECK(a == b)'
+ ' [readability/check] [2]')
+ self.TestLint('DCHECK(x != 42);',
+ 'Consider using DCHECK_NE instead of DCHECK(a != b)'
+ ' [readability/check] [2]')
+ self.TestLint('DCHECK(x >= 42);',
+ 'Consider using DCHECK_GE instead of DCHECK(a >= b)'
+ ' [readability/check] [2]')
+ self.TestLint('DCHECK(x > 42);',
+ 'Consider using DCHECK_GT instead of DCHECK(a > b)'
+ ' [readability/check] [2]')
+ self.TestLint('DCHECK(x <= 42);',
+ 'Consider using DCHECK_LE instead of DCHECK(a <= b)'
+ ' [readability/check] [2]')
+ self.TestLint('DCHECK(x < 42);',
+ 'Consider using DCHECK_LT instead of DCHECK(a < b)'
+ ' [readability/check] [2]')
+
+ self.TestLint(
+ 'EXPECT_TRUE("42" == x);',
+ 'Consider using EXPECT_EQ instead of EXPECT_TRUE(a == b)'
+ ' [readability/check] [2]')
+ self.TestLint(
+ 'EXPECT_TRUE("42" != x);',
+ 'Consider using EXPECT_NE instead of EXPECT_TRUE(a != b)'
+ ' [readability/check] [2]')
+ self.TestLint(
+ 'EXPECT_TRUE(+42 >= x);',
+ 'Consider using EXPECT_GE instead of EXPECT_TRUE(a >= b)'
+ ' [readability/check] [2]')
+
+ self.TestLint(
+ 'EXPECT_FALSE(x == 42);',
+ 'Consider using EXPECT_NE instead of EXPECT_FALSE(a == b)'
+ ' [readability/check] [2]')
+ self.TestLint(
+ 'EXPECT_FALSE(x != 42);',
+ 'Consider using EXPECT_EQ instead of EXPECT_FALSE(a != b)'
+ ' [readability/check] [2]')
+ self.TestLint(
+ 'EXPECT_FALSE(x >= 42);',
+ 'Consider using EXPECT_LT instead of EXPECT_FALSE(a >= b)'
+ ' [readability/check] [2]')
+ self.TestLint(
+ 'ASSERT_FALSE(x > 42);',
+ 'Consider using ASSERT_LE instead of ASSERT_FALSE(a > b)'
+ ' [readability/check] [2]')
+ self.TestLint(
+ 'ASSERT_FALSE(x <= 42);',
+ 'Consider using ASSERT_GT instead of ASSERT_FALSE(a <= b)'
+ ' [readability/check] [2]')
+
+ self.TestLint('CHECK(x<42);',
+ ['Missing spaces around <'
+ ' [whitespace/operators] [3]',
+ 'Consider using CHECK_LT instead of CHECK(a < b)'
+ ' [readability/check] [2]'])
+ self.TestLint('CHECK(x>42);',
+ ['Missing spaces around >'
+ ' [whitespace/operators] [3]',
+ 'Consider using CHECK_GT instead of CHECK(a > b)'
+ ' [readability/check] [2]'])
+
+ self.TestLint('using some::namespace::operator<<;', '')
+ self.TestLint('using some::namespace::operator>>;', '')
+
+ self.TestLint('CHECK(x->y == 42);',
+ 'Consider using CHECK_EQ instead of CHECK(a == b)'
+ ' [readability/check] [2]')
+
+ self.TestLint(
+ ' EXPECT_TRUE(42 < x); // Random comment.',
+ 'Consider using EXPECT_LT instead of EXPECT_TRUE(a < b)'
+ ' [readability/check] [2]')
+ self.TestLint(
+ 'EXPECT_TRUE( 42 < x );',
+ ['Extra space after ( in function call'
+ ' [whitespace/parens] [4]',
+ 'Extra space before ) [whitespace/parens] [2]',
+ 'Consider using EXPECT_LT instead of EXPECT_TRUE(a < b)'
+ ' [readability/check] [2]'])
+
+ self.TestLint('CHECK(4\'2 == x);',
+ 'Consider using CHECK_EQ instead of CHECK(a == b)'
+ ' [readability/check] [2]')
+
+ def testCheckCheckFalsePositives(self):
+ self.TestLint('CHECK(some_iterator == obj.end());', '')
+ self.TestLint('EXPECT_TRUE(some_iterator == obj.end());', '')
+ self.TestLint('EXPECT_FALSE(some_iterator == obj.end());', '')
+ self.TestLint('CHECK(some_pointer != NULL);', '')
+ self.TestLint('EXPECT_TRUE(some_pointer != NULL);', '')
+ self.TestLint('EXPECT_FALSE(some_pointer != NULL);', '')
+
+ self.TestLint('CHECK(CreateTestFile(dir, (1 << 20)));', '')
+ self.TestLint('CHECK(CreateTestFile(dir, (1 >> 20)));', '')
+
+ self.TestLint('CHECK(x ^ (y < 42));', '')
+ self.TestLint('CHECK((x > 42) ^ (x < 54));', '')
+ self.TestLint('CHECK(a && b < 42);', '')
+ self.TestLint('CHECK(42 < a && a < b);', '')
+ self.TestLint('SOFT_CHECK(x > 42);', '')
+
+ self.TestMultiLineLint(
+ """_STLP_DEFINE_BINARY_OP_CHECK(==, _OP_EQUAL);
+ _STLP_DEFINE_BINARY_OP_CHECK(!=, _OP_NOT_EQUAL);
+ _STLP_DEFINE_BINARY_OP_CHECK(<, _OP_LESS_THAN);
+ _STLP_DEFINE_BINARY_OP_CHECK(<=, _OP_LESS_EQUAL);
+ _STLP_DEFINE_BINARY_OP_CHECK(>, _OP_GREATER_THAN);
+ _STLP_DEFINE_BINARY_OP_CHECK(>=, _OP_GREATER_EQUAL);
+ _STLP_DEFINE_BINARY_OP_CHECK(+, _OP_PLUS);
+ _STLP_DEFINE_BINARY_OP_CHECK(*, _OP_TIMES);
+ _STLP_DEFINE_BINARY_OP_CHECK(/, _OP_DIVIDE);
+ _STLP_DEFINE_BINARY_OP_CHECK(-, _OP_SUBTRACT);
+ _STLP_DEFINE_BINARY_OP_CHECK(%, _OP_MOD);""",
+ '')
+
+ self.TestLint('CHECK(x < 42) << "Custom error message";', '')
+
+ # Alternative token to punctuation operator replacements
+ def testCheckAltTokens(self):
+ self.TestLint('true or true',
+ 'Use operator || instead of or'
+ ' [readability/alt_tokens] [2]')
+ self.TestLint('true and true',
+ 'Use operator && instead of and'
+ ' [readability/alt_tokens] [2]')
+ self.TestLint('if (not true)',
+ 'Use operator ! instead of not'
+ ' [readability/alt_tokens] [2]')
+ self.TestLint('1 bitor 1',
+ 'Use operator | instead of bitor'
+ ' [readability/alt_tokens] [2]')
+ self.TestLint('1 xor 1',
+ 'Use operator ^ instead of xor'
+ ' [readability/alt_tokens] [2]')
+ self.TestLint('1 bitand 1',
+ 'Use operator & instead of bitand'
+ ' [readability/alt_tokens] [2]')
+ self.TestLint('x = compl 1',
+ 'Use operator ~ instead of compl'
+ ' [readability/alt_tokens] [2]')
+ self.TestLint('x and_eq y',
+ 'Use operator &= instead of and_eq'
+ ' [readability/alt_tokens] [2]')
+ self.TestLint('x or_eq y',
+ 'Use operator |= instead of or_eq'
+ ' [readability/alt_tokens] [2]')
+ self.TestLint('x xor_eq y',
+ 'Use operator ^= instead of xor_eq'
+ ' [readability/alt_tokens] [2]')
+ self.TestLint('x not_eq y',
+ 'Use operator != instead of not_eq'
+ ' [readability/alt_tokens] [2]')
+ self.TestLint('line_continuation or',
+ 'Use operator || instead of or'
+ ' [readability/alt_tokens] [2]')
+ self.TestLint('if(true and(parentheses',
+ 'Use operator && instead of and'
+ ' [readability/alt_tokens] [2]')
+
+ self.TestLint('#include "base/false-and-false.h"', '')
+ self.TestLint('#error false or false', '')
+ self.TestLint('false nor false', '')
+ self.TestLint('false nand false', '')
+
+ # Passing and returning non-const references
+ def testNonConstReference(self):
+ # Passing a non-const reference as function parameter is forbidden.
+ operand_error_message = ('Is this a non-const reference? '
+ 'If so, make const or use a pointer: %s'
+ ' [runtime/references] [2]')
+ # Warn of use of a non-const reference in operators and functions
+ self.TestLint('bool operator>(Foo& s, Foo& f);',
+ [operand_error_message % 'Foo& s',
+ operand_error_message % 'Foo& f'])
+ self.TestLint('bool operator+(Foo& s, Foo& f);',
+ [operand_error_message % 'Foo& s',
+ operand_error_message % 'Foo& f'])
+ self.TestLint('int len(Foo& s);', operand_error_message % 'Foo& s')
+ # Allow use of non-const references in a few specific cases
+ self.TestLint('stream& operator>>(stream& s, Foo& f);', '')
+ self.TestLint('stream& operator<<(stream& s, Foo& f);', '')
+ self.TestLint('void swap(Bar& a, Bar& b);', '')
+ self.TestLint('ostream& LogFunc(ostream& s);', '')
+ self.TestLint('ostringstream& LogFunc(ostringstream& s);', '')
+ self.TestLint('istream& LogFunc(istream& s);', '')
+ self.TestLint('istringstream& LogFunc(istringstream& s);', '')
+ # Returning a non-const reference from a function is OK.
+ self.TestLint('int& g();', '')
+ # Passing a const reference to a struct (using the struct keyword) is OK.
+ self.TestLint('void foo(const struct tm& tm);', '')
+ # Passing a const reference to a typename is OK.
+ self.TestLint('void foo(const typename tm& tm);', '')
+ # Const reference to a pointer type is OK.
+ self.TestLint('void foo(const Bar* const& p) {', '')
+ self.TestLint('void foo(Bar const* const& p) {', '')
+ self.TestLint('void foo(Bar* const& p) {', '')
+ # Const reference to a templated type is OK.
+ self.TestLint('void foo(const std::vector<std::string>& v);', '')
+ # Non-const reference to a pointer type is not OK.
+ self.TestLint('void foo(Bar*& p);',
+ operand_error_message % 'Bar*& p')
+ self.TestLint('void foo(const Bar*& p);',
+ operand_error_message % 'const Bar*& p')
+ self.TestLint('void foo(Bar const*& p);',
+ operand_error_message % 'Bar const*& p')
+ self.TestLint('void foo(struct Bar*& p);',
+ operand_error_message % 'struct Bar*& p')
+ self.TestLint('void foo(const struct Bar*& p);',
+ operand_error_message % 'const struct Bar*& p')
+ self.TestLint('void foo(struct Bar const*& p);',
+ operand_error_message % 'struct Bar const*& p')
+ # Non-const reference to a templated type is not OK.
+ self.TestLint('void foo(std::vector<int>& p);',
+ operand_error_message % 'std::vector<int>& p')
+ # Returning an address of something is not prohibited.
+ self.TestLint('return &something;', '')
+ self.TestLint('if (condition) {return &something; }', '')
+ self.TestLint('if (condition) return &something;', '')
+ self.TestLint('if (condition) address = &something;', '')
+ self.TestLint('if (condition) result = lhs&rhs;', '')
+ self.TestLint('if (condition) result = lhs & rhs;', '')
+ self.TestLint('a = (b+c) * sizeof &f;', '')
+ self.TestLint('a = MySize(b) * sizeof &f;', '')
+ # We don't get confused by C++11 range-based for loops.
+ self.TestLint('for (const string& s : c)', '')
+ self.TestLint('for (auto& r : c)', '')
+ self.TestLint('for (typename Type& a : b)', '')
+ # We don't get confused by some other uses of '&'.
+ self.TestLint('T& operator=(const T& t);', '')
+ self.TestLint('int g() { return (a & b); }', '')
+ self.TestLint('T& r = (T&)*(vp());', '')
+ self.TestLint('T& r = v', '')
+ self.TestLint('static_assert((kBits & kMask) == 0, "text");', '')
+ self.TestLint('COMPILE_ASSERT((kBits & kMask) == 0, text);', '')
+ # Spaces before template arguments. This is poor style, but
+ # happens 0.15% of the time.
+ self.TestLint('void Func(const vector <int> &const_x, '
+ 'vector <int> &nonconst_x) {',
+ operand_error_message % 'vector<int> &nonconst_x')
+
+ # Derived member functions are spared from override check
+ self.TestLint('void Func(X& x);', operand_error_message % 'X& x')
+ self.TestLint('void Func(X& x) {}', operand_error_message % 'X& x')
+ self.TestLint('void Func(X& x) override;', '')
+ self.TestLint('void Func(X& x) override {', '')
+ self.TestLint('void Func(X& x) const override;', '')
+ self.TestLint('void Func(X& x) const override {', '')
+
+ # Don't warn on out-of-line method definitions.
+ self.TestLint('void NS::Func(X& x) {', '')
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(
+ 'foo.cc', 'cc',
+ ['// Copyright 2014 Your Company. All Rights Reserved.',
+ 'void a::b() {}',
+ 'void f(int& q) {}',
+ ''],
+ error_collector)
+ self.assertEquals(
+ operand_error_message % 'int& q',
+ error_collector.Results())
+
+ # Other potential false positives. These need full parser
+ # state to reproduce as opposed to just TestLint.
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(
+ 'foo.cc', 'cc',
+ ['// Copyright 2014 Your Company. All Rights Reserved.',
+ 'void swap(int &x,',
+ ' int &y) {',
+ '}',
+ 'void swap(',
+ ' sparsegroup<T, GROUP_SIZE, Alloc> &x,',
+ ' sparsegroup<T, GROUP_SIZE, Alloc> &y) {',
+ '}',
+ 'ostream& operator<<(',
+ ' ostream& out',
+ ' const dense_hash_set<Value, Hash, Equals, Alloc>& seq) {',
+ '}',
+ 'class A {',
+ ' void Function(',
+ ' string &x) override {',
+ ' }',
+ '};',
+ 'void Derived::Function(',
+ ' string &x) {',
+ '}',
+ '#define UNSUPPORTED_MASK(_mask) \\',
+ ' if (flags & _mask) { \\',
+ ' LOG(FATAL) << "Unsupported flag: " << #_mask; \\',
+ ' }',
+ 'Constructor::Constructor()',
+ ' : initializer1_(a1 & b1),',
+ ' initializer2_(a2 & b2) {',
+ '}',
+ 'Constructor::Constructor()',
+ ' : initializer1_{a3 & b3},',
+ ' initializer2_(a4 & b4) {',
+ '}',
+ 'Constructor::Constructor()',
+ ' : initializer1_{a5 & b5},',
+ ' initializer2_(a6 & b6) {}',
+ ''],
+ error_collector)
+ self.assertEquals('', error_collector.Results())
+
+ # Multi-line references
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(
+ 'foo.cc', 'cc',
+ ['// Copyright 2014 Your Company. All Rights Reserved.',
+ 'void Func(const Outer::',
+ ' Inner& const_x,',
+ ' const Outer',
+ ' ::Inner& const_y,',
+ ' const Outer<',
+ ' int>::Inner& const_z,',
+ ' Outer::',
+ ' Inner& nonconst_x,',
+ ' Outer',
+ ' ::Inner& nonconst_y,',
+ ' Outer<',
+ ' int>::Inner& nonconst_z) {',
+ '}',
+ ''],
+ error_collector)
+ self.assertEquals(
+ [operand_error_message % 'Outer::Inner& nonconst_x',
+ operand_error_message % 'Outer::Inner& nonconst_y',
+ operand_error_message % 'Outer<int>::Inner& nonconst_z'],
+ error_collector.Results())
+
+ # A peculiar false positive due to bad template argument parsing
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(
+ 'foo.cc', 'cc',
+ ['// Copyright 2014 Your Company. All Rights Reserved.',
+ 'inline RCULocked<X>::ReadPtr::ReadPtr(const RCULocked* rcu) {',
+ ' DCHECK(!(data & kFlagMask)) << "Error";',
+ '}',
+ '',
+ 'RCULocked<X>::WritePtr::WritePtr(RCULocked* rcu)',
+ ' : lock_(&rcu_->mutex_) {',
+ '}',
+ ''],
+ error_collector.Results())
+ self.assertEquals('', error_collector.Results())
+
+ def testBraceAtBeginOfLine(self):
+ self.TestLint('{',
+ '{ should almost always be at the end of the previous line'
+ ' [whitespace/braces] [4]')
+
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc',
+ ['int function()',
+ '{', # warning here
+ ' MutexLock l(&mu);',
+ '}',
+ 'int variable;'
+ '{', # no warning
+ ' MutexLock l(&mu);',
+ '}',
+ 'MyType m = {',
+ ' {value1, value2},',
+ ' {', # no warning
+ ' loooong_value1, looooong_value2',
+ ' }',
+ '};',
+ '#if PREPROCESSOR',
+ '{', # no warning
+ ' MutexLock l(&mu);',
+ '}',
+ '#endif'],
+ error_collector)
+ self.assertEquals(1, error_collector.Results().count(
+ '{ should almost always be at the end of the previous line'
+ ' [whitespace/braces] [4]'))
+
+ self.TestMultiLineLint(
+ """
+ foo(
+ {
+ loooooooooooooooong_value,
+ });""",
+ '')
+
+ def testMismatchingSpacesInParens(self):
+ self.TestLint('if (foo ) {', 'Mismatching spaces inside () in if'
+ ' [whitespace/parens] [5]')
+ self.TestLint('switch ( foo) {', 'Mismatching spaces inside () in switch'
+ ' [whitespace/parens] [5]')
+ self.TestLint('for (foo; ba; bar ) {', 'Mismatching spaces inside () in for'
+ ' [whitespace/parens] [5]')
+ self.TestLint('for (; foo; bar) {', '')
+ self.TestLint('for ( ; foo; bar) {', '')
+ self.TestLint('for ( ; foo; bar ) {', '')
+ self.TestLint('for (foo; bar; ) {', '')
+ self.TestLint('while ( foo ) {', 'Should have zero or one spaces inside'
+ ' ( and ) in while [whitespace/parens] [5]')
+
+ def testSpacingForFncall(self):
+ self.TestLint('if (foo) {', '')
+ self.TestLint('for (foo; bar; baz) {', '')
+ self.TestLint('for (;;) {', '')
+ # Space should be allowed in placement new operators.
+ self.TestLint('Something* p = new (place) Something();', '')
+ # Test that there is no warning when increment statement is empty.
+ self.TestLint('for (foo; baz;) {', '')
+ self.TestLint('for (foo;bar;baz) {', 'Missing space after ;'
+ ' [whitespace/semicolon] [3]')
+ # we don't warn about this semicolon, at least for now
+ self.TestLint('if (condition) {return &something; }',
+ '')
+ # seen in some macros
+ self.TestLint('DoSth();\\', '')
+ # Test that there is no warning about semicolon here.
+ self.TestLint('abc;// this is abc',
+ 'At least two spaces is best between code'
+ ' and comments [whitespace/comments] [2]')
+ self.TestLint('while (foo) {', '')
+ self.TestLint('switch (foo) {', '')
+ self.TestLint('foo( bar)', 'Extra space after ( in function call'
+ ' [whitespace/parens] [4]')
+ self.TestLint('foo( // comment', '')
+ self.TestLint('foo( // comment',
+ 'At least two spaces is best between code'
+ ' and comments [whitespace/comments] [2]')
+ self.TestLint('foobar( \\', '')
+ self.TestLint('foobar( \\', '')
+ self.TestLint('( a + b)', 'Extra space after ('
+ ' [whitespace/parens] [2]')
+ self.TestLint('((a+b))', '')
+ self.TestLint('foo (foo)', 'Extra space before ( in function call'
+ ' [whitespace/parens] [4]')
+ # asm volatile () may have a space, as it isn't a function call.
+ self.TestLint('asm volatile ("")', '')
+ self.TestLint('__asm__ __volatile__ ("")', '')
+ self.TestLint('} catch (const Foo& ex) {', '')
+ self.TestLint('case (42):', '')
+ self.TestLint('typedef foo (*foo)(foo)', '')
+ self.TestLint('typedef foo (*foo12bar_)(foo)', '')
+ self.TestLint('typedef foo (Foo::*bar)(foo)', '')
+ self.TestLint('using foo = type (Foo::*bar)(foo)', '')
+ self.TestLint('using foo = type (Foo::*bar)(', '')
+ self.TestLint('using foo = type (Foo::*)(', '')
+ self.TestLint('foo (Foo::*bar)(', '')
+ self.TestLint('foo (x::y::*z)(', '')
+ self.TestLint('foo (Foo::bar)(',
+ 'Extra space before ( in function call'
+ ' [whitespace/parens] [4]')
+ self.TestLint('foo (*bar)(', '')
+ self.TestLint('typedef foo (Foo::*bar)(', '')
+ self.TestLint('(foo)(bar)', '')
+ self.TestLint('Foo (*foo)(bar)', '')
+ self.TestLint('Foo (*foo)(Bar bar,', '')
+ self.TestLint('char (*p)[sizeof(foo)] = &foo', '')
+ self.TestLint('char (&ref)[sizeof(foo)] = &foo', '')
+ self.TestLint('const char32 (*table[])[6];', '')
+ # The sizeof operator is often written as if it were a function call, with
+ # an opening parenthesis directly following the operator name, but it can
+ # also be written like any other operator, with a space following the
+ # operator name, and the argument optionally in parentheses.
+ self.TestLint('sizeof(foo)', '')
+ self.TestLint('sizeof foo', '')
+ self.TestLint('sizeof (foo)', '')
+
+ def testSpacingBeforeBraces(self):
+ self.TestLint('if (foo){', 'Missing space before {'
+ ' [whitespace/braces] [5]')
+ self.TestLint('for{', 'Missing space before {'
+ ' [whitespace/braces] [5]')
+ self.TestLint('for {', '')
+ self.TestLint('EXPECT_DEBUG_DEATH({', '')
+ self.TestLint('std::is_convertible<A, B>{}', '')
+ self.TestLint('blah{32}', 'Missing space before {'
+ ' [whitespace/braces] [5]')
+ self.TestLint('int8_t{3}', '')
+ self.TestLint('int16_t{3}', '')
+ self.TestLint('int32_t{3}', '')
+ self.TestLint('uint64_t{12345}', '')
+ self.TestLint('constexpr int64_t kBatchGapMicros ='
+ ' int64_t{7} * 24 * 3600 * 1000000; // 1 wk.', '')
+ self.TestLint('MoveOnly(int i1, int i2) : ip1{new int{i1}}, '
+ 'ip2{new int{i2}} {}',
+ '')
+
+ def testSemiColonAfterBraces(self):
+ self.TestLint('if (cond) { func(); };',
+ 'You don\'t need a ; after a } [readability/braces] [4]')
+ self.TestLint('void Func() {};',
+ 'You don\'t need a ; after a } [readability/braces] [4]')
+ self.TestLint('void Func() const {};',
+ 'You don\'t need a ; after a } [readability/braces] [4]')
+ self.TestLint('class X {};', '')
+ for keyword in ['struct', 'union']:
+ for align in ['', ' alignas(16)']:
+ for typename in ['', ' X']:
+ for identifier in ['', ' x']:
+ self.TestLint(keyword + align + typename + ' {}' + identifier + ';',
+ '')
+
+ self.TestLint('class X : public Y {};', '')
+ self.TestLint('class X : public MACRO() {};', '')
+ self.TestLint('class X : public decltype(expr) {};', '')
+ self.TestLint('DEFINE_FACADE(PCQueue::Watcher, PCQueue) {};', '')
+ self.TestLint('VCLASS(XfaTest, XfaContextTest) {};', '')
+ self.TestLint('class STUBBY_CLASS(H, E) {};', '')
+ self.TestLint('class STUBBY2_CLASS(H, E) {};', '')
+ self.TestLint('TEST(TestCase, TestName) {};',
+ 'You don\'t need a ; after a } [readability/braces] [4]')
+ self.TestLint('TEST_F(TestCase, TestName) {};',
+ 'You don\'t need a ; after a } [readability/braces] [4]')
+
+ self.TestLint('file_tocs_[i] = (FileToc) {a, b, c};', '')
+ self.TestMultiLineLint('class X : public Y,\npublic Z {};', '')
+
+ def testLambda(self):
+ self.TestLint('auto x = []() {};', '')
+ self.TestLint('return []() {};', '')
+ self.TestMultiLineLint('auto x = []() {\n};\n', '')
+ self.TestLint('int operator[](int x) {};',
+ 'You don\'t need a ; after a } [readability/braces] [4]')
+
+ self.TestMultiLineLint('auto x = [&a,\nb]() {};', '')
+ self.TestMultiLineLint('auto x = [&a,\nb]\n() {};', '')
+ self.TestMultiLineLint('auto x = [&a,\n'
+ ' b](\n'
+ ' int a,\n'
+ ' int b) {\n'
+ ' return a +\n'
+ ' b;\n'
+ '};\n',
+ '')
+
+ # Avoid false positives with operator[]
+ self.TestLint('table_to_children[&*table].push_back(dependent);', '')
+
+ def testBraceInitializerList(self):
+ self.TestLint('MyStruct p = {1, 2};', '')
+ self.TestLint('MyStruct p{1, 2};', '')
+ self.TestLint('vector<int> p = {1, 2};', '')
+ self.TestLint('vector<int> p{1, 2};', '')
+ self.TestLint('x = vector<int>{1, 2};', '')
+ self.TestLint('x = (struct in_addr){ 0 };', '')
+ self.TestLint('Func(vector<int>{1, 2})', '')
+ self.TestLint('Func((struct in_addr){ 0 })', '')
+ self.TestLint('Func(vector<int>{1, 2}, 3)', '')
+ self.TestLint('Func((struct in_addr){ 0 }, 3)', '')
+ self.TestLint('LOG(INFO) << char{7};', '')
+ self.TestLint('LOG(INFO) << char{7} << "!";', '')
+ self.TestLint('int p[2] = {1, 2};', '')
+ self.TestLint('return {1, 2};', '')
+ self.TestLint('std::unique_ptr<Foo> foo{new Foo{}};', '')
+ self.TestLint('auto foo = std::unique_ptr<Foo>{new Foo{}};', '')
+ self.TestLint('static_assert(Max7String{}.IsValid(), "");', '')
+ self.TestLint('map_of_pairs[{1, 2}] = 3;', '')
+ self.TestLint('ItemView{has_offer() ? new Offer{offer()} : nullptr', '')
+ self.TestLint('template <class T, EnableIf<::std::is_const<T>{}> = 0>', '')
+
+ self.TestMultiLineLint('std::unique_ptr<Foo> foo{\n'
+ ' new Foo{}\n'
+ '};\n', '')
+ self.TestMultiLineLint('std::unique_ptr<Foo> foo{\n'
+ ' new Foo{\n'
+ ' new Bar{}\n'
+ ' }\n'
+ '};\n', '')
+ self.TestMultiLineLint('if (true) {\n'
+ ' if (false){ func(); }\n'
+ '}\n',
+ 'Missing space before { [whitespace/braces] [5]')
+ self.TestMultiLineLint('MyClass::MyClass()\n'
+ ' : initializer_{\n'
+ ' Func()} {\n'
+ '}\n', '')
+ self.TestLint('const pair<string, string> kCL' +
+ ('o' * 41) + 'gStr[] = {\n',
+ 'Lines should be <= 80 characters long'
+ ' [whitespace/line_length] [2]')
+ self.TestMultiLineLint('const pair<string, string> kCL' +
+ ('o' * 40) + 'ngStr[] =\n'
+ ' {\n'
+ ' {"gooooo", "oooogle"},\n'
+ '};\n', '')
+ self.TestMultiLineLint('const pair<string, string> kCL' +
+ ('o' * 39) + 'ngStr[] =\n'
+ ' {\n'
+ ' {"gooooo", "oooogle"},\n'
+ '};\n', '{ should almost always be at the end of '
+ 'the previous line [whitespace/braces] [4]')
+
+ def testSpacingAroundElse(self):
+ self.TestLint('}else {', 'Missing space before else'
+ ' [whitespace/braces] [5]')
+ self.TestLint('} else{', 'Missing space before {'
+ ' [whitespace/braces] [5]')
+ self.TestLint('} else {', '')
+ self.TestLint('} else if (foo) {', '')
+
+ def testSpacingWithInitializerLists(self):
+ self.TestLint('int v[1][3] = {{1, 2, 3}};', '')
+ self.TestLint('int v[1][1] = {{0}};', '')
+
+ def testSpacingForBinaryOps(self):
+ self.TestLint('if (foo||bar) {', 'Missing spaces around ||'
+ ' [whitespace/operators] [3]')
+ self.TestLint('if (foo<=bar) {', 'Missing spaces around <='
+ ' [whitespace/operators] [3]')
+ self.TestLint('if (foo<bar) {', 'Missing spaces around <'
+ ' [whitespace/operators] [3]')
+ self.TestLint('if (foo>bar) {', 'Missing spaces around >'
+ ' [whitespace/operators] [3]')
+ self.TestLint('if (foo<bar->baz) {', 'Missing spaces around <'
+ ' [whitespace/operators] [3]')
+ self.TestLint('if (foo<bar->bar) {', 'Missing spaces around <'
+ ' [whitespace/operators] [3]')
+ self.TestLint('template<typename T = double>', '')
+ self.TestLint('std::unique_ptr<No<Spaces>>', '')
+ self.TestLint('typedef hash_map<Foo, Bar>', '')
+ self.TestLint('10<<20', '')
+ self.TestLint('10<<a',
+ 'Missing spaces around << [whitespace/operators] [3]')
+ self.TestLint('a<<20',
+ 'Missing spaces around << [whitespace/operators] [3]')
+ self.TestLint('a<<b',
+ 'Missing spaces around << [whitespace/operators] [3]')
+ self.TestLint('10LL<<20', '')
+ self.TestLint('10ULL<<20', '')
+ self.TestLint('a>>b',
+ 'Missing spaces around >> [whitespace/operators] [3]')
+ self.TestLint('10>>b',
+ 'Missing spaces around >> [whitespace/operators] [3]')
+ self.TestLint('LOG(ERROR)<<*foo',
+ 'Missing spaces around << [whitespace/operators] [3]')
+ self.TestLint('LOG(ERROR)<<&foo',
+ 'Missing spaces around << [whitespace/operators] [3]')
+ self.TestLint('StringCoder<vector<string>>::ToString()', '')
+ self.TestLint('map<pair<int, int>, map<int, int>>::iterator', '')
+ self.TestLint('func<int, pair<int, pair<int, int>>>()', '')
+ self.TestLint('MACRO1(list<list<int>>)', '')
+ self.TestLint('MACRO2(list<list<int>>, 42)', '')
+ self.TestLint('void DoFoo(const set<vector<string>>& arg1);', '')
+ self.TestLint('void SetFoo(set<vector<string>>* arg1);', '')
+ self.TestLint('foo = new set<vector<string>>;', '')
+ self.TestLint('reinterpret_cast<set<vector<string>>*>(a);', '')
+ self.TestLint('MACRO(<<)', '')
+ self.TestLint('MACRO(<<, arg)', '')
+ self.TestLint('MACRO(<<=)', '')
+ self.TestLint('MACRO(<<=, arg)', '')
+
+ self.TestLint('using Vector3<T>::operator==;', '')
+ self.TestLint('using Vector3<T>::operator!=;', '')
+
+ def testSpacingBeforeLastSemicolon(self):
+ self.TestLint('call_function() ;',
+ 'Extra space before last semicolon. If this should be an '
+ 'empty statement, use {} instead.'
+ ' [whitespace/semicolon] [5]')
+ self.TestLint('while (true) ;',
+ 'Extra space before last semicolon. If this should be an '
+ 'empty statement, use {} instead.'
+ ' [whitespace/semicolon] [5]')
+ self.TestLint('default:;',
+ 'Semicolon defining empty statement. Use {} instead.'
+ ' [whitespace/semicolon] [5]')
+ self.TestLint(' ;',
+ 'Line contains only semicolon. If this should be an empty '
+ 'statement, use {} instead.'
+ ' [whitespace/semicolon] [5]')
+ self.TestLint('for (int i = 0; ;', '')
+
+ def testEmptyBlockBody(self):
+ self.TestLint('while (true);',
+ 'Empty loop bodies should use {} or continue'
+ ' [whitespace/empty_loop_body] [5]')
+ self.TestLint('if (true);',
+ 'Empty conditional bodies should use {}'
+ ' [whitespace/empty_conditional_body] [5]')
+ self.TestLint('while (true)', '')
+ self.TestLint('while (true) continue;', '')
+ self.TestLint('for (;;);',
+ 'Empty loop bodies should use {} or continue'
+ ' [whitespace/empty_loop_body] [5]')
+ self.TestLint('for (;;)', '')
+ self.TestLint('for (;;) continue;', '')
+ self.TestLint('for (;;) func();', '')
+ self.TestLint('if (test) {}',
+ 'If statement had no body and no else clause'
+ ' [whitespace/empty_if_body] [4]')
+ self.TestLint('if (test) func();', '')
+ self.TestLint('if (test) {} else {}', '')
+ self.TestMultiLineLint("""while (true &&
+ false);""",
+ 'Empty loop bodies should use {} or continue'
+ ' [whitespace/empty_loop_body] [5]')
+ self.TestMultiLineLint("""do {
+ } while (false);""",
+ '')
+ self.TestMultiLineLint("""#define MACRO \\
+ do { \\
+ } while (false);""",
+ '')
+ self.TestMultiLineLint("""do {
+ } while (false); // next line gets a warning
+ while (false);""",
+ 'Empty loop bodies should use {} or continue'
+ ' [whitespace/empty_loop_body] [5]')
+ self.TestMultiLineLint("""if (test) {
+ }""",
+ 'If statement had no body and no else clause'
+ ' [whitespace/empty_if_body] [4]')
+ self.TestMultiLineLint("""if (test,
+ func({})) {
+ }""",
+ 'If statement had no body and no else clause'
+ ' [whitespace/empty_if_body] [4]')
+ self.TestMultiLineLint("""if (test)
+ func();""", '')
+ self.TestLint('if (test) { hello; }', '')
+ self.TestLint('if (test({})) { hello; }', '')
+ self.TestMultiLineLint("""if (test) {
+ func();
+ }""", '')
+ self.TestMultiLineLint("""if (test) {
+ // multiline
+ // comment
+ }""", '')
+ self.TestMultiLineLint("""if (test) { // comment
+ }""", '')
+ self.TestMultiLineLint("""if (test) {
+ } else {
+ }""", '')
+ self.TestMultiLineLint("""if (func(p1,
+ p2,
+ p3)) {
+ func();
+ }""", '')
+ self.TestMultiLineLint("""if (func({}, p1)) {
+ func();
+ }""", '')
+
+ def testSpacingForRangeBasedFor(self):
+ # Basic correctly formatted case:
+ self.TestLint('for (int i : numbers) {', '')
+
+ # Missing space before colon:
+ self.TestLint('for (int i: numbers) {',
+ 'Missing space around colon in range-based for loop'
+ ' [whitespace/forcolon] [2]')
+ # Missing space after colon:
+ self.TestLint('for (int i :numbers) {',
+ 'Missing space around colon in range-based for loop'
+ ' [whitespace/forcolon] [2]')
+ # Missing spaces both before and after the colon.
+ self.TestLint('for (int i:numbers) {',
+ 'Missing space around colon in range-based for loop'
+ ' [whitespace/forcolon] [2]')
+
+ # The scope operator '::' shouldn't cause warnings...
+ self.TestLint('for (std::size_t i : sizes) {}', '')
+ # ...but it shouldn't suppress them either.
+ self.TestLint('for (std::size_t i: sizes) {}',
+ 'Missing space around colon in range-based for loop'
+ ' [whitespace/forcolon] [2]')
+
+
+ # Static or global STL strings.
+ def testStaticOrGlobalSTLStrings(self):
+ # A template for the error message for a const global/static string.
+ error_msg = ('For a static/global string constant, use a C style '
+ 'string instead: "%s[]". [runtime/string] [4]')
+
+ # The error message for a non-const global/static string variable.
+ nonconst_error_msg = ('Static/global string variables are not permitted.'
+ ' [runtime/string] [4]')
+
+ self.TestLint('string foo;',
+ nonconst_error_msg)
+ self.TestLint('string kFoo = "hello"; // English',
+ nonconst_error_msg)
+ self.TestLint('static string foo;',
+ nonconst_error_msg)
+ self.TestLint('static const string foo;',
+ error_msg % 'static const char foo')
+ self.TestLint('static const std::string foo;',
+ error_msg % 'static const char foo')
+ self.TestLint('string Foo::bar;',
+ nonconst_error_msg)
+
+ self.TestLint('std::string foo;',
+ nonconst_error_msg)
+ self.TestLint('std::string kFoo = "hello"; // English',
+ nonconst_error_msg)
+ self.TestLint('static std::string foo;',
+ nonconst_error_msg)
+ self.TestLint('static const std::string foo;',
+ error_msg % 'static const char foo')
+ self.TestLint('std::string Foo::bar;',
+ nonconst_error_msg)
+
+ self.TestLint('::std::string foo;',
+ nonconst_error_msg)
+ self.TestLint('::std::string kFoo = "hello"; // English',
+ nonconst_error_msg)
+ self.TestLint('static ::std::string foo;',
+ nonconst_error_msg)
+ self.TestLint('static const ::std::string foo;',
+ error_msg % 'static const char foo')
+ self.TestLint('::std::string Foo::bar;',
+ nonconst_error_msg)
+
+ self.TestLint('string* pointer', '')
+ self.TestLint('string *pointer', '')
+ self.TestLint('string* pointer = Func();', '')
+ self.TestLint('string *pointer = Func();', '')
+ self.TestLint('const string* pointer', '')
+ self.TestLint('const string *pointer', '')
+ self.TestLint('const string* pointer = Func();', '')
+ self.TestLint('const string *pointer = Func();', '')
+ self.TestLint('string const* pointer', '')
+ self.TestLint('string const *pointer', '')
+ self.TestLint('string const* pointer = Func();', '')
+ self.TestLint('string const *pointer = Func();', '')
+ self.TestLint('string* const pointer', '')
+ self.TestLint('string *const pointer', '')
+ self.TestLint('string* const pointer = Func();', '')
+ self.TestLint('string *const pointer = Func();', '')
+ self.TestLint('string Foo::bar() {}', '')
+ self.TestLint('string Foo::operator*() {}', '')
+ # Rare case.
+ self.TestLint('string foo("foobar");', nonconst_error_msg)
+ # Should not catch local or member variables.
+ self.TestLint(' string foo', '')
+ # Should not catch functions.
+ self.TestLint('string EmptyString() { return ""; }', '')
+ self.TestLint('string EmptyString () { return ""; }', '')
+ self.TestLint('string const& FileInfo::Pathname() const;', '')
+ self.TestLint('string const &FileInfo::Pathname() const;', '')
+ self.TestLint('string VeryLongNameFunctionSometimesEndsWith(\n'
+ ' VeryLongNameType very_long_name_variable) {}', '')
+ self.TestLint('template<>\n'
+ 'string FunctionTemplateSpecialization<SomeType>(\n'
+ ' int x) { return ""; }', '')
+ self.TestLint('template<>\n'
+ 'string FunctionTemplateSpecialization<vector<A::B>* >(\n'
+ ' int x) { return ""; }', '')
+
+ # should not catch methods of template classes.
+ self.TestLint('string Class<Type>::Method() const {\n'
+ ' return "";\n'
+ '}\n', '')
+ self.TestLint('string Class<Type>::Method(\n'
+ ' int arg) const {\n'
+ ' return "";\n'
+ '}\n', '')
+
+ # Check multiline cases.
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc',
+ ['// Copyright 2014 Your Company.',
+ 'string Class',
+ '::MemberFunction1();',
+ 'string Class::',
+ 'MemberFunction2();',
+ 'string Class::',
+ 'NestedClass::MemberFunction3();',
+ 'string TemplateClass<T>::',
+ 'NestedClass::MemberFunction4();',
+ 'const string Class',
+ '::static_member_variable1;',
+ 'const string Class::',
+ 'static_member_variable2;',
+ 'const string Class',
+ '::static_member_variable3 = "initial value";',
+ 'const string Class::',
+ 'static_member_variable4 = "initial value";',
+ 'string Class::',
+ 'static_member_variable5;',
+ ''],
+ error_collector)
+ self.assertEquals(error_collector.Results(),
+ [error_msg % 'const char Class::static_member_variable1',
+ error_msg % 'const char Class::static_member_variable2',
+ error_msg % 'const char Class::static_member_variable3',
+ error_msg % 'const char Class::static_member_variable4',
+ nonconst_error_msg])
+
+ def testNoSpacesInFunctionCalls(self):
+ self.TestLint('TellStory(1, 3);',
+ '')
+ self.TestLint('TellStory(1, 3 );',
+ 'Extra space before )'
+ ' [whitespace/parens] [2]')
+ self.TestLint('TellStory(1 /* wolf */, 3 /* pigs */);',
+ '')
+ self.TestMultiLineLint("""TellStory(1, 3
+ );""",
+ 'Closing ) should be moved to the previous line'
+ ' [whitespace/parens] [2]')
+ self.TestMultiLineLint("""TellStory(Wolves(1),
+ Pigs(3
+ ));""",
+ 'Closing ) should be moved to the previous line'
+ ' [whitespace/parens] [2]')
+ self.TestMultiLineLint("""TellStory(1,
+ 3 );""",
+ 'Extra space before )'
+ ' [whitespace/parens] [2]')
+
+ def testToDoComments(self):
+ start_space = ('Too many spaces before TODO'
+ ' [whitespace/todo] [2]')
+ missing_username = ('Missing username in TODO; it should look like '
+ '"// TODO(my_username): Stuff."'
+ ' [readability/todo] [2]')
+ end_space = ('TODO(my_username) should be followed by a space'
+ ' [whitespace/todo] [2]')
+
+ self.TestLint('// TODOfix this',
+ [start_space, missing_username, end_space])
+ self.TestLint('// TODO(ljenkins)fix this',
+ [start_space, end_space])
+ self.TestLint('// TODO fix this',
+ [start_space, missing_username])
+ self.TestLint('// TODO fix this', missing_username)
+ self.TestLint('// TODO: fix this', missing_username)
+ self.TestLint('//TODO(ljenkins): Fix this',
+ 'Should have a space between // and comment'
+ ' [whitespace/comments] [4]')
+ self.TestLint('// TODO(ljenkins):Fix this', end_space)
+ self.TestLint('// TODO(ljenkins):', '')
+ self.TestLint('// TODO(ljenkins): fix this', '')
+ self.TestLint('// TODO(ljenkins): Fix this', '')
+ self.TestLint('#if 1 // TEST_URLTODOCID_WHICH_HAS_THAT_WORD_IN_IT_H_', '')
+ self.TestLint('// See also similar TODO above', '')
+ self.TestLint(r'EXPECT_EQ("\\", '
+ r'NormalizePath("/./../foo///bar/..//x/../..", ""));',
+ '')
+
+ def testTwoSpacesBetweenCodeAndComments(self):
+ self.TestLint('} // namespace foo',
+ 'At least two spaces is best between code and comments'
+ ' [whitespace/comments] [2]')
+ self.TestLint('}// namespace foo',
+ 'At least two spaces is best between code and comments'
+ ' [whitespace/comments] [2]')
+ self.TestLint('printf("foo"); // Outside quotes.',
+ 'At least two spaces is best between code and comments'
+ ' [whitespace/comments] [2]')
+ self.TestLint('int i = 0; // Having two spaces is fine.', '')
+ self.TestLint('int i = 0; // Having three spaces is OK.', '')
+ self.TestLint('// Top level comment', '')
+ self.TestLint(' // Line starts with two spaces.', '')
+ self.TestMultiLineLint('void foo() {\n'
+ ' { // A scope is opening.\n'
+ ' int a;', '')
+ self.TestMultiLineLint('void foo() {\n'
+ ' { // A scope is opening.\n'
+ '#define A a',
+ 'At least two spaces is best between code and '
+ 'comments [whitespace/comments] [2]')
+ self.TestMultiLineLint(' foo();\n'
+ ' { // An indented scope is opening.\n'
+ ' int a;', '')
+ self.TestMultiLineLint('vector<int> my_elements = {// first\n'
+ ' 1,', '')
+ self.TestMultiLineLint('vector<int> my_elements = {// my_elements is ..\n'
+ ' 1,',
+ 'At least two spaces is best between code and '
+ 'comments [whitespace/comments] [2]')
+ self.TestLint('if (foo) { // not a pure scope; comment is too close!',
+ 'At least two spaces is best between code and comments'
+ ' [whitespace/comments] [2]')
+ self.TestLint('printf("// In quotes.")', '')
+ self.TestLint('printf("\\"%s // In quotes.")', '')
+ self.TestLint('printf("%s", "// In quotes.")', '')
+
+ def testSpaceAfterCommentMarker(self):
+ self.TestLint('//', '')
+ self.TestLint('//x', 'Should have a space between // and comment'
+ ' [whitespace/comments] [4]')
+ self.TestLint('// x', '')
+ self.TestLint('///', '')
+ self.TestLint('/// x', '')
+ self.TestLint('//!', '')
+ self.TestLint('//----', '')
+ self.TestLint('//====', '')
+ self.TestLint('//////', '')
+ self.TestLint('////// x', '')
+ self.TestLint('///< x', '') # After-member Doxygen comment
+ self.TestLint('//!< x', '') # After-member Doxygen comment
+ self.TestLint('////x', 'Should have a space between // and comment'
+ ' [whitespace/comments] [4]')
+ self.TestLint('//}', '')
+ self.TestLint('//}x', 'Should have a space between // and comment'
+ ' [whitespace/comments] [4]')
+ self.TestLint('//!<x', 'Should have a space between // and comment'
+ ' [whitespace/comments] [4]')
+ self.TestLint('///<x', 'Should have a space between // and comment'
+ ' [whitespace/comments] [4]')
+
+ # Test a line preceded by empty or comment lines. There was a bug
+ # that caused it to print the same warning N times if the erroneous
+ # line was preceded by N lines of empty or comment lines. To be
+ # precise, the '// marker so line numbers and indices both start at
+ # 1' line was also causing the issue.
+ def testLinePrecededByEmptyOrCommentLines(self):
+ def DoTest(self, lines):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc', lines, error_collector)
+ # The warning appears only once.
+ self.assertEquals(
+ 1,
+ error_collector.Results().count(
+ 'Do not use namespace using-directives. '
+ 'Use using-declarations instead.'
+ ' [build/namespaces] [5]'))
+ DoTest(self, ['using namespace foo;'])
+ DoTest(self, ['', '', '', 'using namespace foo;'])
+ DoTest(self, ['// hello', 'using namespace foo;'])
+
+ def testNewlineAtEOF(self):
+ def DoTest(self, data, is_missing_eof):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc', data.split('\n'),
+ error_collector)
+ # The warning appears only once.
+ self.assertEquals(
+ int(is_missing_eof),
+ error_collector.Results().count(
+ 'Could not find a newline character at the end of the file.'
+ ' [whitespace/ending_newline] [5]'))
+
+ DoTest(self, '// Newline\n// at EOF\n', False)
+ DoTest(self, '// No newline\n// at EOF', True)
+
+ def testInvalidUtf8(self):
+ def DoTest(self, raw_bytes, has_invalid_utf8):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(
+ 'foo.cc', 'cc',
+ unicode(raw_bytes, 'utf8', 'replace').split('\n'),
+ error_collector)
+ # The warning appears only once.
+ self.assertEquals(
+ int(has_invalid_utf8),
+ error_collector.Results().count(
+ 'Line contains invalid UTF-8'
+ ' (or Unicode replacement character).'
+ ' [readability/utf8] [5]'))
+
+ DoTest(self, 'Hello world\n', False)
+ DoTest(self, '\xe9\x8e\xbd\n', False)
+ DoTest(self, '\xe9x\x8e\xbd\n', True)
+ # This is the encoding of the replacement character itself (which
+ # you can see by evaluating codecs.getencoder('utf8')(u'\ufffd')).
+ DoTest(self, '\xef\xbf\xbd\n', True)
+
+ def testBadCharacters(self):
+ # Test for NUL bytes only
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('nul.cc', 'cc',
+ ['// Copyright 2014 Your Company.',
+ '\0', ''], error_collector)
+ self.assertEquals(
+ error_collector.Results(),
+ 'Line contains NUL byte. [readability/nul] [5]')
+
+ # Make sure both NUL bytes and UTF-8 are caught if they appear on
+ # the same line.
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(
+ 'nul_utf8.cc', 'cc',
+ ['// Copyright 2014 Your Company.',
+ unicode('\xe9x\0', 'utf8', 'replace'), ''],
+ error_collector)
+ self.assertEquals(
+ error_collector.Results(),
+ ['Line contains invalid UTF-8 (or Unicode replacement character).'
+ ' [readability/utf8] [5]',
+ 'Line contains NUL byte. [readability/nul] [5]'])
+
+ def testIsBlankLine(self):
+ self.assert_(cpplint.IsBlankLine(''))
+ self.assert_(cpplint.IsBlankLine(' '))
+ self.assert_(cpplint.IsBlankLine(' \t\r\n'))
+ self.assert_(not cpplint.IsBlankLine('int a;'))
+ self.assert_(not cpplint.IsBlankLine('{'))
+
+ def testBlankLinesCheck(self):
+ self.TestBlankLinesCheck(['{\n', '\n', '\n', '}\n'], 1, 1)
+ self.TestBlankLinesCheck([' if (foo) {\n', '\n', ' }\n'], 1, 1)
+ self.TestBlankLinesCheck(
+ ['\n', '// {\n', '\n', '\n', '// Comment\n', '{\n', '}\n'], 0, 0)
+ self.TestBlankLinesCheck(['\n', 'run("{");\n', '\n'], 0, 0)
+ self.TestBlankLinesCheck(['\n', ' if (foo) { return 0; }\n', '\n'], 0, 0)
+ self.TestBlankLinesCheck(
+ ['int x(\n', ' int a) {\n', '\n', 'return 0;\n', '}'], 0, 0)
+ self.TestBlankLinesCheck(
+ ['int x(\n', ' int a) const {\n', '\n', 'return 0;\n', '}'], 0, 0)
+ self.TestBlankLinesCheck(
+ ['int x(\n', ' int a) {\n', '\n', 'return 0;\n', '}'], 1, 0)
+ self.TestBlankLinesCheck(
+ ['int x(\n', ' int a) {\n', '\n', 'return 0;\n', '}'], 1, 0)
+
+ def testAllowBlankLineBeforeClosingNamespace(self):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc',
+ ['namespace {',
+ '',
+ '} // namespace',
+ 'namespace another_namespace {',
+ '',
+ '}',
+ 'namespace {',
+ '',
+ 'template<class T, ',
+ ' class A = hoge<T>, ',
+ ' class B = piyo<T>, ',
+ ' class C = fuga<T> >',
+ 'class D {',
+ ' public:',
+ '};',
+ '', '', '', '',
+ '}'],
+ error_collector)
+ self.assertEquals(0, error_collector.Results().count(
+ 'Redundant blank line at the end of a code block should be deleted.'
+ ' [whitespace/blank_line] [3]'))
+
+ def testAllowBlankLineBeforeIfElseChain(self):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc',
+ ['if (hoge) {',
+ '', # No warning
+ '} else if (piyo) {',
+ '', # No warning
+ '} else if (piyopiyo) {',
+ ' hoge = true;', # No warning
+ '} else {',
+ '', # Warning on this line
+ '}'],
+ error_collector)
+ self.assertEquals(1, error_collector.Results().count(
+ 'Redundant blank line at the end of a code block should be deleted.'
+ ' [whitespace/blank_line] [3]'))
+
+ def testAllowBlankLineAfterExtern(self):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc',
+ ['extern "C" {',
+ '',
+ 'EXPORTAPI void APICALL Some_function() {}',
+ '',
+ '}'],
+ error_collector)
+ self.assertEquals(0, error_collector.Results().count(
+ 'Redundant blank line at the start of a code block should be deleted.'
+ ' [whitespace/blank_line] [2]'))
+ self.assertEquals(0, error_collector.Results().count(
+ 'Redundant blank line at the end of a code block should be deleted.'
+ ' [whitespace/blank_line] [3]'))
+
+ def testBlankLineBeforeSectionKeyword(self):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc',
+ ['class A {',
+ ' public:',
+ ' protected:', # warning 1
+ ' private:', # warning 2
+ ' struct B {',
+ ' public:',
+ ' private:'] + # warning 3
+ ([''] * 100) + # Make A and B longer than 100 lines
+ [' };',
+ ' struct C {',
+ ' protected:',
+ ' private:', # C is too short for warnings
+ ' };',
+ '};',
+ 'class D',
+ ' : public {',
+ ' public:', # no warning
+ '};',
+ 'class E {\\',
+ ' public:\\'] +
+ (['\\'] * 100) + # Makes E > 100 lines
+ [' int non_empty_line;\\',
+ ' private:\\', # no warning
+ ' int a;\\',
+ '};'],
+ error_collector)
+ self.assertEquals(2, error_collector.Results().count(
+ '"private:" should be preceded by a blank line'
+ ' [whitespace/blank_line] [3]'))
+ self.assertEquals(1, error_collector.Results().count(
+ '"protected:" should be preceded by a blank line'
+ ' [whitespace/blank_line] [3]'))
+
+ def testNoBlankLineAfterSectionKeyword(self):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc',
+ ['class A {',
+ ' public:',
+ '', # warning 1
+ ' private:',
+ '', # warning 2
+ ' struct B {',
+ ' protected:',
+ '', # warning 3
+ ' };',
+ '};'],
+ error_collector)
+ self.assertEquals(1, error_collector.Results().count(
+ 'Do not leave a blank line after "public:"'
+ ' [whitespace/blank_line] [3]'))
+ self.assertEquals(1, error_collector.Results().count(
+ 'Do not leave a blank line after "protected:"'
+ ' [whitespace/blank_line] [3]'))
+ self.assertEquals(1, error_collector.Results().count(
+ 'Do not leave a blank line after "private:"'
+ ' [whitespace/blank_line] [3]'))
+
+ def testAllowBlankLinesInRawStrings(self):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc',
+ ['// Copyright 2014 Your Company.',
+ 'static const char *kData[] = {R"(',
+ '',
+ ')", R"(',
+ '',
+ ')"};',
+ ''],
+ error_collector)
+ self.assertEquals('', error_collector.Results())
+
+ def testElseOnSameLineAsClosingBraces(self):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc',
+ ['if (hoge) {',
+ '}',
+ 'else if (piyo) {', # Warning on this line
+ '}',
+ ' else {' # Warning on this line
+ '',
+ '}'],
+ error_collector)
+ self.assertEquals(2, error_collector.Results().count(
+ 'An else should appear on the same line as the preceding }'
+ ' [whitespace/newline] [4]'))
+
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc',
+ ['if (hoge) {',
+ '',
+ '}',
+ 'else', # Warning on this line
+ '{',
+ '',
+ '}'],
+ error_collector)
+ self.assertEquals(1, error_collector.Results().count(
+ 'An else should appear on the same line as the preceding }'
+ ' [whitespace/newline] [4]'))
+
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc',
+ ['if (hoge) {',
+ '',
+ '}',
+ 'else_function();'],
+ error_collector)
+ self.assertEquals(0, error_collector.Results().count(
+ 'An else should appear on the same line as the preceding }'
+ ' [whitespace/newline] [4]'))
+
+ def testMultipleStatementsOnSameLine(self):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc',
+ ['for (int i = 0; i < 1; i++) {}',
+ 'switch (x) {',
+ ' case 0: func(); break; ',
+ '}',
+ 'sum += MathUtil::SafeIntRound(x); x += 0.1;'],
+ error_collector)
+ self.assertEquals(0, error_collector.Results().count(
+ 'More than one command on the same line [whitespace/newline] [0]'))
+
+ old_verbose_level = cpplint._cpplint_state.verbose_level
+ cpplint._cpplint_state.verbose_level = 0
+ cpplint.ProcessFileData('foo.cc', 'cc',
+ ['sum += MathUtil::SafeIntRound(x); x += 0.1;'],
+ error_collector)
+ cpplint._cpplint_state.verbose_level = old_verbose_level
+
+ def testEndOfNamespaceComments(self):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('foo.cc', 'cc',
+ ['namespace {',
+ '',
+ '}', # No warning (too short)
+ 'namespace expected {',
+ '} // namespace mismatched', # Warning here
+ 'namespace {',
+ '} // namespace mismatched', # Warning here
+ 'namespace outer { namespace nested {'] +
+ ([''] * 10) +
+ ['}', # Warning here
+ '}', # Warning here
+ 'namespace {'] +
+ ([''] * 10) +
+ ['}', # Warning here
+ 'namespace {'] +
+ ([''] * 10) +
+ ['} // namespace some description', # Anon warning
+ 'namespace {'] +
+ ([''] * 10) +
+ ['} // namespace anonymous', # Variant warning
+ 'namespace {'] +
+ ([''] * 10) +
+ ['} // anonymous namespace (utils)', # Variant
+ 'namespace {'] +
+ ([''] * 10) +
+ ['} // anonymous namespace', # No warning
+ 'namespace missing_comment {'] +
+ ([''] * 10) +
+ ['}', # Warning here
+ 'namespace no_warning {'] +
+ ([''] * 10) +
+ ['} // namespace no_warning',
+ 'namespace no_warning {'] +
+ ([''] * 10) +
+ ['}; // end namespace no_warning',
+ '#define MACRO \\',
+ 'namespace c_style { \\'] +
+ (['\\'] * 10) +
+ ['} /* namespace c_style. */ \\',
+ ';'],
+ error_collector)
+ self.assertEquals(1, error_collector.Results().count(
+ 'Namespace should be terminated with "// namespace expected"'
+ ' [readability/namespace] [5]'))
+ self.assertEquals(1, error_collector.Results().count(
+ 'Namespace should be terminated with "// namespace outer"'
+ ' [readability/namespace] [5]'))
+ self.assertEquals(1, error_collector.Results().count(
+ 'Namespace should be terminated with "// namespace nested"'
+ ' [readability/namespace] [5]'))
+ self.assertEquals(3, error_collector.Results().count(
+ 'Anonymous namespace should be terminated with "// namespace"'
+ ' [readability/namespace] [5]'))
+ self.assertEquals(2, error_collector.Results().count(
+ 'Anonymous namespace should be terminated with "// namespace" or'
+ ' "// anonymous namespace"'
+ ' [readability/namespace] [5]'))
+ self.assertEquals(1, error_collector.Results().count(
+ 'Namespace should be terminated with "// namespace missing_comment"'
+ ' [readability/namespace] [5]'))
+ self.assertEquals(0, error_collector.Results().count(
+ 'Namespace should be terminated with "// namespace no_warning"'
+ ' [readability/namespace] [5]'))
+
+ def testElseClauseNotOnSameLineAsElse(self):
+ self.TestLint(' else DoSomethingElse();',
+ 'Else clause should never be on same line as else '
+ '(use 2 lines) [whitespace/newline] [4]')
+ self.TestLint(' else ifDoSomethingElse();',
+ 'Else clause should never be on same line as else '
+ '(use 2 lines) [whitespace/newline] [4]')
+ self.TestLint(' } else if (blah) {', '')
+ self.TestLint(' variable_ends_in_else = true;', '')
+
+ def testComma(self):
+ self.TestLint('a = f(1,2);',
+ 'Missing space after , [whitespace/comma] [3]')
+ self.TestLint('int tmp=a,a=b,b=tmp;',
+ ['Missing spaces around = [whitespace/operators] [4]',
+ 'Missing space after , [whitespace/comma] [3]'])
+ self.TestLint('f(a, /* name */ b);', '')
+ self.TestLint('f(a, /* name */b);', '')
+ self.TestLint('f(a, /* name */-1);', '')
+ self.TestLint('f(a, /* name */"1");', '')
+ self.TestLint('f(1, /* empty macro arg */, 2)', '')
+ self.TestLint('f(1,, 2)', '')
+ self.TestLint('operator,()', '')
+ self.TestLint('operator,(a,b)',
+ 'Missing space after , [whitespace/comma] [3]')
+
+ def testEqualsOperatorSpacing(self):
+ self.TestLint('int tmp= a;',
+ 'Missing spaces around = [whitespace/operators] [4]')
+ self.TestLint('int tmp =a;',
+ 'Missing spaces around = [whitespace/operators] [4]')
+ self.TestLint('int tmp=a;',
+ 'Missing spaces around = [whitespace/operators] [4]')
+ self.TestLint('int tmp= 7;',
+ 'Missing spaces around = [whitespace/operators] [4]')
+ self.TestLint('int tmp =7;',
+ 'Missing spaces around = [whitespace/operators] [4]')
+ self.TestLint('int tmp=7;',
+ 'Missing spaces around = [whitespace/operators] [4]')
+ self.TestLint('int* tmp=*p;',
+ 'Missing spaces around = [whitespace/operators] [4]')
+ self.TestLint('int* tmp= *p;',
+ 'Missing spaces around = [whitespace/operators] [4]')
+ self.TestMultiLineLint(
+ TrimExtraIndent('''
+ lookahead_services_=
+ ::strings::Split(FLAGS_ls, ",", ::strings::SkipEmpty());'''),
+ 'Missing spaces around = [whitespace/operators] [4]')
+ self.TestLint('bool result = a>=42;',
+ 'Missing spaces around >= [whitespace/operators] [3]')
+ self.TestLint('bool result = a<=42;',
+ 'Missing spaces around <= [whitespace/operators] [3]')
+ self.TestLint('bool result = a==42;',
+ 'Missing spaces around == [whitespace/operators] [3]')
+ self.TestLint('auto result = a!=42;',
+ 'Missing spaces around != [whitespace/operators] [3]')
+ self.TestLint('int a = b!=c;',
+ 'Missing spaces around != [whitespace/operators] [3]')
+ self.TestLint('a&=42;', '')
+ self.TestLint('a|=42;', '')
+ self.TestLint('a^=42;', '')
+ self.TestLint('a+=42;', '')
+ self.TestLint('a*=42;', '')
+ self.TestLint('a/=42;', '')
+ self.TestLint('a%=42;', '')
+ self.TestLint('a>>=5;', '')
+ self.TestLint('a<<=5;', '')
+
+ def testShiftOperatorSpacing(self):
+ self.TestLint('a<<b',
+ 'Missing spaces around << [whitespace/operators] [3]')
+ self.TestLint('a>>b',
+ 'Missing spaces around >> [whitespace/operators] [3]')
+ self.TestLint('1<<20', '')
+ self.TestLint('1024>>10', '')
+ self.TestLint('Kernel<<<1, 2>>>()', '')
+
+ def testIndent(self):
+ self.TestLint('static int noindent;', '')
+ self.TestLint(' int two_space_indent;', '')
+ self.TestLint(' int four_space_indent;', '')
+ self.TestLint(' int one_space_indent;',
+ 'Weird number of spaces at line-start. '
+ 'Are you using a 2-space indent? [whitespace/indent] [3]')
+ self.TestLint(' int three_space_indent;',
+ 'Weird number of spaces at line-start. '
+ 'Are you using a 2-space indent? [whitespace/indent] [3]')
+ self.TestLint(' char* one_space_indent = "public:";',
+ 'Weird number of spaces at line-start. '
+ 'Are you using a 2-space indent? [whitespace/indent] [3]')
+ self.TestLint(' public:', '')
+ self.TestLint(' protected:', '')
+ self.TestLint(' private:', '')
+ self.TestLint(' protected: \\', '')
+ self.TestLint(' public: \\', '')
+ self.TestLint(' private: \\', '')
+ self.TestMultiLineLint(
+ TrimExtraIndent("""
+ class foo {
+ public slots:
+ void bar();
+ };"""),
+ 'Weird number of spaces at line-start. '
+ 'Are you using a 2-space indent? [whitespace/indent] [3]')
+ self.TestMultiLineLint(
+ TrimExtraIndent('''
+ static const char kRawString[] = R"("
+ ")";'''),
+ '')
+ self.TestMultiLineLint(
+ TrimExtraIndent('''
+ KV<Query,
+ Tuple<TaxonomyId, PetacatCategoryId, double>>'''),
+ '')
+ self.TestMultiLineLint(
+ ' static const char kSingleLineRawString[] = R"(...)";',
+ 'Weird number of spaces at line-start. '
+ 'Are you using a 2-space indent? [whitespace/indent] [3]')
+
+ def testSectionIndent(self):
+ self.TestMultiLineLint(
+ """
+ class A {
+ public: // no warning
+ private: // warning here
+ };""",
+ 'private: should be indented +1 space inside class A'
+ ' [whitespace/indent] [3]')
+ self.TestMultiLineLint(
+ """
+ class B {
+ public: // no warning
+ template<> struct C {
+ public: // warning here
+ protected: // no warning
+ };
+ };""",
+ 'public: should be indented +1 space inside struct C'
+ ' [whitespace/indent] [3]')
+ self.TestMultiLineLint(
+ """
+ struct D {
+ };""",
+ 'Closing brace should be aligned with beginning of struct D'
+ ' [whitespace/indent] [3]')
+ self.TestMultiLineLint(
+ """
+ template<typename E> class F {
+ };""",
+ 'Closing brace should be aligned with beginning of class F'
+ ' [whitespace/indent] [3]')
+ self.TestMultiLineLint(
+ """
+ class G {
+ Q_OBJECT
+ public slots:
+ signals:
+ };""",
+ ['public slots: should be indented +1 space inside class G'
+ ' [whitespace/indent] [3]',
+ 'signals: should be indented +1 space inside class G'
+ ' [whitespace/indent] [3]'])
+ self.TestMultiLineLint(
+ """
+ class H {
+ /* comments */ class I {
+ public: // no warning
+ private: // warning here
+ };
+ };""",
+ 'private: should be indented +1 space inside class I'
+ ' [whitespace/indent] [3]')
+ self.TestMultiLineLint(
+ """
+ class J
+ : public ::K {
+ public: // no warning
+ protected: // warning here
+ };""",
+ 'protected: should be indented +1 space inside class J'
+ ' [whitespace/indent] [3]')
+ self.TestMultiLineLint(
+ """
+ class L
+ : public M,
+ public ::N {
+ };""",
+ '')
+ self.TestMultiLineLint(
+ """
+ template <class O,
+ class P,
+ class Q,
+ typename R>
+ static void Func() {
+ }""",
+ '')
+
+ def testConditionals(self):
+ self.TestMultiLineLint(
+ """
+ if (foo)
+ goto fail;
+ goto fail;""",
+ 'If/else bodies with multiple statements require braces'
+ ' [readability/braces] [4]')
+ self.TestMultiLineLint(
+ """
+ if (foo)
+ goto fail; goto fail;""",
+ 'If/else bodies with multiple statements require braces'
+ ' [readability/braces] [4]')
+ self.TestMultiLineLint(
+ """
+ if (foo)
+ foo;
+ else
+ goto fail;
+ goto fail;""",
+ 'If/else bodies with multiple statements require braces'
+ ' [readability/braces] [4]')
+ self.TestMultiLineLint(
+ """
+ if (foo) goto fail;
+ goto fail;""",
+ 'If/else bodies with multiple statements require braces'
+ ' [readability/braces] [4]')
+ self.TestMultiLineLint(
+ """
+ if (foo)
+ if (bar)
+ baz;
+ else
+ qux;""",
+ 'Else clause should be indented at the same level as if. Ambiguous'
+ ' nested if/else chains require braces. [readability/braces] [4]')
+ self.TestMultiLineLint(
+ """
+ if (foo)
+ if (bar)
+ baz;
+ else
+ qux;""",
+ 'Else clause should be indented at the same level as if. Ambiguous'
+ ' nested if/else chains require braces. [readability/braces] [4]')
+ self.TestMultiLineLint(
+ """
+ if (foo) {
+ bar;
+ baz;
+ } else
+ qux;""",
+ 'If an else has a brace on one side, it should have it on both'
+ ' [readability/braces] [5]')
+ self.TestMultiLineLint(
+ """
+ if (foo)
+ bar;
+ else {
+ baz;
+ }""",
+ 'If an else has a brace on one side, it should have it on both'
+ ' [readability/braces] [5]')
+ self.TestMultiLineLint(
+ """
+ if (foo)
+ bar;
+ else if (baz) {
+ qux;
+ }""",
+ 'If an else has a brace on one side, it should have it on both'
+ ' [readability/braces] [5]')
+ self.TestMultiLineLint(
+ """
+ if (foo) {
+ bar;
+ } else if (baz)
+ qux;""",
+ 'If an else has a brace on one side, it should have it on both'
+ ' [readability/braces] [5]')
+ self.TestMultiLineLint(
+ """
+ if (foo)
+ goto fail;
+ bar;""",
+ '')
+ self.TestMultiLineLint(
+ """
+ if (foo
+ && bar) {
+ baz;
+ qux;
+ }""",
+ '')
+ self.TestMultiLineLint(
+ """
+ if (foo)
+ goto
+ fail;""",
+ '')
+ self.TestMultiLineLint(
+ """
+ if (foo)
+ bar;
+ else
+ baz;
+ qux;""",
+ '')
+ self.TestMultiLineLint(
+ """
+ for (;;) {
+ if (foo)
+ bar;
+ else
+ baz;
+ }""",
+ '')
+ self.TestMultiLineLint(
+ """
+ if (foo)
+ bar;
+ else if (baz)
+ baz;""",
+ '')
+ self.TestMultiLineLint(
+ """
+ if (foo)
+ bar;
+ else
+ baz;""",
+ '')
+ self.TestMultiLineLint(
+ """
+ if (foo) {
+ bar;
+ } else {
+ baz;
+ }""",
+ '')
+ self.TestMultiLineLint(
+ """
+ if (foo) {
+ bar;
+ } else if (baz) {
+ qux;
+ }""",
+ '')
+ # Note: this is an error for a different reason, but should not trigger the
+ # single-line if error.
+ self.TestMultiLineLint(
+ """
+ if (foo)
+ {
+ bar;
+ baz;
+ }""",
+ '{ should almost always be at the end of the previous line'
+ ' [whitespace/braces] [4]')
+ self.TestMultiLineLint(
+ """
+ if (foo) { \\
+ bar; \\
+ baz; \\
+ }""",
+ '')
+ self.TestMultiLineLint(
+ """
+ void foo() { if (bar) baz; }""",
+ '')
+ self.TestMultiLineLint(
+ """
+ #if foo
+ bar;
+ #else
+ baz;
+ qux;
+ #endif""",
+ '')
+ self.TestMultiLineLint(
+ """void F() {
+ variable = [] { if (true); };
+ variable =
+ [] { if (true); };
+ Call(
+ [] { if (true); },
+ [] { if (true); });
+ }""",
+ '')
+
+ def testTab(self):
+ self.TestLint('\tint a;',
+ 'Tab found; better to use spaces [whitespace/tab] [1]')
+ self.TestLint('int a = 5;\t\t// set a to 5',
+ 'Tab found; better to use spaces [whitespace/tab] [1]')
+
+ def testParseArguments(self):
+ old_usage = cpplint._USAGE
+ old_error_categories = cpplint._ERROR_CATEGORIES
+ old_output_format = cpplint._cpplint_state.output_format
+ old_verbose_level = cpplint._cpplint_state.verbose_level
+ old_headers = cpplint._hpp_headers
+ old_filters = cpplint._cpplint_state.filters
+ old_line_length = cpplint._line_length
+ old_valid_extensions = cpplint._valid_extensions
+ try:
+ # Don't print usage during the tests, or filter categories
+ cpplint._USAGE = ''
+ cpplint._ERROR_CATEGORIES = ''
+
+ self.assertRaises(SystemExit, cpplint.ParseArguments, [])
+ self.assertRaises(SystemExit, cpplint.ParseArguments, ['--badopt'])
+ self.assertRaises(SystemExit, cpplint.ParseArguments, ['--help'])
+ self.assertRaises(SystemExit, cpplint.ParseArguments, ['--v=0'])
+ self.assertRaises(SystemExit, cpplint.ParseArguments, ['--filter='])
+ # This is illegal because all filters must start with + or -
+ self.assertRaises(SystemExit, cpplint.ParseArguments, ['--filter=foo'])
+ self.assertRaises(SystemExit, cpplint.ParseArguments,
+ ['--filter=+a,b,-c'])
+ self.assertRaises(SystemExit, cpplint.ParseArguments, ['--headers'])
+
+ self.assertEquals(['foo.cc'], cpplint.ParseArguments(['foo.cc']))
+ self.assertEquals(old_output_format, cpplint._cpplint_state.output_format)
+ self.assertEquals(old_verbose_level, cpplint._cpplint_state.verbose_level)
+
+ self.assertEquals(['foo.cc'],
+ cpplint.ParseArguments(['--v=1', 'foo.cc']))
+ self.assertEquals(1, cpplint._cpplint_state.verbose_level)
+ self.assertEquals(['foo.h'],
+ cpplint.ParseArguments(['--v=3', 'foo.h']))
+ self.assertEquals(3, cpplint._cpplint_state.verbose_level)
+ self.assertEquals(['foo.cpp'],
+ cpplint.ParseArguments(['--verbose=5', 'foo.cpp']))
+ self.assertEquals(5, cpplint._cpplint_state.verbose_level)
+ self.assertRaises(ValueError,
+ cpplint.ParseArguments, ['--v=f', 'foo.cc'])
+
+ self.assertEquals(['foo.cc'],
+ cpplint.ParseArguments(['--output=emacs', 'foo.cc']))
+ self.assertEquals('emacs', cpplint._cpplint_state.output_format)
+ self.assertEquals(['foo.h'],
+ cpplint.ParseArguments(['--output=vs7', 'foo.h']))
+ self.assertEquals('vs7', cpplint._cpplint_state.output_format)
+ self.assertRaises(SystemExit,
+ cpplint.ParseArguments, ['--output=blah', 'foo.cc'])
+
+ filt = '-,+whitespace,-whitespace/indent'
+ self.assertEquals(['foo.h'],
+ cpplint.ParseArguments(['--filter='+filt, 'foo.h']))
+ self.assertEquals(['-', '+whitespace', '-whitespace/indent'],
+ cpplint._cpplint_state.filters)
+
+ self.assertEquals(['foo.cc', 'foo.h'],
+ cpplint.ParseArguments(['foo.cc', 'foo.h']))
+
+ self.assertEqual(['foo.h'],
+ cpplint.ParseArguments(['--linelength=120', 'foo.h']))
+ self.assertEqual(120, cpplint._line_length)
+
+ self.assertEqual(['foo.h'],
+ cpplint.ParseArguments(['--extensions=hpp,cpp,cpp', 'foo.h']))
+ self.assertEqual(set(['hpp', 'cpp']), cpplint._valid_extensions)
+
+ self.assertEqual(set(['h']), cpplint._hpp_headers) # Default value
+ self.assertEqual(['foo.h'],
+ cpplint.ParseArguments(['--extensions=cpp,cpp', '--headers=hpp,h', 'foo.h']))
+ self.assertEqual(set(['hpp', 'h']), cpplint._hpp_headers)
+ self.assertEqual(set(['hpp', 'h', 'cpp']), cpplint._valid_extensions)
+
+ finally:
+ cpplint._USAGE = old_usage
+ cpplint._ERROR_CATEGORIES = old_error_categories
+ cpplint._cpplint_state.output_format = old_output_format
+ cpplint._cpplint_state.verbose_level = old_verbose_level
+ cpplint._cpplint_state.filters = old_filters
+ cpplint._line_length = old_line_length
+ cpplint._valid_extensions = old_valid_extensions
+ cpplint._hpp_headers = old_headers
+
+ def testLineLength(self):
+ old_line_length = cpplint._line_length
+ try:
+ cpplint._line_length = 80
+ self.TestLint(
+ '// H %s' % ('H' * 75),
+ '')
+ self.TestLint(
+ '// H %s' % ('H' * 76),
+ 'Lines should be <= 80 characters long'
+ ' [whitespace/line_length] [2]')
+ cpplint._line_length = 120
+ self.TestLint(
+ '// H %s' % ('H' * 115),
+ '')
+ self.TestLint(
+ '// H %s' % ('H' * 116),
+ 'Lines should be <= 120 characters long'
+ ' [whitespace/line_length] [2]')
+ finally:
+ cpplint._line_length = old_line_length
+
+ def testFilter(self):
+ old_filters = cpplint._cpplint_state.filters
+ try:
+ cpplint._cpplint_state.SetFilters('-,+whitespace,-whitespace/indent')
+ self.TestLint(
+ '// Hello there ',
+ 'Line ends in whitespace. Consider deleting these extra spaces.'
+ ' [whitespace/end_of_line] [4]')
+ self.TestLint('int a = (int)1.0;', '')
+ self.TestLint(' weird opening space', '')
+ finally:
+ cpplint._cpplint_state.filters = old_filters
+
+ def testDefaultFilter(self):
+ default_filters = cpplint._DEFAULT_FILTERS
+ old_filters = cpplint._cpplint_state.filters
+ cpplint._DEFAULT_FILTERS = ['-whitespace']
+ try:
+ # Reset filters
+ cpplint._cpplint_state.SetFilters('')
+ self.TestLint('// Hello there ', '')
+ cpplint._cpplint_state.SetFilters('+whitespace/end_of_line')
+ self.TestLint(
+ '// Hello there ',
+ 'Line ends in whitespace. Consider deleting these extra spaces.'
+ ' [whitespace/end_of_line] [4]')
+ self.TestLint(' weird opening space', '')
+ finally:
+ cpplint._cpplint_state.filters = old_filters
+ cpplint._DEFAULT_FILTERS = default_filters
+
+ def testDuplicateHeader(self):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData('path/self.cc', 'cc',
+ ['// Copyright 2014 Your Company. All Rights Reserved.',
+ '#include "path/self.h"',
+ '#include "path/duplicate.h"',
+ '#include "path/duplicate.h"',
+ '#ifdef MACRO',
+ '#include "path/unique.h"',
+ '#else',
+ '#include "path/unique.h"',
+ '#endif',
+ ''],
+ error_collector)
+ self.assertEquals(
+ ['"path/duplicate.h" already included at path/self.cc:3 '
+ '[build/include] [4]'],
+ error_collector.ResultList())
+
+ def testUnnamedNamespacesInHeaders(self):
+ self.TestLanguageRulesCheck(
+ 'foo.h', 'namespace {',
+ 'Do not use unnamed namespaces in header files. See'
+ ' https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Namespaces'
+ ' for more information. [build/namespaces] [4]')
+ # namespace registration macros are OK.
+ self.TestLanguageRulesCheck('foo.h', 'namespace { \\', '')
+ # named namespaces are OK.
+ self.TestLanguageRulesCheck('foo.h', 'namespace foo {', '')
+ self.TestLanguageRulesCheck('foo.h', 'namespace foonamespace {', '')
+ self.TestLanguageRulesCheck('foo.cc', 'namespace {', '')
+ self.TestLanguageRulesCheck('foo.cc', 'namespace foo {', '')
+
+ def testBuildClass(self):
+ # Test that the linter can parse to the end of class definitions,
+ # and that it will report when it can't.
+ # Use multi-line linter because it performs the ClassState check.
+ self.TestMultiLineLint(
+ 'class Foo {',
+ 'Failed to find complete declaration of class Foo'
+ ' [build/class] [5]')
+ # Do the same for namespaces
+ self.TestMultiLineLint(
+ 'namespace Foo {',
+ 'Failed to find complete declaration of namespace Foo'
+ ' [build/namespaces] [5]')
+ # Don't warn on forward declarations of various types.
+ self.TestMultiLineLint(
+ 'class Foo;',
+ '')
+ self.TestMultiLineLint(
+ """struct Foo*
+ foo = NewFoo();""",
+ '')
+ # Test preprocessor.
+ self.TestMultiLineLint(
+ """#ifdef DERIVE_FROM_GOO
+ struct Foo : public Goo {
+ #else
+ struct Foo : public Hoo {
+ #endif
+ };""",
+ '')
+ self.TestMultiLineLint(
+ """
+ class Foo
+ #ifdef DERIVE_FROM_GOO
+ : public Goo {
+ #else
+ : public Hoo {
+ #endif
+ };""",
+ '')
+ # Test incomplete class
+ self.TestMultiLineLint(
+ 'class Foo {',
+ 'Failed to find complete declaration of class Foo'
+ ' [build/class] [5]')
+
+ def testBuildEndComment(self):
+ # The crosstool compiler we currently use will fail to compile the
+ # code in this test, so we might consider removing the lint check.
+ self.TestMultiLineLint(
+ """#if 0
+ #endif Not a comment""",
+ 'Uncommented text after #endif is non-standard. Use a comment.'
+ ' [build/endif_comment] [5]')
+
+ def testBuildForwardDecl(self):
+ # The crosstool compiler we currently use will fail to compile the
+ # code in this test, so we might consider removing the lint check.
+ self.TestLint('class Foo::Goo;',
+ 'Inner-style forward declarations are invalid.'
+ ' Remove this line.'
+ ' [build/forward_decl] [5]')
+
+ def GetBuildHeaderGuardPreprocessorSymbol(self, file_path):
+ # Figure out the expected header guard by processing an empty file.
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'h', [], error_collector)
+ for error in error_collector.ResultList():
+ matched = re.search(
+ 'No #ifndef header guard found, suggested CPP variable is: '
+ '([A-Z0-9_]+)',
+ error)
+ if matched is not None:
+ return matched.group(1)
+
+ def testBuildHeaderGuard(self):
+ file_path = 'mydir/foo.h'
+ expected_guard = self.GetBuildHeaderGuardPreprocessorSymbol(file_path)
+ self.assertTrue(re.search('MYDIR_FOO_H_$', expected_guard))
+
+ # No guard at all: expect one error.
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'h', [], error_collector)
+ self.assertEquals(
+ 1,
+ error_collector.ResultList().count(
+ 'No #ifndef header guard found, suggested CPP variable is: %s'
+ ' [build/header_guard] [5]' % expected_guard),
+ error_collector.ResultList())
+
+ # No header guard, but the error is suppressed.
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'h',
+ ['// Copyright 2014 Your Company.',
+ '// NOLINT(build/header_guard)', ''],
+ error_collector)
+ self.assertEquals([], error_collector.ResultList())
+
+ # Wrong guard
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'h',
+ ['#ifndef FOO_H', '#define FOO_H'], error_collector)
+ self.assertEquals(
+ 1,
+ error_collector.ResultList().count(
+ '#ifndef header guard has wrong style, please use: %s'
+ ' [build/header_guard] [5]' % expected_guard),
+ error_collector.ResultList())
+
+ # No define
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'h',
+ ['#ifndef %s' % expected_guard], error_collector)
+ self.assertEquals(
+ 1,
+ error_collector.ResultList().count(
+ 'No #ifndef header guard found, suggested CPP variable is: %s'
+ ' [build/header_guard] [5]' % expected_guard),
+ error_collector.ResultList())
+
+ # Mismatched define
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'h',
+ ['#ifndef %s' % expected_guard,
+ '#define FOO_H'],
+ error_collector)
+ self.assertEquals(
+ 1,
+ error_collector.ResultList().count(
+ 'No #ifndef header guard found, suggested CPP variable is: %s'
+ ' [build/header_guard] [5]' % expected_guard),
+ error_collector.ResultList())
+
+ # No endif
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'h',
+ ['#ifndef %s' % expected_guard,
+ '#define %s' % expected_guard,
+ ''],
+ error_collector)
+ self.assertEquals(
+ 1,
+ error_collector.ResultList().count(
+ '#endif line should be "#endif // %s"'
+ ' [build/header_guard] [5]' % expected_guard),
+ error_collector.ResultList())
+
+ # Commentless endif
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'h',
+ ['#ifndef %s' % expected_guard,
+ '#define %s' % expected_guard,
+ '#endif'],
+ error_collector)
+ self.assertEquals(
+ 1,
+ error_collector.ResultList().count(
+ '#endif line should be "#endif // %s"'
+ ' [build/header_guard] [5]' % expected_guard),
+ error_collector.ResultList())
+
+ # Commentless endif for old-style guard
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'h',
+ ['#ifndef %s_' % expected_guard,
+ '#define %s_' % expected_guard,
+ '#endif'],
+ error_collector)
+ self.assertEquals(
+ 1,
+ error_collector.ResultList().count(
+ '#endif line should be "#endif // %s"'
+ ' [build/header_guard] [5]' % expected_guard),
+ error_collector.ResultList())
+
+ # No header guard errors
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'h',
+ ['#ifndef %s' % expected_guard,
+ '#define %s' % expected_guard,
+ '#endif // %s' % expected_guard],
+ error_collector)
+ for line in error_collector.ResultList():
+ if line.find('build/header_guard') != -1:
+ self.fail('Unexpected error: %s' % line)
+
+ # No header guard errors for old-style guard
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'h',
+ ['#ifndef %s_' % expected_guard,
+ '#define %s_' % expected_guard,
+ '#endif // %s_' % expected_guard],
+ error_collector)
+ for line in error_collector.ResultList():
+ if line.find('build/header_guard') != -1:
+ self.fail('Unexpected error: %s' % line)
+
+ old_verbose_level = cpplint._cpplint_state.verbose_level
+ try:
+ cpplint._cpplint_state.verbose_level = 0
+ # Warn on old-style guard if verbosity is 0.
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'h',
+ ['#ifndef %s_' % expected_guard,
+ '#define %s_' % expected_guard,
+ '#endif // %s_' % expected_guard],
+ error_collector)
+ self.assertEquals(
+ 1,
+ error_collector.ResultList().count(
+ '#ifndef header guard has wrong style, please use: %s'
+ ' [build/header_guard] [0]' % expected_guard),
+ error_collector.ResultList())
+ finally:
+ cpplint._cpplint_state.verbose_level = old_verbose_level
+
+ # Completely incorrect header guard
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'h',
+ ['#ifndef FOO',
+ '#define FOO',
+ '#endif // FOO'],
+ error_collector)
+ self.assertEquals(
+ 1,
+ error_collector.ResultList().count(
+ '#ifndef header guard has wrong style, please use: %s'
+ ' [build/header_guard] [5]' % expected_guard),
+ error_collector.ResultList())
+ self.assertEquals(
+ 1,
+ error_collector.ResultList().count(
+ '#endif line should be "#endif // %s"'
+ ' [build/header_guard] [5]' % expected_guard),
+ error_collector.ResultList())
+
+ # incorrect header guard with nolint
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'h',
+ ['#ifndef FOO // NOLINT',
+ '#define FOO',
+ '#endif // FOO NOLINT'],
+ error_collector)
+ self.assertEquals(
+ 0,
+ error_collector.ResultList().count(
+ '#ifndef header guard has wrong style, please use: %s'
+ ' [build/header_guard] [5]' % expected_guard),
+ error_collector.ResultList())
+ self.assertEquals(
+ 0,
+ error_collector.ResultList().count(
+ '#endif line should be "#endif // %s"'
+ ' [build/header_guard] [5]' % expected_guard),
+ error_collector.ResultList())
+
+ # Special case for flymake
+ for test_file in ['mydir/foo_flymake.h', 'mydir/.flymake/foo.h']:
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(test_file, 'h',
+ ['// Copyright 2014 Your Company.', ''],
+ error_collector)
+ self.assertEquals(
+ 1,
+ error_collector.ResultList().count(
+ 'No #ifndef header guard found, suggested CPP variable is: %s'
+ ' [build/header_guard] [5]' % expected_guard),
+ error_collector.ResultList())
+
+ def testBuildHeaderGuardWithRoot(self):
+ # note: Tested file paths must be real, otherwise
+ # the repository name lookup will fail.
+ file_path = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+ 'cpplint_test_header.h')
+ file_info = cpplint.FileInfo(file_path)
+ if file_info.FullName() == file_info.RepositoryName():
+ # When FileInfo cannot deduce the root directory of the repository,
+ # FileInfo.RepositoryName returns the same value as FileInfo.FullName.
+ # This can happen when this source file was obtained without .svn or
+ # .git directory. (e.g. using 'svn export' or 'git archive').
+ # Skip this test in such a case because --root flag makes sense only
+ # when the root directory of the repository is properly deduced.
+ return
+
+ self.assertEquals('CPPLINT_CPPLINT_TEST_HEADER_H_',
+ cpplint.GetHeaderGuardCPPVariable(file_path))
+ #
+ # test --root flags:
+ # this changes the cpp header guard prefix
+ #
+
+ # left-strip the header guard by using a root dir inside of the repo dir.
+ # relative directory
+ cpplint._root = 'cpplint'
+ self.assertEquals('CPPLINT_TEST_HEADER_H_',
+ cpplint.GetHeaderGuardCPPVariable(file_path))
+
+ nested_file_path = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+ os.path.join('nested',
+ 'cpplint_test_header.h'))
+ cpplint._root = os.path.join('cpplint', 'nested')
+ actual = cpplint.GetHeaderGuardCPPVariable(nested_file_path)
+ self.assertEquals('CPPLINT_TEST_HEADER_H_',
+ actual)
+
+ # absolute directory
+ # (note that CPPLINT.cfg root=setting is always made absolute)
+ cpplint._root = os.path.join(os.path.dirname(os.path.abspath(__file__)))
+ self.assertEquals('CPPLINT_TEST_HEADER_H_',
+ cpplint.GetHeaderGuardCPPVariable(file_path))
+
+ nested_file_path = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+ os.path.join('nested',
+ 'cpplint_test_header.h'))
+ cpplint._root = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+ 'nested')
+ self.assertEquals('CPPLINT_TEST_HEADER_H_',
+ cpplint.GetHeaderGuardCPPVariable(nested_file_path))
+
+ # --root flag is ignored if an non-existent directory is specified.
+ cpplint._root = 'NON_EXISTENT_DIR'
+ self.assertEquals('CPPLINT_CPPLINT_TEST_HEADER_H_',
+ cpplint.GetHeaderGuardCPPVariable(file_path))
+
+ # prepend to the header guard by using a root dir that is more outer
+ # than the repo dir
+
+ # (using absolute paths)
+ # (note that CPPLINT.cfg root=setting is always made absolute)
+ this_files_path = os.path.dirname(os.path.abspath(__file__))
+ (styleguide_path, this_files_dir) = os.path.split(this_files_path)
+ (styleguide_parent_path, _) = os.path.split(styleguide_path)
+ # parent dir of styleguide
+ cpplint._root = styleguide_parent_path
+ self.assertIsNotNone(styleguide_parent_path)
+ # do not have 'styleguide' repo in '/'
+ self.assertEquals('STYLEGUIDE_CPPLINT_CPPLINT_TEST_HEADER_H_',
+ cpplint.GetHeaderGuardCPPVariable(file_path))
+
+ # To run the 'relative path' tests, we must be in the directory of this test file.
+ cur_dir = os.getcwd()
+ os.chdir(this_files_path)
+
+ # (using relative paths)
+ styleguide_rel_path = os.path.relpath(styleguide_path, this_files_path)
+ # '..'
+ cpplint._root = styleguide_rel_path
+ self.assertEquals('CPPLINT_CPPLINT_TEST_HEADER_H_',
+ cpplint.GetHeaderGuardCPPVariable(file_path))
+
+ styleguide_rel_path = os.path.relpath(styleguide_parent_path,
+ this_files_path) # '../..'
+ cpplint._root = styleguide_rel_path
+ self.assertEquals('STYLEGUIDE_CPPLINT_CPPLINT_TEST_HEADER_H_',
+ cpplint.GetHeaderGuardCPPVariable(file_path))
+
+ cpplint._root = None
+
+ # Restore previous CWD.
+ os.chdir(cur_dir)
+
+ def testPathSplitToList(self):
+ self.assertEquals([''],
+ cpplint.PathSplitToList(os.path.join('')))
+
+ self.assertEquals(['.'],
+ cpplint.PathSplitToList(os.path.join('.')))
+
+ self.assertEquals(['..'],
+ cpplint.PathSplitToList(os.path.join('..')))
+
+ self.assertEquals(['..', 'a', 'b'],
+ cpplint.PathSplitToList(os.path.join('..', 'a', 'b')))
+
+ self.assertEquals(['a', 'b', 'c', 'd'],
+ cpplint.PathSplitToList(os.path.join('a', 'b', 'c', 'd')))
+
+ def testBuildInclude(self):
+ # Test that include statements have slashes in them.
+ self.TestLint('#include "foo.h"',
+ 'Include the directory when naming .h files'
+ ' [build/include] [4]')
+ self.TestLint('#include "Python.h"', '')
+ self.TestLint('#include "lua.h"', '')
+
+ def testBuildPrintfFormat(self):
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(
+ 'foo.cc', 'cc',
+ [r'printf("\%%d", value);',
+ r'snprintf(buffer, sizeof(buffer), "\[%d", value);',
+ r'fprintf(file, "\(%d", value);',
+ r'vsnprintf(buffer, sizeof(buffer), "\\\{%d", ap);'],
+ error_collector)
+ self.assertEquals(
+ 4,
+ error_collector.Results().count(
+ '%, [, (, and { are undefined character escapes. Unescape them.'
+ ' [build/printf_format] [3]'))
+
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(
+ 'foo.cc', 'cc',
+ ['// Copyright 2014 Your Company.',
+ r'printf("\\%%%d", value);',
+ r'printf(R"(\[)");',
+ r'printf(R"(\[%s)", R"(\])");',
+ ''],
+ error_collector)
+ self.assertEquals('', error_collector.Results())
+
+ def testRuntimePrintfFormat(self):
+ self.TestLint(
+ r'fprintf(file, "%q", value);',
+ '%q in format strings is deprecated. Use %ll instead.'
+ ' [runtime/printf_format] [3]')
+
+ self.TestLint(
+ r'aprintf(file, "The number is %12q", value);',
+ '%q in format strings is deprecated. Use %ll instead.'
+ ' [runtime/printf_format] [3]')
+
+ self.TestLint(
+ r'printf(file, "The number is" "%-12q", value);',
+ '%q in format strings is deprecated. Use %ll instead.'
+ ' [runtime/printf_format] [3]')
+
+ self.TestLint(
+ r'printf(file, "The number is" "%+12q", value);',
+ '%q in format strings is deprecated. Use %ll instead.'
+ ' [runtime/printf_format] [3]')
+
+ self.TestLint(
+ r'printf(file, "The number is" "% 12q", value);',
+ '%q in format strings is deprecated. Use %ll instead.'
+ ' [runtime/printf_format] [3]')
+
+ self.TestLint(
+ r'snprintf(file, "Never mix %d and %1$d parameters!", value);',
+ '%N$ formats are unconventional. Try rewriting to avoid them.'
+ ' [runtime/printf_format] [2]')
+
+ def TestLintLogCodeOnError(self, code, expected_message):
+ # Special TestLint which logs the input code on error.
+ result = self.PerformSingleLineLint(code)
+ if result != expected_message:
+ self.fail('For code: "%s"\nGot: "%s"\nExpected: "%s"'
+ % (code, result, expected_message))
+
+ def testBuildStorageClass(self):
+ qualifiers = [None, 'const', 'volatile']
+ signs = [None, 'signed', 'unsigned']
+ types = ['void', 'char', 'int', 'float', 'double',
+ 'schar', 'int8', 'uint8', 'int16', 'uint16',
+ 'int32', 'uint32', 'int64', 'uint64']
+ storage_classes = ['extern', 'register', 'static', 'typedef']
+
+ build_storage_class_error_message = (
+ 'Storage-class specifier (static, extern, typedef, etc) should be '
+ 'at the beginning of the declaration. [build/storage_class] [5]')
+
+ # Some explicit cases. Legal in C++, deprecated in C99.
+ self.TestLint('const int static foo = 5;',
+ build_storage_class_error_message)
+
+ self.TestLint('char static foo;',
+ build_storage_class_error_message)
+
+ self.TestLint('double const static foo = 2.0;',
+ build_storage_class_error_message)
+
+ self.TestLint('uint64 typedef unsigned_long_long;',
+ build_storage_class_error_message)
+
+ self.TestLint('int register foo = 0;',
+ build_storage_class_error_message)
+
+ # Since there are a very large number of possibilities, randomly
+ # construct declarations.
+ # Make sure that the declaration is logged if there's an error.
+ # Seed generator with an integer for absolute reproducibility.
+ random.seed(25)
+ for unused_i in range(10):
+ # Build up random list of non-storage-class declaration specs.
+ other_decl_specs = [random.choice(qualifiers), random.choice(signs),
+ random.choice(types)]
+ # remove None
+ other_decl_specs = [x for x in other_decl_specs if x is not None]
+
+ # shuffle
+ random.shuffle(other_decl_specs)
+
+ # insert storage class after the first
+ storage_class = random.choice(storage_classes)
+ insertion_point = random.randint(1, len(other_decl_specs))
+ decl_specs = (other_decl_specs[0:insertion_point]
+ + [storage_class]
+ + other_decl_specs[insertion_point:])
+
+ self.TestLintLogCodeOnError(
+ ' '.join(decl_specs) + ';',
+ build_storage_class_error_message)
+
+ # but no error if storage class is first
+ self.TestLintLogCodeOnError(
+ storage_class + ' ' + ' '.join(other_decl_specs),
+ '')
+
+ def testLegalCopyright(self):
+ legal_copyright_message = (
+ 'No copyright message found. '
+ 'You should have a line: "Copyright [year] <Copyright Owner>"'
+ ' [legal/copyright] [5]')
+
+ copyright_line = '// Copyright 2014 Google Inc. All Rights Reserved.'
+
+ file_path = 'mydir/googleclient/foo.cc'
+
+ # There should be a copyright message in the first 10 lines
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'cc', [], error_collector)
+ self.assertEquals(
+ 1,
+ error_collector.ResultList().count(legal_copyright_message))
+
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(
+ file_path, 'cc',
+ ['' for unused_i in range(10)] + [copyright_line],
+ error_collector)
+ self.assertEquals(
+ 1,
+ error_collector.ResultList().count(legal_copyright_message))
+
+ # Test that warning isn't issued if Copyright line appears early enough.
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(file_path, 'cc', [copyright_line], error_collector)
+ for message in error_collector.ResultList():
+ if message.find('legal/copyright') != -1:
+ self.fail('Unexpected error: %s' % message)
+
+ error_collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(
+ file_path, 'cc',
+ ['' for unused_i in range(9)] + [copyright_line],
+ error_collector)
+ for message in error_collector.ResultList():
+ if message.find('legal/copyright') != -1:
+ self.fail('Unexpected error: %s' % message)
+
+ def testInvalidIncrement(self):
+ self.TestLint('*count++;',
+ 'Changing pointer instead of value (or unused value of '
+ 'operator*). [runtime/invalid_increment] [5]')
+
+ def testSnprintfSize(self):
+ self.TestLint('vsnprintf(NULL, 0, format)', '')
+ self.TestLint('snprintf(fisk, 1, format)',
+ 'If you can, use sizeof(fisk) instead of 1 as the 2nd arg '
+ 'to snprintf. [runtime/printf] [3]')
+class Cxx11Test(CpplintTestBase):
+
+ def Helper(self, package, extension, lines, count):
+ filename = package + '/foo.' + extension
+ lines = lines[:]
+
+ # Header files need to have an ifdef guard wrapped around their code.
+ if extension == 'h':
+ guard = filename.upper().replace('/', '_').replace('.', '_') + '_'
+ lines.insert(0, '#ifndef ' + guard)
+ lines.insert(1, '#define ' + guard)
+ lines.append('#endif // ' + guard)
+
+ # All files need a final blank line.
+ lines.append('')
+
+ # Process the file and check resulting error count.
+ collector = ErrorCollector(self.assert_)
+ cpplint.ProcessFileData(filename, extension, lines, collector)
+ error_list = collector.ResultList()
+ self.assertEquals(count, len(error_list), error_list)
+
+ def TestCxx11Feature(self, code, expected_error):
+ lines = code.split('\n')
+ collector = ErrorCollector(self.assert_)
+ cpplint.RemoveMultiLineComments('foo.h', lines, collector)
+ clean_lines = cpplint.CleansedLines(lines)
+ cpplint.FlagCxx11Features('foo.cc', clean_lines, 0, collector)
+ self.assertEquals(expected_error, collector.Results())
+
+ def testBlockedHeaders(self):
+ self.TestCxx11Feature('#include <tr1/regex>',
+ 'C++ TR1 headers such as <tr1/regex> are '
+ 'unapproved. [build/c++tr1] [5]')
+ self.TestCxx11Feature('#include <mutex>',
+ '<mutex> is an unapproved C++11 header.'
+ ' [build/c++11] [5]')
+
+ def testBlockedClasses(self):
+ self.TestCxx11Feature('std::alignment_of<T>',
+ 'std::alignment_of is an unapproved '
+ 'C++11 class or function. Send c-style an example '
+ 'of where it would make your code more readable, '
+ 'and they may let you use it.'
+ ' [build/c++11] [5]')
+ self.TestCxx11Feature('std::alignment_offer', '')
+ self.TestCxx11Feature('mystd::alignment_of', '')
+ self.TestCxx11Feature('std::binomial_distribution', '')
+
+ def testBlockedFunctions(self):
+ self.TestCxx11Feature('std::alignment_of<int>',
+ 'std::alignment_of is an unapproved '
+ 'C++11 class or function. Send c-style an example '
+ 'of where it would make your code more readable, '
+ 'and they may let you use it.'
+ ' [build/c++11] [5]')
+ # Missed because of the lack of "std::". Compiles because ADL
+ # looks in the namespace of my_shared_ptr, which (presumably) is
+ # std::. But there will be a lint error somewhere in this file
+ # since my_shared_ptr had to be defined.
+ self.TestCxx11Feature('static_pointer_cast<Base>(my_shared_ptr)', '')
+ self.TestCxx11Feature('std::declval<T>()', '')
+
+ def testExplicitMakePair(self):
+ self.TestLint('make_pair', '')
+ self.TestLint('make_pair(42, 42)', '')
+ self.TestLint('make_pair<',
+ 'For C++11-compatibility, omit template arguments from'
+ ' make_pair OR use pair directly OR if appropriate,'
+ ' construct a pair directly'
+ ' [build/explicit_make_pair] [4]')
+ self.TestLint('make_pair <',
+ 'For C++11-compatibility, omit template arguments from'
+ ' make_pair OR use pair directly OR if appropriate,'
+ ' construct a pair directly'
+ ' [build/explicit_make_pair] [4]')
+ self.TestLint('my_make_pair<int, int>', '')
+
+class Cxx14Test(CpplintTestBase):
+
+ def TestCxx14Feature(self, code, expected_error):
+ lines = code.split('\n')
+ collector = ErrorCollector(self.assert_)
+ cpplint.RemoveMultiLineComments('foo.h', lines, collector)
+ clean_lines = cpplint.CleansedLines(lines)
+ cpplint.FlagCxx14Features('foo.cc', clean_lines, 0, collector)
+ self.assertEquals(expected_error, collector.Results())
+
+ def testBlockedHeaders(self):
+ self.TestCxx14Feature('#include <scoped_allocator>',
+ '<scoped_allocator> is an unapproved C++14 header.'
+ ' [build/c++14] [5]')
+ self.TestCxx14Feature('#include <shared_mutex>',
+ '<shared_mutex> is an unapproved C++14 header.'
+ ' [build/c++14] [5]')
+
+
+class CleansedLinesTest(unittest.TestCase):
+
+ def testInit(self):
+ lines = ['Line 1',
+ 'Line 2',
+ 'Line 3 // Comment test',
+ 'Line 4 /* Comment test */',
+ 'Line 5 "foo"']
+
+ clean_lines = cpplint.CleansedLines(lines)
+ self.assertEquals(lines, clean_lines.raw_lines)
+ self.assertEquals(5, clean_lines.NumLines())
+
+ self.assertEquals(['Line 1',
+ 'Line 2',
+ 'Line 3',
+ 'Line 4',
+ 'Line 5 "foo"'],
+ clean_lines.lines)
+
+ self.assertEquals(['Line 1',
+ 'Line 2',
+ 'Line 3',
+ 'Line 4',
+ 'Line 5 ""'],
+ clean_lines.elided)
+
+ def testInitEmpty(self):
+ clean_lines = cpplint.CleansedLines([])
+ self.assertEquals([], clean_lines.raw_lines)
+ self.assertEquals(0, clean_lines.NumLines())
+
+ def testCollapseStrings(self):
+ collapse = cpplint.CleansedLines._CollapseStrings
+ self.assertEquals('""', collapse('""')) # "" (empty)
+ self.assertEquals('"""', collapse('"""')) # """ (bad)
+ self.assertEquals('""', collapse('"xyz"')) # "xyz" (string)
+ self.assertEquals('""', collapse('"\\\""')) # "\"" (string)
+ self.assertEquals('""', collapse('"\'"')) # "'" (string)
+ self.assertEquals('"\"', collapse('"\"')) # "\" (bad)
+ self.assertEquals('""', collapse('"\\\\"')) # "\\" (string)
+ self.assertEquals('"', collapse('"\\\\\\"')) # "\\\" (bad)
+ self.assertEquals('""', collapse('"\\\\\\\\"')) # "\\\\" (string)
+
+ self.assertEquals('\'\'', collapse('\'\'')) # '' (empty)
+ self.assertEquals('\'\'', collapse('\'a\'')) # 'a' (char)
+ self.assertEquals('\'\'', collapse('\'\\\'\'')) # '\'' (char)
+ self.assertEquals('\'', collapse('\'\\\'')) # '\' (bad)
+ self.assertEquals('', collapse('\\012')) # '\012' (char)
+ self.assertEquals('', collapse('\\xfF0')) # '\xfF0' (char)
+ self.assertEquals('', collapse('\\n')) # '\n' (char)
+ self.assertEquals(r'\#', collapse('\\#')) # '\#' (bad)
+
+ self.assertEquals('"" + ""', collapse('"\'" + "\'"'))
+ self.assertEquals("'', ''", collapse("'\"', '\"'"))
+ self.assertEquals('""[0b10]', collapse('"a\'b"[0b1\'0]'))
+
+ self.assertEquals('42', collapse("4'2"))
+ self.assertEquals('0b0101', collapse("0b0'1'0'1"))
+ self.assertEquals('1048576', collapse("1'048'576"))
+ self.assertEquals('0X100000', collapse("0X10'0000"))
+ self.assertEquals('0004000000', collapse("0'004'000'000"))
+ self.assertEquals('1.602176565e-19', collapse("1.602'176'565e-19"))
+ self.assertEquals('\'\' + 0xffff', collapse("'i' + 0xf'f'f'f"))
+ self.assertEquals('sizeof\'\' == 1', collapse("sizeof'x' == 1"))
+ self.assertEquals('0x.03p100', collapse('0x.0\'3p1\'0\'0'))
+ self.assertEquals('123.45', collapse('1\'23.4\'5'))
+
+ self.assertEquals('StringReplace(body, "", "");',
+ collapse('StringReplace(body, "\\\\", "\\\\\\\\");'))
+ self.assertEquals('\'\' ""',
+ collapse('\'"\' "foo"'))
+
+
+class OrderOfIncludesTest(CpplintTestBase):
+
+ def setUp(self):
+ CpplintTestBase.setUp(self)
+ self.include_state = cpplint._IncludeState()
+ os.path.abspath = lambda value: value
+
+ def testCheckNextIncludeOrder_OtherThenCpp(self):
+ self.assertEqual('', self.include_state.CheckNextIncludeOrder(
+ cpplint._OTHER_HEADER))
+ self.assertEqual('Found C++ system header after other header',
+ self.include_state.CheckNextIncludeOrder(
+ cpplint._CPP_SYS_HEADER))
+
+ def testCheckNextIncludeOrder_CppThenC(self):
+ self.assertEqual('', self.include_state.CheckNextIncludeOrder(
+ cpplint._CPP_SYS_HEADER))
+ self.assertEqual('Found C system header after C++ system header',
+ self.include_state.CheckNextIncludeOrder(
+ cpplint._C_SYS_HEADER))
+
+ def testCheckNextIncludeOrder_LikelyThenCpp(self):
+ self.assertEqual('', self.include_state.CheckNextIncludeOrder(
+ cpplint._LIKELY_MY_HEADER))
+ self.assertEqual('', self.include_state.CheckNextIncludeOrder(
+ cpplint._CPP_SYS_HEADER))
+
+ def testCheckNextIncludeOrder_PossibleThenCpp(self):
+ self.assertEqual('', self.include_state.CheckNextIncludeOrder(
+ cpplint._POSSIBLE_MY_HEADER))
+ self.assertEqual('', self.include_state.CheckNextIncludeOrder(
+ cpplint._CPP_SYS_HEADER))
+
+ def testCheckNextIncludeOrder_CppThenLikely(self):
+ self.assertEqual('', self.include_state.CheckNextIncludeOrder(
+ cpplint._CPP_SYS_HEADER))
+ # This will eventually fail.
+ self.assertEqual('', self.include_state.CheckNextIncludeOrder(
+ cpplint._LIKELY_MY_HEADER))
+
+ def testCheckNextIncludeOrder_CppThenPossible(self):
+ self.assertEqual('', self.include_state.CheckNextIncludeOrder(
+ cpplint._CPP_SYS_HEADER))
+ self.assertEqual('', self.include_state.CheckNextIncludeOrder(
+ cpplint._POSSIBLE_MY_HEADER))
+
+ def testClassifyInclude(self):
+ file_info = cpplint.FileInfo
+ classify_include = cpplint._ClassifyInclude
+ self.assertEqual(cpplint._C_SYS_HEADER,
+ classify_include(file_info('foo/foo.cc'),
+ 'stdio.h',
+ True))
+ self.assertEqual(cpplint._CPP_SYS_HEADER,
+ classify_include(file_info('foo/foo.cc'),
+ 'string',
+ True))
+ self.assertEqual(cpplint._CPP_SYS_HEADER,
+ classify_include(file_info('foo/foo.cc'),
+ 'typeinfo',
+ True))
+ self.assertEqual(cpplint._OTHER_HEADER,
+ classify_include(file_info('foo/foo.cc'),
+ 'string',
+ False))
+
+ self.assertEqual(cpplint._LIKELY_MY_HEADER,
+ classify_include(file_info('foo/foo.cc'),
+ 'foo/foo-inl.h',
+ False))
+ self.assertEqual(cpplint._LIKELY_MY_HEADER,
+ classify_include(file_info('foo/internal/foo.cc'),
+ 'foo/public/foo.h',
+ False))
+ self.assertEqual(cpplint._POSSIBLE_MY_HEADER,
+ classify_include(file_info('foo/internal/foo.cc'),
+ 'foo/other/public/foo.h',
+ False))
+ self.assertEqual(cpplint._OTHER_HEADER,
+ classify_include(file_info('foo/internal/foo.cc'),
+ 'foo/other/public/foop.h',
+ False))
+
+ def testTryDropCommonSuffixes(self):
+ self.assertEqual('foo/foo', cpplint._DropCommonSuffixes('foo/foo-inl.h'))
+ self.assertEqual('foo/bar/foo',
+ cpplint._DropCommonSuffixes('foo/bar/foo_inl.h'))
+ self.assertEqual('foo/foo', cpplint._DropCommonSuffixes('foo/foo.cc'))
+ self.assertEqual('foo/foo_unusualinternal',
+ cpplint._DropCommonSuffixes('foo/foo_unusualinternal.h'))
+ self.assertEqual('',
+ cpplint._DropCommonSuffixes('_test.cc'))
+ self.assertEqual('test',
+ cpplint._DropCommonSuffixes('test.cc'))
+
+ def testRegression(self):
+ def Format(includes):
+ include_list = []
+ for item in includes:
+ if item.startswith('"') or item.startswith('<'):
+ include_list.append('#include %s\n' % item)
+ else:
+ include_list.append(item + '\n')
+ return ''.join(include_list)
+
+ # Test singleton cases first.
+ self.TestLanguageRulesCheck('foo/foo.cc', Format(['"foo/foo.h"']), '')
+ self.TestLanguageRulesCheck('foo/foo.cc', Format(['<stdio.h>']), '')
+ self.TestLanguageRulesCheck('foo/foo.cc', Format(['<string>']), '')
+ self.TestLanguageRulesCheck('foo/foo.cc', Format(['"foo/foo-inl.h"']), '')
+ self.TestLanguageRulesCheck('foo/foo.cc', Format(['"bar/bar-inl.h"']), '')
+ self.TestLanguageRulesCheck('foo/foo.cc', Format(['"bar/bar.h"']), '')
+
+ # Test everything in a good and new order.
+ self.TestLanguageRulesCheck('foo/foo.cc',
+ Format(['"foo/foo.h"',
+ '"foo/foo-inl.h"',
+ '<stdio.h>',
+ '<string>',
+ '<unordered_map>',
+ '"bar/bar-inl.h"',
+ '"bar/bar.h"']),
+ '')
+
+ # Test bad orders.
+ self.TestLanguageRulesCheck(
+ 'foo/foo.cc',
+ Format(['<string>', '<stdio.h>']),
+ 'Found C system header after C++ system header.'
+ ' Should be: foo.h, c system, c++ system, other.'
+ ' [build/include_order] [4]')
+ self.TestLanguageRulesCheck(
+ 'foo/foo.cc',
+ Format(['"foo/bar-inl.h"',
+ '"foo/foo-inl.h"']),
+ '')
+ self.TestLanguageRulesCheck(
+ 'foo/foo.cc',
+ Format(['"foo/e.h"',
+ '"foo/b.h"', # warning here (e>b)
+ '"foo/c.h"',
+ '"foo/d.h"',
+ '"foo/a.h"']), # warning here (d>a)
+ ['Include "foo/b.h" not in alphabetical order'
+ ' [build/include_alpha] [4]',
+ 'Include "foo/a.h" not in alphabetical order'
+ ' [build/include_alpha] [4]'])
+ # -inl.h headers are no longer special.
+ self.TestLanguageRulesCheck('foo/foo.cc',
+ Format(['"foo/foo-inl.h"', '<string>']),
+ '')
+ self.TestLanguageRulesCheck('foo/foo.cc',
+ Format(['"foo/bar.h"', '"foo/bar-inl.h"']),
+ '')
+ # Test componentized header. OK to have my header in ../public dir.
+ self.TestLanguageRulesCheck('foo/internal/foo.cc',
+ Format(['"foo/public/foo.h"', '<string>']),
+ '')
+ # OK to have my header in other dir (not stylistically, but
+ # cpplint isn't as good as a human).
+ self.TestLanguageRulesCheck('foo/internal/foo.cc',
+ Format(['"foo/other/public/foo.h"',
+ '<string>']),
+ '')
+ self.TestLanguageRulesCheck('foo/foo.cc',
+ Format(['"foo/foo.h"',
+ '<string>',
+ '"base/google.h"',
+ '"base/flags.h"']),
+ 'Include "base/flags.h" not in alphabetical '
+ 'order [build/include_alpha] [4]')
+ # According to the style, -inl.h should come before .h, but we don't
+ # complain about that.
+ self.TestLanguageRulesCheck('foo/foo.cc',
+ Format(['"foo/foo-inl.h"',
+ '"foo/foo.h"',
+ '"base/google.h"',
+ '"base/google-inl.h"']),
+ '')
+ # Allow project includes to be separated by blank lines
+ self.TestLanguageRulesCheck('a/a.cc',
+ Format(['"a/a.h"',
+ '<string>',
+ '"base/google.h"',
+ '',
+ '"b/c.h"',
+ '',
+ 'MACRO',
+ '"a/b.h"']),
+ '')
+ self.TestLanguageRulesCheck('a/a.cc',
+ Format(['"a/a.h"',
+ '<string>',
+ '"base/google.h"',
+ '"a/b.h"']),
+ 'Include "a/b.h" not in alphabetical '
+ 'order [build/include_alpha] [4]')
+
+ # Test conditional includes
+ self.TestLanguageRulesCheck(
+ 'a/a.cc',
+ ''.join(['#include <string.h>\n',
+ '#include "base/port.h"\n',
+ '#include <initializer_list>\n']),
+ ('Found C++ system header after other header. '
+ 'Should be: a.h, c system, c++ system, other. '
+ '[build/include_order] [4]'))
+ self.TestLanguageRulesCheck(
+ 'a/a.cc',
+ ''.join(['#include <string.h>\n',
+ '#include "base/port.h"\n',
+ '#ifdef LANG_CXX11\n',
+ '#include <initializer_list>\n',
+ '#endif // LANG_CXX11\n']),
+ '')
+ self.TestLanguageRulesCheck(
+ 'a/a.cc',
+ ''.join(['#include <string.h>\n',
+ '#ifdef LANG_CXX11\n',
+ '#include "base/port.h"\n',
+ '#include <initializer_list>\n',
+ '#endif // LANG_CXX11\n']),
+ ('Found C++ system header after other header. '
+ 'Should be: a.h, c system, c++ system, other. '
+ '[build/include_order] [4]'))
+
+ # Third party headers are exempt from order checks
+ self.TestLanguageRulesCheck('foo/foo.cc',
+ Format(['<string>', '"Python.h"', '<vector>']),
+ '')
+
+
+class CheckForFunctionLengthsTest(CpplintTestBase):
+
+ def setUp(self):
+ # Reducing these thresholds for the tests speeds up tests significantly.
+ self.old_normal_trigger = cpplint._FunctionState._NORMAL_TRIGGER
+ self.old_test_trigger = cpplint._FunctionState._TEST_TRIGGER
+
+ cpplint._FunctionState._NORMAL_TRIGGER = 10
+ cpplint._FunctionState._TEST_TRIGGER = 25
+
+ def tearDown(self):
+ cpplint._FunctionState._NORMAL_TRIGGER = self.old_normal_trigger
+ cpplint._FunctionState._TEST_TRIGGER = self.old_test_trigger
+
+ def TestFunctionLengthsCheck(self, code, expected_message):
+ """Check warnings for long function bodies are as expected.
+
+ Args:
+ code: C++ source code expected to generate a warning message.
+ expected_message: Message expected to be generated by the C++ code.
+ """
+ self.assertEquals(expected_message,
+ self.PerformFunctionLengthsCheck(code))
+
+ def TriggerLines(self, error_level):
+ """Return number of lines needed to trigger a function length warning.
+
+ Args:
+ error_level: --v setting for cpplint.
+
+ Returns:
+ Number of lines needed to trigger a function length warning.
+ """
+ return cpplint._FunctionState._NORMAL_TRIGGER * 2**error_level
+
+ def TestLines(self, error_level):
+ """Return number of lines needed to trigger a test function length warning.
+
+ Args:
+ error_level: --v setting for cpplint.
+
+ Returns:
+ Number of lines needed to trigger a test function length warning.
+ """
+ return cpplint._FunctionState._TEST_TRIGGER * 2**error_level
+
+ def TestFunctionLengthCheckDefinition(self, lines, error_level):
+ """Generate long function definition and check warnings are as expected.
+
+ Args:
+ lines: Number of lines to generate.
+ error_level: --v setting for cpplint.
+ """
+ trigger_level = self.TriggerLines(cpplint._VerboseLevel())
+ self.TestFunctionLengthsCheck(
+ 'void test(int x)' + self.FunctionBody(lines),
+ ('Small and focused functions are preferred: '
+ 'test() has %d non-comment lines '
+ '(error triggered by exceeding %d lines).'
+ ' [readability/fn_size] [%d]'
+ % (lines, trigger_level, error_level)))
+
+ def TestFunctionLengthCheckDefinitionOK(self, lines):
+ """Generate shorter function definition and check no warning is produced.
+
+ Args:
+ lines: Number of lines to generate.
+ """
+ self.TestFunctionLengthsCheck(
+ 'void test(int x)' + self.FunctionBody(lines),
+ '')
+
+ def TestFunctionLengthCheckAtErrorLevel(self, error_level):
+ """Generate and check function at the trigger level for --v setting.
+
+ Args:
+ error_level: --v setting for cpplint.
+ """
+ self.TestFunctionLengthCheckDefinition(self.TriggerLines(error_level),
+ error_level)
+
+ def TestFunctionLengthCheckBelowErrorLevel(self, error_level):
+ """Generate and check function just below the trigger level for --v setting.
+
+ Args:
+ error_level: --v setting for cpplint.
+ """
+ self.TestFunctionLengthCheckDefinition(self.TriggerLines(error_level)-1,
+ error_level-1)
+
+ def TestFunctionLengthCheckAboveErrorLevel(self, error_level):
+ """Generate and check function just above the trigger level for --v setting.
+
+ Args:
+ error_level: --v setting for cpplint.
+ """
+ self.TestFunctionLengthCheckDefinition(self.TriggerLines(error_level)+1,
+ error_level)
+
+ def FunctionBody(self, number_of_lines):
+ return ' {\n' + ' this_is_just_a_test();\n'*number_of_lines + '}'
+
+ def FunctionBodyWithBlankLines(self, number_of_lines):
+ return ' {\n' + ' this_is_just_a_test();\n\n'*number_of_lines + '}'
+
+ def FunctionBodyWithNoLints(self, number_of_lines):
+ return (' {\n' +
+ ' this_is_just_a_test(); // NOLINT\n'*number_of_lines + '}')
+
+ # Test line length checks.
+ def testFunctionLengthCheckDeclaration(self):
+ self.TestFunctionLengthsCheck(
+ 'void test();', # Not a function definition
+ '')
+
+ def testFunctionLengthCheckDeclarationWithBlockFollowing(self):
+ self.TestFunctionLengthsCheck(
+ ('void test();\n'
+ + self.FunctionBody(66)), # Not a function definition
+ '')
+
+ def testFunctionLengthCheckClassDefinition(self):
+ self.TestFunctionLengthsCheck( # Not a function definition
+ 'class Test' + self.FunctionBody(66) + ';',
+ '')
+
+ def testFunctionLengthCheckTrivial(self):
+ self.TestFunctionLengthsCheck(
+ 'void test() {}', # Not counted
+ '')
+
+ def testFunctionLengthCheckEmpty(self):
+ self.TestFunctionLengthsCheck(
+ 'void test() {\n}',
+ '')
+
+ def testFunctionLengthCheckDefinitionBelowSeverity0(self):
+ old_verbosity = cpplint._SetVerboseLevel(0)
+ self.TestFunctionLengthCheckDefinitionOK(self.TriggerLines(0)-1)
+ cpplint._SetVerboseLevel(old_verbosity)
+
+ def testFunctionLengthCheckDefinitionAtSeverity0(self):
+ old_verbosity = cpplint._SetVerboseLevel(0)
+ self.TestFunctionLengthCheckDefinitionOK(self.TriggerLines(0))
+ cpplint._SetVerboseLevel(old_verbosity)
+
+ def testFunctionLengthCheckDefinitionAboveSeverity0(self):
+ old_verbosity = cpplint._SetVerboseLevel(0)
+ self.TestFunctionLengthCheckAboveErrorLevel(0)
+ cpplint._SetVerboseLevel(old_verbosity)
+
+ def testFunctionLengthCheckDefinitionBelowSeverity1v0(self):
+ old_verbosity = cpplint._SetVerboseLevel(0)
+ self.TestFunctionLengthCheckBelowErrorLevel(1)
+ cpplint._SetVerboseLevel(old_verbosity)
+
+ def testFunctionLengthCheckDefinitionAtSeverity1v0(self):
+ old_verbosity = cpplint._SetVerboseLevel(0)
+ self.TestFunctionLengthCheckAtErrorLevel(1)
+ cpplint._SetVerboseLevel(old_verbosity)
+
+ def testFunctionLengthCheckDefinitionBelowSeverity1(self):
+ self.TestFunctionLengthCheckDefinitionOK(self.TriggerLines(1)-1)
+
+ def testFunctionLengthCheckDefinitionAtSeverity1(self):
+ self.TestFunctionLengthCheckDefinitionOK(self.TriggerLines(1))
+
+ def testFunctionLengthCheckDefinitionAboveSeverity1(self):
+ self.TestFunctionLengthCheckAboveErrorLevel(1)
+
+ def testFunctionLengthCheckDefinitionSeverity1PlusBlanks(self):
+ error_level = 1
+ error_lines = self.TriggerLines(error_level) + 1
+ trigger_level = self.TriggerLines(cpplint._VerboseLevel())
+ self.TestFunctionLengthsCheck(
+ 'void test_blanks(int x)' + self.FunctionBody(error_lines),
+ ('Small and focused functions are preferred: '
+ 'test_blanks() has %d non-comment lines '
+ '(error triggered by exceeding %d lines).'
+ ' [readability/fn_size] [%d]')
+ % (error_lines, trigger_level, error_level))
+
+ def testFunctionLengthCheckComplexDefinitionSeverity1(self):
+ error_level = 1
+ error_lines = self.TriggerLines(error_level) + 1
+ trigger_level = self.TriggerLines(cpplint._VerboseLevel())
+ self.TestFunctionLengthsCheck(
+ ('my_namespace::my_other_namespace::MyVeryLongTypeName*\n'
+ 'my_namespace::my_other_namespace::MyFunction(int arg1, char* arg2)'
+ + self.FunctionBody(error_lines)),
+ ('Small and focused functions are preferred: '
+ 'my_namespace::my_other_namespace::MyFunction()'
+ ' has %d non-comment lines '
+ '(error triggered by exceeding %d lines).'
+ ' [readability/fn_size] [%d]')
+ % (error_lines, trigger_level, error_level))
+
+ def testFunctionLengthCheckDefinitionSeverity1ForTest(self):
+ error_level = 1
+ error_lines = self.TestLines(error_level) + 1
+ trigger_level = self.TestLines(cpplint._VerboseLevel())
+ self.TestFunctionLengthsCheck(
+ 'TEST_F(Test, Mutator)' + self.FunctionBody(error_lines),
+ ('Small and focused functions are preferred: '
+ 'TEST_F(Test, Mutator) has %d non-comment lines '
+ '(error triggered by exceeding %d lines).'
+ ' [readability/fn_size] [%d]')
+ % (error_lines, trigger_level, error_level))
+
+ def testFunctionLengthCheckDefinitionSeverity1ForSplitLineTest(self):
+ error_level = 1
+ error_lines = self.TestLines(error_level) + 1
+ trigger_level = self.TestLines(cpplint._VerboseLevel())
+ self.TestFunctionLengthsCheck(
+ ('TEST_F(GoogleUpdateRecoveryRegistryProtectedTest,\n'
+ ' FixGoogleUpdate_AllValues_MachineApp)' # note: 4 spaces
+ + self.FunctionBody(error_lines)),
+ ('Small and focused functions are preferred: '
+ 'TEST_F(GoogleUpdateRecoveryRegistryProtectedTest, ' # 1 space
+ 'FixGoogleUpdate_AllValues_MachineApp) has %d non-comment lines '
+ '(error triggered by exceeding %d lines).'
+ ' [readability/fn_size] [%d]')
+ % (error_lines+1, trigger_level, error_level))
+
+ def testFunctionLengthCheckDefinitionSeverity1ForBadTestDoesntBreak(self):
+ error_level = 1
+ error_lines = self.TestLines(error_level) + 1
+ trigger_level = self.TestLines(cpplint._VerboseLevel())
+ self.TestFunctionLengthsCheck(
+ ('TEST_F('
+ + self.FunctionBody(error_lines)),
+ ('Small and focused functions are preferred: '
+ 'TEST_F has %d non-comment lines '
+ '(error triggered by exceeding %d lines).'
+ ' [readability/fn_size] [%d]')
+ % (error_lines, trigger_level, error_level))
+
+ def testFunctionLengthCheckDefinitionSeverity1WithEmbeddedNoLints(self):
+ error_level = 1
+ error_lines = self.TriggerLines(error_level)+1
+ trigger_level = self.TriggerLines(cpplint._VerboseLevel())
+ self.TestFunctionLengthsCheck(
+ 'void test(int x)' + self.FunctionBodyWithNoLints(error_lines),
+ ('Small and focused functions are preferred: '
+ 'test() has %d non-comment lines '
+ '(error triggered by exceeding %d lines).'
+ ' [readability/fn_size] [%d]')
+ % (error_lines, trigger_level, error_level))
+
+ def testFunctionLengthCheckDefinitionSeverity1WithNoLint(self):
+ self.TestFunctionLengthsCheck(
+ ('void test(int x)' + self.FunctionBody(self.TriggerLines(1))
+ + ' // NOLINT -- long function'),
+ '')
+
+ def testFunctionLengthCheckDefinitionBelowSeverity2(self):
+ self.TestFunctionLengthCheckBelowErrorLevel(2)
+
+ def testFunctionLengthCheckDefinitionSeverity2(self):
+ self.TestFunctionLengthCheckAtErrorLevel(2)
+
+ def testFunctionLengthCheckDefinitionAboveSeverity2(self):
+ self.TestFunctionLengthCheckAboveErrorLevel(2)
+
+ def testFunctionLengthCheckDefinitionBelowSeverity3(self):
+ self.TestFunctionLengthCheckBelowErrorLevel(3)
+
+ def testFunctionLengthCheckDefinitionSeverity3(self):
+ self.TestFunctionLengthCheckAtErrorLevel(3)
+
+ def testFunctionLengthCheckDefinitionAboveSeverity3(self):
+ self.TestFunctionLengthCheckAboveErrorLevel(3)
+
+ def testFunctionLengthCheckDefinitionBelowSeverity4(self):
+ self.TestFunctionLengthCheckBelowErrorLevel(4)
+
+ def testFunctionLengthCheckDefinitionSeverity4(self):
+ self.TestFunctionLengthCheckAtErrorLevel(4)
+
+ def testFunctionLengthCheckDefinitionAboveSeverity4(self):
+ self.TestFunctionLengthCheckAboveErrorLevel(4)
+
+ def testFunctionLengthCheckDefinitionBelowSeverity5(self):
+ self.TestFunctionLengthCheckBelowErrorLevel(5)
+
+ def testFunctionLengthCheckDefinitionAtSeverity5(self):
+ self.TestFunctionLengthCheckAtErrorLevel(5)
+
+ def testFunctionLengthCheckDefinitionAboveSeverity5(self):
+ self.TestFunctionLengthCheckAboveErrorLevel(5)
+
+ def testFunctionLengthCheckDefinitionHugeLines(self):
+ # 5 is the limit
+ self.TestFunctionLengthCheckDefinition(self.TriggerLines(10), 5)
+
+ def testFunctionLengthNotDeterminable(self):
+ # Macro invocation without terminating semicolon.
+ self.TestFunctionLengthsCheck(
+ 'MACRO(arg)',
+ '')
+
+ # Macro with underscores
+ self.TestFunctionLengthsCheck(
+ 'MACRO_WITH_UNDERSCORES(arg1, arg2, arg3)',
+ '')
+
+ self.TestFunctionLengthsCheck(
+ 'NonMacro(arg)',
+ 'Lint failed to find start of function body.'
+ ' [readability/fn_size] [5]')
+
+ def testFunctionLengthCheckWithNamespace(self):
+ old_verbosity = cpplint._SetVerboseLevel(1)
+ self.TestFunctionLengthsCheck(
+ ('namespace {\n'
+ 'void CodeCoverageCL35256059() {\n' +
+ (' X++;\n' * 3000) +
+ '}\n'
+ '} // namespace\n'),
+ ('Small and focused functions are preferred: '
+ 'CodeCoverageCL35256059() has 3000 non-comment lines '
+ '(error triggered by exceeding 20 lines).'
+ ' [readability/fn_size] [5]'))
+ cpplint._SetVerboseLevel(old_verbosity)
+
+
+def TrimExtraIndent(text_block):
+ """Trim a uniform amount of whitespace off of each line in a string.
+
+ Compute the minimum indent on all non blank lines and trim that from each, so
+ that the block of text has no extra indentation.
+
+ Args:
+ text_block: a multiline string
+
+ Returns:
+ text_block with the common whitespace indent of each line removed.
+ """
+
+ def CountLeadingWhitespace(s):
+ count = 0
+ for c in s:
+ if not c.isspace():
+ break
+ count += 1
+ return count
+ # find the minimum indent (except for blank lines)
+ min_indent = min([CountLeadingWhitespace(line)
+ for line in text_block.split('\n') if line])
+ return '\n'.join([line[min_indent:] for line in text_block.split('\n')])
+
+
+class CloseExpressionTest(unittest.TestCase):
+
+ def setUp(self):
+ self.lines = cpplint.CleansedLines(
+ # 1 2 3 4 5
+ # 0123456789012345678901234567890123456789012345678901234567890
+ ['// Line 0',
+ 'inline RCULocked<X>::ReadPtr::ReadPtr(const RCULocked* rcu) {',
+ ' DCHECK(!(data & kFlagMask)) << "Error";',
+ '}',
+ '// Line 4',
+ 'RCULocked<X>::WritePtr::WritePtr(RCULocked* rcu)',
+ ' : lock_(&rcu_->mutex_) {',
+ '}',
+ '// Line 8',
+ 'template <typename T, typename... A>',
+ 'typename std::enable_if<',
+ ' std::is_array<T>::value && (std::extent<T>::value > 0)>::type',
+ 'MakeUnique(A&&... a) = delete;',
+ '// Line 13',
+ 'auto x = []() {};',
+ '// Line 15',
+ 'template <typename U>',
+ 'friend bool operator==(const reffed_ptr& a,',
+ ' const reffed_ptr<U>& b) {',
+ ' return a.get() == b.get();',
+ '}',
+ '// Line 21'])
+
+ def testCloseExpression(self):
+ # List of positions to test:
+ # (start line, start position, end line, end position + 1)
+ positions = [(1, 16, 1, 19),
+ (1, 37, 1, 59),
+ (1, 60, 3, 1),
+ (2, 8, 2, 29),
+ (2, 30, 22, -1), # Left shift operator
+ (9, 9, 9, 36),
+ (10, 23, 11, 59),
+ (11, 54, 22, -1), # Greater than operator
+ (14, 9, 14, 11),
+ (14, 11, 14, 13),
+ (14, 14, 14, 16),
+ (17, 22, 18, 46),
+ (18, 47, 20, 1)]
+ for p in positions:
+ (_, line, column) = cpplint.CloseExpression(self.lines, p[0], p[1])
+ self.assertEquals((p[2], p[3]), (line, column))
+
+ def testReverseCloseExpression(self):
+ # List of positions to test:
+ # (end line, end position, start line, start position)
+ positions = [(1, 18, 1, 16),
+ (1, 58, 1, 37),
+ (2, 27, 2, 10),
+ (2, 28, 2, 8),
+ (6, 18, 0, -1), # -> operator
+ (9, 35, 9, 9),
+ (11, 54, 0, -1), # Greater than operator
+ (11, 57, 11, 31),
+ (14, 10, 14, 9),
+ (14, 12, 14, 11),
+ (14, 15, 14, 14),
+ (18, 45, 17, 22),
+ (20, 0, 18, 47)]
+ for p in positions:
+ (_, line, column) = cpplint.ReverseCloseExpression(self.lines, p[0], p[1])
+ self.assertEquals((p[2], p[3]), (line, column))
+
+
+class NestingStateTest(unittest.TestCase):
+
+ def setUp(self):
+ self.nesting_state = cpplint.NestingState()
+ self.error_collector = ErrorCollector(self.assert_)
+
+ def UpdateWithLines(self, lines):
+ clean_lines = cpplint.CleansedLines(lines)
+ for line in xrange(clean_lines.NumLines()):
+ self.nesting_state.Update('test.cc',
+ clean_lines, line, self.error_collector)
+
+ def testEmpty(self):
+ self.UpdateWithLines([])
+ self.assertEquals(self.nesting_state.stack, [])
+
+ def testNamespace(self):
+ self.UpdateWithLines(['namespace {'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertTrue(isinstance(self.nesting_state.stack[0],
+ cpplint._NamespaceInfo))
+ self.assertTrue(self.nesting_state.stack[0].seen_open_brace)
+ self.assertEquals(self.nesting_state.stack[0].name, '')
+
+ self.UpdateWithLines(['namespace outer { namespace inner'])
+ self.assertEquals(len(self.nesting_state.stack), 3)
+ self.assertTrue(self.nesting_state.stack[0].seen_open_brace)
+ self.assertTrue(self.nesting_state.stack[1].seen_open_brace)
+ self.assertFalse(self.nesting_state.stack[2].seen_open_brace)
+ self.assertEquals(self.nesting_state.stack[0].name, '')
+ self.assertEquals(self.nesting_state.stack[1].name, 'outer')
+ self.assertEquals(self.nesting_state.stack[2].name, 'inner')
+
+ self.UpdateWithLines(['{'])
+ self.assertTrue(self.nesting_state.stack[2].seen_open_brace)
+
+ self.UpdateWithLines(['}', '}}'])
+ self.assertEquals(len(self.nesting_state.stack), 0)
+
+ def testClass(self):
+ self.UpdateWithLines(['class A {'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertTrue(isinstance(self.nesting_state.stack[0], cpplint._ClassInfo))
+ self.assertEquals(self.nesting_state.stack[0].name, 'A')
+ self.assertFalse(self.nesting_state.stack[0].is_derived)
+ self.assertEquals(self.nesting_state.stack[0].class_indent, 0)
+
+ self.UpdateWithLines(['};',
+ 'struct B : public A {'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertTrue(isinstance(self.nesting_state.stack[0], cpplint._ClassInfo))
+ self.assertEquals(self.nesting_state.stack[0].name, 'B')
+ self.assertTrue(self.nesting_state.stack[0].is_derived)
+
+ self.UpdateWithLines(['};',
+ 'class C',
+ ': public A {'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertTrue(isinstance(self.nesting_state.stack[0], cpplint._ClassInfo))
+ self.assertEquals(self.nesting_state.stack[0].name, 'C')
+ self.assertTrue(self.nesting_state.stack[0].is_derived)
+
+ self.UpdateWithLines(['};',
+ 'template<T>'])
+ self.assertEquals(len(self.nesting_state.stack), 0)
+
+ self.UpdateWithLines(['class D {', ' class E {'])
+ self.assertEquals(len(self.nesting_state.stack), 2)
+ self.assertTrue(isinstance(self.nesting_state.stack[0], cpplint._ClassInfo))
+ self.assertEquals(self.nesting_state.stack[0].name, 'D')
+ self.assertFalse(self.nesting_state.stack[0].is_derived)
+ self.assertTrue(isinstance(self.nesting_state.stack[1], cpplint._ClassInfo))
+ self.assertEquals(self.nesting_state.stack[1].name, 'E')
+ self.assertFalse(self.nesting_state.stack[1].is_derived)
+ self.assertEquals(self.nesting_state.stack[1].class_indent, 2)
+ self.assertEquals(self.nesting_state.InnermostClass().name, 'E')
+
+ self.UpdateWithLines(['}', '}'])
+ self.assertEquals(len(self.nesting_state.stack), 0)
+
+ def testClassAccess(self):
+ self.UpdateWithLines(['class A {'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertTrue(isinstance(self.nesting_state.stack[0], cpplint._ClassInfo))
+ self.assertEquals(self.nesting_state.stack[0].access, 'private')
+
+ self.UpdateWithLines([' public:'])
+ self.assertEquals(self.nesting_state.stack[0].access, 'public')
+ self.UpdateWithLines([' protracted:'])
+ self.assertEquals(self.nesting_state.stack[0].access, 'public')
+ self.UpdateWithLines([' protected:'])
+ self.assertEquals(self.nesting_state.stack[0].access, 'protected')
+ self.UpdateWithLines([' private:'])
+ self.assertEquals(self.nesting_state.stack[0].access, 'private')
+
+ self.UpdateWithLines([' struct B {'])
+ self.assertEquals(len(self.nesting_state.stack), 2)
+ self.assertTrue(isinstance(self.nesting_state.stack[1], cpplint._ClassInfo))
+ self.assertEquals(self.nesting_state.stack[1].access, 'public')
+ self.assertEquals(self.nesting_state.stack[0].access, 'private')
+
+ self.UpdateWithLines([' protected :'])
+ self.assertEquals(self.nesting_state.stack[1].access, 'protected')
+ self.assertEquals(self.nesting_state.stack[0].access, 'private')
+
+ self.UpdateWithLines([' }', '}'])
+ self.assertEquals(len(self.nesting_state.stack), 0)
+
+ def testStruct(self):
+ self.UpdateWithLines(['struct A {'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertTrue(isinstance(self.nesting_state.stack[0], cpplint._ClassInfo))
+ self.assertEquals(self.nesting_state.stack[0].name, 'A')
+ self.assertFalse(self.nesting_state.stack[0].is_derived)
+
+ self.UpdateWithLines(['}',
+ 'void Func(struct B arg) {'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertFalse(isinstance(self.nesting_state.stack[0],
+ cpplint._ClassInfo))
+
+ self.UpdateWithLines(['}'])
+ self.assertEquals(len(self.nesting_state.stack), 0)
+
+ def testPreprocessor(self):
+ self.assertEquals(len(self.nesting_state.pp_stack), 0)
+ self.UpdateWithLines(['#if MACRO1'])
+ self.assertEquals(len(self.nesting_state.pp_stack), 1)
+ self.UpdateWithLines(['#endif'])
+ self.assertEquals(len(self.nesting_state.pp_stack), 0)
+
+ self.UpdateWithLines(['#ifdef MACRO2'])
+ self.assertEquals(len(self.nesting_state.pp_stack), 1)
+ self.UpdateWithLines(['#else'])
+ self.assertEquals(len(self.nesting_state.pp_stack), 1)
+ self.UpdateWithLines(['#ifdef MACRO3'])
+ self.assertEquals(len(self.nesting_state.pp_stack), 2)
+ self.UpdateWithLines(['#elif MACRO4'])
+ self.assertEquals(len(self.nesting_state.pp_stack), 2)
+ self.UpdateWithLines(['#endif'])
+ self.assertEquals(len(self.nesting_state.pp_stack), 1)
+ self.UpdateWithLines(['#endif'])
+ self.assertEquals(len(self.nesting_state.pp_stack), 0)
+
+ self.UpdateWithLines(['#ifdef MACRO5',
+ 'class A {',
+ '#elif MACRO6',
+ 'class B {',
+ '#else',
+ 'class C {',
+ '#endif'])
+ self.assertEquals(len(self.nesting_state.pp_stack), 0)
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertTrue(isinstance(self.nesting_state.stack[0], cpplint._ClassInfo))
+ self.assertEquals(self.nesting_state.stack[0].name, 'A')
+ self.UpdateWithLines(['};'])
+ self.assertEquals(len(self.nesting_state.stack), 0)
+
+ self.UpdateWithLines(['class D',
+ '#ifdef MACRO7'])
+ self.assertEquals(len(self.nesting_state.pp_stack), 1)
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertTrue(isinstance(self.nesting_state.stack[0], cpplint._ClassInfo))
+ self.assertEquals(self.nesting_state.stack[0].name, 'D')
+ self.assertFalse(self.nesting_state.stack[0].is_derived)
+
+ self.UpdateWithLines(['#elif MACRO8',
+ ': public E'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertEquals(self.nesting_state.stack[0].name, 'D')
+ self.assertTrue(self.nesting_state.stack[0].is_derived)
+ self.assertFalse(self.nesting_state.stack[0].seen_open_brace)
+
+ self.UpdateWithLines(['#else',
+ '{'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertEquals(self.nesting_state.stack[0].name, 'D')
+ self.assertFalse(self.nesting_state.stack[0].is_derived)
+ self.assertTrue(self.nesting_state.stack[0].seen_open_brace)
+
+ self.UpdateWithLines(['#endif'])
+ self.assertEquals(len(self.nesting_state.pp_stack), 0)
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertEquals(self.nesting_state.stack[0].name, 'D')
+ self.assertFalse(self.nesting_state.stack[0].is_derived)
+ self.assertFalse(self.nesting_state.stack[0].seen_open_brace)
+
+ self.UpdateWithLines([';'])
+ self.assertEquals(len(self.nesting_state.stack), 0)
+
+ def testTemplate(self):
+ self.UpdateWithLines(['template <T,',
+ ' class Arg1 = tmpl<T> >'])
+ self.assertEquals(len(self.nesting_state.stack), 0)
+ self.UpdateWithLines(['class A {'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertTrue(isinstance(self.nesting_state.stack[0], cpplint._ClassInfo))
+ self.assertEquals(self.nesting_state.stack[0].name, 'A')
+
+ self.UpdateWithLines(['};',
+ 'template <T,',
+ ' template <typename, typename> class B>',
+ 'class C'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertTrue(isinstance(self.nesting_state.stack[0], cpplint._ClassInfo))
+ self.assertEquals(self.nesting_state.stack[0].name, 'C')
+ self.UpdateWithLines([';'])
+ self.assertEquals(len(self.nesting_state.stack), 0)
+
+ self.UpdateWithLines(['class D : public Tmpl<E>'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertTrue(isinstance(self.nesting_state.stack[0], cpplint._ClassInfo))
+ self.assertEquals(self.nesting_state.stack[0].name, 'D')
+
+ self.UpdateWithLines(['{', '};'])
+ self.assertEquals(len(self.nesting_state.stack), 0)
+
+ self.UpdateWithLines(['template <class F,',
+ ' class G,',
+ ' class H,',
+ ' typename I>',
+ 'static void Func() {'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertFalse(isinstance(self.nesting_state.stack[0],
+ cpplint._ClassInfo))
+ self.UpdateWithLines(['}',
+ 'template <class J> class K {'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertTrue(isinstance(self.nesting_state.stack[0], cpplint._ClassInfo))
+ self.assertEquals(self.nesting_state.stack[0].name, 'K')
+
+ def testTemplateInnerClass(self):
+ self.UpdateWithLines(['class A {',
+ ' public:'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertTrue(isinstance(self.nesting_state.stack[0], cpplint._ClassInfo))
+
+ self.UpdateWithLines([' template <class B>',
+ ' class C<alloc<B> >',
+ ' : public A {'])
+ self.assertEquals(len(self.nesting_state.stack), 2)
+ self.assertTrue(isinstance(self.nesting_state.stack[1], cpplint._ClassInfo))
+
+ def testArguments(self):
+ self.UpdateWithLines(['class A {'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertTrue(isinstance(self.nesting_state.stack[0], cpplint._ClassInfo))
+ self.assertEquals(self.nesting_state.stack[0].name, 'A')
+ self.assertEquals(self.nesting_state.stack[-1].open_parentheses, 0)
+
+ self.UpdateWithLines([' void Func(',
+ ' struct X arg1,'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertEquals(self.nesting_state.stack[-1].open_parentheses, 1)
+ self.UpdateWithLines([' struct X *arg2);'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertEquals(self.nesting_state.stack[-1].open_parentheses, 0)
+
+ self.UpdateWithLines(['};'])
+ self.assertEquals(len(self.nesting_state.stack), 0)
+
+ self.UpdateWithLines(['struct B {'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertTrue(isinstance(self.nesting_state.stack[0], cpplint._ClassInfo))
+ self.assertEquals(self.nesting_state.stack[0].name, 'B')
+
+ self.UpdateWithLines(['#ifdef MACRO',
+ ' void Func(',
+ ' struct X arg1'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertEquals(self.nesting_state.stack[-1].open_parentheses, 1)
+ self.UpdateWithLines(['#else'])
+
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertEquals(self.nesting_state.stack[-1].open_parentheses, 0)
+ self.UpdateWithLines([' void Func(',
+ ' struct X arg1'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertEquals(self.nesting_state.stack[-1].open_parentheses, 1)
+
+ self.UpdateWithLines(['#endif'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertEquals(self.nesting_state.stack[-1].open_parentheses, 1)
+ self.UpdateWithLines([' struct X *arg2);'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertEquals(self.nesting_state.stack[-1].open_parentheses, 0)
+
+ self.UpdateWithLines(['};'])
+ self.assertEquals(len(self.nesting_state.stack), 0)
+
+ def testInlineAssembly(self):
+ self.UpdateWithLines(['void CopyRow_SSE2(const uint8* src, uint8* dst,',
+ ' int count) {'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertEquals(self.nesting_state.stack[-1].open_parentheses, 0)
+ self.assertEquals(self.nesting_state.stack[-1].inline_asm, cpplint._NO_ASM)
+
+ self.UpdateWithLines([' asm volatile ('])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertEquals(self.nesting_state.stack[-1].open_parentheses, 1)
+ self.assertEquals(self.nesting_state.stack[-1].inline_asm,
+ cpplint._INSIDE_ASM)
+
+ self.UpdateWithLines([' "sub %0,%1 \\n"',
+ ' "1: \\n"',
+ ' "movdqa (%0),%%xmm0 \\n"',
+ ' "movdqa 0x10(%0),%%xmm1 \\n"',
+ ' "movdqa %%xmm0,(%0,%1) \\n"',
+ ' "movdqa %%xmm1,0x10(%0,%1) \\n"',
+ ' "lea 0x20(%0),%0 \\n"',
+ ' "sub $0x20,%2 \\n"',
+ ' "jg 1b \\n"',
+ ' : "+r"(src), // %0',
+ ' "+r"(dst), // %1',
+ ' "+r"(count) // %2',
+ ' :',
+ ' : "memory", "cc"'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertEquals(self.nesting_state.stack[-1].open_parentheses, 1)
+ self.assertEquals(self.nesting_state.stack[-1].inline_asm,
+ cpplint._INSIDE_ASM)
+
+ self.UpdateWithLines(['#if defined(__SSE2__)',
+ ' , "xmm0", "xmm1"'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertEquals(self.nesting_state.stack[-1].open_parentheses, 1)
+ self.assertEquals(self.nesting_state.stack[-1].inline_asm,
+ cpplint._INSIDE_ASM)
+
+ self.UpdateWithLines(['#endif'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertEquals(self.nesting_state.stack[-1].open_parentheses, 1)
+ self.assertEquals(self.nesting_state.stack[-1].inline_asm,
+ cpplint._INSIDE_ASM)
+
+ self.UpdateWithLines([' );'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+ self.assertEquals(self.nesting_state.stack[-1].open_parentheses, 0)
+ self.assertEquals(self.nesting_state.stack[-1].inline_asm, cpplint._END_ASM)
+
+ self.UpdateWithLines(['__asm {'])
+ self.assertEquals(len(self.nesting_state.stack), 2)
+ self.assertEquals(self.nesting_state.stack[-1].open_parentheses, 0)
+ self.assertEquals(self.nesting_state.stack[-1].inline_asm,
+ cpplint._BLOCK_ASM)
+
+ self.UpdateWithLines(['}'])
+ self.assertEquals(len(self.nesting_state.stack), 1)
+
+ self.UpdateWithLines(['}'])
+ self.assertEquals(len(self.nesting_state.stack), 0)
+
+
+class QuietTest(unittest.TestCase):
+
+ def setUp(self):
+ self.this_dir_path = os.path.dirname(os.path.abspath(__file__))
+ self.python_executable = sys.executable or 'python'
+ self.cpplint_test_h = os.path.join(self.this_dir_path,
+ 'cpplint_test_header.h')
+
+ def _runCppLint(self, *args):
+ cpplint_abspath = os.path.join(self.this_dir_path, 'cpplint.py')
+
+ cmd_line = [self.python_executable, cpplint_abspath] + \
+ list(args) + \
+ [ self.cpplint_test_h ]
+
+ return_code = 0
+ try:
+ output = subprocess.check_output(cmd_line,
+ stderr=subprocess.STDOUT)
+ except subprocess.CalledProcessError as err:
+ return_code = err.returncode
+ output = err.output
+
+ return (return_code, output)
+
+ def testNonQuietWithErrors(self):
+ # This will fail: the test header is missing a copyright and header guard.
+ (return_code, output) = self._runCppLint()
+ self.assertEquals(1, return_code)
+ # Always-on behavior: Print error messages as they come up.
+ self.assertIn("[legal/copyright]", output)
+ self.assertIn("[build/header_guard]", output)
+ # If --quiet was unspecified: Print 'Done processing' and 'Total errors..'
+ self.assertIn("Done processing", output)
+ self.assertIn("Total errors found:", output)
+
+ def testQuietWithErrors(self):
+ # When there are errors, behavior is identical to not passing --quiet.
+ (return_code, output) = self._runCppLint('--quiet')
+ self.assertEquals(1, return_code)
+ self.assertIn("[legal/copyright]", output)
+ self.assertIn("[build/header_guard]", output)
+ # Even though --quiet was used, print these since there were errors.
+ self.assertIn("Done processing", output)
+ self.assertIn("Total errors found:", output)
+
+ def testNonQuietWithoutErrors(self):
+ # This will succeed. We filtered out all the known errors for that file.
+ (return_code, output) = self._runCppLint('--filter=' +
+ '-legal/copyright,' +
+ '-build/header_guard')
+ self.assertEquals(0, return_code, output)
+ # No cpplint errors are printed since there were no errors.
+ self.assertNotIn("[legal/copyright]", output)
+ self.assertNotIn("[build/header_guard]", output)
+ # Print 'Done processing' and 'Total errors found' since
+ # --quiet was not specified.
+ self.assertIn("Done processing", output)
+ self.assertIn("Total errors found:", output)
+
+ def testQuietWithoutErrors(self):
+ # This will succeed. We filtered out all the known errors for that file.
+ (return_code, output) = self._runCppLint('--quiet',
+ '--filter=' +
+ '-legal/copyright,' +
+ '-build/header_guard')
+ self.assertEquals(0, return_code, output)
+ # No cpplint errors are printed since there were no errors.
+ self.assertNotIn("[legal/copyright]", output)
+ self.assertNotIn("[build/header_guard]", output)
+ # --quiet was specified and there were no errors:
+ # skip the printing of 'Done processing' and 'Total errors..'
+ self.assertNotIn("Done processing", output)
+ self.assertNotIn("Total errors found:", output)
+ # Output with no errors must be completely blank!
+ self.assertEquals("", output)
+
+# pylint: disable-msg=C6409
+def setUp():
+ """Runs before all tests are executed.
+ """
+ # Enable all filters, so we don't miss anything that is off by default.
+ cpplint._DEFAULT_FILTERS = []
+ cpplint._cpplint_state.SetFilters('')
+
+
+# pylint: disable-msg=C6409
+def tearDown():
+ """A global check to make sure all error-categories have been tested.
+
+ The main tearDown() routine is the only code we can guarantee will be
+ run after all other tests have been executed.
+ """
+ try:
+ if _run_verifyallcategoriesseen:
+ ErrorCollector(None).VerifyAllCategoriesAreSeen()
+ except NameError:
+ # If nobody set the global _run_verifyallcategoriesseen, then
+ # we assume we should silently not run the test
+ pass
+
+
+if __name__ == '__main__':
+ # We don't want to run the VerifyAllCategoriesAreSeen() test unless
+ # we're running the full test suite: if we only run one test,
+ # obviously we're not going to see all the error categories. So we
+ # only run VerifyAllCategoriesAreSeen() when no commandline flags
+ # are passed in.
+ global _run_verifyallcategoriesseen
+ _run_verifyallcategoriesseen = (len(sys.argv) == 1)
+
+ setUp()
+ unittest.main()
+ tearDown()
diff --git a/cpplint/nested/cpplint_test_header.h b/cpplint/nested/cpplint_test_header.h
new file mode 100644
index 0000000..4307e80
--- /dev/null
+++ b/cpplint/nested/cpplint_test_header.h
@@ -0,0 +1 @@
+// A test header for cpplint_unittest.py.
diff --git a/docguide/README.md b/docguide/README.md
new file mode 100644
index 0000000..39fe2ec
--- /dev/null
+++ b/docguide/README.md
@@ -0,0 +1,10 @@
+# Google documentation guide
+
+* [Markdown styleguide](style.md)
+* [Best practices](best_practices.md)
+* [README files](READMEs.md)
+* [Philosophy](philosophy.md)
+
+## See also
+
+* [How to update this guide](https://goto.google.com/doc-guide), for Googlers.
diff --git a/docguide/READMEs.md b/docguide/READMEs.md
new file mode 100644
index 0000000..5854af2
--- /dev/null
+++ b/docguide/READMEs.md
@@ -0,0 +1,69 @@
+# README.md files
+
+About README.md files.
+
+1. [Overview](#overview)
+1. [Guidelines](#guidelines)
+1. [Filename](#filename)
+1. [Contents](#contents)
+1. [Example](#example)
+
+## Overview
+
+`README.md` files are Markdown files that describe a directory.
+GitHub and Gitiles renders it when you browse the directory.
+
+For example, the file /README.md is rendered when you view the contents of the
+containing directory:
+
+https://github.com/google/styleguide/tree/gh-pages
+
+Also `README.md` at `HEAD` ref is rendered by Gitiles when displaying repository
+index:
+
+https://gerrit.googlesource.com/gitiles/
+
+## Guidelines
+
+**`README.md` files are intended to provide orientation for engineers browsing
+your code, especially first-time users.** The `README.md` is likely the first
+file a reader encounters when they browse a directory that
+contains your code. In this way, it acts as a landing page for the directory.
+
+We recommend that top-level directories for your code have an up-to-date
+`README.md` file. This is especially important for package directories that
+provide interfaces for other teams.
+
+### Filename
+
+Use `README.md`.
+
+Files named `README` are not displayed in the directory view in Gitiles.
+
+### Contents
+
+At minimum, every package-level `README.md` should include or point to the
+following information:
+
+1. **What** is in this package/library and what's it used for.
+2. **Who** to contact.
+3. **Status**: whether this package/library is deprecated, or not for general
+ release, etc.
+4. **More info**: where to go for more detailed documentation, such as:
+ * An overview.md file for more detailed conceptual information.
+ * Any API documentation for using this package/library.
+
+## Example
+
+```markdown
+# APIs
+
+This is the top-level directory for all externally-visible APIs, plus some
+private APIs under `internal/` directories.
+See [API Style Guide](docs/apistyle.md) for more information.
+
+*TL;DR*: API definitions and configurations should be defined in `.proto` files,
+checked into `apis/`.
+
+...
+```
diff --git a/docguide/VERSION b/docguide/VERSION
new file mode 100644
index 0000000..d3827e7
--- /dev/null
+++ b/docguide/VERSION
@@ -0,0 +1 @@
+1.0
diff --git a/docguide/best_practices.md b/docguide/best_practices.md
new file mode 100644
index 0000000..8f02545
--- /dev/null
+++ b/docguide/best_practices.md
@@ -0,0 +1,115 @@
+# Documentation Best Practices
+
+"Say what you mean, simply and directly." - [Brian Kernighan]
+(https://en.wikipedia.org/wiki/The_Elements_of_Programming_Style)
+
+Contents:
+
+1. [Minimum viable documentation](#minimum-viable-documentation)
+1. [Update docs with code](#update-docs-with-code)
+1. [Delete dead documentation](#delete-dead-documentation)
+1. [Documentation is the story of your code](#documentation-is-the-story-of-your-code)
+
+## Minimum viable documentation
+
+A small set of fresh and accurate docs are better than a sprawling, loose
+assembly of "documentation" in various states of disrepair.
+
+Write short and useful documents. Cut out everything unnecessary, while also
+making a habit of continually massaging and improving every doc to suit your
+changing needs. **Docs work best when they are alive but frequently trimmed,
+like a bonsai tree**.
+
+This guide encourages engineers to take ownership of their docs and keep
+them up to date with the same zeal we keep our tests in good order. Strive for
+this.
+
+* Identify what you really need: release docs, API docs, testing guidelines.
+* Delete cruft frequently and in small batches.
+
+## Update docs with code
+
+**Change your documentation in the same CL as the code change**. This keeps your
+docs fresh, and is also a good place to explain to your reviewer what you're
+doing.
+
+A good reviewer can at least insist that docstrings, header files, README.md
+files, and any other docs get updated alongside the CL.
+
+## Delete dead documentation
+
+Dead docs are bad. They misinform, they slow down, they incite despair in
+engineers and laziness in team leads. They set a precedent for leaving behind
+messes in a code base. If your home is clean, most guests will be clean without
+being asked.
+
+Just like any big cleaning project, **it's easy to be overwhelmed**. If your
+docs are in bad shape:
+
+* Take it slow, doc health is a gradual accumulation.
+* First delete what you're certain is wrong, ignore what's unclear.
+* Get your whole team involved. Devote time to quickly scan every doc and make
+ a simple decision: Keep or delete?
+* Default to delete or leave behind if migrating. Stragglers can always be
+ recovered.
+* Iterate.
+
+## Prefer the good over the perfect
+
+Your documentation should be as good as possible within a reasonable time frame.
+The standards for an documentation review are different from the
+standards for code reviews. Reviewers can and should ask for improvements, but
+in general, the author should always be able to invoke the "Good Over Perfect
+Rule". It's preferable to allow authors to quickly submit changes that improve
+the document, instead of forcing rounds of review until it's "perfect". Docs are
+never perfect, and tend to gradually improve as the team learns what they really
+need to write down.
+
+## Documentation is the story of your code
+
+Writing excellent code doesn't end when your code compiles or even if your
+test coverage reaches 100%. It's easy to write something a computer understands,
+it's much harder to write something both a human and a computer understand. Your
+mission as a Code Health-conscious engineer is to **write for humans first,
+computers second.** Documentation is an important part of this skill.
+
+There's a spectrum of engineering documentation that ranges from terse comments
+to detailed prose:
+
+1. **Inline comments**: The primary purpose of inline comments is to provide
+ information that the code itself cannot contain, such as why the code is
+ there.
+
+2. **Method and class comments**:
+
+ * **Method API documentation**: The header / Javadoc / docstring
+ comments that say what methods do and how to use them. This
+ documentation is **the contract of how your code must behave**. The
+ intended audience is future programmers who will use and modify your
+ code.
+
+ It is often reasonable to say that any behavior documented here should
+ have a test verifying it. This documentation details what arguments the
+ method takes, what it returns, any "gotchas" or restrictions, and what
+ exceptions it can throw or errors it can return. It does not usually
+ explain why code behaves a particular way unless that's relevant to a
+ developer's understanding of how to use the method. "Why" explanations
+ are for inline comments. Think in practical terms when writing method
+ documentation: "This is a hammer. You use it to pound nails."
+
+ * **Class / Module API documentation**: The header / Javadoc / docstring
+ comments for a class or a whole file. This documentation gives a brief
+ overview of what the class / file does and often gives a few short
+ examples of how you might use the class / file.
+
+ Examples are particularly relevant when there's several distinct ways to
+ use the class (some advanced, some simple). Always list the simplest
+ use case first.
+
+3. **README.md**: A good README.md orients the new user to the directory and
+ points to more detailed explanation and user guides:
+ * What is this directory intended to hold?
+ * Which files should the developer look at first? Are some files an API?
+ * Who maintains this directory and where I can learn more?
+
+ See the [README.md guidelines](READMEs.md).
diff --git a/docguide/philosophy.md b/docguide/philosophy.md
new file mode 100644
index 0000000..0937c5b
--- /dev/null
+++ b/docguide/philosophy.md
@@ -0,0 +1,71 @@
+# Philosophy
+
+埏埴以為器，當其無，有器之用.
+
+*Clay becomes pottery through craft, but it's the emptiness that makes a pot
+useful.*
+
+\- [Laozi](http://ctext.org/dictionary.pl?if=en&id=11602)
+
+Contents:
+
+1. [Radical simplicity](#radical-simplicity)
+1. [Readable source text](#readable-source-text)
+1. [Minimum viable documentation](#minimum-viable-documentation)
+1. [Better is better than perfect](#better-is-better-than-perfect)
+
+## Radical simplicity
+
+* **Scalability and interoperability** are more important than a menagerie of
+ unessential features. Scale comes from simplicity, speed, and ease.
+ Interoperability comes from unadorned, digestable content.
+
+* **Fewer distractions** make for better writing and more productive reading.
+
+* **New features should never interfere with the simplest use case** and should
+ remain invisible to users who don't need them.
+
+* **This guide is designed for the average engineer** -- the busy,
+ just-want-to-go-back-to-coding engineer. Large and complex documentation is
+ possible but not the primary focus.
+
+* **Minimizing context switching makes people happier.** Engineers should be
+ able to interact with documentation using the same tools they use to read and
+ write code.
+
+## Readable source text
+
+* **Plain text not only suffices, it is superior**. Markdown itself is not
+ essential to this formula, but it is the best and most widely supported
+ solution right now. HTML is generally not encouraged.
+
+* **Content and presentation should not mingle**. It should always be possible
+ to ditch the renderer and read the essential information at source. Users
+ should never have to touch the presentation layer if they don't want to.
+
+* **Portability and future-proofing leave room for the unimagined integrations
+ to come**, and are best achieved by keeping the source as human-readable as
+ possible.
+
+* **Static content is better than dynamic**, because content should not depend
+ on the features of any one server. However, **fresh is better than stale**. We
+ strive to balance these needs.
+
+## Minimum viable documentation
+
+* **Docs thrive when they're treated like tests**: a necessary chore one learns
+ to savor because it rewards over time.
+ See [Best Practices](best_practices.md).
+
+* **Brief and utilitarian is better than long and exhaustive**. The vast
+ majority of users need only a small fraction of the author's total knowledge,
+ but they need it quickly and often.
+
+## Better is better than perfect
+
+* **Incremental improvement is better than prolonged debate**. Patience and
+ tolerance of imperfection allow projects to evolve organically.
+
+* **Don't lick the cookie, pass the plate**. We're drowning in potentially
+ impactful projects. Choose only those you can really handle and release those
+ you can't.
diff --git a/docguide/style.md b/docguide/style.md
new file mode 100644
index 0000000..f00d61e
--- /dev/null
+++ b/docguide/style.md
@@ -0,0 +1,420 @@
+# Markdown style guide
+
+Much of what makes Markdown great is the ability to write plain text, and get
+great formatted output as a result. To keep the slate clean for the next author,
+your Markdown should be simple and consistent with the whole corpus wherever
+possible.
+
+We seek to balance three goals:
+
+1. *Source text is readable and portable.*
+2. *Markdown files are maintainable over time and across teams.*
+3. *The syntax is simple and easy to remember.*
+
+Contents:
+
+1. [Document layout](#document-layout)
+1. [Character line limit](#character-line-limit)
+1. [Trailing whitespace](#trailing-whitespace)
+1. [Headings](#headings)
+ 1. [ATX-style headings](#atx-style-headings)
+ 1. [Add spacing to headings](#add-spacing-to-headings)
+1. [Lists](#lists)
+ 1. [Use lazy numbering for long lists](#use-lazy-numbering-for-long-lists)
+ 1. [Nested list spacing](#nested-list-spacing)
+1. [Code](#code)
+ 1. [Inline](#inline)
+ 1. [Codeblocks](#codeblocks)
+ 1. [Declare the language](#declare-the-language)
+ 1. [Escape newlines](#escape-newlines)
+ 1. [Nest codeblocks within lists](#nest-codeblocks-within-lists)
+1. [Links](#links)
+ 1. [Use informative Markdown link titles](#use-informative-markdown-link-titles)
+1. [Images](#images)
+1. [Prefer lists to tables](#prefer-lists-to-tables)
+1. [Strongly prefer Markdown to HTML](#strongly-prefer-markdown-to-html)
+
+## Document layout
+
+In general, most documents benefit from some variation of the following layout:
+
+```markdown
+# Document Title
+
+Short introduction.
+
+[TOC]
+
+## Topic
+
+Content.
+
+## See also
+
+* https://link-to-more-info
+```
+
+1. `# Document Title`: The first heading should be a level one heading, and
+ should ideally be the same or nearly the same as the filename. The first
+ level one heading is used as the page `<title>`.
+
+1. `author`: *Optional*. If you'd like to claim ownership of the document or
+ if you are very proud of it, add yourself under the title. However,
+ revision history generally suffices.
+
+1. `Short introduction.` 1-3 sentences providing a high-level overview of the
+ topic. Imagine yourself as a complete newbie, who landed on your "Extending
+ Foo" doc and needs to know the most basic assumptions you take for granted.
+ "What is Foo? Why would I extend it?"
+
+1. `[TOC]`: if you use hosting that supports table of contents, such as Gitiles,
+ put `[TOC]` after the short introduction. See
+ [`[TOC]` documentation](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Table-of-contents).
+
+1. `## Topic`: The rest of your headings should start from level 2.
+
+1. `## See also`: Put miscellaneous links at the bottom for the user who wants
+ to know more or didn't find what she needed.
+
+## Character line limit
+
+Obey projects' character line limit wherever possible. Long URLs and tables are
+the usual suspects when breaking the rule. (Headings also can't be wrapped, but
+we encourage keeping them short). Otherwise, wrap your text:
+
+```markdown
+Lorem ipsum dolor sit amet, nec eius volumus patrioque cu, nec et commodo
+hendrerit, id nobis saperet fuisset ius.
+
+* Malorum moderatius vim eu. In vix dico persecuti. Te nam saperet percipitur
+ interesset. See the [foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md).
+```
+
+Often, inserting a newline before a long link preserves readability while
+minimizing the overflow:
+
+```markdown
+Lorem ipsum dolor sit amet. See the
+[foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md)
+for details.
+```
+
+## Trailing whitespace
+
+Don't use trailing whitespace, use a trailing backslash.
+
+The [CommonMark spec](http://spec.commonmark.org/0.20/#hard-line-breaks) decrees
+that two spaces at the end of a line should insert a `<br />` tag. However, many
+directories have a trailing whitespace presubmit check in place, and many IDEs
+will clean it up anyway.
+
+Best practice is to avoid the need for a `<br />` altogether. Markdown creates
+paragraph tags for you simply with newlines: get used to that.
+
+## Headings
+
+### ATX-style headings
+
+```markdown
+## Heading 2
+```
+
+Headings with `=` or `-` underlines can be annoying to maintain and don't fit
+with the rest of the heading syntax. The user has to ask: Does `---` mean H1 or
+H2?
+
+```markdown
+Heading - do you remember what level? DO NOT DO THIS.
+---------
+```
+
+### Add spacing to headings
+
+Prefer spacing after `#` and newlines before and after:
+
+```markdown
+...text before.
+
+# Heading 1
+
+Text after...
+```
+
+Lack of spacing makes it a little harder to read in source:
+
+```markdown
+...text before.
+
+#Heading 1
+Text after... DO NOT DO THIS.
+```
+
+## Lists
+
+### Use lazy numbering for long lists
+
+Markdown is smart enough to let the resulting HTML render your numbered lists
+correctly. For longer lists that may change, especially long nested lists, use
+"lazy" numbering:
+
+```markdown
+1. Foo.
+1. Bar.
+ 1. Foofoo.
+ 1. Barbar.
+1. Baz.
+```
+
+However, if the list is small and you don't anticipate changing it, prefer fully
+numbered lists, because it's nicer to read in source:
+
+```markdown
+1. Foo.
+2. Bar.
+3. Baz.
+```
+
+### Nested list spacing
+
+When nesting lists, use a 4 space indent for both numbered and bulleted lists:
+
+```markdown
+1. 2 spaces after a numbered list.
+ 4 space indent for wrapped text.
+2. 2 spaces again.
+
+* 3 spaces after a bullet.
+ 4 space indent for wrapped text.
+ 1. 2 spaces after a numbered list.
+ 8 space indent for the wrapped text of a nested list.
+ 2. Looks nice, don't it?
+* 3 spaces after a bullet.
+```
+
+The following works, but it's very messy:
+
+```markdown
+* One space,
+with no indent for wrapped text.
+ 1. Irregular nesting... DO NOT DO THIS.
+```
+
+Even when there's no nesting, using the 4 space indent makes layout consistent
+for wrapped text:
+
+```markdown
+* Foo,
+ wrapped.
+
+1. 2 spaces
+ and 4 space indenting.
+2. 2 spaces again.
+```
+
+However, when lists are small, not nested, and a single line, one space can
+suffice for both kinds of lists:
+
+```markdown
+* Foo
+* Bar
+* Baz.
+
+1. Foo.
+2. Bar.
+```
+
+## Code
+
+### Inline
+
+`Backticks` designate `inline code`, and will render all wrapped content
+literally. Use them for short code quotations and field names:
+
+```markdown
+You'll want to run `really_cool_script.sh arg`.
+
+Pay attention to the `foo_bar_whammy` field in that table.
+```
+
+Use inline code when referring to file types in an abstract sense, rather than a
+specific file:
+
+```markdown
+Be sure to update your `README.md`!
+```
+
+Backticks are the most common approach for "escaping" Markdown metacharacters;
+in most situations where escaping would be needed, code font just makes sense
+anyway.
+
+### Codeblocks
+
+For code quotations longer than a single line, use a codeblock:
+
+<pre>
+```python
+def Foo(self, bar):
+ self.bar = bar
+```
+</pre>
+
+#### Declare the language
+
+It is best practice to explicitly declare the language, so that neither the
+syntax highlighter nor the next editor must guess.
+
+#### Indented codeblocks are sometimes cleaner
+
+Four-space indenting is also interpreted as a codeblock. These can look
+cleaner and be easier to read in source, but there is no way to specify the
+language. We encourage their use when writing many short snippets:
+
+```markdown
+You'll need to run:
+
+ bazel run :thing -- --foo
+
+And then:
+
+ bazel run :another_thing -- --bar
+
+And again:
+
+ bazel run :yet_again -- --baz
+```
+
+#### Escape newlines
+
+Because most commandline snippets are intended to be copied and pasted directly
+into a terminal, it's best practice to escape any newlines. Use a single
+backslash at the end of the line:
+
+<pre>
+```shell
+bazel run :target -- --flag --foo=longlonglonglonglongvalue \
+--bar=anotherlonglonglonglonglonglonglonglonglonglongvalue
+```
+</pre>
+
+#### Nest codeblocks within lists
+
+If you need a codeblock within a list, make sure to indent it so as to not break
+the list:
+
+```markdown
+* Bullet.
+
+ ```c++
+ int foo;
+ ```
+
+* Next bullet.
+```
+
+You can also create a nested code block with 4 spaces. Simply indent 4
+additional spaces from the list indentation:
+
+```markdown
+* Bullet.
+
+ int foo;
+
+* Next bullet.
+```
+
+## Links
+
+Long links make source Markdown difficult to read and break the 80 character
+wrapping. **Wherever possible, shorten your links**.
+
+### Use informative Markdown link titles
+
+Markdown link syntax allows you to set a link title, just as HTML does. Use it
+wisely.
+
+Titling your links as "link" or "here" tells the reader precisely nothing when
+quickly scanning your doc and is a waste of space:
+
+```markdown
+See the syntax guide for more info: [link](syntax_guide.md).
+Or, check out the style guide [here](style_guide.md).
+DO NOT DO THIS.
+```
+
+Instead, write the sentence naturally, then go back and wrap the most
+appropriate phrase with the link:
+
+```markdown
+See the [syntax guide](syntax_guide.md) for more info.
+Or, check out the [style guide](style_guide.md).
+```
+
+## Images
+
+Use images sparingly, and prefer simple screenshots. This guide is designed
+around the idea that plain text gets users down to the business of communication
+faster with less reader distraction and author procrastination. However, it's
+sometimes very helpful to show what you mean.
+
+See [image syntax](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Images).
+
+## Prefer lists to tables
+
+Any tables in your Markdown should be small. Complex, large tables are difficult
+to read in source and most importantly, **a pain to modify later**.
+
+```markdown
+Fruit | Attribute | Notes
+--- | --- | --- | ---
+Apple | [Juicy](https://example.com/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Firm, Sweet | Apples keep doctors away.
+Banana | [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Soft, Sweet | Contrary to popular belief, most apes prefer mangoes.
+
+DO NOT DO THIS
+```
+
+[Lists](#lists) and subheadings usually suffice to present the same information
+in a slightly less compact, though much more edit-friendly way:
+
+```markdown
+## Fruits
+
+### Apple
+
+* [Juicy](https://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)
+* Firm
+* Sweet
+
+Apples keep doctors away.
+
+### Banana
+
+* [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery)
+* Soft
+* Sweet
+
+Contrary to popular belief, most apes prefer mangoes.
+```
+
+However, there are times when a small table is called for:
+
+```markdown
+Transport | Favored by | Advantages
+--- | --- | ---
+Swallow | Coconuts | Otherwise unladen
+Bicycle | Miss Gulch | Weatherproof
+X-34 landspeeder | Whiny farmboys | Cheap since the X-38 came out
+```
+
+## Strongly prefer Markdown to HTML
+
+Please prefer standard Markdown syntax wherever possible and avoid HTML hacks.
+If you can't seem to accomplish what you want, reconsider whether you really
+need it. Except for [big tables](#prefer-lists-to-tables), Markdown meets almost
+all needs already.
+
+Every bit of HTML or Javascript hacking reduces the readability and portability.
+This in turn limits the usefulness of integrations with
+other tools, which may either present the source as plain text or render it. See
+[Philosophy](philosophy.md).
+
+Gitiles does not render HTML.
diff --git a/eclipse-cpp-google-style.xml b/eclipse-cpp-google-style.xml
new file mode 100644
index 0000000..aa05a81
--- /dev/null
+++ b/eclipse-cpp-google-style.xml
@@ -0,0 +1,167 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<profiles version="1">
+<profile kind="CodeFormatterProfile" name="Google C++" version="1">
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_method_declaration" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_for" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_new_line_in_empty_block" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.lineSplit" value="80"/>
+<setting id="org.eclipse.cdt.core.formatter.alignment_for_member_access" value="16"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_base_types" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.keep_else_statement_on_same_line" value="false"/>
+<setting id="org.eclipse.cdt.core.formatter.indent_switchstatements_compare_to_switch" value="true"/>
+<setting id="org.eclipse.cdt.core.formatter.alignment_for_constructor_initializer_list" value="83"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_brace_in_array_initializer" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_method_declaration_parameters" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_if" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_parenthesized_expression" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_exception_specification" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_base_types" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.indent_body_declarations_compare_to_access_specifier" value="true"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_exception_specification" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_template_arguments" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_block" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_method_declaration" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.use_tabs_only_for_leading_indentations" value="false"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_labeled_statement" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_colon_in_case" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.comment.min_distance_between_code_and_line_comment" value="2"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_array_initializer" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_enum_declarations" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.alignment_for_expressions_in_array_initializer" value="16"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_declarator_list" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_bracket" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_for" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_prefix_operator" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.tabulation.size" value="2"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_else_in_if_statement" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.alignment_for_enumerator_list" value="51"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_parenthesized_expression" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_parens_in_method_declaration" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_switch" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.alignment_for_declarator_list" value="16"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_parenthesized_expression" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.indent_empty_lines" value="false"/>
+<setting id="org.eclipse.cdt.core.formatter.indent_switchstatements_compare_to_cases" value="true"/>
+<setting id="org.eclipse.cdt.core.formatter.keep_empty_array_initializer_on_one_line" value="false"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_method_declaration" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.put_empty_statement_on_new_line" value="true"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_switch" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_cast" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_braces_in_array_initializer" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.brace_position_for_method_declaration" value="end_of_line"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_while" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_question_in_conditional" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_semicolon" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_closing_angle_bracket_in_template_arguments" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_base_clause" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.indent_breaks_compare_to_cases" value="true"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_unary_operator" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.join_wrapped_lines" value="true"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_declarator_list" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.alignment_for_arguments_in_method_invocation" value="18"/>
+<setting id="org.eclipse.cdt.core.formatter.comment.never_indent_line_comments_on_first_column" value="true"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_while" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_brackets" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_bracket" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.alignment_for_parameters_in_method_declaration" value="18"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_closing_brace_in_array_initializer" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.number_of_empty_lines_to_preserve" value="1"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_method_invocation" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_brace_in_array_initializer" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_semicolon_in_for" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_conditional" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.brace_position_for_block" value="end_of_line"/>
+<setting id="org.eclipse.cdt.core.formatter.comment.preserve_white_space_between_code_and_line_comments" value="true"/>
+<setting id="org.eclipse.cdt.core.formatter.brace_position_for_type_declaration" value="end_of_line"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_assignment_operator" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_angle_bracket_in_template_arguments" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_expression_list" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_angle_bracket_in_template_parameters" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.continuation_indentation" value="2"/>
+<setting id="org.eclipse.cdt.core.formatter.alignment_for_expression_list" value="0"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_method_declaration" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_template_parameters" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_default" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_binary_operator" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.alignment_for_conditional_expression" value="34"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_parens_in_method_invocation" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_array_initializer" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_if" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.format_guardian_clause_on_one_line" value="false"/>
+<setting id="org.eclipse.cdt.core.formatter.indent_access_specifier_extra_spaces" value="1"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_cast" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.indent_access_specifier_compare_to_type_header" value="false"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_type_declaration" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.continuation_indentation_for_array_initializer" value="2"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_colon_in_labeled_statement" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_method_declaration_parameters" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_semicolon_in_for" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_method_invocation" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.indent_body_declarations_compare_to_namespace_header" value="false"/>
+<setting id="org.eclipse.cdt.core.formatter.alignment_for_compact_if" value="0"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_assignment_operator" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_closing_brace_in_block" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_array_initializer" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_new_line_at_end_of_file_if_missing" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.alignment_for_assignment" value="16"/>
+<setting id="org.eclipse.cdt.core.formatter.alignment_for_conditional_expression_chain" value="18"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_template_parameters" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_expression_list" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_question_in_conditional" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_exception_specification" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_binary_operator" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_identifier_in_function_declaration" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.alignment_for_base_clause_in_type_declaration" value="16"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_method_declaration_throws" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_parens_in_exception_specification" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_method_invocation_arguments" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.indent_declaration_compare_to_template_header" value="false"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_unary_operator" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_switch" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.indent_statements_compare_to_body" value="true"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_method_declaration_throws" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.alignment_for_binary_expression" value="16"/>
+<setting id="org.eclipse.cdt.core.formatter.indent_statements_compare_to_block" value="true"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_template_arguments" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_catch_in_try_statement" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.alignment_for_throws_clause_in_method_declaration" value="16"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_method_invocation" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_closing_paren_in_cast" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_catch" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_angle_bracket_in_template_parameters" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.tabulation.char" value="space"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_angle_bracket_in_template_parameters" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_colon_in_constructor_initializer_list" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_while" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_method_invocation_arguments" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.brace_position_for_block_in_case" value="end_of_line"/>
+<setting id="org.eclipse.cdt.core.formatter.compact_else_if" value="true"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_postfix_operator" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_new_line_after_template_declaration" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_colon_in_base_clause" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_catch" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.keep_then_statement_on_same_line" value="false"/>
+<setting id="org.eclipse.cdt.core.formatter.brace_position_for_switch" value="end_of_line"/>
+<setting id="org.eclipse.cdt.core.formatter.alignment_for_overloaded_left_shift_chain" value="18"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_if" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_switch" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.keep_imple_if_on_one_line" value="false"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_new_line_after_opening_brace_in_array_initializer" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.indentation.size" value="2"/>
+<setting id="org.eclipse.cdt.core.formatter.brace_position_for_namespace_declaration" value="end_of_line"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_colon_in_conditional" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_enum_declarations" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_prefix_operator" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_angle_bracket_in_template_arguments" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.brace_position_for_array_initializer" value="end_of_line"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_case" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_catch" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_namespace_declaration" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_postfix_operator" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_bracket" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_while_in_do_statement" value="do not insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_for" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_closing_angle_bracket_in_template_parameters" value="insert"/>
+<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_angle_bracket_in_template_arguments" value="do not insert"/>
+</profile>
+</profiles>
diff --git a/eclipse-java-google-style.xml b/eclipse-java-google-style.xml
new file mode 100644
index 0000000..7bb6804
--- /dev/null
+++ b/eclipse-java-google-style.xml
@@ -0,0 +1,337 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<profiles version="13">
+<profile kind="CodeFormatterProfile" name="GoogleStyle" version="13">
+<setting id="org.eclipse.jdt.core.formatter.comment.insert_new_line_before_root_tags" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.disabling_tag" value="@formatter:off"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_annotation" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_type_parameters" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_type_declaration" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_type_arguments" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.brace_position_for_anonymous_type_declaration" value="end_of_line"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_case" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_brace_in_array_initializer" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.comment.new_lines_at_block_boundaries" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_cascading_method_invocation_with_arguments.count_dependent" value="16|-1|16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_annotation_declaration" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_annotation" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_field" value="0"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_while" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.use_on_off_tags" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.wrap_prefer_two_fragments" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_annotation_type_member_declaration" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_else_in_if_statement" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_prefix_operator" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.keep_else_statement_on_same_line" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_ellipsis" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.comment.insert_new_line_for_parameter" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.wrap_comment_inline_tags" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_annotation_type_declaration" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.indent_breaks_compare_to_cases" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_at_in_annotation" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_local_variable_declaration" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_multiple_fields" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_parameter" value="1040"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_expressions_in_array_initializer" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_type.count_dependent" value="1585|-1|1585"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_conditional_expression" value="80"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_for" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_multiple_fields.count_dependent" value="16|-1|16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_binary_operator" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_question_in_wildcard" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.brace_position_for_array_initializer" value="end_of_line"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_enum_constant" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_finally_in_try_statement" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_local_variable" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_catch_in_try_statement" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_while" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.blank_lines_after_package" value="1"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_qualified_allocation_expression.count_dependent" value="16|4|80"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_throws_clause_in_method_declaration.count_dependent" value="16|4|48"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_type_parameters" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.continuation_indentation" value="2"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_superinterfaces_in_enum_declaration.count_dependent" value="16|4|49"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_postfix_operator" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_method_invocation" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_angle_bracket_in_type_arguments" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_superinterfaces" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_new_chunk" value="1"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_binary_operator" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_package" value="0"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_cascading_method_invocation_with_arguments" value="16"/>
+<setting id="org.eclipse.jdt.core.compiler.source" value="1.7"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_throws_clause_in_constructor_declaration.count_dependent" value="16|4|48"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_enum_constant_arguments" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_constructor_declaration" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.comment.format_line_comments" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_closing_angle_bracket_in_type_arguments" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_enum_declarations" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.join_wrapped_lines" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_block" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_explicit_constructor_call" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.wrap_non_simple_local_variable_annotation" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_method_invocation_arguments" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.align_type_members_on_columns" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_member_type" value="0"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_enum_constant" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_enum_constants.count_dependent" value="16|5|48"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_for" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_method_declaration" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_selector_in_method_invocation" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_switch" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_unary_operator" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_case" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.comment.indent_parameter_description" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_method_declaration" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_switch" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_enum_declaration" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_angle_bracket_in_type_parameters" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.comment.clear_blank_lines_in_block_comment" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_type_declaration" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.lineSplit" value="100"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_if" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_selector_in_method_invocation.count_dependent" value="16|4|48"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_between_brackets_in_array_type_reference" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_parenthesized_expression" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_explicitconstructorcall_arguments" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_constructor_declaration" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_first_class_body_declaration" value="0"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_method" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.indentation.size" value="4"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_method_declaration" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.enabling_tag" value="@formatter:on"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_enum_constant" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_package" value="1585"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_superclass_in_type_declaration" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_assignment" value="16"/>
+<setting id="org.eclipse.jdt.core.compiler.problem.assertIdentifier" value="error"/>
+<setting id="org.eclipse.jdt.core.formatter.tabulation.char" value="space"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_semicolon_in_try_resources" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_constructor_declaration_parameters" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_prefix_operator" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.indent_statements_compare_to_body" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_method" value="1"/>
+<setting id="org.eclipse.jdt.core.formatter.wrap_outer_expressions_when_nested" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.wrap_non_simple_type_annotation" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.format_guardian_clause_on_one_line" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_for" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_field_declaration" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_cast" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_parameters_in_constructor_declaration" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_labeled_statement" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.brace_position_for_annotation_type_declaration" value="end_of_line"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_method_body" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_method_declaration" value="0"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_try" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_method_invocation" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_bracket_in_array_allocation_expression" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_enum_constant" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_annotation" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_at_in_annotation_type_declaration" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_method_declaration_throws" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_if" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.brace_position_for_switch" value="end_of_line"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_method_declaration_throws" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_parenthesized_expression_in_return" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_annotation" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_question_in_conditional" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_question_in_wildcard" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_try" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_bracket_in_array_allocation_expression" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.comment.preserve_white_space_between_code_and_line_comments" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_parenthesized_expression_in_throw" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_type_arguments" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.compiler.problem.enumIdentifier" value="error"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_generic_type_arguments" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.indent_switchstatements_compare_to_switch" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.comment_new_line_at_start_of_html_paragraph" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_ellipsis" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.brace_position_for_block" value="end_of_line"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comment_prefix" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_for_inits" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.brace_position_for_method_declaration" value="end_of_line"/>
+<setting id="org.eclipse.jdt.core.formatter.compact_else_if" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.wrap_non_simple_parameter_annotation" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.wrap_before_or_operator_multicatch" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_array_initializer" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_for_increments" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_method" value="1585"/>
+<setting id="org.eclipse.jdt.core.formatter.format_line_comment_starting_on_first_column" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_bracket_in_array_reference" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_field" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.comment.indent_root_tags" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.brace_position_for_enum_constant" value="end_of_line"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_enum_declarations" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_union_type_in_multicatch" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_explicitconstructorcall_arguments" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_switch" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_method_declaration_parameters" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_superinterfaces" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_allocation_expression" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.tabulation.size" value="2"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_bracket_in_array_type_reference" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_opening_brace_in_array_initializer" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_closing_brace_in_block" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_bracket_in_array_reference" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_enum_constant" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_angle_bracket_in_type_arguments" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_constructor_declaration" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_constructor_declaration_throws" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_if" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_method_invocation.count_dependent" value="16|5|80"/>
+<setting id="org.eclipse.jdt.core.formatter.comment.clear_blank_lines_in_javadoc_comment" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_parameter.count_dependent" value="1040|-1|1040"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_throws_clause_in_constructor_declaration" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_assignment_operator" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_assignment_operator" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_package.count_dependent" value="1585|-1|1585"/>
+<setting id="org.eclipse.jdt.core.formatter.indent_empty_lines" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_synchronized" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_closing_paren_in_cast" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_method_declaration_parameters" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.force_if_else_statement_brace" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.brace_position_for_block_in_case" value="end_of_line"/>
+<setting id="org.eclipse.jdt.core.formatter.number_of_empty_lines_to_preserve" value="3"/>
+<setting id="org.eclipse.jdt.core.formatter.wrap_non_simple_package_annotation" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_method_declaration" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_catch" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_constructor_declaration" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_method_invocation" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_bracket_in_array_reference" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_qualified_allocation_expression" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_annotation.count_dependent" value="16|-1|16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_and_in_type_parameter" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_type" value="1585"/>
+<setting id="org.eclipse.jdt.core.compiler.compliance" value="1.7"/>
+<setting id="org.eclipse.jdt.core.formatter.continuation_indentation_for_array_initializer" value="2"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_brackets_in_array_allocation_expression" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_at_in_annotation_type_declaration" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_allocation_expression" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_cast" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_unary_operator" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_new_anonymous_class" value="20"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_angle_bracket_in_parameterized_type_reference" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_local_variable.count_dependent" value="1585|-1|1585"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_anonymous_type_declaration" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.keep_empty_array_initializer_on_one_line" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_enum_declaration" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_field.count_dependent" value="1585|-1|1585"/>
+<setting id="org.eclipse.jdt.core.formatter.keep_imple_if_on_one_line" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_constructor_declaration_parameters" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_closing_angle_bracket_in_type_parameters" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_labeled_statement" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_at_end_of_file_if_missing" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_for" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_parameterized_type_reference" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_parameters_in_constructor_declaration.count_dependent" value="16|5|80"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_superinterfaces_in_type_declaration" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.brace_position_for_enum_declaration" value="end_of_line"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_binary_expression" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_while" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_type" value="insert"/>
+<setting id="org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode" value="enabled"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_try" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.put_empty_statement_on_new_line" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_label" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_parameter" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_angle_bracket_in_type_parameters" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_method_invocation" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.comment.format_javadoc_comments" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_enum_constant" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_while_in_do_statement" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_enum_constant.count_dependent" value="16|-1|16"/>
+<setting id="org.eclipse.jdt.core.formatter.comment.line_length" value="100"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_package" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.blank_lines_between_import_groups" value="0"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_enum_constant_arguments" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_semicolon" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.brace_position_for_constructor_declaration" value="end_of_line"/>
+<setting id="org.eclipse.jdt.core.formatter.number_of_blank_lines_at_beginning_of_method_body" value="0"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_conditional" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.indent_body_declarations_compare_to_type_header" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_annotation_type_member_declaration" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.wrap_before_binary_operator" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.blank_lines_between_type_declarations" value="2"/>
+<setting id="org.eclipse.jdt.core.formatter.indent_body_declarations_compare_to_enum_declaration_header" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_synchronized" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_superinterfaces_in_enum_declaration" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.indent_statements_compare_to_block" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.join_lines_in_comments" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_question_in_conditional" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_multiple_field_declarations" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_compact_if" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_for_inits" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.indent_switchstatements_compare_to_cases" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_array_initializer" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_default" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_and_in_type_parameter" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_constructor_declaration" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_imports" value="0"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_assert" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_field" value="1585"/>
+<setting id="org.eclipse.jdt.core.formatter.comment.format_html" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_throws_clause_in_method_declaration" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_angle_bracket_in_type_parameters" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_bracket_in_array_allocation_expression" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_anonymous_type_declaration" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_conditional" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_angle_bracket_in_parameterized_type_reference" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_for" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_expressions_in_array_initializer.count_dependent" value="16|5|80"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_postfix_operator" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.comment.format_source_code" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_synchronized" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_allocation_expression" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_constructor_declaration_throws" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_parameters_in_method_declaration" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_brace_in_array_initializer" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.compiler.codegen.targetPlatform" value="1.7"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_resources_in_try" value="80"/>
+<setting id="org.eclipse.jdt.core.formatter.use_tabs_only_for_leading_indentations" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_annotation" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.comment.format_header" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.comment.format_block_comments" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_enum_constant" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_enum_constants" value="0"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_parenthesized_expression" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.indent_body_declarations_compare_to_annotation_declaration_header" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_block" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_parenthesized_expression" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_catch" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_multiple_local_declarations" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_superinterfaces_in_type_declaration.count_dependent" value="16|4|48"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_switch" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_for_increments" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_method.count_dependent" value="1585|-1|1585"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_method_invocation" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_assert" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.brace_position_for_type_declaration" value="end_of_line"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_array_initializer" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_braces_in_array_initializer" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_binary_expression.count_dependent" value="16|-1|16"/>
+<setting id="org.eclipse.jdt.core.formatter.wrap_non_simple_member_annotation" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_local_variable" value="1585"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_method_declaration" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_semicolon_in_for" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_explicit_constructor_call.count_dependent" value="16|5|80"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_catch" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_angle_bracket_in_parameterized_type_reference" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_multiple_field_declarations" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_annotation" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_generic_type_arguments.count_dependent" value="16|-1|16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_parameterized_type_reference" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_allocation_expression.count_dependent" value="16|5|80"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_method_invocation_arguments" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_parameters_in_method_declaration.count_dependent" value="16|5|80"/>
+<setting id="org.eclipse.jdt.core.formatter.comment.new_lines_at_javadoc_boundaries" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.blank_lines_after_imports" value="1"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_multiple_local_declarations" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.indent_body_declarations_compare_to_enum_constant_header" value="true"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_after_semicolon_in_for" value="insert"/>
+<setting id="org.eclipse.jdt.core.formatter.never_indent_line_comments_on_first_column" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_semicolon_in_try_resources" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.alignment_for_for_statement" value="16"/>
+<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_angle_bracket_in_type_arguments" value="do not insert"/>
+<setting id="org.eclipse.jdt.core.formatter.never_indent_block_comments_on_first_column" value="false"/>
+<setting id="org.eclipse.jdt.core.formatter.keep_then_statement_on_same_line" value="false"/>
+</profile>
+</profiles>
diff --git a/google-c-style.el b/google-c-style.el
new file mode 100644
index 0000000..9bb12c6
--- /dev/null
+++ b/google-c-style.el
@@ -0,0 +1,151 @@
+;;; google-c-style.el --- Google's C/C++ style for c-mode
+
+;; Keywords: c, tools
+
+;; google-c-style.el is Copyright (C) 2008 Google Inc. All Rights Reserved.
+;;
+;; It is free software; you can redistribute it and/or modify it under the
+;; terms of either:
+;;
+;; a) the GNU General Public License as published by the Free Software
+;; Foundation; either version 1, or (at your option) any later version, or
+;;
+;; b) the "Artistic License".
+
+;;; Commentary:
+
+;; Provides the google C/C++ coding style. You may wish to add
+;; `google-set-c-style' to your `c-mode-common-hook' after requiring this
+;; file. For example:
+;;
+;; (add-hook 'c-mode-common-hook 'google-set-c-style)
+;;
+;; If you want the RETURN key to go to the next line and space over
+;; to the right place, add this to your .emacs right after the load-file:
+;;
+;; (add-hook 'c-mode-common-hook 'google-make-newline-indent)
+
+;;; Code:
+
+;; For some reason 1) c-backward-syntactic-ws is a macro and 2) under Emacs 22
+;; bytecode cannot call (unexpanded) macros at run time:
+(eval-when-compile (require 'cc-defs))
+
+;; Wrapper function needed for Emacs 21 and XEmacs (Emacs 22 offers the more
+;; elegant solution of composing a list of lineup functions or quantities with
+;; operators such as "add")
+(defun google-c-lineup-expression-plus-4 (langelem)
+ "Indents to the beginning of the current C expression plus 4 spaces.
+
+This implements title \"Function Declarations and Definitions\"
+of the Google C++ Style Guide for the case where the previous
+line ends with an open parenthese.
+
+\"Current C expression\", as per the Google Style Guide and as
+clarified by subsequent discussions, means the whole expression
+regardless of the number of nested parentheses, but excluding
+non-expression material such as \"if(\" and \"for(\" control
+structures.
+
+Suitable for inclusion in `c-offsets-alist'."
+ (save-excursion
+ (back-to-indentation)
+ ;; Go to beginning of *previous* line:
+ (c-backward-syntactic-ws)
+ (back-to-indentation)
+ (cond
+ ;; We are making a reasonable assumption that if there is a control
+ ;; structure to indent past, it has to be at the beginning of the line.
+ ((looking-at "\\(\\(if\\|for\\|while\\)\\s *(\\)")
+ (goto-char (match-end 1)))
+ ;; For constructor initializer lists, the reference point for line-up is
+ ;; the token after the initial colon.
+ ((looking-at ":\\s *")
+ (goto-char (match-end 0))))
+ (vector (+ 4 (current-column)))))
+
+;;;###autoload
+(defconst google-c-style
+ `((c-recognize-knr-p . nil)
+ (c-enable-xemacs-performance-kludge-p . t) ; speed up indentation in XEmacs
+ (c-basic-offset . 2)
+ (indent-tabs-mode . nil)
+ (c-comment-only-line-offset . 0)
+ (c-hanging-braces-alist . ((defun-open after)
+ (defun-close before after)
+ (class-open after)
+ (class-close before after)
+ (inexpr-class-open after)
+ (inexpr-class-close before)
+ (namespace-open after)
+ (inline-open after)
+ (inline-close before after)
+ (block-open after)
+ (block-close . c-snug-do-while)
+ (extern-lang-open after)
+ (extern-lang-close after)
+ (statement-case-open after)
+ (substatement-open after)))
+ (c-hanging-colons-alist . ((case-label)
+ (label after)
+ (access-label after)
+ (member-init-intro before)
+ (inher-intro)))
+ (c-hanging-semi&comma-criteria
+ . (c-semi&comma-no-newlines-for-oneline-inliners
+ c-semi&comma-inside-parenlist
+ c-semi&comma-no-newlines-before-nonblanks))
+ (c-indent-comments-syntactically-p . t)
+ (comment-column . 40)
+ (c-indent-comment-alist . ((other . (space . 2))))
+ (c-cleanup-list . (brace-else-brace
+ brace-elseif-brace
+ brace-catch-brace
+ empty-defun-braces
+ defun-close-semi
+ list-close-comma
+ scope-operator))
+ (c-offsets-alist . ((arglist-intro google-c-lineup-expression-plus-4)
+ (func-decl-cont . ++)
+ (member-init-intro . ++)
+ (inher-intro . ++)
+ (comment-intro . 0)
+ (arglist-close . c-lineup-arglist)
+ (topmost-intro . 0)
+ (block-open . 0)
+ (inline-open . 0)
+ (substatement-open . 0)
+ (statement-cont
+ .
+ (,(when (fboundp 'c-no-indent-after-java-annotations)
+ 'c-no-indent-after-java-annotations)
+ ,(when (fboundp 'c-lineup-assignments)
+ 'c-lineup-assignments)
+ ++))
+ (label . /)
+ (case-label . +)
+ (statement-case-open . +)
+ (statement-case-intro . +) ; case w/o {
+ (access-label . /)
+ (innamespace . 0))))
+ "Google C/C++ Programming Style.")
+
+;;;###autoload
+(defun google-set-c-style ()
+ "Set the current buffer's c-style to Google C/C++ Programming
+ Style. Meant to be added to `c-mode-common-hook'."
+ (interactive)
+ (make-local-variable 'c-tab-always-indent)
+ (setq c-tab-always-indent t)
+ (c-add-style "Google" google-c-style t))
+
+;;;###autoload
+(defun google-make-newline-indent ()
+ "Sets up preferred newline behavior. Not set by default. Meant
+ to be added to `c-mode-common-hook'."
+ (interactive)
+ (define-key c-mode-base-map "\C-m" 'newline-and-indent)
+ (define-key c-mode-base-map [ret] 'newline-and-indent))
+
+(provide 'google-c-style)
+;;; google-c-style.el ends here
diff --git a/google-r-style.html b/google-r-style.html
new file mode 100644
index 0000000..21a73f6
--- /dev/null
+++ b/google-r-style.html
@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html>
+<head>
+ <meta charset="utf8">
+ <meta http-equiv="content-type" content="text/html;charset=utf-8">
+ <meta http-equiv="refresh" content="1; url=Rguide.xml">
+ <title>Redirecting</title>
+</head>
+<!-- The BODY onLoad redirect is the best: it preserves #fragments and
+ ?queries. But it requires javascript. If that fails, the
+ meta-refresh kicks in; it works more generally, but loses fragments
+ and queries, takes a second, and pollutes the browser history.
+ If they both fail, we let the user manually click on the new link.
+-->
+ <body onload="location.replace(location.href.replace('google-r-style.html', 'Rguide.xml'))">
+ Redirecting you to <a href="Rguide.xml">Rguide.xml</a>.
+</body>
+</html>
diff --git a/google_python_style.vim b/google_python_style.vim
new file mode 100644
index 0000000..a8feea9
--- /dev/null
+++ b/google_python_style.vim
@@ -0,0 +1,36 @@
+" Indent Python in the Google way.
+
+setlocal indentexpr=GetGooglePythonIndent(v:lnum)
+
+let s:maxoff = 50 " maximum number of lines to look backwards.
+
+function GetGooglePythonIndent(lnum)
+
+ " Indent inside parens.
+ " Align with the open paren unless it is at the end of the line.
+ " E.g.
+ " open_paren_not_at_EOL(100,
+ " (200,
+ " 300),
+ " 400)
+ " open_paren_at_EOL(
+ " 100, 200, 300, 400)
+ call cursor(a:lnum, 1)
+ let [par_line, par_col] = searchpairpos('(\|{\|\[', '', ')\|}\|\]', 'bW',
+ \ "line('.') < " . (a:lnum - s:maxoff) . " ? dummy :"
+ \ . " synIDattr(synID(line('.'), col('.'), 1), 'name')"
+ \ . " =~ '\\(Comment\\|String\\)$'")
+ if par_line > 0
+ call cursor(par_line, 1)
+ if par_col != col("$") - 1
+ return par_col
+ endif
+ endif
+
+ " Delegate the rest to the original function.
+ return GetPythonIndent(a:lnum)
+
+endfunction
+
+let pyindent_nested_paren="&sw*2"
+let pyindent_open_paren="&sw*2"
diff --git a/htmlcssguide.html b/htmlcssguide.html
new file mode 100644
index 0000000..6fc7b39
--- /dev/null
+++ b/htmlcssguide.html
@@ -0,0 +1,902 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Google HTML/CSS Style Guide</title>
+<link rel="stylesheet" href="javaguide.css">
+<script src="include/styleguide.js"></script>
+<link rel="shortcut icon" href="https://www.google.com/favicon.ico">
+<script src="include/jsguide.js"></script>
+</head>
+<body onload="initStyleGuide();">
+<div id="content">
+<h1>Google HTML/CSS Style Guide</h1>
+<h2 id="Background">1 Background</h2>
+
+<p></p>
+
+<p>This document defines formatting and style rules for HTML and CSS. It aims at
+improving collaboration, code quality, and enabling supporting infrastructure.
+It applies to raw, working files that use HTML and CSS, including GSS files.
+Tools are free to obfuscate, minify, and compile as long as the general code
+quality is maintained.</p>
+
+<p></p>
+
+<p></p>
+
+<h2 id="General">2 General</h2>
+
+<h3 id="General_Style_Rules">2.1 General Style Rules</h3>
+
+<h4 id="Protocol">2.1.1 Protocol</h4>
+
+<p>Use the HTTPS protocol for embedded resources where possible.</p>
+
+<p>Always use the HTTPS protocol (<code>https:</code>) for images and other media
+files, style sheets, and scripts, unless the respective files are not available
+over HTTPS.</p>
+
+<pre><code class="language-html prettyprint badcode"><!-- Not recommended: omits the protocol -->
+<script src="//ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
+
+<!-- Not recommended: uses the HTTP protocol -->
+<script src="http://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
+</code></pre>
+
+<pre><code class="language-html prettyprint"><!-- Recommended -->
+<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
+</code></pre>
+
+<pre><code class="language-css prettyprint badcode">/* Not recommended: omits the protocol */
+@import '//fonts.googleapis.com/css?family=Open+Sans';
+
+/* Not recommended: uses the HTTP protocol */
+@import 'http://fonts.googleapis.com/css?family=Open+Sans';
+</code></pre>
+
+<pre><code class="language-css prettyprint">/* Recommended */
+@import 'https://fonts.googleapis.com/css?family=Open+Sans';
+</code></pre>
+
+
+
+<p></p>
+
+<p></p>
+
+<p></p>
+
+<h3 id="General_Formatting_Rules">2.2 General Formatting Rules</h3>
+
+<h4 id="Indentation">2.2.1 Indentation</h4>
+
+<p>Indent by 2 spaces at a time.</p>
+
+<p>Don’t use tabs or mix tabs and spaces for indentation.</p>
+
+<pre><code class="language-html prettyprint"><ul>
+ <li>Fantastic
+ <li>Great
+</ul>
+</code></pre>
+
+<pre><code class="language-css prettyprint">.example {
+ color: blue;
+}
+</code></pre>
+
+<h4 id="Capitalization">2.2.2 Capitalization</h4>
+
+<p>Use only lowercase.</p>
+
+<p>All code has to be lowercase: This applies to HTML element names, attributes,
+attribute values (unless <code>text/CDATA</code>), CSS selectors, properties, and property
+values (with the exception of strings).</p>
+
+<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
+<A HREF="/">Home</A>
+</code></pre>
+
+<pre><code class="language-html prettyprint"><!-- Recommended -->
+<img src="google.png" alt="Google">
+</code></pre>
+
+<pre><code class="language-css prettyprint badcode">/* Not recommended */
+color: #E5E5E5;
+</code></pre>
+
+<pre><code class="language-css prettyprint">/* Recommended */
+color: #e5e5e5;
+</code></pre>
+
+<h4 id="Trailing_Whitespace">2.2.3 Trailing Whitespace</h4>
+
+<p>Remove trailing white spaces.</p>
+
+<p>Trailing white spaces are unnecessary and can complicate diffs.</p>
+
+<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
+<p>What?_
+</code></pre>
+
+<pre><code class="language-html prettyprint"><!-- Recommended -->
+<p>Yes please.
+</code></pre>
+
+<h3 id="General_Meta_Rules">2.3 General Meta Rules</h3>
+
+<h4 id="Encoding">2.3.1 Encoding</h4>
+
+<p>Use UTF-8 (no BOM).</p>
+
+<p>Make sure your editor uses UTF-8 as character encoding, without a byte order
+mark.</p>
+
+<p>Specify the encoding in HTML templates and documents via <code><meta
+charset="utf-8"></code>. Do not specify the encoding of style sheets as these assume
+UTF-8.</p>
+
+<p>(More on encodings and when and how to specify them can be found in <a href="https://www.w3.org/International/tutorials/tutorial-char-enc/">Handling
+character encodings in HTML and CSS</a>.)</p>
+
+<h4 id="Comments">2.3.2 Comments</h4>
+
+<p>Explain code as needed, where possible.</p>
+
+<p>Use comments to explain code: What does it cover, what purpose does it serve,
+why is respective solution used or preferred?</p>
+
+<p>(This item is optional as it is not deemed a realistic expectation to always
+demand fully documented code. Mileage may vary heavily for HTML and CSS code and
+depends on the project’s complexity.)</p>
+
+<h4 id="Action_Items">2.3.3 Action Items</h4>
+
+<p>Mark todos and action items with <code>TODO</code>.</p>
+
+<p>Highlight todos by using the keyword <code>TODO</code> only, not other common formats like
+<code>@@</code>.</p>
+
+<p>Append a contact (username or mailing list) in parentheses as with the format
+<code>TODO(contact)</code>.</p>
+
+<p>Append action items after a colon as in <code>TODO: action item</code>.</p>
+
+<pre></pre>
+
+<pre><code class="language-django prettyprint external">{# TODO(john.doe): revisit centering #}
+<center>Test</center>
+</code></pre>
+
+<p></p>
+
+<pre><code class="language-html prettyprint"><!-- TODO: remove optional tags -->
+<ul>
+ <li>Apples</li>
+ <li>Oranges</li>
+</ul>
+</code></pre>
+
+<h2 id="HTML">3 HTML</h2>
+
+<h3 id="HTML_Style_Rules">3.1 HTML Style Rules</h3>
+
+<h4 id="Document_Type">3.1.1 Document Type</h4>
+
+<p>Use HTML5.</p>
+
+<p>HTML5 (HTML syntax) is preferred for all HTML documents: <code><!DOCTYPE html></code>.</p>
+
+<p>(It’s recommended to use HTML, as <code>text/html</code>. Do not use XHTML. XHTML, as
+<a href="https://hixie.ch/advocacy/xhtml"><code>application/xhtml+xml</code></a>, lacks both browser
+and infrastructure support and offers less room for optimization than HTML.)</p>
+
+<p>Although fine with HTML, do not close void elements, i.e. write <code><br></code>, not
+<code><br /></code>.</p>
+
+<h4 id="HTML_Validity">3.1.2 HTML Validity</h4>
+
+<p>Use valid HTML where possible.</p>
+
+<p>Use valid HTML code unless that is not possible due to otherwise unattainable
+performance goals regarding file size.</p>
+
+<p>
+
+Use tools such as the <a href="https://validator.w3.org/nu/">W3C HTML validator</a>
+to test.
+</p>
+
+<p>Using valid HTML is a measurable baseline quality attribute that contributes to
+learning about technical requirements and constraints, and that ensures proper
+HTML usage.</p>
+
+<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
+<title>Test</title>
+<article>This is only a test.
+</code></pre>
+
+<pre><code class="language-html prettyprint"><!-- Recommended -->
+<!DOCTYPE html>
+<meta charset="utf-8">
+<title>Test</title>
+<article>This is only a test.</article>
+</code></pre>
+
+<h4 id="Semantics">3.1.3 Semantics</h4>
+
+<p>Use HTML according to its purpose.</p>
+
+<p>Use elements (sometimes incorrectly called “tags”) for what they have been
+created for. For example, use heading elements for headings, <code>p</code> elements for
+paragraphs, <code>a</code> elements for anchors, etc.</p>
+
+<p>Using HTML according to its purpose is important for accessibility, reuse, and
+code efficiency reasons.</p>
+
+<p></p>
+
+<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
+<div onclick="goToRecommendations();">All recommendations</div>
+</code></pre>
+
+<pre><code class="language-html prettyprint"><!-- Recommended -->
+<a href="recommendations/">All recommendations</a>
+</code></pre>
+
+<h4 id="Multimedia_Fallback">3.1.4 Multimedia Fallback</h4>
+
+<p>Provide alternative contents for multimedia.</p>
+
+<p>For multimedia, such as images, videos, animated objects via <code>canvas</code>, make sure
+to offer alternative access. For images that means use of meaningful alternative
+text (<code>alt</code>) and for video and audio transcripts and captions, if available.</p>
+
+<p>Providing alternative contents is important for accessibility reasons: A blind
+user has few cues to tell what an image is about without <code>@alt</code>, and other users
+may have no way of understanding what video or audio contents are about either.</p>
+
+<p>(For images whose <code>alt</code> attributes would introduce redundancy, and for images
+whose purpose is purely decorative which you cannot immediately use CSS for, use
+no alternative text, as in <code>alt=""</code>.)</p>
+
+<p></p>
+
+<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
+<img src="spreadsheet.png">
+</code></pre>
+
+<pre><code class="language-html prettyprint"><!-- Recommended -->
+<img src="spreadsheet.png" alt="Spreadsheet screenshot.">
+</code></pre>
+
+<h4 id="Separation_of_Concerns">3.1.5 Separation of Concerns</h4>
+
+<p>Separate structure from presentation from behavior.</p>
+
+<p>Strictly keep structure (markup), presentation (styling), and behavior
+(scripting) apart, and try to keep the interaction between the three to an
+absolute minimum.</p>
+
+<p>That is, make sure documents and templates contain only HTML and HTML that is
+solely serving structural purposes. Move everything presentational into style
+sheets, and everything behavioral into scripts.</p>
+
+<p>In addition, keep the contact area as small as possible by linking as few style
+sheets and scripts as possible from documents and templates.</p>
+
+<p>Separating structure from presentation from behavior is important for
+maintenance reasons. It is always more expensive to change HTML documents and
+templates than it is to update style sheets and scripts.</p>
+
+<p></p>
+
+<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
+<!DOCTYPE html>
+<title>HTML sucks</title>
+<link rel="stylesheet" href="base.css" media="screen">
+<link rel="stylesheet" href="grid.css" media="screen">
+<link rel="stylesheet" href="print.css" media="print">
+<h1 style="font-size: 1em;">HTML sucks</h1>
+<p>I’ve read about this on a few sites but now I’m sure:
+ <u>HTML is stupid!!1</u>
+<center>I can’t believe there’s no way to control the styling of
+ my website without doing everything all over again!</center>
+</code></pre>
+
+<pre><code class="language-html prettyprint"><!-- Recommended -->
+<!DOCTYPE html>
+<title>My first CSS-only redesign</title>
+<link rel="stylesheet" href="default.css">
+<h1>My first CSS-only redesign</h1>
+<p>I’ve read about this on a few sites but today I’m actually
+ doing it: separating concerns and avoiding anything in the HTML of
+ my website that is presentational.
+<p>It’s awesome!
+</code></pre>
+
+<h4 id="Entity_References">3.1.6 Entity References</h4>
+
+<p>Do not use entity references.</p>
+
+<p>There is no need to use entity references like <code>&mdash;</code>, <code>&rdquo;</code>, or
+<code>&#x263a;</code>, assuming the same encoding (UTF-8) is used for files and editors
+as well as among teams.</p>
+
+<p>The only exceptions apply to characters with special meaning in HTML (like <code><</code>
+and <code>&</code>) as well as control or “invisible” characters (like no-break spaces).</p>
+
+<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
+The currency symbol for the Euro is &ldquo;&eur;&rdquo;.
+</code></pre>
+
+<pre><code class="language-html prettyprint"><!-- Recommended -->
+The currency symbol for the Euro is “€”.
+</code></pre>
+
+<h4 id="Optional_Tags">3.1.7 Optional Tags</h4>
+
+<p>Omit optional tags (optional).</p>
+
+<p>For file size optimization and scannability purposes, consider omitting optional
+tags. The <a href="https://whatwg.org/specs/web-apps/current-work/multipage/syntax.html#syntax-tag-omission">HTML5 specification</a>
+defines what tags can be omitted.</p>
+
+<p>(This approach may require a grace period to be established as a wider guideline
+as it’s significantly different from what web developers are typically taught.
+For consistency and simplicity reasons it’s best served omitting all optional
+tags, not just a selection.)</p>
+
+<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>Spending money, spending bytes</title>
+ </head>
+ <body>
+ <p>Sic.</p>
+ </body>
+</html>
+</code></pre>
+
+<pre><code class="language-html prettyprint"><!-- Recommended -->
+<!DOCTYPE html>
+<title>Saving money, saving bytes</title>
+<p>Qed.
+</code></pre>
+
+<h4 id="type_Attributes">3.1.8 <code>type</code> Attributes</h4>
+
+<p>Omit <code>type</code> attributes for style sheets and scripts.</p>
+
+<p>Do not use <code>type</code> attributes for style sheets (unless not using CSS) and scripts
+(unless not using JavaScript).</p>
+
+<p>Specifying <code>type</code> attributes in these contexts is not necessary as HTML5 implies
+<a href="https://whatwg.org/specs/web-apps/current-work/multipage/semantics.html#attr-style-type"><code>text/css</code></a>
+and <a href="https://whatwg.org/specs/web-apps/current-work/multipage/scripting.html#attr-script-type"><code>text/javascript</code></a>
+as defaults. This can be safely done even for older browsers.</p>
+
+<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
+<link rel="stylesheet" href="https://www.google.com/css/maia.css"
+ type="text/css">
+</code></pre>
+
+<pre><code class="language-html prettyprint"><!-- Recommended -->
+<link rel="stylesheet" href="https://www.google.com/css/maia.css">
+</code></pre>
+
+<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
+<script src="https://www.google.com/js/gweb/analytics/autotrack.js"
+ type="text/javascript"></script>
+</code></pre>
+
+<pre><code class="language-html prettyprint"><!-- Recommended -->
+<script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>
+</code></pre>
+
+<h3 id="HTML_Formatting_Rules">3.2 HTML Formatting Rules</h3>
+
+<h4 id="General_Formatting">3.2.1 General Formatting</h4>
+
+<p>Use a new line for every block, list, or table element, and indent every such
+child element.</p>
+
+<p>Independent of the styling of an element (as CSS allows elements to assume a
+different role per <code>display</code> property), put every block, list, or table element
+on a new line.</p>
+
+<p>Also, indent them if they are child elements of a block, list, or table element.</p>
+
+<p>(If you run into issues around whitespace between list items it’s acceptable to
+put all <code>li</code> elements in one line. A linter is encouraged to throw a warning
+instead of an error.)</p>
+
+<pre><code class="language-html prettyprint"><blockquote>
+ <p><em>Space</em>, the final frontier.</p>
+</blockquote>
+</code></pre>
+
+<pre><code class="language-html prettyprint"><ul>
+ <li>Moe
+ <li>Larry
+ <li>Curly
+</ul>
+</code></pre>
+
+<pre><code class="language-html prettyprint"><table>
+ <thead>
+ <tr>
+ <th scope="col">Income
+ <th scope="col">Taxes
+ <tbody>
+ <tr>
+ <td>$ 5.00
+ <td>$ 4.50
+</table>
+</code></pre>
+
+<h4 id="HTML_Quotation_Marks">3.2.2 HTML Quotation Marks</h4>
+
+<p>When quoting attributes values, use double quotation marks.</p>
+
+<p>Use double (<code>""</code>) rather than single quotation marks (<code>''</code>) around attribute
+values.</p>
+
+<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
+<a class='maia-button maia-button-secondary'>Sign in</a>
+</code></pre>
+
+<pre><code class="language-html prettyprint"><!-- Recommended -->
+<a class="maia-button maia-button-secondary">Sign in</a>
+</code></pre>
+
+<h2 id="CSS">4 CSS</h2>
+
+<h3 id="CSS_Style_Rules">4.1 CSS Style Rules</h3>
+
+<h4 id="CSS_Validity">4.1.1 CSS Validity</h4>
+
+<p>Use valid CSS where possible.</p>
+
+<p>Unless dealing with CSS validator bugs or requiring proprietary syntax, use
+valid CSS code.</p>
+
+<p>
+
+Use tools such as the <a href="https://jigsaw.w3.org/css-validator/">W3C CSS validator</a>
+to test.
+</p>
+
+<p>Using valid CSS is a measurable baseline quality attribute that allows to spot
+CSS code that may not have any effect and can be removed, and that ensures
+proper CSS usage.</p>
+
+<h4 id="ID_and_Class_Naming">4.1.2 ID and Class Naming</h4>
+
+<p>Use meaningful or generic ID and class names.</p>
+
+<p>Instead of presentational or cryptic names, always use ID and class names that
+reflect the purpose of the element in question, or that are otherwise generic.</p>
+
+<p>Names that are specific and reflect the purpose of the element should be
+preferred as these are most understandable and the least likely to change.</p>
+
+<p>Generic names are simply a fallback for elements that have no particular or no
+meaning different from their siblings. They are typically needed as “helpers.”</p>
+
+<p>Using functional or generic names reduces the probability of unnecessary
+document or template changes.</p>
+
+<pre><code class="language-css prettyprint badcode">/* Not recommended: meaningless */
+#yee-1901 {}
+
+/* Not recommended: presentational */
+.button-green {}
+.clear {}
+</code></pre>
+
+<pre><code class="language-css prettyprint">/* Recommended: specific */
+#gallery {}
+#login {}
+.video {}
+
+/* Recommended: generic */
+.aux {}
+.alt {}
+</code></pre>
+
+<h4 id="ID_and_Class_Name_Style">4.1.3 ID and Class Name Style</h4>
+
+<p>Use ID and class names that are as short as possible but as long as necessary.</p>
+
+<p>Try to convey what an ID or class is about while being as brief as possible.</p>
+
+<p>Using ID and class names this way contributes to acceptable levels of
+understandability and code efficiency.</p>
+
+<pre><code class="language-css prettyprint badcode">/* Not recommended */
+#navigation {}
+.atr {}
+</code></pre>
+
+<pre><code class="language-css prettyprint">/* Recommended */
+#nav {}
+.author {}
+</code></pre>
+
+<h4 id="Type_Selectors">4.1.4 Type Selectors</h4>
+
+<p>Avoid qualifying ID and class names with type selectors.</p>
+
+<p>Unless necessary (for example with helper classes), do not use element names in
+conjunction with IDs or classes.</p>
+
+<p>Avoiding unnecessary ancestor selectors is useful for <a href="http://www.stevesouders.com/blog/2009/06/18/simplifying-css-selectors/">performance reasons</a>.</p>
+
+<pre><code class="language-css prettyprint badcode">/* Not recommended */
+ul#example {}
+div.error {}
+</code></pre>
+
+<pre><code class="language-css prettyprint">/* Recommended */
+#example {}
+.error {}
+</code></pre>
+
+<h4 id="Shorthand_Properties">4.1.5 Shorthand Properties</h4>
+
+<p>Use shorthand properties where possible.</p>
+
+<p>CSS offers a variety of <a href="https://www.w3.org/TR/CSS21/about.html#shorthand">shorthand</a>
+properties (like <code>font</code>) that should be used whenever possible, even in cases
+where only one value is explicitly set.</p>
+
+<p>Using shorthand properties is useful for code efficiency and understandability.</p>
+
+<pre><code class="language-css prettyprint badcode">/* Not recommended */
+border-top-style: none;
+font-family: palatino, georgia, serif;
+font-size: 100%;
+line-height: 1.6;
+padding-bottom: 2em;
+padding-left: 1em;
+padding-right: 1em;
+padding-top: 0;
+</code></pre>
+
+<pre><code class="language-css prettyprint">/* Recommended */
+border-top: 0;
+font: 100%/1.6 palatino, georgia, serif;
+padding: 0 1em 2em;
+</code></pre>
+
+<h4 id="0_and_Units">4.1.6 0 and Units</h4>
+
+<p>Omit unit specification after “0” values, unless required.</p>
+
+<p>Do not use units after <code>0</code> values unless they are required.</p>
+
+<pre><code class="language-css prettyprint">flex: 0px; /* This flex-basis component requires a unit. */
+flex: 1 1 0px; /* Not ambiguous without the unit, but needed in IE11. */
+margin: 0;
+padding: 0;
+</code></pre>
+
+<h4 id="Leading_0s">4.1.7 Leading 0s</h4>
+
+<p>Omit leading “0”s in values.</p>
+
+<p>Do not use put <code>0</code>s in front of values or lengths between -1 and 1.</p>
+
+<pre><code class="language-css prettyprint">font-size: .8em;
+</code></pre>
+
+<h4 id="Hexadecimal_Notation">4.1.8 Hexadecimal Notation</h4>
+
+<p>Use 3 character hexadecimal notation where possible.</p>
+
+<p>For color values that permit it, 3 character hexadecimal notation is shorter and
+more succinct.</p>
+
+<pre><code class="language-css prettyprint badcode">/* Not recommended */
+color: #eebbcc;
+</code></pre>
+
+<pre><code class="language-css prettyprint">/* Recommended */
+color: #ebc;
+</code></pre>
+
+<h4 id="Prefixes">4.1.9 Prefixes</h4>
+
+<p>Prefix selectors with an application-specific prefix (optional).</p>
+
+<p>In large projects as well as for code that gets embedded in other projects or on
+external sites use prefixes (as namespaces) for ID and class names. Use short,
+unique identifiers followed by a dash.</p>
+
+<p></p>
+
+<p></p>
+
+<p>Using namespaces helps preventing naming conflicts and can make maintenance
+easier, for example in search and replace operations.</p>
+
+<pre><code class="language-css prettyprint">.adw-help {} /* AdWords */
+#maia-note {} /* Maia */
+</code></pre>
+
+<h4 id="ID_and_Class_Name_Delimiters">4.1.10 ID and Class Name Delimiters</h4>
+
+<p>Separate words in ID and class names by a hyphen.</p>
+
+<p>Do not concatenate words and abbreviations in selectors by any characters
+(including none at all) other than hyphens, in order to improve understanding
+and scannability.</p>
+
+<pre><code class="language-css prettyprint badcode">/* Not recommended: does not separate the words “demo” and “image” */
+.demoimage {}
+
+/* Not recommended: uses underscore instead of hyphen */
+.error_status {}
+</code></pre>
+
+<pre><code class="language-css prettyprint">/* Recommended */
+#video-id {}
+.ads-sample {}
+</code></pre>
+
+<h4 id="Hacks">4.1.11 Hacks</h4>
+
+<p>Avoid user agent detection as well as CSS “hacks”—try a different approach
+first.</p>
+
+<p>It’s tempting to address styling differences over user agent detection or
+special CSS filters, workarounds, and hacks. Both approaches should be
+considered last resort in order to achieve and maintain an efficient and
+manageable code base. Put another way, giving detection and hacks a free pass
+will hurt projects in the long run as projects tend to take the way of least
+resistance. That is, allowing and making it easy to use detection and hacks
+means using detection and hacks more frequently—and more frequently is too
+frequently.</p>
+
+<p></p>
+
+<p></p>
+
+<h3 id="CSS_Formatting_Rules">4.2 CSS Formatting Rules</h3>
+
+<h4 id="Declaration_Order">4.2.1 Declaration Order</h4>
+
+<p>Alphabetize declarations.</p>
+
+<p>Put declarations in alphabetical order in order to achieve consistent code in a
+way that is easy to remember and maintain.</p>
+
+<p>Ignore vendor-specific prefixes for sorting purposes. However, multiple
+vendor-specific prefixes for a certain CSS property should be kept sorted (e.g.
+-moz prefix comes before -webkit).</p>
+
+<pre><code class="language-css prettyprint">background: fuchsia;
+border: 1px solid;
+-moz-border-radius: 4px;
+-webkit-border-radius: 4px;
+border-radius: 4px;
+color: black;
+text-align: center;
+text-indent: 2em;
+</code></pre>
+
+<h4 id="Block_Content_Indentation">4.2.2 Block Content Indentation</h4>
+
+<p>Indent all block content.</p>
+
+<p>Indent all <a href="https://www.w3.org/TR/CSS21/syndata.html#block">block content</a>,
+that is rules within rules as well as declarations, so to reflect hierarchy and
+improve understanding.</p>
+
+<pre><code class="language-css prettyprint">@media screen, projection {
+
+ html {
+ background: #fff;
+ color: #444;
+ }
+
+}
+</code></pre>
+
+<h4 id="Declaration_Stops">4.2.3 Declaration Stops</h4>
+
+<p>Use a semicolon after every declaration.</p>
+
+<p>End every declaration with a semicolon for consistency and extensibility
+reasons.</p>
+
+<pre><code class="language-css prettyprint badcode">/* Not recommended */
+.test {
+ display: block;
+ height: 100px
+}
+</code></pre>
+
+<pre><code class="language-css prettyprint">/* Recommended */
+.test {
+ display: block;
+ height: 100px;
+}
+</code></pre>
+
+<h4 id="Property_Name_Stops">4.2.4 Property Name Stops</h4>
+
+<p>Use a space after a property name’s colon.</p>
+
+<p>Always use a single space between property and value (but no space between
+property and colon) for consistency reasons.</p>
+
+<pre><code class="language-css prettyprint badcode">/* Not recommended */
+h3 {
+ font-weight:bold;
+}
+</code></pre>
+
+<pre><code class="language-css prettyprint">/* Recommended */
+h3 {
+ font-weight: bold;
+}
+</code></pre>
+
+<h4 id="Declaration_Block_Separation">4.2.5 Declaration Block Separation</h4>
+
+<p>Use a space between the last selector and the declaration block.</p>
+
+<p>Always use a single space between the last selector and the opening brace that
+begins the <a href="https://www.w3.org/TR/CSS21/syndata.html#rule-sets">declaration block</a>.</p>
+
+<p>The opening brace should be on the same line as the last selector in a given
+rule.</p>
+
+<pre><code class="language-css prettyprint badcode">/* Not recommended: missing space */
+#video{
+ margin-top: 1em;
+}
+
+/* Not recommended: unnecessary line break */
+#video
+{
+ margin-top: 1em;
+}
+</code></pre>
+
+<pre><code class="language-css prettyprint">/* Recommended */
+#video {
+ margin-top: 1em;
+}
+</code></pre>
+
+<h4 id="Selector_and_Declaration_Separation">4.2.6 Selector and Declaration Separation</h4>
+
+<p>Separate selectors and declarations by new lines.</p>
+
+<p>Always start a new line for each selector and declaration.</p>
+
+<pre><code class="language-css prettyprint badcode">/* Not recommended */
+a:focus, a:active {
+ position: relative; top: 1px;
+}
+</code></pre>
+
+<pre><code class="language-css prettyprint">/* Recommended */
+h1,
+h2,
+h3 {
+ font-weight: normal;
+ line-height: 1.2;
+}
+</code></pre>
+
+<h4 id="Rule_Separation">4.2.7 Rule Separation</h4>
+
+<p>Separate rules by new lines.</p>
+
+<p>Always put a blank line (two line breaks) between rules.</p>
+
+<pre><code class="language-css prettyprint">html {
+ background: #fff;
+}
+
+body {
+ margin: auto;
+ width: 50%;
+}
+</code></pre>
+
+<h4 id="CSS_Quotation_Marks">4.2.8 CSS Quotation Marks</h4>
+
+<p>Use single quotation marks for attribute selectors and property values.</p>
+
+<p>Use single (<code>''</code>) rather than double (<code>""</code>) quotation marks for attribute
+selectors or property values. Do not use quotation marks in URI values
+(<code>url()</code>).</p>
+
+<p>Exception: If you do need to use the <code>@charset</code> rule, use double quotation
+marks—<a href="https://www.w3.org/TR/CSS21/syndata.html#charset">single quotation marks are not permitted</a>.</p>
+
+<pre><code class="language-css prettyprint badcode">/* Not recommended */
+@import url("https://www.google.com/css/maia.css");
+
+html {
+ font-family: "open sans", arial, sans-serif;
+}
+</code></pre>
+
+<pre><code class="language-css prettyprint">/* Recommended */
+@import url(https://www.google.com/css/maia.css);
+
+html {
+ font-family: 'open sans', arial, sans-serif;
+}
+</code></pre>
+
+<h3 id="CSS_Meta_Rules">4.3 CSS Meta Rules</h3>
+
+<h4 id="Section_Comments">4.3.1 Section Comments</h4>
+
+<p>Group sections by a section comment (optional).</p>
+
+<p>If possible, group style sheet sections together by using comments. Separate
+sections with new lines.</p>
+
+<pre><code class="language-css prettyprint">/* Header */
+
+#adw-header {}
+
+/* Footer */
+
+#adw-footer {}
+
+/* Gallery */
+
+.adw-gallery {}
+</code></pre>
+
+
+
+<p></p>
+
+<p></p>
+
+
+
+<p></p>
+
+<p></p>
+
+<pre></pre>
+
+
+
+
+
+<p></p>
+
+<p></p>
+
+<h2 id="Parting_Words">Parting Words</h2>
+
+<p><em>Be consistent.</em></p>
+
+<p>If you’re editing code, take a few minutes to look at the code around you and
+determine its style. If they use spaces around all their arithmetic operators,
+you should too. If their comments have little boxes of hash marks around them,
+make your comments have little boxes of hash marks around them too.</p>
+
+<p>The point of having style guidelines is to have a common vocabulary of coding so
+people can concentrate on what you’re saying rather than on how you’re saying
+it. We present global style rules here so people know the vocabulary, but local
+style is also important. If code you add to a file looks drastically different
+from the existing code around it, it throws readers out of their rhythm when
+they go to read it. Avoid this.</p>
+</div>
+</body>
+</html>
diff --git a/htmlcssguide.xml b/htmlcssguide.xml
new file mode 100644
index 0000000..0ab9f80
--- /dev/null
+++ b/htmlcssguide.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0"?>
+<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
+<GUIDE title="Google HTML/CSS Style Guide">
+ <p>
+ The style guide has moved to
+ <a href="htmlcssguide.html">htmlcssguide.html</a>
+ </p>
+</GUIDE>
diff --git a/include/jsguide.js b/include/jsguide.js
new file mode 100644
index 0000000..dcf5689
--- /dev/null
+++ b/include/jsguide.js
@@ -0,0 +1,56 @@
+window.initStyleGuide = function(init) {
+ // Runs the callback on every element matched by the query selector.
+ function find(querySelector, callback) {
+ var elements = [].slice.call(document.querySelectorAll(querySelector));
+ for (var i = 0; i < elements.length; i++) {
+ callback(elements[i]);
+ }
+ }
+ // Add the tocDiv at the top.
+ var title = document.getElementsByTagName('h1')[0];
+ var toc = document.createElement('div');
+ toc.id = 'tocDiv';
+ toc.className = 'vertical_toc';
+ title.parentNode.insertBefore(toc, title.nextSibling);
+
+ // If a paragraph starts with (e.g.) "Note:" or "Tip:" then add
+ // that "callout class" to its element.
+ find('p', function(paragraph) {
+ var match = /^([a-z]+):/i.exec(paragraph.textContent);
+ if (match) {
+ paragraph.classList.add(match[1].toLowerCase());
+ }
+ });
+
+ // Fill in text for intra-document links, ensuring that links
+ // remain up-to-date even if sections are moved or renumbered.
+ // This triggers on any link with "??" as its text and a URL
+ // starting with "#", and the filled-in text is exactly the same
+ // as the text of the referenced section heading.
+ find('a[href^="#"]', function(link) {
+ var href = link.getAttribute('href');
+ var heading = document.getElementById(href.substring(1));
+ // Fill in link text with heading title
+ if (heading && link.textContent == '??') {
+ link.textContent = heading.textContent;
+ }
+ });
+
+ // Hoedown renders fenced code blocks incompatibly with what
+ // prettify expects. As a result, prettify doesn't handle them
+ // properly. Fix it by moving the code directly into the pre.
+ find('pre > code', function(code) {
+ var pre = code.parentElement;
+ pre.className = code.className;
+ pre.innerHTML = code.innerHTML;
+ });
+
+ // Run the normal init function.
+ init();
+
+ // Call the pretty-printer after we've fixed up the code blocks.
+ var pretty = document.createElement('script');
+ pretty.src = 'https://cdn.rawgit.com/google/code-prettify/master/loader/' +
+ 'run_prettify.js';
+ document.body.appendChild(pretty);
+}.bind(null, window.initStyleGuide);
diff --git a/include/link.png b/include/link.png
new file mode 100644
index 0000000..75d5c7b
--- /dev/null
+++ b/include/link.png
Binary files differ
diff --git a/include/styleguide.css b/include/styleguide.css
new file mode 100644
index 0000000..ef62024
--- /dev/null
+++ b/include/styleguide.css
@@ -0,0 +1,261 @@
+/* General CSS */
+
+body {
+ background-color: #fff;
+ color: #333;
+ font-family: sans-serif;
+ font-size: 10pt;
+ margin-right: 100px;
+ margin-left: 100px;
+}
+
+h1 {
+ text-align: center;
+ font-size: 18pt;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ color: #06c;
+ margin-top: 2em;
+ margin-bottom: 1em;
+ padding: 25px;
+ font-weight:bold;
+}
+
+h2,
+h3,
+h4,
+h5,
+h6 {
+ margin-top:1.5em;
+ margin-bottom:.75em;
+}
+
+h1 {font-size:200%;}
+h2 {font-size:167%;}
+h3 {font-size:133%;}
+h4 {font-size:120%;}
+h5 {font-size:110%;}
+
+
+table {
+ border: 1px solid #bbb;
+ border-spacing: 0;
+ border-collapse: collapse;
+ margin: 0 0 1.5em;
+ vertical-align: middle;
+ width: 100%
+}
+
+td, th {
+ border: 1px solid #ccc;
+ padding: 2px 12px;
+ font-size: 10pt;
+}
+
+code, samp, var {
+ background-color:#FAFAFA;
+ white-space: nowrap
+}
+
+pre {
+ padding:6px 10px;
+ background-color:#FAFAFA;
+ border:1px solid #bbb;
+ overflow:auto;
+}
+
+pre.prettyprint {
+ padding:6px 10px !important;
+ border:1px solid #bbb !important;
+}
+
+code.bad, code.badcode {
+ color: magenta;
+}
+
+pre.bad, pre.badcode {
+ background-color:#ffe6d8;
+ border-top:1px inset #a03;
+ border-left:1px inset #a03;
+}
+
+hr {
+ margin-top: 3.5em;
+ border-width: 1px;
+ color: #fff;
+}
+
+/* TOC CSS */
+
+table.columns {
+ border: none;
+}
+
+td.two_columns {
+ -webkit-column-count: 2;
+ column-count: 2;
+}
+
+.toc_category {
+ font-size: 10pt;
+ padding-top: 1em;
+ padding-bottom: 1em;
+ border-left-width: 2px;
+ border-right-width: 2px;
+ border-color: grey;
+}
+
+.toc_stylepoint {
+ font-size: 10pt;
+ padding-top: 1em;
+ padding-bottom: 1em;
+}
+
+li.toc_entry {
+ padding-right: 1em;
+ display: inline;
+ list-style-type: none;
+}
+
+/*
+ * This space is required to trigger the linewrap on the links
+ * at href boundaries
+ */
+li.toc_entry::after {
+ content: " ";
+ }
+
+li.toc_entry a {
+ white-space: nowrap;
+}
+
+/* Horizontal TOC */
+.toc td, .toc th {
+ border-width: 1px 5px;
+ overflow: hidden;
+}
+
+/* Vertical TOC */
+
+.toc td.two_columns {
+ border-width: 0px;
+}
+
+/* Special Sections */
+
+address {
+ text-align: right;
+}
+
+.revision {
+ text-align: right;
+}
+
+.headerbox {
+ margin-left: 50%;
+ font-size: 75%;
+}
+
+.legend {
+ padding-top: 1em;
+ margin-left: 50%;
+ font-size: 10pt;
+}
+
+.link_button {
+ float: left;
+ display: none;
+ background-color: #f8f8ff;
+ border-color: #f0f0ff;
+ border-style: solid;
+ border-width: 1px;
+ font-size: 75%;
+ margin-top: 0;
+ margin-left: -50px;
+ padding: 24px;
+ border-radius: 3px;
+ -webkit-border-radius: 3px;
+ -moz-border-radius: 3px;
+}
+
+.ignoreLink {
+ padding: 0px;
+}
+
+.divider{
+ width:5px;
+ height:auto;
+ display:inline-block;
+}
+
+/* Style Guide semantic CSS */
+
+.summary {
+ margin-top: 1em;
+ margin-bottom: 1em;
+}
+
+.stylebody {
+ margin-top: 1em;
+ margin-bottom: 1em;
+}
+
+.stylepoint_section {
+ display: block;
+ margin-bottom: 1em;
+ font-family: sans-serif;
+ font-weight: bold;
+}
+
+.stylepoint_subsection {
+ display: block;
+ margin-bottom: 1em;
+}
+
+.stylepoint_subsubsection {
+ display: block;
+ margin-bottom: 1em;
+}
+
+.definition:before {
+ content: "Definition: ";
+ font-weight: bold;
+ display: block;
+ margin-bottom: 1em;
+}
+
+.pros:before {
+ content: "Pros: ";
+ font-weight: bold;
+ display: block;
+ margin-bottom: 1em;
+}
+
+.cons:before {
+ content: "Cons: ";
+ font-weight: bold;
+ display: block;
+ margin-bottom: 1em;
+}
+
+.decision:before {
+ content: "Decision: ";
+ font-weight: bold;
+ display: block;
+ margin-bottom: 1em;
+}
+
+.exception:before {
+ content: "Exception: ";
+ font-weight: bold;
+ display: block;
+ margin-bottom: 1em;
+}
+
+.note:before {
+ content: "Note: ";
+ font-weight: bold;
+ display: block;
+ margin-bottom: 1em;
+}
diff --git a/include/styleguide.js b/include/styleguide.js
new file mode 100644
index 0000000..3c21e10
--- /dev/null
+++ b/include/styleguide.js
@@ -0,0 +1,289 @@
+TocTypeEnum = {
+ VERTICAL: 1,
+ HORIZONTAL: 2
+};
+
+function CreateTOC(tocElement) {
+
+ // Find the toc element DIV. We'll place our TOC there.
+ var toc = document.getElementById(tocElement);
+
+ var tocTypeClass = toc.className;
+ var tocType;
+
+ switch (tocTypeClass) {
+ case 'horizontal_toc':
+ tocType = TocTypeEnum.HORIZONTAL;
+ break;
+ case 'vertical_toc':
+ tocType = TocTypeEnum.VERTICAL;
+ break;
+ default:
+ tocType = TocTypeEnum.VERTICAL;
+ break;
+ }
+
+ // If toc_levels is defined, set headingLevels to it.
+ // Otherwise, use default value of "h2,h3"
+ var headingLevels;
+ if (typeof toc_levels === 'undefined') {
+ headingLevels = 'h2,h3';
+ } else {
+
+ }
+
+ // Collect all section heading elements in an array
+ var headings = document.querySelectorAll(headingLevels);
+
+ // Add TOC title elements
+ var tocHeadingDiv = document.createElement('div');
+ toc.appendChild(tocHeadingDiv);
+ tocHeadingDiv.className = 'toc_title';
+ var tocHeading = document.createElement('h3');
+ toc.appendChild(tocHeading);
+ tocHeading.className = 'ignoreLink';
+ tocHeading.id = 'toc';
+ var tocText = document.createTextNode('Table of Contents');
+ tocHeading.appendChild(tocText);
+
+ // Add table and tbody
+ var tocTable = document.createElement('table');
+ if (tocType == TocTypeEnum.VERTICAL) {
+ tocTable.className = 'columns';
+ }
+ toc.appendChild(tocTable);
+
+ var tbody_element = document.createElement('tbody');
+ tbody_element.setAttribute('valign', 'top');
+ tbody_element.className = 'toc';
+ tocTable.appendChild(tbody_element);
+
+ // Get the highest level heading
+ var firstHeading = headings[0];
+ var masterLevel = parseInt(headingLevels.charAt(1));
+
+ // Get the lowest heading level
+ var lowestLevel = parseInt(headingLevels.charAt(headingLevels - 1));
+
+ switch (tocType) {
+ case TocTypeEnum.HORIZONTAL:
+ CreateHorizontalTOC(headings, masterLevel, lowestLevel, tbody_element);
+ break;
+ case TocTypeEnum.VERTICAL:
+ CreateVerticalTOC(headings, masterLevel, lowestLevel, tbody_element);
+ break;
+ default:
+ }
+}
+
+function CreateHorizontalTOC(
+ headings, masterLevel, lowestLevel, tbody_element) {
+
+ // Initialize the header counter
+ var h = 0;
+ var ignoreChildren = false;
+
+ while (h < headings.length) {
+ // Get current heading
+ var heading = headings[h];
+
+ // Get the current heading level
+ var level = parseInt(heading.tagName.charAt(1));
+
+ if (isNaN(level) || level < 1 || level > lowestLevel) continue;
+
+ // If level is a masterLevel, make it a TOC parent category
+ if ((level == masterLevel) && (!hasClass(heading, 'ignoreLink'))) {
+ toc_current_row = AddTOCMaster(tbody_element, heading);
+ ignoreChildren = false;
+ }
+
+ if ((level == masterLevel) && (hasClass(heading, 'ignoreLink'))) {
+ ignoreChildren = true;
+ }
+
+ if ((level != masterLevel) && (!ignoreChildren)) {
+ AddTOCElements(toc_current_row, heading);
+ }
+
+ // Advance the header counter
+ h++;
+ }
+}
+
+// Adds a master Table of Content heading
+function AddTOCMaster(tocTable, heading) {
+
+ // Add the table row scaffolding
+ var toc_tr = document.createElement('tr');
+ tocTable.appendChild(toc_tr);
+ toc_tr.setAttribute('valign', 'top');
+ var toc_tr_td = document.createElement('td');
+ toc_tr.appendChild(toc_tr_td);
+ var toc_category = document.createElement('div');
+ toc_tr_td.appendChild(toc_category);
+ toc_category.className = 'toc_category';
+
+ // Create the link to this header
+ var link = document.createElement('a');
+ link.href = '#' + heading.id; // Create the anchor link
+ link.textContent = heading.textContent; // Link text is same as heading
+ toc_category.appendChild(link);
+
+ // Add the container table cell for its children
+ var toc_td = document.createElement('td');
+ toc_tr.appendChild(toc_td);
+ var toc_td_div = document.createElement('div');
+ toc_td_div.className = 'toc_stylepoint';
+ toc_td.appendChild(toc_td_div);
+
+ return (toc_td_div);
+}
+
+// Adds Table of Contents element to a master heading as children
+function AddTOCElements(toc_div, heading) {
+
+ if (heading.offsetParent === null) {
+ // The element is currently hidden, so don't create a TOC entry
+ } else {
+ // Create the list item element
+ var toc_list_element = document.createElement('li');
+ toc_list_element.className = 'toc_entry';
+ toc_div.appendChild(toc_list_element);
+
+ // Create the link to this header
+ var link = document.createElement('a');
+ link.href = '#' + heading.id; // Create the anchor link
+ link.textContent = heading.textContent; // Link text is same as heading
+ toc_list_element.appendChild(link);
+ }
+}
+
+function CreateVerticalTOC(headings, masterLevel, lowestLevel, tbody_element) {
+
+ // Create the Column scaffolding
+ var toc_tr = document.createElement('tr');
+ tbody_element.appendChild(toc_tr);
+ var toc_tr_td = document.createElement('td');
+ toc_tr_td.className = 'two_columns';
+ toc_tr.appendChild(toc_tr_td);
+
+
+ // Initialize the header counter and the current row
+ var h = 0;
+ var toc_current_col = null;
+ var ignoreChildren = false;
+
+ while (h < headings.length) {
+ // Get current heading
+ var heading = headings[h];
+
+ // Get the current heading level
+ var level = parseInt(heading.tagName.charAt(1));
+
+ if (isNaN(level) || level < 1 || level > lowestLevel) continue;
+
+ // If level is a masterLevel, make it a TOC parent category
+ if ((level == masterLevel) && (!hasClass(heading, 'ignoreLink'))) {
+ if (heading.offsetParent === null) {
+ // The element is currently hidden, so don't create a TOC entry
+ } else {
+ var td_dl = document.createElement('dl');
+ toc_tr_td.appendChild(td_dl);
+ var td_dt = document.createElement('dt');
+ td_dl.appendChild(td_dt);
+ toc_current_col = td_dl;
+
+ // Create the link to this header
+ var link = document.createElement('a');
+ link.href = '#' + heading.id; // Create the anchor link
+ link.textContent = heading.textContent; // Link text is same as heading
+ td_dt.appendChild(link);
+ ignoreChildren = false;
+ }
+ }
+
+ // If level is a masterLevel but it's specified to ignore links, skip it
+ // and its children.
+ if ((level == masterLevel) && (hasClass(heading, 'ignoreLink'))) {
+ ignoreChildren = true;
+ }
+
+ if ((level != masterLevel) && (!ignoreChildren)) {
+ if (heading.offsetParent === null) {
+ // The element is currently hidden, so don't create a TOC entry
+ } else {
+ var td_dd = document.createElement('dd');
+ toc_current_col.appendChild(td_dd);
+ // Create the link to this header
+ var link = document.createElement('a');
+ link.href = '#' + heading.id; // Create the anchor link
+ link.textContent = heading.textContent; // Link text is same as heading
+ td_dd.appendChild(link);
+ }
+ }
+
+ // Advance the header counter
+ h++;
+ }
+}
+
+/*
+ * Utility function for finding elements with a given
+ * class.
+ */
+function hasClass(element, cls) {
+ return (' ' + element.className + ' ').indexOf(' ' + cls + ' ') > -1;
+}
+
+/*
+ * Linkify all h2 through h4 headers, except for those marked
+ * "ignoreLink"
+ */
+
+// Add the link image to the element.
+function LinkifyHeader(header, fileName, sizePixels) {
+ var link = document.createElement('a');
+ link.href = '#' + header.id;
+ link.setAttribute('alt', 'link to ' + header.id);
+ link.innerHTML =
+ '<img src="include/' + fileName + '"' +
+ ' width=' + sizePixels +
+ ' height=' + sizePixels +
+ ' style="float:left;position:relative;bottom:5px;">';
+ header.appendChild(link);
+}
+
+// Find all elements of the given tag and linkify if
+// they don't have 'ignoreLink' in their class.
+function LinkifyHeadersForTag(tagName) {
+ var headers = document.getElementsByTagName(tagName);
+ var header;
+ for (var j = 0; j != headers.length; j++) {
+ header = headers[j];
+ if (!hasClass(header, 'ignoreLink') && ('id' in header)) {
+ if (header.id != '') {
+ LinkifyHeader(header, 'link.png', 21);
+ header.style.left = '-46px';
+ header.style.position = 'relative';
+ }
+ }
+ }
+}
+
+// Linkify all h2, h3, and h4s. h1s are titles.
+function LinkifyHeaders() {
+ LinkifyHeadersForTag('h2');
+ LinkifyHeadersForTag('h3');
+ LinkifyHeadersForTag('h4');
+}
+
+/*
+ * Initialize the style guide by showing all internal
+ * elements and then linkifying the headers.
+ */
+
+function initStyleGuide() {
+ LinkifyHeaders();
+ CreateTOC('tocDiv');
+}
diff --git a/intellij-java-google-style.xml b/intellij-java-google-style.xml
new file mode 100644
index 0000000..f3a6743
--- /dev/null
+++ b/intellij-java-google-style.xml
@@ -0,0 +1,598 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<code_scheme name="GoogleStyle">
+ <option name="OTHER_INDENT_OPTIONS">
+ <value>
+ <option name="INDENT_SIZE" value="2" />
+ <option name="CONTINUATION_INDENT_SIZE" value="4" />
+ <option name="TAB_SIZE" value="2" />
+ <option name="USE_TAB_CHARACTER" value="false" />
+ <option name="SMART_TABS" value="false" />
+ <option name="LABEL_INDENT_SIZE" value="0" />
+ <option name="LABEL_INDENT_ABSOLUTE" value="false" />
+ <option name="USE_RELATIVE_INDENTS" value="false" />
+ </value>
+ </option>
+ <option name="INSERT_INNER_CLASS_IMPORTS" value="true" />
+ <option name="CLASS_COUNT_TO_USE_IMPORT_ON_DEMAND" value="999" />
+ <option name="NAMES_COUNT_TO_USE_IMPORT_ON_DEMAND" value="999" />
+ <option name="PACKAGES_TO_USE_IMPORT_ON_DEMAND">
+ <value />
+ </option>
+ <option name="IMPORT_LAYOUT_TABLE">
+ <value>
+ <package name="" withSubpackages="true" static="true" />
+ <emptyLine />
+ <package name="" withSubpackages="true" static="false" />
+ </value>
+ </option>
+ <option name="RIGHT_MARGIN" value="100" />
+ <option name="JD_ALIGN_PARAM_COMMENTS" value="false" />
+ <option name="JD_ALIGN_EXCEPTION_COMMENTS" value="false" />
+ <option name="JD_P_AT_EMPTY_LINES" value="false" />
+ <option name="JD_KEEP_EMPTY_PARAMETER" value="false" />
+ <option name="JD_KEEP_EMPTY_EXCEPTION" value="false" />
+ <option name="JD_KEEP_EMPTY_RETURN" value="false" />
+ <option name="KEEP_CONTROL_STATEMENT_IN_ONE_LINE" value="false" />
+ <option name="KEEP_BLANK_LINES_BEFORE_RBRACE" value="0" />
+ <option name="KEEP_BLANK_LINES_IN_CODE" value="1" />
+ <option name="BLANK_LINES_AFTER_CLASS_HEADER" value="0" />
+ <option name="ALIGN_MULTILINE_PARAMETERS" value="false" />
+ <option name="ALIGN_MULTILINE_FOR" value="false" />
+ <option name="CALL_PARAMETERS_WRAP" value="1" />
+ <option name="METHOD_PARAMETERS_WRAP" value="1" />
+ <option name="EXTENDS_LIST_WRAP" value="1" />
+ <option name="THROWS_KEYWORD_WRAP" value="1" />
+ <option name="METHOD_CALL_CHAIN_WRAP" value="1" />
+ <option name="BINARY_OPERATION_WRAP" value="1" />
+ <option name="BINARY_OPERATION_SIGN_ON_NEXT_LINE" value="true" />
+ <option name="TERNARY_OPERATION_WRAP" value="1" />
+ <option name="TERNARY_OPERATION_SIGNS_ON_NEXT_LINE" value="true" />
+ <option name="FOR_STATEMENT_WRAP" value="1" />
+ <option name="ARRAY_INITIALIZER_WRAP" value="1" />
+ <option name="WRAP_COMMENTS" value="true" />
+ <option name="IF_BRACE_FORCE" value="3" />
+ <option name="DOWHILE_BRACE_FORCE" value="3" />
+ <option name="WHILE_BRACE_FORCE" value="3" />
+ <option name="FOR_BRACE_FORCE" value="3" />
+ <option name="SPACE_BEFORE_ARRAY_INITIALIZER_LBRACE" value="true" />
+ <AndroidXmlCodeStyleSettings>
+ <option name="USE_CUSTOM_SETTINGS" value="true" />
+ <option name="LAYOUT_SETTINGS">
+ <value>
+ <option name="INSERT_BLANK_LINE_BEFORE_TAG" value="false" />
+ </value>
+ </option>
+ </AndroidXmlCodeStyleSettings>
+ <JSCodeStyleSettings>
+ <option name="INDENT_CHAINED_CALLS" value="false" />
+ </JSCodeStyleSettings>
+ <Python>
+ <option name="USE_CONTINUATION_INDENT_FOR_ARGUMENTS" value="true" />
+ </Python>
+ <TypeScriptCodeStyleSettings>
+ <option name="INDENT_CHAINED_CALLS" value="false" />
+ </TypeScriptCodeStyleSettings>
+ <XML>
+ <option name="XML_ALIGN_ATTRIBUTES" value="false" />
+ <option name="XML_LEGACY_SETTINGS_IMPORTED" value="true" />
+ </XML>
+ <codeStyleSettings language="CSS">
+ <indentOptions>
+ <option name="INDENT_SIZE" value="2" />
+ <option name="CONTINUATION_INDENT_SIZE" value="4" />
+ <option name="TAB_SIZE" value="2" />
+ </indentOptions>
+ </codeStyleSettings>
+ <codeStyleSettings language="ECMA Script Level 4">
+ <option name="KEEP_BLANK_LINES_IN_CODE" value="1" />
+ <option name="ALIGN_MULTILINE_PARAMETERS" value="false" />
+ <option name="ALIGN_MULTILINE_FOR" value="false" />
+ <option name="CALL_PARAMETERS_WRAP" value="1" />
+ <option name="METHOD_PARAMETERS_WRAP" value="1" />
+ <option name="EXTENDS_LIST_WRAP" value="1" />
+ <option name="BINARY_OPERATION_WRAP" value="1" />
+ <option name="BINARY_OPERATION_SIGN_ON_NEXT_LINE" value="true" />
+ <option name="TERNARY_OPERATION_WRAP" value="1" />
+ <option name="TERNARY_OPERATION_SIGNS_ON_NEXT_LINE" value="true" />
+ <option name="FOR_STATEMENT_WRAP" value="1" />
+ <option name="ARRAY_INITIALIZER_WRAP" value="1" />
+ <option name="IF_BRACE_FORCE" value="3" />
+ <option name="DOWHILE_BRACE_FORCE" value="3" />
+ <option name="WHILE_BRACE_FORCE" value="3" />
+ <option name="FOR_BRACE_FORCE" value="3" />
+ <option name="PARENT_SETTINGS_INSTALLED" value="true" />
+ </codeStyleSettings>
+ <codeStyleSettings language="HTML">
+ <indentOptions>
+ <option name="INDENT_SIZE" value="2" />
+ <option name="CONTINUATION_INDENT_SIZE" value="4" />
+ <option name="TAB_SIZE" value="2" />
+ </indentOptions>
+ </codeStyleSettings>
+ <codeStyleSettings language="JAVA">
+ <option name="KEEP_CONTROL_STATEMENT_IN_ONE_LINE" value="false" />
+ <option name="KEEP_BLANK_LINES_IN_CODE" value="1" />
+ <option name="BLANK_LINES_AFTER_CLASS_HEADER" value="1" />
+ <option name="ALIGN_MULTILINE_PARAMETERS" value="false" />
+ <option name="ALIGN_MULTILINE_RESOURCES" value="false" />
+ <option name="ALIGN_MULTILINE_FOR" value="false" />
+ <option name="CALL_PARAMETERS_WRAP" value="1" />
+ <option name="METHOD_PARAMETERS_WRAP" value="1" />
+ <option name="EXTENDS_LIST_WRAP" value="1" />
+ <option name="THROWS_KEYWORD_WRAP" value="1" />
+ <option name="METHOD_CALL_CHAIN_WRAP" value="1" />
+ <option name="BINARY_OPERATION_WRAP" value="1" />
+ <option name="BINARY_OPERATION_SIGN_ON_NEXT_LINE" value="true" />
+ <option name="TERNARY_OPERATION_WRAP" value="1" />
+ <option name="TERNARY_OPERATION_SIGNS_ON_NEXT_LINE" value="true" />
+ <option name="FOR_STATEMENT_WRAP" value="1" />
+ <option name="ARRAY_INITIALIZER_WRAP" value="1" />
+ <option name="WRAP_COMMENTS" value="true" />
+ <option name="IF_BRACE_FORCE" value="3" />
+ <option name="DOWHILE_BRACE_FORCE" value="3" />
+ <option name="WHILE_BRACE_FORCE" value="3" />
+ <option name="FOR_BRACE_FORCE" value="3" />
+ <option name="PARENT_SETTINGS_INSTALLED" value="true" />
+ <indentOptions>
+ <option name="INDENT_SIZE" value="2" />
+ <option name="CONTINUATION_INDENT_SIZE" value="4" />
+ <option name="TAB_SIZE" value="2" />
+ </indentOptions>
+ </codeStyleSettings>
+ <codeStyleSettings language="JSON">
+ <indentOptions>
+ <option name="CONTINUATION_INDENT_SIZE" value="4" />
+ <option name="TAB_SIZE" value="2" />
+ </indentOptions>
+ </codeStyleSettings>
+ <codeStyleSettings language="JavaScript">
+ <option name="RIGHT_MARGIN" value="80" />
+ <option name="KEEP_BLANK_LINES_IN_CODE" value="1" />
+ <option name="ALIGN_MULTILINE_PARAMETERS" value="false" />
+ <option name="ALIGN_MULTILINE_FOR" value="false" />
+ <option name="CALL_PARAMETERS_WRAP" value="1" />
+ <option name="METHOD_PARAMETERS_WRAP" value="1" />
+ <option name="BINARY_OPERATION_WRAP" value="1" />
+ <option name="BINARY_OPERATION_SIGN_ON_NEXT_LINE" value="true" />
+ <option name="TERNARY_OPERATION_WRAP" value="1" />
+ <option name="TERNARY_OPERATION_SIGNS_ON_NEXT_LINE" value="true" />
+ <option name="FOR_STATEMENT_WRAP" value="1" />
+ <option name="ARRAY_INITIALIZER_WRAP" value="1" />
+ <option name="IF_BRACE_FORCE" value="3" />
+ <option name="DOWHILE_BRACE_FORCE" value="3" />
+ <option name="WHILE_BRACE_FORCE" value="3" />
+ <option name="FOR_BRACE_FORCE" value="3" />
+ <option name="PARENT_SETTINGS_INSTALLED" value="true" />
+ <indentOptions>
+ <option name="INDENT_SIZE" value="2" />
+ <option name="TAB_SIZE" value="2" />
+ </indentOptions>
+ </codeStyleSettings>
+ <codeStyleSettings language="PROTO">
+ <option name="RIGHT_MARGIN" value="80" />
+ <indentOptions>
+ <option name="INDENT_SIZE" value="2" />
+ <option name="CONTINUATION_INDENT_SIZE" value="2" />
+ <option name="TAB_SIZE" value="2" />
+ </indentOptions>
+ </codeStyleSettings>
+ <codeStyleSettings language="protobuf">
+ <option name="RIGHT_MARGIN" value="80" />
+ <indentOptions>
+ <option name="INDENT_SIZE" value="2" />
+ <option name="CONTINUATION_INDENT_SIZE" value="2" />
+ <option name="TAB_SIZE" value="2" />
+ </indentOptions>
+ </codeStyleSettings>
+ <codeStyleSettings language="Python">
+ <option name="KEEP_BLANK_LINES_IN_CODE" value="1" />
+ <option name="RIGHT_MARGIN" value="80" />
+ <option name="ALIGN_MULTILINE_PARAMETERS" value="false" />
+ <option name="PARENT_SETTINGS_INSTALLED" value="true" />
+ <indentOptions>
+ <option name="INDENT_SIZE" value="2" />
+ <option name="CONTINUATION_INDENT_SIZE" value="4" />
+ <option name="TAB_SIZE" value="2" />
+ </indentOptions>
+ </codeStyleSettings>
+ <codeStyleSettings language="SASS">
+ <indentOptions>
+ <option name="CONTINUATION_INDENT_SIZE" value="4" />
+ <option name="TAB_SIZE" value="2" />
+ </indentOptions>
+ </codeStyleSettings>
+ <codeStyleSettings language="SCSS">
+ <indentOptions>
+ <option name="CONTINUATION_INDENT_SIZE" value="4" />
+ <option name="TAB_SIZE" value="2" />
+ </indentOptions>
+ </codeStyleSettings>
+ <codeStyleSettings language="TypeScript">
+ <indentOptions>
+ <option name="INDENT_SIZE" value="2" />
+ <option name="TAB_SIZE" value="2" />
+ </indentOptions>
+ </codeStyleSettings>
+ <codeStyleSettings language="XML">
+ <indentOptions>
+ <option name="INDENT_SIZE" value="2" />
+ <option name="CONTINUATION_INDENT_SIZE" value="2" />
+ <option name="TAB_SIZE" value="2" />
+ </indentOptions>
+ <arrangement>
+ <rules>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>xmlns:android</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>^$</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>xmlns:.*</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>^$</XML_NAMESPACE>
+ </AND>
+ </match>
+ <order>BY_NAME</order>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:id</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>style</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>^$</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>^$</XML_NAMESPACE>
+ </AND>
+ </match>
+ <order>BY_NAME</order>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:.*Style</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ <order>BY_NAME</order>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:layout_width</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:layout_height</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:layout_weight</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:layout_margin</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:layout_marginTop</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:layout_marginBottom</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:layout_marginStart</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:layout_marginEnd</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:layout_marginLeft</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:layout_marginRight</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:layout_.*</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ <order>BY_NAME</order>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:padding</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:paddingTop</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:paddingBottom</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:paddingStart</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:paddingEnd</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:paddingLeft</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*:paddingRight</NAME>
+ <XML_ATTRIBUTE />
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*</NAME>
+ <XML_NAMESPACE>http://schemas.android.com/apk/res/android</XML_NAMESPACE>
+ </AND>
+ </match>
+ <order>BY_NAME</order>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*</NAME>
+ <XML_NAMESPACE>http://schemas.android.com/apk/res-auto</XML_NAMESPACE>
+ </AND>
+ </match>
+ <order>BY_NAME</order>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*</NAME>
+ <XML_NAMESPACE>http://schemas.android.com/tools</XML_NAMESPACE>
+ </AND>
+ </match>
+ <order>BY_NAME</order>
+ </rule>
+ </section>
+ <section>
+ <rule>
+ <match>
+ <AND>
+ <NAME>.*</NAME>
+ <XML_NAMESPACE>.*</XML_NAMESPACE>
+ </AND>
+ </match>
+ <order>BY_NAME</order>
+ </rule>
+ </section>
+ </rules>
+ </arrangement>
+ </codeStyleSettings>
+ <Objective-C>
+ <option name="INDENT_NAMESPACE_MEMBERS" value="0" />
+ <option name="INDENT_C_STRUCT_MEMBERS" value="2" />
+ <option name="INDENT_CLASS_MEMBERS" value="2" />
+ <option name="INDENT_VISIBILITY_KEYWORDS" value="1" />
+ <option name="INDENT_INSIDE_CODE_BLOCK" value="2" />
+ <option name="KEEP_STRUCTURES_IN_ONE_LINE" value="true" />
+ <option name="FUNCTION_PARAMETERS_WRAP" value="5" />
+ <option name="FUNCTION_CALL_ARGUMENTS_WRAP" value="5" />
+ <option name="TEMPLATE_CALL_ARGUMENTS_WRAP" value="5" />
+ <option name="TEMPLATE_CALL_ARGUMENTS_ALIGN_MULTILINE" value="true" />
+ <option name="ALIGN_INIT_LIST_IN_COLUMNS" value="false" />
+ <option name="SPACE_BEFORE_SUPERCLASS_COLON" value="false" />
+ </Objective-C>
+ <Objective-C-extensions>
+ <option name="GENERATE_INSTANCE_VARIABLES_FOR_PROPERTIES" value="ASK" />
+ <option name="RELEASE_STYLE" value="IVAR" />
+ <option name="TYPE_QUALIFIERS_PLACEMENT" value="BEFORE" />
+ <file>
+ <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Import" />
+ <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Macro" />
+ <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Typedef" />
+ <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Enum" />
+ <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Constant" />
+ <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Global" />
+ <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Struct" />
+ <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="FunctionPredecl" />
+ <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Function" />
+ </file>
+ <class>
+ <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Property" />
+ <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="Synthesize" />
+ <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="InitMethod" />
+ <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="StaticMethod" />
+ <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="InstanceMethod" />
+ <option name="com.jetbrains.cidr.lang.util.OCDeclarationKind" value="DeallocMethod" />
+ </class>
+ <extensions>
+ <pair source="cc" header="h" />
+ <pair source="c" header="h" />
+ </extensions>
+ </Objective-C-extensions>
+ <codeStyleSettings language="ObjectiveC">
+ <option name="RIGHT_MARGIN" value="80" />
+ <option name="KEEP_BLANK_LINES_BEFORE_RBRACE" value="1" />
+ <option name="BLANK_LINES_BEFORE_IMPORTS" value="0" />
+ <option name="BLANK_LINES_AFTER_IMPORTS" value="0" />
+ <option name="BLANK_LINES_AROUND_CLASS" value="0" />
+ <option name="BLANK_LINES_AROUND_METHOD" value="0" />
+ <option name="BLANK_LINES_AROUND_METHOD_IN_INTERFACE" value="0" />
+ <option name="ALIGN_MULTILINE_BINARY_OPERATION" value="false" />
+ <option name="BINARY_OPERATION_SIGN_ON_NEXT_LINE" value="true" />
+ <option name="FOR_STATEMENT_WRAP" value="1" />
+ <option name="ASSIGNMENT_WRAP" value="1" />
+ <indentOptions>
+ <option name="INDENT_SIZE" value="2" />
+ <option name="CONTINUATION_INDENT_SIZE" value="4" />
+ </indentOptions>
+ </codeStyleSettings>
+</code_scheme>
diff --git a/javaguide.css b/javaguide.css
new file mode 100644
index 0000000..10cd730
--- /dev/null
+++ b/javaguide.css
@@ -0,0 +1,572 @@
+table {
+ border-collapse: collapse;
+}
+
+td, th {
+ border: 1px solid #ccc;
+ padding: 2px 12px;
+ font-size: 10pt;
+}
+
+code, samp, var {
+ color: #060;
+}
+
+pre {
+ font-size: 10pt;
+ display: block;
+ color: #060;
+ background-color: #e8fff6;
+ border-color: #f0fff0;
+ border-style: solid;
+ border-top-width: 1px;
+ border-bottom-width: 1px;
+ border-right-width: 1px;
+ border-left-width: 5px;
+ padding-left: 12px;
+ padding-right: 12px;
+ padding-top: 4px;
+ padding-bottom: 4px;
+}
+
+pre.badcode {
+ color: #c00;
+ background-color: #ffe6d8;
+ border-color: #fff0f0;
+}
+
+hr {
+ margin-top: 3.5em;
+ border-width: 1px;
+ color: #fff;
+}
+
+html {
+ margin-top:2em;
+ margin-left:10%;
+ margin-right:10%;
+ padding:0;
+}
+
+.bp-reset-element,
+body,
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+article,
+aside,
+details,
+figcaption,
+figure,
+footer,
+header,
+hgroup,
+menu,
+nav,
+section,
+summary,
+blockquote,
+q,
+th,
+td,
+caption,
+table,
+div,
+span,
+object,
+iframe,
+p,
+pre,
+a,
+abbr,
+acronym,
+address,
+code,
+del,
+dfn,
+em,
+img,
+dl,
+dt,
+dd,
+ol,
+ul,
+li,
+fieldset,
+form,
+label,
+legend,
+caption,
+tbody,
+tfoot,
+thead,
+tr {
+ margin:0;
+ padding:0;
+ border:0;
+ font-weight:inherit;
+ font-style:inherit;
+ font-size:100%;
+ font-family:inherit;
+ vertical-align:baseline;
+}
+
+body {
+ font-family:'Arial', sans-serif;
+ font-size:81.25%;
+ color:#222;
+ background-color:#fff;
+ line-height:1.67;
+ overflow: auto;
+}
+
+.change {
+ text-align: right;
+ margin-bottom:1em;
+}
+
+em {
+ font-style: italic
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+ font-weight:bold;
+}
+
+h1 {
+ margin-bottom:.50em;
+ text-align: center
+}
+
+h2,
+h3,
+h4,
+h5,
+h6 {
+ margin-top:1.5em;
+ margin-bottom:.75em;
+}
+
+h1 {font-size:200%;}
+h2 {font-size:167%;}
+h3 {font-size:133%;}
+h4 {font-size:120%;}
+h5 {font-size:110%;}
+
+p {
+ margin:0 0 1.5em;
+}
+
+a[href=''] {
+ cursor:default;
+}
+
+h1 img,
+h2 img,
+h3 img,
+h4 img,
+h5 img,
+h6 img {
+ margin:0;
+}
+
+a img {
+ border:none;
+}
+
+pre {
+ margin:1.5em 0;
+ white-space:pre;
+}
+
+pre,
+code,
+kbd,
+tt {
+ font:1em 'Droid Sans Mono', monospace;
+ line-height:1.5;
+}
+
+dl {
+ margin:0 0 1.5em 0;
+}
+
+dl dt {
+ font-weight:bold;
+}
+
+dd {
+ margin-left:1.5em;
+}
+
+dd.toc3 {
+ margin-left:3em;
+}
+
+hr {
+ height:0;
+ border:0;
+ border-top:1px solid #ccc;
+ background-color:#ccc;
+}
+
+table {
+ border:1px solid #bbb;
+ border-spacing:0;
+ border-collapse:collapse;
+ margin:0 0 1.5em;
+ vertical-align:middle;
+ width:100%;
+}
+
+table.unlined,
+table.unlined th,
+table.unlined tr,
+table.unlined td {
+ border:0;
+}
+
+th,
+td,
+caption {
+ float:none !important;
+ text-align:left;
+ font-weight:normal;
+ vertical-align:middle;
+ padding:4px;
+}
+
+caption {
+ padding:0;
+}
+
+td {
+ border:1px solid #bbb;
+ vertical-align:top;
+}
+
+th {
+ border:0;
+ border-bottom:1px solid black;
+ font-weight:bold;
+ background:rgb(229, 236, 249);
+}
+
+table th code {
+ background-color:inherit;
+ color:inherit;
+}
+
+table tfoot th {
+ border:1px solid #bbb;
+}
+
+tfoot {
+ font-style:italic;
+}
+
+caption {
+ background:#eee;
+}
+
+table[border='0'] {
+ border:none;
+}
+
+table[border='0']>tbody>tr>td,
+table[border='0']>tr>td {
+ border:none;
+}
+
+tr.alt td,
+td.alt {
+ background-color:#efefef;
+}
+
+table.striped tr:nth-child(even) td,
+table tr.even td {
+ background:#efefef;
+}
+
+table.columns {
+ border:none;
+}
+
+table.columns>tbody>tr>td,
+table.columns>tr>td {
+ border:none;
+ padding:0 3em 0 0;
+}
+
+table.columns>tbody>tr>td:last-child,
+table.columns>tr>td:last-child {
+ border:none;
+ padding:0;
+}
+
+ul,
+ol {
+ margin:0 1.5em 1.5em 0;
+ padding-left:2em;
+}
+
+li ul,
+li ol {
+ margin:0;
+}
+
+ul {
+ list-style-type:disc;
+}
+
+ol {
+ list-style-type:decimal;
+}
+
+ul {
+ list-style-type:disc;
+}
+
+ul ul {
+ list-style-type:circle;
+}
+
+ul ul ul {
+ list-style-type:square;
+}
+
+ul.disc {
+ list-style-type:disc;
+}
+
+ul.circle {
+ list-style-type:circle;
+}
+
+ul.square {
+ list-style-type:square;
+}
+
+ol {
+ list-style-type:decimal;
+}
+
+ol ol {
+ list-style-type:lower-alpha;
+}
+
+ol ol ol {
+ list-style-type:lower-roman;
+}
+
+ol ul {
+ list-style-type:circle;
+}
+
+ol.decimal {
+ list-style-type:decimal;
+}
+
+ol.upper-alpha {
+ list-style-type:upper-alpha;
+}
+
+ol.lower-alpha {
+ list-style-type:lower-alpha;
+}
+
+ol.upper-roman {
+ list-style-type:upper-roman;
+}
+
+ol.lower-roman {
+ list-style-type:lower-roman;
+}
+
+ol.nolist,
+ul.nolist {
+ padding-left:0;
+ list-style-image:none;
+ list-style-type:none;
+ margin-left:0;
+}
+
+.center {
+ text-align:center;
+}
+
+code,
+kbd,
+pre {
+ color:#009900;
+}
+
+kbd {
+ font-weight: bold;
+}
+
+table.striped code {
+ background-color:inherit;
+}
+
+pre {
+ padding:6px 10px;
+ background-color:#FAFAFA;
+ border:1px solid #bbb;
+ overflow:auto;
+}
+
+pre.prettyprint {
+ padding:6px 10px !important;
+ border:1px solid #bbb !important;
+}
+
+code.bad, code.badcode {
+ color: magenta;
+}
+pre.bad, pre.badcode {
+ background-color:#ffe6d8;
+ border-top:1px inset #a03;
+ border-left:1px inset #a03;
+}
+
+.tip {
+ background-color:#fffbd9;
+ padding:6px 8px 6px 10px;
+ border-left:6px solid #ffef70;
+}
+
+.note {
+ background-color:#e5ecf9;
+ padding:6px 8px 6px 10px;
+ border-left:6px solid #36c;
+}
+
+@media print {
+
+ .str {
+ color:#060;
+ }
+
+ .kwd {
+ color:#006;
+ font-weight:bold;
+ }
+
+ .com {
+ color:#600;
+ font-style:italic;
+ }
+
+ .typ {
+ color:#404;
+ font-weight:bold;
+ }
+
+ .lit {
+ color:#044;
+ }
+
+ .pun,
+ .opn,
+ .clo {
+ color:#440;
+ }
+
+ .pln {
+ color:#000;
+ }
+
+ .tag {
+ color:#006;
+ font-weight:bold;
+ }
+
+ .atn {
+ color:#404;
+ }
+
+ .atv {
+ color:#060;
+ }
+
+ h1 {
+ font-style:italic;
+ }
+}
+
+ol.linenums {
+ margin-top:0;
+ margin-bottom:0;
+}
+
+code {
+ background-color:#FAFAFA;
+ padding: 0.25em 0.5em;
+ white-space: nowrap
+}
+
+
+/* TOC CSS */
+
+table.columns {
+ border: none;
+}
+
+td.two_columns {
+ -webkit-column-count: 2;
+ column-count: 2;
+}
+
+.toc_category {
+ font-size: 10pt;
+ padding-top: 1em;
+ padding-bottom: 1em;
+ border-left-width: 2px;
+ border-right-width: 2px;
+ border-color: grey;
+}
+
+.toc_stylepoint {
+ font-size: 10pt;
+ padding-top: 1em;
+ padding-bottom: 1em;
+}
+
+li.toc_entry {
+ padding-right: 1em;
+ display: inline;
+ list-style-type: none;
+}
+
+/*
+ * This space is required to trigger the linewrap on the links
+ * at href boundaries
+ */
+li.toc_entry::after {
+ content: " ";
+ }
+
+li.toc_entry a {
+ white-space: nowrap;
+}
+
+/* Horizontal TOC */
+.toc td, .toc th {
+ border-width: 1px 5px;
+ overflow: hidden;
+}
+
+/* Vertical TOC */
+
+.toc td.two_columns {
+ border-width: 0px;
+}
diff --git a/javaguide.html b/javaguide.html
new file mode 100644
index 0000000..b171426
--- /dev/null
+++ b/javaguide.html
@@ -0,0 +1,1187 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta http-equiv="content-type" content="text/html; charset=UTF-8">
+<title>Google Java Style Guide</title>
+<link rel="stylesheet" type="text/css" href="javaguide.css">
+<script language="javascript" src="include/styleguide.js"></script>
+<link rel="shortcut icon" type="image/x-icon" href="https://www.google.com/favicon.ico" />
+<script src="https://cdn.rawgit.com/google/code-prettify/master/loader/run_prettify.js"></script>
+</head>
+<body onload="initStyleGuide();">
+<div id="content">
+<h1>Google Java Style Guide</h1>
+<div class="vertical_toc" id="tocDiv"></div>
+
+<div class="main_body">
+
+<h2 id="s1-introduction">1 Introduction</h2>
+
+<p>This document serves as the <strong>complete</strong> definition of Google's coding standards for
+source code in the Java™ Programming Language. A Java source file is described as being <em>in
+Google Style</em> if and only if it adheres to the rules herein.</p>
+
+<p>Like other programming style guides, the issues covered span not only aesthetic issues of
+formatting, but other types of conventions or coding standards as well. However, this document
+focuses primarily on the <strong>hard-and-fast rules</strong> that we follow universally, and
+avoids giving <em>advice</em> that isn't clearly enforceable (whether by human or tool).
+</p>
+
+
+
+<h3 id="s1.1-terminology">1.1 Terminology notes</h3>
+
+<p>In this document, unless otherwise clarified:</p>
+
+<ol>
+ <li>The term <em>class</em> is used inclusively to mean an "ordinary" class, enum class,
+ interface or annotation type (<code class="prettyprint lang-java">@interface</code>).</li>
+
+ <li>The term <em>member</em> (of a class) is used inclusively to mean a nested class, field,
+ method, <em>or constructor</em>; that is, all top-level contents of a class except initializers
+ and comments.
+
+ </li><li>The term <em>comment</em> always refers to <em>implementation</em> comments. We do not
+ use the phrase "documentation comments", instead using the common term "Javadoc."</li>
+</ol>
+
+<p>Other "terminology notes" will appear occasionally throughout the document.</p>
+
+<h3 id="s1.2-guide-notes">1.2 Guide notes</h3>
+
+<p>Example code in this document is <strong>non-normative</strong>. That is, while the examples
+are in Google Style, they may not illustrate the <em>only</em> stylish way to represent the
+code. Optional formatting choices made in examples should not be enforced as rules.</p>
+
+
+<h2 id="s2-source-file-basics">2 Source file basics</h2>
+
+<h3 id="s2.1-file-name">2.1 File name</h3>
+
+<p>The source file name consists of the case-sensitive name of the top-level class it contains
+(of which there is <a href="#s3.4.1-one-top-level-class">exactly one</a>), plus the
+<code>.java</code> extension.</p>
+
+<h3 id="s2.2-file-encoding">2.2 File encoding: UTF-8</h3>
+
+<p>Source files are encoded in <strong>UTF-8</strong>.</p>
+
+<h3 id="s2.3-special-characters">2.3 Special characters</h3>
+
+<h4 id="s2.3.1-whitespace-characters">2.3.1 Whitespace characters</h4>
+
+<p>Aside from the line terminator sequence, the <strong>ASCII horizontal space
+character</strong> (<strong>0x20</strong>) is the only whitespace character that appears
+anywhere in a source file. This implies that:</p>
+
+<ol>
+ <li>All other whitespace characters in string and character literals are escaped.</li>
+
+ <li>Tab characters are <strong>not</strong> used for indentation.</li>
+</ol>
+
+<h4 id="s2.3.2-special-escape-sequences">2.3.2 Special escape sequences</h4>
+
+<p>For any character that has a
+<a href="http://docs.oracle.com/javase/tutorial/java/data/characters.html">
+ special escape sequence</a>
+(<code class="prettyprint lang-java">\b</code>,
+<code class="prettyprint lang-java">\t</code>,
+<code class="prettyprint lang-java">\n</code>,
+<code class="prettyprint lang-java">\f</code>,
+<code class="prettyprint lang-java">\r</code>,
+<code class="prettyprint lang-java">\"</code>,
+<code class="prettyprint lang-java">\'</code> and
+<code class="prettyprint lang-java">\\</code>), that sequence
+is used rather than the corresponding octal
+(e.g. <code class="badcode">\012</code>) or Unicode
+(e.g. <code class="badcode">\u000a</code>) escape.</p>
+
+<h4 id="s2.3.3-non-ascii-characters">2.3.3 Non-ASCII characters</h4>
+
+<p>For the remaining non-ASCII characters, either the actual Unicode character
+(e.g. <code class="prettyprint lang-java">∞</code>) or the equivalent Unicode escape
+(e.g. <code class="prettyprint lang-java">\u221e</code>) is used. The choice depends only on
+which makes the code <strong>easier to read and understand</strong>, although Unicode escapes
+outside string literals and comments are strongly discouraged.</p>
+
+<p class="tip"><strong>Tip:</strong> In the Unicode escape case, and occasionally even when actual
+Unicode characters are used, an explanatory comment can be very helpful.</p>
+
+<p>Examples:</p>
+
+<table>
+ <tbody><tr>
+ <th>Example</th>
+ <th>Discussion</th>
+ </tr>
+
+ <tr>
+ <td><code class="prettyprint lang-java">String unitAbbrev = "μs";</code></td>
+ <td>Best: perfectly clear even without a comment.</td>
+ </tr>
+
+ <tr>
+ <td><code class="prettyprint lang-java">String unitAbbrev = "\u03bcs"; // "μs"</code></td>
+ <td>Allowed, but there's no reason to do this.</td>
+ </tr>
+
+ <tr>
+ <td><code class="prettyprint lang-java">String unitAbbrev = "\u03bcs";
+ // Greek letter mu, "s"</code></td>
+ <td>Allowed, but awkward and prone to mistakes.</td>
+ </tr>
+
+ <tr>
+ <td><code class="badcode">String unitAbbrev = "\u03bcs";</code></td>
+ <td>Poor: the reader has no idea what this is.</td>
+ </tr>
+
+ <tr>
+ <td><code class="prettyprint lang-java">return '\ufeff' + content;
+ // byte order mark</code></td>
+ <td>Good: use escapes for non-printable characters, and comment if necessary.</td>
+ </tr>
+</tbody></table>
+
+<p class="tip"><strong>Tip:</strong> Never make your code less readable simply out of fear that
+some programs might not handle non-ASCII characters properly. If that should happen, those
+programs are <strong>broken</strong> and they must be <strong>fixed</strong>.</p>
+
+
+<a name="filestructure"></a>
+<h2 id="s3-source-file-structure">3 Source file structure</h2>
+
+<div>
+<p>A source file consists of, <strong>in order</strong>:</p>
+
+<ol>
+ <li>License or copyright information, if present</li>
+ <li>Package statement</li>
+ <li>Import statements</li>
+ <li>Exactly one top-level class</li>
+</ol>
+</div>
+
+<p><strong>Exactly one blank line</strong> separates each section that is present.</p>
+
+<h3 id="s3.1-copyright-statement">3.1 License or copyright information, if present</h3>
+
+<p>If license or copyright information belongs in a file, it belongs here.</p>
+
+
+
+<h3 id="s3.2-package-statement">3.2 Package statement</h3>
+
+<p>The package statement is <strong>not line-wrapped</strong>. The column limit (Section 4.4,
+<a href="#s4.4-column-limit">Column limit: 100</a>) does not apply to package statements.</p>
+
+<a name="imports"></a>
+<h3 id="s3.3-import-statements">3.3 Import statements</h3>
+
+<h4 id="s3.3.1-wildcard-imports">3.3.1 No wildcard imports</h4>
+
+<p><strong>Wildcard imports</strong>, static or otherwise, <strong>are not used</strong>.</p>
+
+<h4 id="s3.3.2-import-line-wrapping">3.3.2 No line-wrapping</h4>
+
+<p>Import statements are <strong>not line-wrapped</strong>. The column limit (Section 4.4,
+<a href="#s4.4-column-limit">Column limit: 100</a>) does not apply to import
+statements.</p>
+
+<h4 id="s3.3.3-import-ordering-and-spacing">3.3.3 Ordering and spacing</h4>
+
+<p>Imports are ordered as follows:</p>
+
+<ol>
+ <li>All static imports in a single block.</li>
+ <li>All non-static imports in a single block.</li>
+</ol>
+
+<p>If there are both static and non-static imports, a single blank line separates the two
+blocks. There are no other blank lines between import statements.</p>
+
+<p>Within each block the imported names appear in ASCII sort order. (<strong>Note:</strong>
+this is not the same as the import <em>statements</em> being in ASCII sort order, since '.'
+sorts before ';'.)</p>
+
+
+
+<h4 id="s3.3.4-import-class-not-static">3.3.4 No static import for classes</h4>
+
+<p>Static import is not used for static nested classes. They are imported with
+normal imports.</p>
+
+<h3 id="s3.4-class-declaration">3.4 Class declaration</h3>
+
+<a name="oneclassperfile"></a>
+<h4 id="s3.4.1-one-top-level-class">3.4.1 Exactly one top-level class declaration</h4>
+
+<p>Each top-level class resides in a source file of its own.</p>
+
+<a name="s3.4.2-class-member-ordering"></a>
+<h4 id="s3.4.2-ordering-class-contents">3.4.2 Ordering of class contents</h4>
+
+<p>The order you choose for the members and initializers of your class can have a great effect on
+learnability. However, there's no single correct recipe for how to do it; different classes may
+order their contents in different ways.</p>
+
+<p>What is important is that each class uses <strong><em>some</em> logical order</strong>, which its
+maintainer could explain if asked. For example, new methods are not just habitually added to the end
+of the class, as that would yield "chronological by date added" ordering, which is not a logical
+ordering.</p>
+
+
+
+<a name="overloads"></a>
+<h5 id="s3.4.2.1-overloads-never-split">3.4.2.1 Overloads: never split</h5>
+
+<p>When a class has multiple constructors, or multiple methods with the same name, these appear
+sequentially, with no other code in between (not even private members).</p>
+
+<h2 id="s4-formatting">4 Formatting</h2>
+
+<p class="terminology"><strong>Terminology Note:</strong> <em>block-like construct</em> refers to
+the body of a class, method or constructor. Note that, by Section 4.8.3.1 on
+<a href="#s4.8.3.1-array-initializers">array initializers</a>, any array initializer
+<em>may</em> optionally be treated as if it were a block-like construct.</p>
+
+<a name="braces"></a>
+<h3 id="s4.1-braces">4.1 Braces</h3>
+
+<h4 id="s4.1.1-braces-always-used">4.1.1 Braces are used where optional</h4>
+
+<p>Braces are used with
+<code class="prettyprint lang-java">if</code>,
+<code class="prettyprint lang-java">else</code>,
+<code class="prettyprint lang-java">for</code>,
+<code class="prettyprint lang-java">do</code> and
+<code class="prettyprint lang-java">while</code> statements, even when the
+body is empty or contains only a single statement.</p>
+
+<h4 id="s4.1.2-blocks-k-r-style">4.1.2 Nonempty blocks: K & R style</h4>
+
+<p>Braces follow the Kernighan and Ritchie style
+("<a href="http://www.codinghorror.com/blog/2012/07/new-programming-jargon.html">Egyptian brackets</a>")
+for <em>nonempty</em> blocks and block-like constructs:</p>
+
+<ul>
+ <li>No line break before the opening brace.</li>
+
+ <li>Line break after the opening brace.</li>
+
+ <li>Line break before the closing brace.</li>
+
+ <li>Line break after the closing brace, <em>only if</em> that brace terminates a statement or
+ terminates the body of a method, constructor, or <em>named</em> class.
+ For example, there is <em>no</em> line break after the brace if it is followed by
+ <code class="prettyprint lang-java">else</code> or a comma.</li>
+</ul>
+
+<p>Examples:</p>
+
+<pre class="prettyprint lang-java">return () -> {
+ while (condition()) {
+ method();
+ }
+};
+
+return new MyClass() {
+ @Override public void method() {
+ if (condition()) {
+ try {
+ something();
+ } catch (ProblemException e) {
+ recover();
+ }
+ } else if (otherCondition()) {
+ somethingElse();
+ } else {
+ lastThing();
+ }
+ }
+};
+</pre>
+
+<p>A few exceptions for enum classes are given in Section 4.8.1,
+<a href="#s4.8.1-enum-classes">Enum classes</a>.</p>
+
+<a name="emptyblocks"></a>
+<h4 id="s4.1.3-braces-empty-blocks">4.1.3 Empty blocks: may be concise</h4>
+
+<p>An empty block or block-like construct may be in K & R style (as described in
+<a href="#s4.1.2-blocks-k-r-style">Section 4.1.2</a>). Alternatively, it may be closed immediately
+after it is opened, with no characters or line break in between
+(<code class="prettyprint lang-java">{}</code>), <strong>unless</strong> it is part of a
+<em>multi-block statement</em> (one that directly contains multiple blocks:
+<code class="prettyprint lang-java">if/else</code> or
+<code class="prettyprint lang-java">try/catch/finally</code>).</p>
+
+<p>Examples:</p>
+
+<pre class="prettyprint lang-java"> // This is acceptable
+ void doNothing() {}
+
+ // This is equally acceptable
+ void doNothingElse() {
+ }
+</pre>
+<pre class="prettyprint lang-java badcode"> // This is not acceptable: No concise empty blocks in a multi-block statement
+ try {
+ doSomething();
+ } catch (Exception e) {}
+</pre>
+
+<h3 id="s4.2-block-indentation">4.2 Block indentation: +2 spaces</h3>
+
+<p>Each time a new block or block-like construct is opened, the indent increases by two
+spaces. When the block ends, the indent returns to the previous indent level. The indent level
+applies to both code and comments throughout the block. (See the example in Section 4.1.2,
+<a href="#s4.1.2-blocks-k-r-style">Nonempty blocks: K & R Style</a>.)</p>
+
+<h3 id="s4.3-one-statement-per-line">4.3 One statement per line</h3>
+
+<p>Each statement is followed by a line break.</p>
+
+<a name="columnlimit"></a>
+<h3 id="s4.4-column-limit">4.4 Column limit: 100</h3>
+
+<p>Java code has a column limit of 100 characters. A "character" means any Unicode code point.
+Except as noted below, any line that would exceed this limit must be line-wrapped, as explained in
+Section 4.5, <a href="#s4.5-line-wrapping">Line-wrapping</a>.
+</p>
+
+<p class="tip">Each Unicode code point counts as one character, even if its display width is
+greater or less. For example, if using
+<a href="https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms">fullwidth characters</a>,
+you may choose to wrap the line earlier than where this rule strictly requires.</p>
+
+<p><strong>Exceptions:</strong></p>
+
+<ol>
+ <li>Lines where obeying the column limit is not possible (for example, a long URL in Javadoc,
+ or a long JSNI method reference).</li>
+
+ <li><code class="prettyprint lang-java">package</code> and
+ <code class="prettyprint lang-java">import</code> statements (see Sections
+ 3.2 <a href="#s3.2-package-statement">Package statement</a> and
+ 3.3 <a href="#s3.3-import-statements">Import statements</a>).</li>
+
+ <li>Command lines in a comment that may be cut-and-pasted into a shell.</li>
+</ol>
+
+<h3 id="s4.5-line-wrapping">4.5 Line-wrapping</h3>
+
+<p class="terminology"><strong>Terminology Note:</strong> When code that might otherwise legally
+occupy a single line is divided into multiple lines, this activity is called
+<em>line-wrapping</em>.</p>
+
+<p>There is no comprehensive, deterministic formula showing <em>exactly</em> how to line-wrap in
+every situation. Very often there are several valid ways to line-wrap the same piece of code.</p>
+
+<p class="note"><strong>Note:</strong> While the typical reason for line-wrapping is to avoid
+overflowing the column limit, even code that would in fact fit within the column limit <em>may</em>
+be line-wrapped at the author's discretion.</p>
+
+<p class="tip"><strong>Tip:</strong> Extracting a method or local variable may solve the problem
+without the need to line-wrap.</p>
+
+<h4 id="s4.5.1-line-wrapping-where-to-break">4.5.1 Where to break</h4>
+
+<p>The prime directive of line-wrapping is: prefer to break at a
+<strong>higher syntactic level</strong>. Also:</p>
+
+<ol>
+ <li>When a line is broken at a <em>non-assignment</em> operator the break comes <em>before</em>
+ the symbol. (Note that this is not the same practice used in Google style for other languages,
+ such as C++ and JavaScript.)
+ <ul>
+ <li>This also applies to the following "operator-like" symbols:
+ <ul>
+ <li>the dot separator (<code class="prettyprint lang-java">.</code>)</li>
+ <li>the two colons of a method reference
+ (<code class="prettyprint lang-java">::</code>)</li>
+ <li>an ampersand in a type bound
+ (<code class="prettyprint lang-java"><T extends Foo & Bar></code>)</li>
+ <li>a pipe in a catch block
+ (<code class="prettyprint lang-java">catch (FooException | BarException e)</code>).</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+
+ <li>When a line is broken at an <em>assignment</em> operator the break typically comes
+ <em>after</em> the symbol, but either way is acceptable.
+ <ul>
+ <li>This also applies to the "assignment-operator-like" colon in an enhanced
+ <code class="prettyprint lang-java">for</code> ("foreach") statement.</li>
+ </ul>
+ </li>
+
+ <li>A method or constructor name stays attached to the open parenthesis
+ (<code class="prettyprint lang-java">(</code>) that follows it.</li>
+
+ <li>A comma (<code class="prettyprint lang-java">,</code>) stays attached to the token that
+ precedes it.</li>
+
+ <li>A line is never broken adjacent to the arrow in a lambda, except that a
+ break may come immediately after the arrow if the body of the lambda consists
+ of a single unbraced expression. Examples:
+<pre class="prettyprint lang-java">MyLambda<String, Long, Object> lambda =
+ (String label, Long value, Object obj) -> {
+ ...
+ };
+
+Predicate<String> predicate = str ->
+ longExpressionInvolving(str);
+</pre>
+ </li>
+</ol>
+
+<p class="note"><strong>Note:</strong> The primary goal for line wrapping is to have clear
+code, <em>not necessarily</em> code that fits in the smallest number of lines.</p>
+
+<a name="indentation"></a>
+<h4 id="s4.5.2-line-wrapping-indent">4.5.2 Indent continuation lines at least +4 spaces</h4>
+
+<p>When line-wrapping, each line after the first (each <em>continuation line</em>) is indented
+at least +4 from the original line.</p>
+
+<p>When there are multiple continuation lines, indentation may be varied beyond +4 as
+desired. In general, two continuation lines use the same indentation level if and only if they
+begin with syntactically parallel elements.</p>
+
+<p>Section 4.6.3 on <a href="#s4.6.3-horizontal-alignment">Horizontal alignment</a> addresses
+the discouraged practice of using a variable number of spaces to align certain tokens with
+previous lines.</p>
+
+<h3 id="s4.6-whitespace">4.6 Whitespace</h3>
+
+<h4 id="s4.6.1-vertical-whitespace">4.6.1 Vertical Whitespace</h4>
+
+<p>A single blank line appears:</p>
+
+<ol>
+ <li><em>Between</em> consecutive members or initializers of a class: fields, constructors,
+ methods, nested classes, static initializers, and instance initializers.
+ <ul>
+ <li><span class="exception"><strong>Exception:</strong> A blank line between two consecutive
+ fields (having no other code between them) is optional. Such blank lines are used as needed to
+ create <em>logical groupings</em> of fields.</span></li>
+ <li><span class="exception"><strong>Exception:</strong> Blank lines between enum constants are
+ covered in <a href="#s4.8.1-enum-classes">Section 4.8.1</a>.</span></li>
+ </ul>
+ </li>
+
+ <li>Between statements, <em>as needed</em> to organize the code into logical subsections.
+
+ </li><li><em>Optionally</em> before the first member or initializer, or after the last member or
+ initializer of the class (neither encouraged nor discouraged).</li>
+
+ <li>As required by other sections of this document (such as Section 3,
+ <a href="#s3-source-file-structure">Source file structure</a>, and Section 3.3,
+ <a href="#s3.3-import-statements">Import statements</a>).</li>
+</ol>
+
+<p><em>Multiple</em> consecutive blank lines are permitted, but never required (or encouraged).</p>
+
+<h4 id="s4.6.2-horizontal-whitespace">4.6.2 Horizontal whitespace</h4>
+
+<p>Beyond where required by the language or other style rules, and apart from literals, comments and
+Javadoc, a single ASCII space also appears in the following places <strong>only</strong>.</p>
+
+<ol>
+ <li>Separating any reserved word, such as
+ <code class="prettyprint lang-java">if</code>,
+ <code class="prettyprint lang-java">for</code> or
+ <code class="prettyprint lang-java">catch</code>, from an open parenthesis
+ (<code class="prettyprint lang-java">(</code>)
+ that follows it on that line</li>
+
+ <li>Separating any reserved word, such as
+ <code class="prettyprint lang-java">else</code> or
+ <code class="prettyprint lang-java">catch</code>, from a closing curly brace
+ (<code class="prettyprint lang-java">}</code>) that precedes it on that line</li>
+
+ <li>Before any open curly brace
+ (<code class="prettyprint lang-java">{</code>), with two exceptions:
+ <ul>
+ <li><code class="prettyprint lang-java">@SomeAnnotation({a, b})</code> (no space is used)</li>
+
+ <li><code class="prettyprint lang-java">String[][] x = {{"foo"}};</code> (no space is required
+ between <code class="prettyprint lang-java">{{</code>, by item 8 below)</li>
+ </ul>
+ </li>
+
+ <li>On both sides of any binary or ternary operator. This also applies to the following
+ "operator-like" symbols:
+ <ul>
+ <li>the ampersand in a conjunctive type bound:
+ <code class="prettyprint lang-java"><T extends Foo & Bar></code></li>
+
+ <li>the pipe for a catch block that handles multiple exceptions:
+ <code class="prettyprint lang-java">catch (FooException | BarException e)</code></li>
+
+ <li>the colon (<code class="prettyprint lang-java">:</code>) in an enhanced
+ <code class="prettyprint lang-java">for</code> ("foreach") statement</li>
+
+ <li>the arrow in a lambda expression:
+ <code class="prettyprint lang-java">(String str) -> str.length()</code></li>
+ </ul>
+ but not
+
+ <ul>
+ <li>the two colons (<code class="prettyprint lang-java">::</code>) of a method reference, which
+ is written like <code class="prettyprint lang-java">Object::toString</code></li>
+ <li>the dot separator (<code class="prettyprint lang-java">.</code>), which is written like
+ <code class="prettyprint lang-java">object.toString()</code></li>
+ </ul>
+ </li>
+
+ <li>After <code class="prettyprint lang-java">,:;</code> or the closing parenthesis
+ (<code class="prettyprint lang-java">)</code>) of a cast</li>
+
+ <li>On both sides of the double slash (<code class="prettyprint lang-java">//</code>) that
+ begins an end-of-line comment. Here, multiple spaces are allowed, but not required.</li>
+
+ <li>Between the type and variable of a declaration:
+ <code class="prettyprint lang-java">List<String> list</code></li>
+
+ <li><em>Optional</em> just inside both braces of an array initializer
+ <ul>
+ <li><code class="prettyprint lang-java">new int[] {5, 6}</code> and
+ <code class="prettyprint lang-java">new int[] { 5, 6 }</code> are both valid</li>
+ </ul>
+ </li>
+</ol>
+
+This rule is never interpreted as requiring or forbidding additional space at the start or
+end of a line; it addresses only <em>interior</em> space.
+
+<h4 id="s4.6.3-horizontal-alignment">4.6.3 Horizontal alignment: never required</h4>
+
+<p class="terminology"><strong>Terminology Note:</strong> <em>Horizontal alignment</em> is the
+practice of adding a variable number of additional spaces in your code with the goal of making
+certain tokens appear directly below certain other tokens on previous lines.</p>
+
+<p>This practice is permitted, but is <strong>never required</strong> by Google Style. It is not
+even required to <em>maintain</em> horizontal alignment in places where it was already used.</p>
+
+<p>Here is an example without alignment, then using alignment:</p>
+
+<pre class="prettyprint lang-java">private int x; // this is fine
+private Color color; // this too
+
+private int x; // permitted, but future edits
+private Color color; // may leave it unaligned
+</pre>
+
+<p class="tip"><strong>Tip:</strong> Alignment can aid readability, but it creates problems for
+future maintenance. Consider a future change that needs to touch just one line. This change may
+leave the formerly-pleasing formatting mangled, and that is <strong>allowed</strong>. More often
+it prompts the coder (perhaps you) to adjust whitespace on nearby lines as well, possibly
+triggering a cascading series of reformattings. That one-line change now has a "blast radius."
+This can at worst result in pointless busywork, but at best it still corrupts version history
+information, slows down reviewers and exacerbates merge conflicts.</p>
+
+<a name="parentheses"></a>
+<h3 id="s4.7-grouping-parentheses">4.7 Grouping parentheses: recommended</h3>
+
+<p>Optional grouping parentheses are omitted only when author and reviewer agree that there is no
+reasonable chance the code will be misinterpreted without them, nor would they have made the code
+easier to read. It is <em>not</em> reasonable to assume that every reader has the entire Java
+operator precedence table memorized.</p>
+
+<h3 id="s4.8-specific-constructs">4.8 Specific constructs</h3>
+
+<h4 id="s4.8.1-enum-classes">4.8.1 Enum classes</h4>
+
+<p>After each comma that follows an enum constant, a line break is optional. Additional blank
+lines (usually just one) are also allowed. This is one possibility:
+
+</p><pre class="prettyprint lang-java">private enum Answer {
+ YES {
+ @Override public String toString() {
+ return "yes";
+ }
+ },
+
+ NO,
+ MAYBE
+}
+</pre>
+
+<p>An enum class with no methods and no documentation on its constants may optionally be formatted
+as if it were an array initializer (see Section 4.8.3.1 on
+<a href="#s4.8.3.1-array-initializers">array initializers</a>).</p>
+
+<pre class="prettyprint lang-java">private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }
+</pre>
+
+<p>Since enum classes <em>are classes</em>, all other rules for formatting classes apply.</p>
+
+<a name="localvariables"></a>
+<h4 id="s4.8.2-variable-declarations">4.8.2 Variable declarations</h4>
+
+<h5 id="s4.8.2.1-variables-per-declaration">4.8.2.1 One variable per declaration</h5>
+
+<p>Every variable declaration (field or local) declares only one variable: declarations such as
+<code class="badcode">int a, b;</code> are not used.</p>
+
+<p><strong>Exception:</strong> Multiple variable declarations are acceptable in the header of a
+<code class="prettyprint lang-java">for</code> loop.</p>
+
+<h5 id="s4.8.2.2-variables-limited-scope">4.8.2.2 Declared when needed</h5>
+
+<p>Local variables are <strong>not</strong> habitually declared at the start of their containing
+block or block-like construct. Instead, local variables are declared close to the point they are
+first used (within reason), to minimize their scope. Local variable declarations typically have
+initializers, or are initialized immediately after declaration.</p>
+
+<h4 id="s4.8.3-arrays">4.8.3 Arrays</h4>
+
+<h5 id="s4.8.3.1-array-initializers">4.8.3.1 Array initializers: can be "block-like"</h5>
+
+<p>Any array initializer may <em>optionally</em> be formatted as if it were a "block-like
+construct." For example, the following are all valid (<strong>not</strong> an exhaustive
+list):</p>
+
+<pre class="prettyprint lang-java">new int[] { new int[] {
+ 0, 1, 2, 3 0,
+} 1,
+ 2,
+new int[] { 3,
+ 0, 1, }
+ 2, 3
+} new int[]
+ {0, 1, 2, 3}
+</pre>
+
+<h5 id="s4.8.3.2-array-declarations">4.8.3.2 No C-style array declarations</h5>
+
+<p>The square brackets form a part of the <em>type</em>, not the variable:
+<code class="prettyprint lang-java">String[] args</code>, not
+<code class="badcode">String args[]</code>.</p>
+
+<h4 id="s4.8.4-switch">4.8.4 Switch statements</h4>
+
+
+
+<p class="terminology"><strong>Terminology Note:</strong> Inside the braces of a
+<em>switch block</em> are one or more <em>statement groups</em>. Each statement group consists of
+one or more <em>switch labels</em> (either <code class="prettyprint lang-java">case FOO:</code> or
+<code class="prettyprint lang-java">default:</code>), followed by one or more statements (or, for
+the <em>last</em> statement group, <em>zero</em> or more statements).</p>
+
+<h5 id="s4.8.4.1-switch-indentation">4.8.4.1 Indentation</h5>
+
+<p>As with any other block, the contents of a switch block are indented +2.</p>
+
+<p>After a switch label, there is a line break, and the indentation level is increased +2, exactly
+as if a block were being opened. The following switch label returns to the previous indentation
+level, as if a block had been closed.</p>
+
+<a name="fallthrough"></a>
+<h5 id="s4.8.4.2-switch-fall-through">4.8.4.2 Fall-through: commented</h5>
+
+<p>Within a switch block, each statement group either terminates abruptly (with a
+<code class="prettyprint lang-java">break</code>,
+<code class="prettyprint lang-java">continue</code>,
+<code class="prettyprint lang-java">return</code> or thrown exception), or is marked with a comment
+to indicate that execution will or <em>might</em> continue into the next statement group. Any
+comment that communicates the idea of fall-through is sufficient (typically
+<code class="prettyprint lang-java">// fall through</code>). This special comment is not required in
+the last statement group of the switch block. Example:</p>
+
+<pre class="prettyprint lang-java">switch (input) {
+ case 1:
+ case 2:
+ prepareOneOrTwo();
+ // fall through
+ case 3:
+ handleOneTwoOrThree();
+ break;
+ default:
+ handleLargeNumber(input);
+}
+</pre>
+
+<p>Notice that no comment is needed after <code class="prettyprint lang-java">case 1:</code>, only
+at the end of the statement group.</p>
+
+<h5 id="s4.8.4.3-switch-default">4.8.4.3 The <code>default</code> case is present</h5>
+
+<p>Each switch statement includes a <code class="prettyprint lang-java">default</code> statement
+group, even if it contains no code.</p>
+
+<p><strong>Exception:</strong> A switch statement for an <code>enum</code> type <em>may</em> omit
+the <code class="prettyprint lang-java">default</code> statement group, <em>if</em> it includes
+explicit cases covering <em>all</em> possible values of that type. This enables IDEs or other static
+analysis tools to issue a warning if any cases were missed.
+
+</p>
+
+<a name="annotations"></a>
+<h4 id="s4.8.5-annotations">4.8.5 Annotations</h4>
+
+<p>Annotations applying to a class, method or constructor appear immediately after the
+documentation block, and each annotation is listed on a line of its own (that is, one annotation
+per line). These line breaks do not constitute line-wrapping (Section
+4.5, <a href="#s4.5-line-wrapping">Line-wrapping</a>), so the indentation level is not
+increased. Example:</p>
+
+<pre class="prettyprint lang-java">@Override
+@Nullable
+public String getNameIfPresent() { ... }
+</pre>
+
+<p class="exception"><strong>Exception:</strong> A <em>single</em> parameterless annotation
+<em>may</em> instead appear together with the first line of the signature, for example:</p>
+
+<pre class="prettyprint lang-java">@Override public int hashCode() { ... }
+</pre>
+
+<p>Annotations applying to a field also appear immediately after the documentation block, but in
+this case, <em>multiple</em> annotations (possibly parameterized) may be listed on the same line;
+for example:</p>
+
+<pre class="prettyprint lang-java">@Partial @Mock DataLoader loader;
+</pre>
+
+<p>There are no specific rules for formatting annotations on parameters, local variables, or types.
+</p>
+
+<a name="comments"></a>
+<h4 id="s4.8.6-comments">4.8.6 Comments</h4>
+
+<p>This section addresses <em>implementation comments</em>. Javadoc is addressed separately in
+Section 7, <a href="#s7-javadoc">Javadoc</a>.</p>
+
+<p>Any line break may be preceded by arbitrary whitespace followed by an implementation comment.
+Such a comment renders the line non-blank.</p>
+
+<h5 id="s4.8.6.1-block-comment-style">4.8.6.1 Block comment style</h5>
+
+<p>Block comments are indented at the same level as the surrounding code. They may be in
+<code class="prettyprint lang-java">/* ... */</code> style or
+<code class="prettyprint lang-java">// ...</code> style. For multi-line
+<code class="prettyprint lang-java">/* ... */</code> comments, subsequent lines must start with
+<code>*</code> aligned with the <code>*</code> on the previous line.</p>
+
+<pre class="prettyprint lang-java">/*
+ * This is // And so /* Or you can
+ * okay. // is this. * even do this. */
+ */
+</pre>
+
+
+<p>Comments are not enclosed in boxes drawn with asterisks or other characters.</p>
+
+<p class="tip"><strong>Tip:</strong> When writing multi-line comments, use the
+<code class="prettyprint lang-java">/* ... */</code> style if you want automatic code formatters to
+re-wrap the lines when necessary (paragraph-style). Most formatters don't re-wrap lines in
+<code class="prettyprint lang-java">// ...</code> style comment blocks.</p>
+
+
+
+<a name="modifiers"></a>
+<h4 id="s4.8.7-modifiers">4.8.7 Modifiers</h4>
+
+<p>Class and member modifiers, when present, appear in the order
+recommended by the Java Language Specification:
+</p>
+
+<pre>public protected private abstract default static final transient volatile synchronized native strictfp
+</pre>
+
+<h4 id="s4.8.8-numeric-literals">4.8.8 Numeric Literals</h4>
+
+<p><code>long</code>-valued integer literals use an uppercase <code>L</code> suffix, never
+lowercase (to avoid confusion with the digit <code>1</code>). For example, <code>3000000000L</code>
+rather than <code class="badcode">3000000000l</code>.</p>
+
+<a name="naming"></a>
+<h2 id="s5-naming">5 Naming</h2>
+
+<h3 id="s5.1-identifier-names">5.1 Rules common to all identifiers</h3>
+
+<p>Identifiers use only ASCII letters and digits, and, in a small number of cases noted below,
+underscores. Thus each valid identifier name is matched by the regular expression
+<code>\w+</code> .</p>
+
+<p>In Google Style special prefixes or
+suffixes, like those seen in the examples <code class="badcode">name_</code>,
+<code class="badcode">mName</code>, <code class="badcode">s_name</code> and
+<code class="badcode">kName</code>, are <strong>not</strong> used.</p>
+
+<h3 id="s5.2-specific-identifier-names">5.2 Rules by identifier type</h3>
+
+<h4 id="s5.2.1-package-names">5.2.1 Package names</h4>
+
+<p>Package names are all lowercase, with consecutive words simply concatenated together (no
+underscores). For example, <code>com.example.deepspace</code>, not
+<code class="badcode">com.example.deepSpace</code> or
+<code class="badcode">com.example.deep_space</code>.</p>
+
+<h4 id="s5.2.2-class-names">5.2.2 Class names</h4>
+
+<p>Class names are written in <a href="#s5.3-camel-case">UpperCamelCase</a>.</p>
+
+<p>Class names are typically nouns or noun phrases. For example,
+<code class="prettyprint lang-java">Character</code> or
+<code class="prettyprint lang-java">ImmutableList</code>. Interface names may also be nouns or
+noun phrases (for example, <code class="prettyprint lang-java">List</code>), but may sometimes be
+adjectives or adjective phrases instead (for example,
+<code class="prettyprint lang-java">Readable</code>).</p>
+
+<p>There are no specific rules or even well-established conventions for naming annotation types.</p>
+
+<p><em>Test</em> classes are named starting with the name of the class they are testing, and ending
+with <code class="prettyprint lang-java">Test</code>. For example,
+<code class="prettyprint lang-java">HashTest</code> or
+<code class="prettyprint lang-java">HashIntegrationTest</code>.</p>
+
+<h4 id="s5.2.3-method-names">5.2.3 Method names</h4>
+
+<p>Method names are written in <a href="#s5.3-camel-case">lowerCamelCase</a>.</p>
+
+<p>Method names are typically verbs or verb phrases. For example,
+<code class="prettyprint lang-java">sendMessage</code> or
+<code class="prettyprint lang-java">stop</code>.</p>
+
+<p>Underscores may appear in JUnit <em>test</em> method names to separate logical components of the
+name, with <em>each</em> component written in <a href="#s5.3-camel-case">lowerCamelCase</a>.
+One typical pattern is <code><i><methodUnderTest></i>_<i><state></i></code>,
+for example <code class="prettyprint lang-java">pop_emptyStack</code>. There is no One Correct
+Way to name test methods.</p>
+
+<a name="constants"></a>
+<h4 id="s5.2.4-constant-names">5.2.4 Constant names</h4>
+
+<p>Constant names use <code class="prettyprint lang-java">CONSTANT_CASE</code>: all uppercase
+letters, with each word separated from the next by a single underscore. But what <em>is</em> a
+constant, exactly?</p>
+
+<p>Constants are static final fields whose contents are deeply immutable and whose methods have no
+detectable side effects. This includes primitives, Strings, immutable types, and immutable
+collections of immutable types. If any of the instance's observable state can change, it is not a
+constant. Merely <em>intending</em> to never mutate the object is not enough. Examples:</p>
+
+<pre class="prettyprint lang-java">// Constants
+static final int NUMBER = 5;
+static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
+static final ImmutableMap<String, Integer> AGES = ImmutableMap.of("Ed", 35, "Ann", 32);
+static final Joiner COMMA_JOINER = Joiner.on(','); // because Joiner is immutable
+static final SomeMutableType[] EMPTY_ARRAY = {};
+enum SomeEnum { ENUM_CONSTANT }
+
+// Not constants
+static String nonFinal = "non-final";
+final String nonStatic = "non-static";
+static final Set<String> mutableCollection = new HashSet<String>();
+static final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable);
+static final ImmutableMap<String, SomeMutableType> mutableValues =
+ ImmutableMap.of("Ed", mutableInstance, "Ann", mutableInstance2);
+static final Logger logger = Logger.getLogger(MyClass.getName());
+static final String[] nonEmptyArray = {"these", "can", "change"};
+</pre>
+
+<p>These names are typically nouns or noun phrases.</p>
+
+<h4 id="s5.2.5-non-constant-field-names">5.2.5 Non-constant field names</h4>
+
+<p>Non-constant field names (static or otherwise) are written
+in <a href="#s5.3-camel-case">lowerCamelCase</a>.</p>
+
+<p>These names are typically nouns or noun phrases. For example,
+<code class="prettyprint lang-java">computedValues</code> or
+<code class="prettyprint lang-java">index</code>.</p>
+
+<h4 id="s5.2.6-parameter-names">5.2.6 Parameter names</h4>
+
+<p>Parameter names are written in <a href="#s5.3-camel-case">lowerCamelCase</a>.</p>
+
+<p>One-character parameter names in public methods should be avoided.</p>
+
+<h4 id="s5.2.7-local-variable-names">5.2.7 Local variable names</h4>
+
+<p>Local variable names are written in <a href="#s5.3-camel-case">lowerCamelCase</a>.</p>
+
+<p>Even when final and immutable, local variables are not considered to be constants, and should not
+be styled as constants.</p>
+
+<h4 id="s5.2.8-type-variable-names">5.2.8 Type variable names</h4>
+
+<p>Each type variable is named in one of two styles:</p>
+
+<ul>
+ <li>A single capital letter, optionally followed by a single numeral (such as
+ <code class="prettyprint lang-java">E</code>, <code class="prettyprint lang-java">T</code>,
+ <code class="prettyprint lang-java">X</code>, <code class="prettyprint lang-java">T2</code>)
+ </li>
+
+ <li>A name in the form used for classes (see Section 5.2.2,
+ <a href="#s5.2.2-class-names">Class names</a>), followed by the capital letter
+ <code class="prettyprint lang-java">T</code> (examples:
+ <code class="prettyprint lang-java">RequestT</code>,
+ <code class="prettyprint lang-java">FooBarT</code>).</li>
+</ul>
+
+<a name="acronyms"></a>
+<a name="camelcase"></a>
+<h3 id="s5.3-camel-case">5.3 Camel case: defined</h3>
+
+<p>Sometimes there is more than one reasonable way to convert an English phrase into camel case,
+such as when acronyms or unusual constructs like "IPv6" or "iOS" are present. To improve
+predictability, Google Style specifies the following (nearly) deterministic scheme.</p>
+
+<p>Beginning with the prose form of the name:</p>
+
+<ol>
+ <li>Convert the phrase to plain ASCII and remove any apostrophes. For example, "Müller's
+ algorithm" might become "Muellers algorithm".</li>
+
+ <li>Divide this result into words, splitting on spaces and any remaining punctuation (typically
+ hyphens).
+
+ <ul>
+ <li><em>Recommended:</em> if any word already has a conventional camel-case appearance in common
+ usage, split this into its constituent parts (e.g., "AdWords" becomes "ad words"). Note
+ that a word such as "iOS" is not really in camel case <em>per se</em>; it defies <em>any</em>
+ convention, so this recommendation does not apply.</li>
+ </ul>
+ </li>
+
+ <li>Now lowercase <em>everything</em> (including acronyms), then uppercase only the first
+ character of:
+ <ul>
+ <li>... each word, to yield <em>upper camel case</em>, or</li>
+ <li>... each word except the first, to yield <em>lower camel case</em></li>
+ </ul>
+ </li>
+
+ <li>Finally, join all the words into a single identifier.</li>
+</ol>
+
+<p>Note that the casing of the original words is almost entirely disregarded. Examples:</p>
+
+<table>
+ <tbody><tr>
+ <th>Prose form</th>
+ <th>Correct</th>
+ <th>Incorrect</th>
+ </tr>
+ <tr>
+ <td>"XML HTTP request"</td>
+ <td><code class="prettyprint lang-java">XmlHttpRequest</code></td>
+ <td><code class="badcode">XMLHTTPRequest</code></td>
+ </tr>
+ <tr>
+ <td>"new customer ID"</td>
+ <td><code class="prettyprint lang-java">newCustomerId</code></td>
+ <td><code class="badcode">newCustomerID</code></td>
+ </tr>
+ <tr>
+ <td>"inner stopwatch"</td>
+ <td><code class="prettyprint lang-java">innerStopwatch</code></td>
+ <td><code class="badcode">innerStopWatch</code></td>
+ </tr>
+ <tr>
+ <td>"supports IPv6 on iOS?"</td>
+ <td><code class="prettyprint lang-java">supportsIpv6OnIos</code></td>
+ <td><code class="badcode">supportsIPv6OnIOS</code></td>
+ </tr>
+ <tr>
+ <td>"YouTube importer"</td>
+ <td><code class="prettyprint lang-java">YouTubeImporter</code><br>
+ <code class="prettyprint lang-java">YoutubeImporter</code>*</td>
+ <td></td>
+ </tr>
+</tbody></table>
+
+<p>*Acceptable, but not recommended.</p>
+
+<p class="note"><strong>Note:</strong> Some words are ambiguously hyphenated in the English
+language: for example "nonempty" and "non-empty" are both correct, so the method names
+<code class="prettyprint lang-java">checkNonempty</code> and
+<code class="prettyprint lang-java">checkNonEmpty</code> are likewise both correct.</p>
+
+
+<h2 id="s6-programming-practices">6 Programming Practices</h2>
+
+<h3 id="s6.1-override-annotation">6.1 <code>@Override</code>: always used</h3>
+
+<p>A method is marked with the <code class="prettyprint lang-java">@Override</code> annotation
+whenever it is legal. This includes a class method overriding a superclass method, a class method
+implementing an interface method, and an interface method respecifying a superinterface
+method.</p>
+
+<p class="exception"><strong>Exception:</strong>
+<code class="prettyprint lang-java">@Override</code> may be omitted when the parent method is
+<code class="prettyprint lang-java">@Deprecated</code>.</p>
+
+<a name="caughtexceptions"></a>
+<h3 id="s6.2-caught-exceptions">6.2 Caught exceptions: not ignored</h3>
+
+<p>Except as noted below, it is very rarely correct to do nothing in response to a caught
+exception. (Typical responses are to log it, or if it is considered "impossible", rethrow it as an
+<code class="prettyprint lang-java">AssertionError</code>.)</p>
+
+<p>When it truly is appropriate to take no action whatsoever in a catch block, the reason this is
+justified is explained in a comment.</p>
+
+<pre class="prettyprint lang-java">try {
+ int i = Integer.parseInt(response);
+ return handleNumericResponse(i);
+} catch (NumberFormatException ok) {
+ // it's not numeric; that's fine, just continue
+}
+return handleTextResponse(response);
+</pre>
+
+<p class="exception"><strong>Exception:</strong> In tests, a caught exception may be ignored
+without comment <em>if</em> its name is or begins with <code class="prettyprint lang-java">expected</code>. The
+following is a very common idiom for ensuring that the code under test <em>does</em> throw an
+exception of the expected type, so a comment is unnecessary here.</p>
+
+<pre class="prettyprint lang-java">try {
+ emptyStack.pop();
+ fail();
+} catch (NoSuchElementException expected) {
+}
+</pre>
+
+<h3 id="s6.3-static-members">6.3 Static members: qualified using class</h3>
+
+<p>When a reference to a static class member must be qualified, it is qualified with that class's
+name, not with a reference or expression of that class's type.</p>
+
+<pre class="prettyprint lang-java">Foo aFoo = ...;
+Foo.aStaticMethod(); // good
+<span class="badcode">aFoo.aStaticMethod();</span> // bad
+<span class="badcode">somethingThatYieldsAFoo().aStaticMethod();</span> // very bad
+</pre>
+
+<a name="finalizers"></a>
+<h3 id="s6.4-finalizers">6.4 Finalizers: not used</h3>
+
+<p>It is <strong>extremely rare</strong> to override <code class="prettyprint
+lang-java">Object.finalize</code>.</p>
+
+<p class="tip"><strong>Tip:</strong> Don't do it. If you absolutely must, first read and understand
+
+
+ <a href="http://books.google.com/books?isbn=8131726592"><em>Effective Java</em> Item 7,</a>
+
+"Avoid Finalizers," very carefully, and <em>then</em> don't do it.</p>
+
+
+<a name="javadoc"></a>
+<h2 id="s7-javadoc">7 Javadoc</h2>
+
+
+
+<h3 id="s7.1-javadoc-formatting">7.1 Formatting</h3>
+
+<h4 id="s7.1.1-javadoc-multi-line">7.1.1 General form</h4>
+
+<p>The <em>basic</em> formatting of Javadoc blocks is as seen in this example:</p>
+
+<pre class="prettyprint lang-java">/**
+ * Multiple lines of Javadoc text are written here,
+ * wrapped normally...
+ */
+public int method(String p1) { ... }
+</pre>
+
+<p>... or in this single-line example:</p>
+
+<pre class="prettyprint lang-java">/** An especially short bit of Javadoc. */
+</pre>
+
+<p>The basic form is always acceptable. The single-line form may be substituted when the entirety
+of the Javadoc block (including comment markers) can fit on a single line. Note that this only
+applies when there are no block tags such as <code>@return</code>.
+
+</p><h4 id="s7.1.2-javadoc-paragraphs">7.1.2 Paragraphs</h4>
+
+<p>One blank line—that is, a line containing only the aligned leading asterisk
+(<code>*</code>)—appears between paragraphs, and before the group of block tags if
+present. Each paragraph but the first has <code><p></code> immediately before the first word,
+with no space after.</p>
+
+<a name="s7.1.3-javadoc-at-clauses"></a>
+
+<h4 id="s7.1.3-javadoc-block-tags">7.1.3 Block tags</h4>
+
+<p>Any of the standard "block tags" that are used appear in the order <code>@param</code>,
+<code>@return</code>, <code>@throws</code>, <code>@deprecated</code>, and these four types never
+appear with an empty description. When a block tag doesn't fit on a single line, continuation lines
+are indented four (or more) spaces from the position of the <code>@</code>.
+</p>
+
+<h3 id="s7.2-summary-fragment">7.2 The summary fragment</h3>
+
+<p>Each Javadoc block begins with a brief <strong>summary fragment</strong>. This
+fragment is very important: it is the only part of the text that appears in certain contexts such as
+class and method indexes.</p>
+
+<p>This is a fragment—a noun phrase or verb phrase, not a complete sentence. It does
+<strong>not</strong> begin with <code class="badcode">A {@code Foo} is a...</code>, or
+<code class="badcode">This method returns...</code>, nor does it form a complete imperative sentence
+like <code class="badcode">Save the record.</code>. However, the fragment is capitalized and
+punctuated as if it were a complete sentence.</p>
+
+<p class="tip"><strong>Tip:</strong> A common mistake is to write simple Javadoc in the form
+<code class="badcode">/** @return the customer ID */</code>. This is incorrect, and should be
+changed to <code class="prettyprint lang-java">/** Returns the customer ID. */</code>.</p>
+
+<a name="s7.3.3-javadoc-optional"></a>
+<h3 id="s7.3-javadoc-where-required">7.3 Where Javadoc is used</h3>
+
+<p>At the <em>minimum</em>, Javadoc is present for every
+<code class="prettyprint lang-java">public</code> class, and every
+<code class="prettyprint lang-java">public</code> or
+<code class="prettyprint lang-java">protected</code> member of such a class, with a few exceptions
+noted below.</p>
+
+<p>Additional Javadoc content may also be present, as explained in Section 7.3.4,
+<a href="#s7.3.4-javadoc-non-required">Non-required Javadoc</a>.</p>
+
+<h4 id="s7.3.1-javadoc-exception-self-explanatory">7.3.1 Exception: self-explanatory methods</h4>
+
+<p>Javadoc is optional for "simple, obvious" methods like
+<code class="prettyprint lang-java">getFoo</code>, in cases where there <em>really and truly</em> is
+nothing else worthwhile to say but "Returns the foo".</p>
+
+<p class="note"><strong>Important:</strong> it is not appropriate to cite this exception to justify
+omitting relevant information that a typical reader might need to know. For example, for a method
+named <code class="prettyprint lang-java">getCanonicalName</code>, don't omit its documentation
+(with the rationale that it would say only
+<code class="badcode">/** Returns the canonical name. */</code>) if a typical reader may have no idea
+what the term "canonical name" means!</p>
+
+<h4 id="s7.3.2-javadoc-exception-overrides">7.3.2 Exception: overrides</h4>
+
+<p>Javadoc is not always present on a method that overrides a supertype method.
+
+</p>
+
+
+
+<h4 id="s7.3.4-javadoc-non-required">7.3.4 Non-required Javadoc</h4>
+
+<p>Other classes and members have Javadoc <em>as needed or desired</em>.
+
+</p><p>Whenever an implementation comment would be used to define the overall purpose or behavior of a
+class or member, that comment is written as Javadoc instead (using <code>/**</code>).</p>
+
+<p>Non-required Javadoc is not strictly required to follow the formatting rules of Sections
+7.1.2, 7.1.3, and 7.2, though it is of course recommended.</p>
+
+
+
+</div>
+</div>
+</body>
+</html>
diff --git a/javaguidelink.png b/javaguidelink.png
new file mode 100644
index 0000000..75d5c7b
--- /dev/null
+++ b/javaguidelink.png
Binary files differ
diff --git a/javascriptguide.xml b/javascriptguide.xml
new file mode 100644
index 0000000..aba5a1e
--- /dev/null
+++ b/javascriptguide.xml
@@ -0,0 +1,3629 @@
+<?xml version = '1.0'?>
+<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
+<GUIDE title="Google JavaScript Style Guide">
+ <p class="revision">
+ Please note: there's a newer version of this guide that includes
+ ECMAScript 6th Edition features. It lives <a href="jsguide.html">here</a>.
+ You should probably be using that for new code.
+
+ Revision 2.93
+ </p>
+
+ <address>
+ Aaron Whyte<br/>
+ Bob Jervis<br/>
+ Dan Pupius<br/>
+ Erik Arvidsson<br/>
+ Fritz Schneider<br/>
+ Robby Walker<br/>
+ </address>
+ <OVERVIEW>
+ <CATEGORY title="Important Note">
+ <STYLEPOINT title="Displaying Hidden Details in this Guide">
+ <SUMMARY>
+ This style guide contains many details that are initially
+ hidden from view. They are marked by the triangle icon, which you
+ see here on your left. Click it now.
+ You should see "Hooray" appear below.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Hooray! Now you know you can expand points to get more
+ details. Alternatively, there's a "toggle all" at the
+ top of this document.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ </CATEGORY>
+ <CATEGORY title="Background">
+ <p>
+ JavaScript is the main client-side scripting language used
+
+ by many of Google's open-source
+ projects.
+ This style guide is a list of <em>do</em>s and <em>don't</em>s for
+ JavaScript programs.
+ </p>
+
+
+
+
+
+ </CATEGORY>
+ </OVERVIEW>
+ <CATEGORY title="JavaScript Language Rules">
+
+
+
+
+ <STYLEPOINT title="var">
+ <SUMMARY>
+ Declarations with <code>var</code>: Always
+ </SUMMARY>
+ <BODY>
+ <DECISION>
+ When you fail to specify <code>var</code>,
+ the variable gets placed in the global context, potentially clobbering
+ existing values. Also, if there's no declaration, it's hard to tell in
+ what scope a variable lives (e.g., it could be in the Document or
+ Window just as easily as in the local scope). So always declare with
+ <code>var</code>.
+ </DECISION>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Constants">
+ <SUMMARY>
+ <ul>
+ <li>Use <code>NAMES_LIKE_THIS</code> for constant <em>values</em>.</li>
+ <li>Use <code>@const</code> to indicate a constant (non-overwritable)
+ <em>pointer</em> (a variable or property).</li>
+ <li>Never use the
+ <a href="https://developer.mozilla.org/en/JavaScript/Reference/Statements/const">
+ <code>const</code> keyword</a>
+ as it's not supported in Internet Explorer.</li>
+ </ul>
+ </SUMMARY>
+ <BODY>
+ <DECISION>
+ <SUBSECTION title="Constant values">
+
+ <p>If a value is intended to be <em>constant</em>
+ and <em>immutable</em>, it should be given a name
+ in <code>CONSTANT_VALUE_CASE</code>.
+ <code>ALL_CAPS</code> additionally implies <code>@const</code>
+ (that the value is not overwritable).
+ </p>
+
+ <p>Primitive types (<code>number</code>, <code>string</code>,
+ <code>boolean</code>) are constant values.</p>
+
+ <p><code>Objects</code>'
+ immutability is more subjective — objects should be
+ considered immutable only if they do not demonstrate observable
+ state change. This is not enforced by the compiler.</p>
+
+
+ </SUBSECTION>
+
+ <SUBSECTION title="Constant pointers (variables and properties)">
+ <p>The <code>@const</code> annotation on a variable or property
+ implies that it is not overwritable. This is enforced by the
+ compiler at build time. This behavior is consistent with the
+ <a href="https://developer.mozilla.org/en/JavaScript/Reference/Statements/const">
+ <code>const</code> keyword</a> (which we do not use due to the
+ lack of support in Internet Explorer).</p>
+
+ <p>A <code>@const</code> annotation on a method additionally
+ implies that the method cannot not be overridden in subclasses.
+ </p>
+
+ <p>A <code>@const</code> annotation on a constructor implies the
+ class cannot be subclassed (akin to <code>final</code> in Java).
+ </p>
+
+ </SUBSECTION>
+
+ <SUBSECTION title="Examples">
+
+ <p>Note that <code>@const</code> does not necessarily imply
+ <code>CONSTANT_VALUES_CASE</code>.
+
+ However, <code>CONSTANT_VALUES_CASE</code>
+ <em>does</em> imply <code>@const</code>.
+ </p>
+
+ <CODE_SNIPPET>
+ /**
+ * Request timeout in milliseconds.
+ * @type {number}
+ */
+ goog.example.TIMEOUT_IN_MILLISECONDS = 60;
+ </CODE_SNIPPET>
+
+ <p>The number of seconds in a minute never changes. It is a
+ constant value. <code>ALL_CAPS</code>
+ also implies <code>@const</code>, so the constant cannot be
+ overwritten.
+ </p>
+
+ <p>The open source compiler will allow the symbol to be
+ overwritten because the constant is
+ <em>not</em> marked as <code>@const</code>.</p>
+
+ <CODE_SNIPPET>
+ /**
+ * Map of URL to response string.
+ * @const
+ */
+ MyClass.fetchedUrlCache_ = new goog.structs.Map();
+ </CODE_SNIPPET>
+
+ <CODE_SNIPPET>
+ /**
+ * Class that cannot be subclassed.
+ * @const
+ * @constructor
+ */
+ sloth.MyFinalClass = function() {};
+ </CODE_SNIPPET>
+
+ <p>In this case, the pointer can never be overwritten, but
+ value is highly mutable and <b>not</b> constant (and thus in
+ <code>camelCase</code>, not <code>ALL_CAPS</code>).</p>
+ </SUBSECTION>
+
+ </DECISION>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Semicolons">
+ <SUMMARY>
+ Always use semicolons.
+ </SUMMARY>
+ <BODY>
+ <p>Relying on implicit insertion can cause subtle, hard to debug
+ problems. Don't do it. You're better than that.</p>
+ <p>There are a couple places where missing semicolons are particularly
+ dangerous:</p>
+ <BAD_CODE_SNIPPET>
+ // 1.
+ MyClass.prototype.myMethod = function() {
+ return 42;
+ } // No semicolon here.
+
+ (function() {
+ // Some initialization code wrapped in a function to create a scope for locals.
+ })();
+
+
+ var x = {
+ 'i': 1,
+ 'j': 2
+ } // No semicolon here.
+
+ // 2. Trying to do one thing on Internet Explorer and another on Firefox.
+ // I know you'd never write code like this, but throw me a bone.
+ [ffVersion, ieVersion][isIE]();
+
+
+ var THINGS_TO_EAT = [apples, oysters, sprayOnCheese] // No semicolon here.
+
+ // 3. conditional execution a la bash
+ -1 == resultOfOperation() || die();
+ </BAD_CODE_SNIPPET>
+ <SUBSECTION title="So what happens?">
+ <ol>
+ <li>JavaScript error - first the function returning 42 is called
+ with the second function as a parameter, then the number 42 is
+ "called" resulting in an error.</li>
+ <li>You will most likely get a 'no such property in undefined'
+ error at runtime as it tries to call
+ <code>x[ffVersion, ieVersion][isIE]()</code>.</li>
+ <li><code>die</code> is always called since the array minus 1 is
+ <code>NaN</code> which is never equal to anything (not even if
+ <code>resultOfOperation()</code> returns <code>NaN</code>) and
+ <code>THINGS_TO_EAT</code> gets assigned the result of
+ <code>die()</code>.</li>
+ </ol>
+ </SUBSECTION>
+ <SUBSECTION title="Why?">
+ <p>JavaScript requires statements to end with a semicolon, except when
+ it thinks it can safely infer their existence. In each of these
+ examples, a function declaration or object or array literal is used
+ inside a statement. The closing brackets are not enough to signal
+ the end of the statement. Javascript never ends a statement if the
+ next token is an infix or bracket operator.</p>
+ <p>This has really surprised people, so make sure your assignments end
+ with semicolons.</p>
+ </SUBSECTION>
+ <SUBSECTION title="Clarification: Semicolons and functions">
+ <p>Semicolons should be included at the end of function expressions,
+ but not at the end of function declarations. The distinction is
+ best illustrated with an example:</p>
+ <CODE_SNIPPET>
+ var foo = function() {
+ return true;
+ }; // semicolon here.
+
+ function foo() {
+ return true;
+ } // no semicolon here.
+ </CODE_SNIPPET>
+ </SUBSECTION>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Nested functions">
+ <SUMMARY>Yes</SUMMARY>
+ <BODY>
+ <p>Nested functions can be very useful, for example in the creation of
+ continuations and for the task of hiding helper functions. Feel free
+ to use them.</p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Function Declarations Within Blocks">
+ <SUMMARY>No</SUMMARY>
+ <BODY>
+ <p>Do not do this:</p>
+ <BAD_CODE_SNIPPET>
+ if (x) {
+ function foo() {}
+ }
+ </BAD_CODE_SNIPPET>
+
+ <p>While most script engines support Function Declarations within blocks
+ it is not part of ECMAScript (see
+ <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">ECMA-262</a>,
+ clause 13 and 14). Worse implementations are inconsistent with each
+ other and with future EcmaScript proposals. ECMAScript only allows for
+ Function Declarations in the root statement list of a script or
+ function. Instead use a variable initialized with a Function
+ Expression to define a function within a block:</p>
+ <CODE_SNIPPET>
+ if (x) {
+ var foo = function() {};
+ }
+ </CODE_SNIPPET>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Exceptions">
+ <SUMMARY>Yes</SUMMARY>
+ <BODY>
+ <p>You basically can't avoid exceptions if you're doing something
+ non-trivial (using an application development framework, etc.).
+ Go for it.</p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Custom exceptions">
+ <SUMMARY>Yes</SUMMARY>
+ <BODY>
+ <p>Without custom exceptions, returning error information from a
+ function that also returns a value can be tricky, not to mention
+ inelegant. Bad solutions include passing in a reference type to hold
+ error information or always returning Objects with a potential
+ error member. These basically amount to a primitive exception
+ handling hack. Feel free to use custom exceptions when
+ appropriate.</p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Standards features">
+ <SUMMARY>Always preferred over non-standards features</SUMMARY>
+ <BODY>
+ <p>For maximum portability and compatibility, always prefer standards
+ features over non-standards features (e.g.,
+ <code>string.charAt(3)</code> over <code>string[3]</code> and element
+ access with DOM functions instead of using an application-specific
+ shorthand).</p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Wrapper objects for primitive types">
+ <SUMMARY>No</SUMMARY>
+ <BODY>
+ <p>There's no reason to use wrapper objects for primitive types, plus
+ they're dangerous:</p>
+ <BAD_CODE_SNIPPET>
+ var x = new Boolean(false);
+ if (x) {
+ alert('hi'); // Shows 'hi'.
+ }
+ </BAD_CODE_SNIPPET>
+ <p>Don't do it!</p>
+ <p>However type casting is fine.</p>
+ <CODE_SNIPPET>
+ var x = Boolean(0);
+ if (x) {
+ alert('hi'); // This will never be alerted.
+ }
+ typeof Boolean(0) == 'boolean';
+ typeof new Boolean(0) == 'object';
+ </CODE_SNIPPET>
+ <p>This is very useful for casting things to
+ <code>number</code>, <code>string</code> and <code>boolean</code>.</p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Multi-level prototype hierarchies">
+ <SUMMARY>Not preferred</SUMMARY>
+ <BODY>
+ <p>Multi-level prototype hierarchies are how JavaScript implements
+ inheritance. You have a multi-level hierarchy if you have a
+ user-defined class D with another user-defined class B as its
+ prototype. These hierarchies are much harder to get right than they
+ first appear! </p>
+
+ <p>For that reason, it is best to use <code>goog.inherits()</code> from
+ <a href="https://code.google.com/closure/library/">
+ the Closure Library
+ </a>
+ or a similar library function.
+ </p>
+ <CODE_SNIPPET>
+ function D() {
+ goog.base(this)
+ }
+ goog.inherits(D, B);
+
+ D.prototype.method = function() {
+ ...
+ };
+ </CODE_SNIPPET>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Method and property definitions">
+ <SUMMARY><code>/** @constructor */
+ function SomeConstructor() {
+ this.someProperty = 1;
+ }
+ Foo.prototype.someMethod = function() { ... };</code></SUMMARY>
+ <BODY>
+ <p>While there are several ways to attach methods and properties to an
+ object created via "new", the preferred style for methods
+ is:</p>
+ <CODE_SNIPPET>
+ Foo.prototype.bar = function() {
+ /* ... */
+ };
+ </CODE_SNIPPET>
+ <p>The preferred style for other properties is to initialize the field
+ in the constructor:</p>
+ <CODE_SNIPPET>
+ /** @constructor */
+ function Foo() {
+ this.bar = value;
+ }
+ </CODE_SNIPPET>
+ <SUBSECTION title="Why?">
+ <p>Current JavaScript engines optimize based on the "shape"
+ of an object, <a href="https://developers.google.com/v8/design#prop_access">
+ adding a property to an object (including overriding
+ a value set on the prototype) changes the shape and can degrade
+ performance.</a></p>
+ </SUBSECTION>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="delete">
+ <SUMMARY>Prefer <code>this.foo = null</code>.</SUMMARY>
+ <BODY>
+ <CODE_SNIPPET>
+ Foo.prototype.dispose = function() {
+ this.property_ = null;
+ };
+ </CODE_SNIPPET>
+ <p>Instead of:</p>
+ <BAD_CODE_SNIPPET>
+ Foo.prototype.dispose = function() {
+ delete this.property_;
+ };
+ </BAD_CODE_SNIPPET>
+ <p>In modern JavaScript engines, changing the number of properties on an
+ object is much slower than reassigning the values. The delete keyword
+ should be avoided except when it is necessary to remove a property
+ from an object's iterated list of keys, or to change the result of
+ <code>if (key in obj)</code>.</p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Closures">
+ <SUMMARY>Yes, but be careful.</SUMMARY>
+ <BODY>
+ <p>The ability to create closures is perhaps the most useful and often
+ overlooked feature of JS. Here is
+ <a href="http://jibbering.com/faq/faq_notes/closures.html">
+ a good description of how closures work</a>.</p>
+ <p>One thing to keep in mind, however, is that a closure keeps a pointer
+ to its enclosing scope. As a result, attaching a closure to a DOM
+ element can create a circular reference and thus, a memory leak. For
+ example, in the following code:</p>
+ <BAD_CODE_SNIPPET>
+ function foo(element, a, b) {
+ element.onclick = function() { /* uses a and b */ };
+ }
+ </BAD_CODE_SNIPPET>
+ <p>the function closure keeps a reference to <code>element</code>,
+ <code>a</code>, and <code>b</code> even if it never uses
+ <code>element</code>. Since <code>element</code> also keeps a
+ reference to the closure, we have a cycle that won't be cleaned up by
+ garbage collection. In these situations, the code can be structured
+ as follows:</p>
+ <CODE_SNIPPET>
+ function foo(element, a, b) {
+ element.onclick = bar(a, b);
+ }
+
+ function bar(a, b) {
+ return function() { /* uses a and b */ };
+ }
+ </CODE_SNIPPET>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="eval()">
+ <SUMMARY>
+ Only for code loaders and REPL (Read–eval–print loop)
+ </SUMMARY>
+ <BODY>
+ <p><code>eval()</code> makes for confusing semantics and is dangerous
+ to use if the string being <code>eval()</code>'d contains user input.
+ There's usually a better, clearer, and safer way to write your code,
+ so its use is generally not permitted.</p>
+
+ <p>For RPC you can always use JSON and read the result using
+ <code>JSON.parse()</code> instead of <code>eval()</code>.</p>
+
+ <p>Let's assume we have a server that returns something like this:</p>
+
+ <CODE_SNIPPET>
+ {
+ "name": "Alice",
+ "id": 31502,
+ "email": "looking_glass@example.com"
+ }
+ </CODE_SNIPPET>
+
+ <BAD_CODE_SNIPPET>
+ var userInfo = eval(feed);
+ var email = userInfo['email'];
+ </BAD_CODE_SNIPPET>
+
+ <p>If the feed was modified to include malicious JavaScript code, then
+ if we use <code>eval</code> then that code will be executed.</p>
+
+ <CODE_SNIPPET>
+ var userInfo = JSON.parse(feed);
+ var email = userInfo['email'];
+ </CODE_SNIPPET>
+
+ <p>With <code>JSON.parse</code>, invalid JSON (including all executable
+ JavaScript) will cause an exception to be thrown.</p>
+
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="with() {}">
+ <SUMMARY>No</SUMMARY>
+ <BODY>
+ <p>Using <code>with</code> clouds the semantics of your program.
+ Because the object of the <code>with</code> can have properties that
+ collide with local variables, it can drastically change the meaning
+ of your program. For example, what does this do?</p>
+ <BAD_CODE_SNIPPET>
+ with (foo) {
+ var x = 3;
+ return x;
+ }
+ </BAD_CODE_SNIPPET>
+ <p>Answer: anything. The local variable <code>x</code> could be
+ clobbered by a property of <code>foo</code> and perhaps it even has
+ a setter, in which case assigning <code>3</code> could cause lots of
+ other code to execute. Don't use <code>with</code>.</p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="this">
+ <SUMMARY>
+ Only in object constructors, methods, and in setting up closures
+ </SUMMARY>
+ <BODY>
+ <p>The semantics of <code>this</code> can be tricky. At times it refers
+ to the global object (in most places), the scope of the caller (in
+ <code>eval</code>), a node in the DOM tree (when attached using an
+ event handler HTML attribute), a newly created object (in a
+ constructor), or some other object (if function was
+ <code>call()</code>ed or <code>apply()</code>ed).</p>
+ <p>Because this is so easy to get wrong, limit its use to those places
+ where it is required:</p>
+ <ul>
+ <li>in constructors</li>
+ <li>in methods of objects (including in the creation of closures)</li>
+ </ul>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="for-in loop">
+ <SUMMARY>
+ Only for iterating over keys in an object/map/hash
+ </SUMMARY>
+ <BODY>
+ <p><code>for-in</code> loops are often incorrectly used to loop over
+ the elements in an <code>Array</code>. This is however very error
+ prone because it does not loop from <code>0</code> to
+ <code>length - 1</code> but over all the present keys in the object
+ and its prototype chain. Here are a few cases where it fails:</p>
+ <BAD_CODE_SNIPPET>
+ function printArray(arr) {
+ for (var key in arr) {
+ print(arr[key]);
+ }
+ }
+
+ printArray([0,1,2,3]); // This works.
+
+ var a = new Array(10);
+ printArray(a); // This is wrong.
+
+ a = document.getElementsByTagName('*');
+ printArray(a); // This is wrong.
+
+ a = [0,1,2,3];
+ a.buhu = 'wine';
+ printArray(a); // This is wrong again.
+
+ a = new Array;
+ a[3] = 3;
+ printArray(a); // This is wrong again.
+ </BAD_CODE_SNIPPET>
+ <p>Always use normal for loops when using arrays.</p>
+ <CODE_SNIPPET>
+ function printArray(arr) {
+ var l = arr.length;
+ for (var i = 0; i < l; i++) {
+ print(arr[i]);
+ }
+ }
+ </CODE_SNIPPET>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Associative Arrays">
+ <SUMMARY>
+ Never use <code>Array</code> as a map/hash/associative array
+ </SUMMARY>
+ <BODY>
+ <p>Associative <code>Array</code>s are not allowed... or more precisely
+ you are not allowed to use non number indexes for arrays. If you need
+ a map/hash use <code>Object</code> instead of <code>Array</code> in
+ these cases because the features that you want are actually features
+ of <code>Object</code> and not of <code>Array</code>.
+ <code>Array</code> just happens to extend <code>Object</code> (like
+ any other object in JS and therefore you might as well have used
+ <code>Date</code>, <code>RegExp</code> or <code>String</code>).</p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Multiline string literals">
+ <SUMMARY>No</SUMMARY>
+ <BODY>
+ <p>Do not do this:</p>
+ <BAD_CODE_SNIPPET>
+ var myString = 'A rather long string of English text, an error message \
+ actually that just keeps going and going -- an error \
+ message to make the Energizer bunny blush (right through \
+ those Schwarzenegger shades)! Where was I? Oh yes, \
+ you\'ve got an error and all the extraneous whitespace is \
+ just gravy. Have a nice day.';
+ </BAD_CODE_SNIPPET>
+ <p>The whitespace at the beginning of each line can't be safely stripped
+ at compile time; whitespace after the slash will result in tricky
+ errors. </p>
+ <p>Use string concatenation instead:</p>
+ <CODE_SNIPPET>
+ var myString = 'A rather long string of English text, an error message ' +
+ 'actually that just keeps going and going -- an error ' +
+ 'message to make the Energizer bunny blush (right through ' +
+ 'those Schwarzenegger shades)! Where was I? Oh yes, ' +
+ 'you\'ve got an error and all the extraneous whitespace is ' +
+ 'just gravy. Have a nice day.';
+ </CODE_SNIPPET>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Array and Object literals">
+ <SUMMARY>Yes</SUMMARY>
+ <BODY>
+ <p>Use <code>Array</code> and <code>Object</code> literals instead of
+ <code>Array</code> and <code>Object</code> constructors.</p>
+ <p>Array constructors are error-prone due to their arguments.</p>
+ <BAD_CODE_SNIPPET>
+ // Length is 3.
+ var a1 = new Array(x1, x2, x3);
+
+ // Length is 2.
+ var a2 = new Array(x1, x2);
+
+ // If x1 is a number and it is a natural number the length will be x1.
+ // If x1 is a number but not a natural number this will throw an exception.
+ // Otherwise the array will have one element with x1 as its value.
+ var a3 = new Array(x1);
+
+ // Length is 0.
+ var a4 = new Array();
+ </BAD_CODE_SNIPPET>
+ <p>Because of this, if someone changes the code to pass 1 argument
+ instead of 2 arguments, the array might not have the expected
+ length.</p>
+ <p>To avoid these kinds of weird cases, always use the more readable
+ array literal.</p>
+ <CODE_SNIPPET>
+ var a = [x1, x2, x3];
+ var a2 = [x1, x2];
+ var a3 = [x1];
+ var a4 = [];
+ </CODE_SNIPPET>
+ <p>Object constructors don't have the same problems, but for readability
+ and consistency object literals should be used.</p>
+ <BAD_CODE_SNIPPET>
+ var o = new Object();
+
+ var o2 = new Object();
+ o2.a = 0;
+ o2.b = 1;
+ o2.c = 2;
+ o2['strange key'] = 3;
+ </BAD_CODE_SNIPPET>
+ <p>Should be written as:</p>
+ <CODE_SNIPPET>
+ var o = {};
+
+ var o2 = {
+ a: 0,
+ b: 1,
+ c: 2,
+ 'strange key': 3
+ };
+ </CODE_SNIPPET>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Modifying prototypes of builtin objects">
+ <SUMMARY>No</SUMMARY>
+ <BODY>
+ <p>Modifying builtins like <code>Object.prototype</code> and
+ <code>Array.prototype</code> are strictly forbidden. Modifying other
+ builtins like <code>Function.prototype</code> is less dangerous but
+ still leads to hard to debug issues in production and should be
+ avoided.</p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Internet Explorer's Conditional Comments">
+ <SUMMARY>No</SUMMARY>
+ <BODY>
+ <p>Don't do this:</p>
+ <BAD_CODE_SNIPPET>
+ var f = function () {
+ /*@cc_on if (@_jscript) { return 2* @*/ 3; /*@ } @*/
+ };
+ </BAD_CODE_SNIPPET>
+ <p>Conditional Comments hinder automated tools as they can vary the
+ JavaScript syntax tree at runtime.</p>
+ </BODY>
+ </STYLEPOINT>
+ </CATEGORY>
+
+ <CATEGORY title="JavaScript Style Rules">
+ <STYLEPOINT title="Naming">
+ <SUMMARY>
+ <p>In general, use
+ <code>functionNamesLikeThis</code>,
+ <code>variableNamesLikeThis</code>,
+ <code>ClassNamesLikeThis</code>,
+ <code>EnumNamesLikeThis</code>,
+ <code>methodNamesLikeThis</code>,
+ <code>CONSTANT_VALUES_LIKE_THIS</code>,
+ <code>foo.namespaceNamesLikeThis.bar</code>, and
+ <code>filenameslikethis.js</code>.
+ </p>
+ </SUMMARY>
+ <BODY>
+ <SUBSECTION title="Properties and methods">
+ <ul>
+ <li><em>Private</em> properties and methods should be named with a
+ trailing underscore.
+ </li>
+ <li><em>Protected</em> properties and methods should be
+ named without a trailing underscore (like public ones).</li>
+ </ul>
+ <p>For more information on <em>private</em> and <em>protected</em>,
+ read the section on
+ <a href="#Visibility__private_and_protected_fields_">
+ visibility</a>.
+ </p>
+
+
+
+
+ </SUBSECTION>
+
+ <SUBSECTION title="Method and function parameter">
+ <p>Optional function arguments start with <code>opt_</code>.</p>
+ <p>Functions that take a variable number of arguments should have the
+ last argument named <code>var_args</code>. You may not refer to
+ <code>var_args</code> in the code; use the <code>arguments</code>
+ array.</p>
+ <p>Optional and variable arguments can also be specified in
+ <code>@param</code> annotations. Although either convention is
+ acceptable to the compiler, using both together is preferred.</p>
+
+ </SUBSECTION>
+
+ <SUBSECTION title="Getters and Setters">
+ <p>EcmaScript 5 getters and setters for properties are discouraged.
+ However, if they are used, then getters must not change observable
+ state.</p>
+ <BAD_CODE_SNIPPET>
+ /**
+ * WRONG -- Do NOT do this.
+ */
+ var foo = { get next() { return this.nextId++; } };
+ </BAD_CODE_SNIPPET>
+ </SUBSECTION>
+
+ <SUBSECTION title="Accessor functions">
+ <p>Getters and setters methods for properties are not required.
+ However, if they are used, then getters must be named
+ <code>getFoo()</code> and setters must be named
+ <code>setFoo(value)</code>. (For boolean getters,
+ <code>isFoo()</code> is also acceptable, and often sounds more
+ natural.)</p>
+ </SUBSECTION>
+
+ <SUBSECTION title="Namespaces">
+ <p>JavaScript has no inherent packaging or namespacing support.</p>
+ <p>Global name conflicts are difficult to debug, and can cause
+ intractable problems when two projects try to integrate. In order
+ to make it possible to share common JavaScript code, we've adopted
+ conventions to prevent collisions. </p>
+ <SUBSUBSECTION title="Use namespaces for global code">
+ <p><em>ALWAYS</em> prefix identifiers in the global scope with a
+ unique pseudo namespace related to the project or library. If you
+ are working on "Project Sloth", a reasonable pseudo namespace
+ would be <code>sloth.*</code>.</p>
+ <CODE_SNIPPET>
+ var sloth = {};
+
+ sloth.sleep = function() {
+ ...
+ };
+ </CODE_SNIPPET>
+
+
+ <p>Many JavaScript libraries, including
+ <a href="https://code.google.com/closure/library/">
+ the Closure Library
+ </a>
+ and
+ <a href="http://www.dojotoolkit.org/">
+ Dojo toolkit
+ </a>
+ give you high-level functions for declaring your namespaces.
+ Be consistent about how you declare your namespaces.</p>
+ <CODE_SNIPPET>
+ goog.provide('sloth');
+
+ sloth.sleep = function() {
+ ...
+ };
+ </CODE_SNIPPET>
+ </SUBSUBSECTION>
+ <SUBSUBSECTION title="Respect namespace ownership">
+ <p>When choosing a child-namespace, make sure that the owners of the
+ parent namespace know what you are doing. If you start a project
+ that creates hats for sloths, make sure that the Sloth team knows
+ that you're using <code>sloth.hats</code>.</p>
+
+ </SUBSUBSECTION>
+ <SUBSUBSECTION title="Use different namespaces for external code and internal code">
+ <p>"External code" is code that comes from outside your codebase,
+ and is compiled independently. Internal and external names should
+ be kept strictly separate. If you're using an external library
+ that makes things available in <code>foo.hats.*</code>, your
+ internal code should not define all its symbols in
+ <code>foo.hats.*</code>, because it will break if the other
+ team defines new symbols.</p>
+ <BAD_CODE_SNIPPET>
+ foo.require('foo.hats');
+
+ /**
+ * WRONG -- Do NOT do this.
+ * @constructor
+ * @extends {foo.hats.RoundHat}
+ */
+ foo.hats.BowlerHat = function() {
+ };
+ </BAD_CODE_SNIPPET>
+ <p>If you need to define new APIs on an external namespace, then you
+ should explicitly export the public API functions, and only those
+ functions. Your internal code should call the internal APIs by
+ their internal names, for consistency and so that the compiler
+ can optimize them better.</p>
+ <CODE_SNIPPET>
+ foo.provide('googleyhats.BowlerHat');
+
+ foo.require('foo.hats');
+
+ /**
+ * @constructor
+ * @extends {foo.hats.RoundHat}
+ */
+ googleyhats.BowlerHat = function() {
+ ...
+ };
+
+ goog.exportSymbol('foo.hats.BowlerHat', googleyhats.BowlerHat);
+ </CODE_SNIPPET>
+
+
+ </SUBSUBSECTION>
+ <SUBSUBSECTION title="Alias long type names to improve readability">
+ <p>Use local aliases for fully-qualified types if doing so improves
+ readability. The name of a local alias should match the last part
+ of the type.</p>
+ <CODE_SNIPPET>
+ /**
+ * @constructor
+ */
+ some.long.namespace.MyClass = function() {
+ };
+
+ /**
+ * @param {some.long.namespace.MyClass} a
+ */
+ some.long.namespace.MyClass.staticHelper = function(a) {
+ ...
+ };
+
+ myapp.main = function() {
+ var MyClass = some.long.namespace.MyClass;
+ var staticHelper = some.long.namespace.MyClass.staticHelper;
+ staticHelper(new MyClass());
+ };
+ </CODE_SNIPPET>
+ <p>Do not create local aliases of namespaces. Namespaces should only
+ be aliased using <a href="#goog-scope">goog.scope</a>.</p>
+ <BAD_CODE_SNIPPET>
+ myapp.main = function() {
+ var namespace = some.long.namespace;
+ namespace.MyClass.staticHelper(new namespace.MyClass());
+ };
+ </BAD_CODE_SNIPPET>
+ <p>Avoid accessing properties of an aliased type, unless it is an
+ enum.</p>
+ <CODE_SNIPPET>
+ /** @enum {string} */
+ some.long.namespace.Fruit = {
+ APPLE: 'a',
+ BANANA: 'b'
+ };
+
+ myapp.main = function() {
+ var Fruit = some.long.namespace.Fruit;
+ switch (fruit) {
+ case Fruit.APPLE:
+ ...
+ case Fruit.BANANA:
+ ...
+ }
+ };
+ </CODE_SNIPPET>
+ <BAD_CODE_SNIPPET>
+ myapp.main = function() {
+ var MyClass = some.long.namespace.MyClass;
+ MyClass.staticHelper(null);
+ };
+ </BAD_CODE_SNIPPET>
+ <p>Never create aliases in the global scope. Use them only in
+ function blocks.</p>
+ </SUBSUBSECTION>
+ </SUBSECTION>
+ <SUBSECTION title="Filenames">
+ <p>Filenames should be all lowercase in order to avoid confusion on
+ case-sensitive platforms. Filenames should end in <code>.js</code>,
+ and should contain no punctuation except for <code>-</code> or
+ <code>_</code> (prefer <code>-</code> to <code>_</code>).</p>
+ </SUBSECTION>
+
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Custom toString() methods">
+ <SUMMARY>
+ Must always succeed without side effects.
+ </SUMMARY>
+ <BODY>
+ <p>You can control how your objects string-ify themselves by defining a
+ custom <code>toString()</code> method. This is fine, but you need
+ to ensure that your method (1) always succeeds and (2) does not have
+ side-effects. If your method doesn't meet these criteria, it's very
+ easy to run into serious problems. For example, if
+ <code>toString()</code> calls a method that does an
+ <code>assert</code>, <code>assert</code> might try to output the name
+ of the object in which it failed, which of course requires calling
+ <code>toString()</code>.</p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Deferred initialization">
+ <SUMMARY>OK</SUMMARY>
+ <BODY>
+ <p>It isn't always possible to initialize variables at the point of
+ declaration, so deferred initialization is fine.</p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Explicit scope">
+ <SUMMARY>Always</SUMMARY>
+ <BODY>
+ <p>Always use explicit scope - doing so increases portability and
+ clarity. For example, don't rely on <code>window</code> being in the
+ scope chain. You might want to use your function in another
+ application for which <code>window</code> is not the content
+ window.</p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Code formatting">
+ <SUMMARY>Expand for more information.</SUMMARY>
+ <BODY>
+ <p>We follow the <a href="cppguide.html#Formatting">C++ formatting
+ rules</a> in spirit, with the following additional clarifications.</p>
+ <SUBSECTION title="Curly Braces">
+ <p>Because of implicit semicolon insertion, always start your curly
+ braces on the same line as whatever they're opening. For
+ example:</p>
+ <CODE_SNIPPET>
+ if (something) {
+ // ...
+ } else {
+ // ...
+ }
+ </CODE_SNIPPET>
+ </SUBSECTION>
+ <SUBSECTION title="Array and Object Initializers">
+ <p>Single-line array and object initializers are allowed when they
+ fit on a line:</p>
+ <CODE_SNIPPET>
+ var arr = [1, 2, 3]; // No space after [ or before ].
+ var obj = {a: 1, b: 2, c: 3}; // No space after { or before }.
+ </CODE_SNIPPET>
+ <p>Multiline array initializers and object initializers are indented
+ 2 spaces, with the braces on their own line, just like blocks.</p>
+ <CODE_SNIPPET>
+ // Object initializer.
+ var inset = {
+ top: 10,
+ right: 20,
+ bottom: 15,
+ left: 12
+ };
+
+ // Array initializer.
+ this.rows_ = [
+ '"Slartibartfast" <fjordmaster@magrathea.com>',
+ '"Zaphod Beeblebrox" <theprez@universe.gov>',
+ '"Ford Prefect" <ford@theguide.com>',
+ '"Arthur Dent" <has.no.tea@gmail.com>',
+ '"Marvin the Paranoid Android" <marv@googlemail.com>',
+ 'the.mice@magrathea.com'
+ ];
+
+ // Used in a method call.
+ goog.dom.createDom(goog.dom.TagName.DIV, {
+ id: 'foo',
+ className: 'some-css-class',
+ style: 'display:none'
+ }, 'Hello, world!');
+ </CODE_SNIPPET>
+ <p>Long identifiers or values present problems for aligned
+ initialization lists, so always prefer non-aligned initialization.
+ For example:</p>
+ <CODE_SNIPPET>
+ CORRECT_Object.prototype = {
+ a: 0,
+ b: 1,
+ lengthyName: 2
+ };
+ </CODE_SNIPPET>
+ <p>Not like this:</p>
+ <BAD_CODE_SNIPPET>
+ WRONG_Object.prototype = {
+ a : 0,
+ b : 1,
+ lengthyName: 2
+ };
+ </BAD_CODE_SNIPPET>
+ </SUBSECTION>
+ <SUBSECTION title="Function Arguments">
+ <p>When possible, all function arguments should be listed on the same
+ line. If doing so would exceed the 80-column limit, the arguments
+ must be line-wrapped in a readable way. To save space, you may wrap
+ as close to 80 as possible, or put each argument on its own line to
+ enhance readability. The indentation may be either four spaces, or
+ aligned to the parenthesis. Below are the most common patterns for
+ argument wrapping:</p>
+ <CODE_SNIPPET>
+ // Four-space, wrap at 80. Works with very long function names, survives
+ // renaming without reindenting, low on space.
+ goog.foo.bar.doThingThatIsVeryDifficultToExplain = function(
+ veryDescriptiveArgumentNumberOne, veryDescriptiveArgumentTwo,
+ tableModelEventHandlerProxy, artichokeDescriptorAdapterIterator) {
+ // ...
+ };
+
+ // Four-space, one argument per line. Works with long function names,
+ // survives renaming, and emphasizes each argument.
+ goog.foo.bar.doThingThatIsVeryDifficultToExplain = function(
+ veryDescriptiveArgumentNumberOne,
+ veryDescriptiveArgumentTwo,
+ tableModelEventHandlerProxy,
+ artichokeDescriptorAdapterIterator) {
+ // ...
+ };
+
+ // Parenthesis-aligned indentation, wrap at 80. Visually groups arguments,
+ // low on space.
+ function foo(veryDescriptiveArgumentNumberOne, veryDescriptiveArgumentTwo,
+ tableModelEventHandlerProxy, artichokeDescriptorAdapterIterator) {
+ // ...
+ }
+
+ // Parenthesis-aligned, one argument per line. Emphasizes each
+ // individual argument.
+ function bar(veryDescriptiveArgumentNumberOne,
+ veryDescriptiveArgumentTwo,
+ tableModelEventHandlerProxy,
+ artichokeDescriptorAdapterIterator) {
+ // ...
+ }
+ </CODE_SNIPPET>
+ <p>When the function call is itself indented, you're free to start the
+ 4-space indent relative to the beginning of the original statement
+ or relative to the beginning of the current function call.
+ The following are all acceptable indentation styles.</p>
+ <CODE_SNIPPET>
+ if (veryLongFunctionNameA(
+ veryLongArgumentName) ||
+ veryLongFunctionNameB(
+ veryLongArgumentName)) {
+ veryLongFunctionNameC(veryLongFunctionNameD(
+ veryLongFunctioNameE(
+ veryLongFunctionNameF)));
+ }
+ </CODE_SNIPPET>
+ </SUBSECTION>
+ <SUBSECTION title="Passing Anonymous Functions">
+ <p>When declaring an anonymous function in the list of arguments for
+ a function call, the body of the function is indented two spaces
+ from the left edge of the statement, or two spaces from the left
+ edge of the function keyword. This is to make the body of the
+ anonymous function easier to read (i.e. not be all squished up into
+ the right half of the screen).</p>
+ <CODE_SNIPPET>
+ prefix.something.reallyLongFunctionName('whatever', function(a1, a2) {
+ if (a1.equals(a2)) {
+ someOtherLongFunctionName(a1);
+ } else {
+ andNowForSomethingCompletelyDifferent(a2.parrot);
+ }
+ });
+
+ var names = prefix.something.myExcellentMapFunction(
+ verboselyNamedCollectionOfItems,
+ function(item) {
+ return item.name;
+ });
+ </CODE_SNIPPET>
+ </SUBSECTION>
+ <SUBSECTION title="Aliasing with goog.scope">
+ <a name="goog-scope"/>
+ <p>
+ <a href="https://docs.google.com/document/pub?id=1ETFAuh2kaXMVL-vafUYhaWlhl6b5D9TOvboVg7Zl68Y"><code>goog.scope</code></a>
+ may be used to shorten references to
+ namespaced symbols in programs using
+ <a href="https://code.google.com/closure/library/">the Closure
+ Library</a>.</p>
+ <p>Only one <code>goog.scope</code> invocation may be added per
+ file. Always place it in the global scope.</p>
+ <p>The opening <code>goog.scope(function() {</code> invocation
+ must be preceded by exactly one blank line and follow any
+ <code>goog.provide</code> statements, <code>goog.require</code>
+ statements, or top-level comments. The invocation must be closed on
+ the last line in the file. Append <code>// goog.scope</code> to the
+ closing statement of the scope. Separate the comment from the
+ semicolon by two spaces.</p>
+ <p>Similar to C++ namespaces, do not indent under goog.scope
+ declarations. Instead, continue from the 0 column.</p>
+ <p>Only alias names that will not be re-assigned to another object
+ (e.g., most constructors, enums, and namespaces). Do not do
+ this (see below for how to alias a constructor):</p>
+
+ <BAD_CODE_SNIPPET>
+ goog.scope(function() {
+ var Button = goog.ui.Button;
+
+ Button = function() { ... };
+ ...
+ </BAD_CODE_SNIPPET>
+
+ <p>Names must be the same as the last property of the global that they
+ are aliasing.</p>
+
+ <CODE_SNIPPET>
+ goog.provide('my.module.SomeType');
+
+ goog.require('goog.dom');
+ goog.require('goog.ui.Button');
+
+ goog.scope(function() {
+ var Button = goog.ui.Button;
+ var dom = goog.dom;
+
+ // Alias new types <b>after</b> the constructor declaration.
+ my.module.SomeType = function() { ... };
+ var SomeType = my.module.SomeType;
+
+ // Declare methods on the prototype as usual:
+ SomeType.prototype.findButton = function() {
+ // Button as aliased above.
+ this.button = new Button(dom.getElement('my-button'));
+ };
+ ...
+ }); // goog.scope
+ </CODE_SNIPPET>
+ </SUBSECTION>
+ <SUBSECTION title="Indenting wrapped lines">
+ <p>Except for <a href="#Array_and_Object_literals">array literals,
+ object literals</a>, and anonymous functions, all wrapped lines
+ should be indented either left-aligned to a sibling expression
+ above, or four spaces (not two spaces) deeper than a parent
+ expression (where "sibling" and "parent" refer to parenthesis
+ nesting level).
+ </p>
+
+ <CODE_SNIPPET>
+ someWonderfulHtml = '<div class="' + getClassesForWonderfulHtml()'">' +
+ getEvenMoreHtml(someReallyInterestingValues, moreValues,
+ evenMoreParams, 'a duck', true, 72,
+ slightlyMoreMonkeys(0xfff)) +
+ '</div>';
+
+ thisIsAVeryLongVariableName =
+ hereIsAnEvenLongerOtherFunctionNameThatWillNotFitOnPrevLine();
+
+ thisIsAVeryLongVariableName = siblingOne + siblingTwo + siblingThree +
+ siblingFour + siblingFive + siblingSix + siblingSeven +
+ moreSiblingExpressions + allAtTheSameIndentationLevel;
+
+ thisIsAVeryLongVariableName = operandOne + operandTwo + operandThree +
+ operandFour + operandFive * (
+ aNestedChildExpression + shouldBeIndentedMore);
+
+ someValue = this.foo(
+ shortArg,
+ 'Some really long string arg - this is a pretty common case, actually.',
+ shorty2,
+ this.bar());
+
+ if (searchableCollection(allYourStuff).contains(theStuffYouWant) &&
+ !ambientNotification.isActive() && (client.isAmbientSupported() ||
+ client.alwaysTryAmbientAnyways())) {
+ ambientNotification.activate();
+ }
+ </CODE_SNIPPET>
+ </SUBSECTION>
+ <SUBSECTION title="Blank lines">
+ <p>Use newlines to group logically related pieces of code.
+ For example:</p>
+ <CODE_SNIPPET>
+ doSomethingTo(x);
+ doSomethingElseTo(x);
+ andThen(x);
+
+ nowDoSomethingWith(y);
+
+ andNowWith(z);
+ </CODE_SNIPPET>
+ </SUBSECTION>
+ <SUBSECTION title="Binary and Ternary Operators">
+ <p>Always put the operator on the preceding line. Otherwise,
+ line breaks and indentation follow the same rules as in other
+ Google style guides. This operator placement was initially agreed
+ upon out of concerns about automatic semicolon insertion. In fact,
+ semicolon insertion cannot happen before a binary operator, but new
+ code should stick to this style for consistency.</p>
+ <CODE_SNIPPET>
+ var x = a ? b : c; // All on one line if it will fit.
+
+ // Indentation +4 is OK.
+ var y = a ?
+ longButSimpleOperandB : longButSimpleOperandC;
+
+ // Indenting to the line position of the first operand is also OK.
+ var z = a ?
+ moreComplicatedB :
+ moreComplicatedC;
+ </CODE_SNIPPET>
+ <p>This includes the dot operator.</p>
+ <CODE_SNIPPET>
+ var x = foo.bar().
+ doSomething().
+ doSomethingElse();
+ </CODE_SNIPPET>
+ </SUBSECTION>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Parentheses">
+ <SUMMARY>Only where required</SUMMARY>
+ <BODY>
+ <p>Use sparingly and in general only where required by the syntax
+ and semantics.</p>
+ <p>Never use parentheses for unary operators such as
+ <code>delete</code>, <code>typeof</code> and <code>void</code> or
+ after keywords such as <code>return</code>, <code>throw</code> as
+ well as others (<code>case</code>, <code>in</code> or
+ <code>new</code>).</p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Strings">
+ <SUMMARY>Prefer ' over "</SUMMARY>
+ <BODY>
+ <p>For consistency single-quotes (') are preferred to double-quotes (").
+ This is helpful when creating strings that include HTML:</p>
+ <CODE_SNIPPET>
+ var msg = 'This is <a href="http://foo">some HTML</a>';
+ </CODE_SNIPPET>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Visibility (private and protected fields)">
+ <SUMMARY>Encouraged, use JSDoc annotations <code>@private</code> and
+ <code>@protected</code></SUMMARY>
+ <BODY>
+ <p>We recommend the use of the JSDoc annotations <code>@private</code> and
+ <code>@protected</code> to indicate visibility levels for classes,
+ functions, and properties.</p>
+ <p>The --jscomp_warning=visibility compiler flag turns on compiler
+ warnings for visibility violations. See
+ <a href="https://code.google.com/p/closure-compiler/wiki/Warnings">
+ Closure Compiler
+ Warnings</a>.
+ </p>
+ <p><code>@private</code> global variables and functions are only
+ accessible to code in the same file.</p>
+ <p>Constructors marked <code>@private</code> may only be instantiated by
+ code in the same file and by their static and instance members.
+ <code>@private</code> constructors may also be accessed anywhere in the
+ same file for their public static properties and by the
+ <code>instanceof</code> operator.</p>
+ <p>Global variables, functions, and constructors should never be
+ annotated <code>@protected</code>.</p>
+ <CODE_SNIPPET>
+ // File 1.
+ // AA_PrivateClass_ and AA_init_ are accessible because they are global
+ // and in the same file.
+
+ /**
+ * @private
+ * @constructor
+ */
+ AA_PrivateClass_ = function() {
+ };
+
+ /** @private */
+ function AA_init_() {
+ return new AA_PrivateClass_();
+ }
+
+ AA_init_();
+ </CODE_SNIPPET>
+ <p><code>@private</code> properties are accessible to all code in the
+ same file, plus all static methods and instance methods of that class
+ that "owns" the property, if the property belongs to a class. They
+ cannot be accessed or overridden from a subclass in a different file.</p>
+ <p><code>@protected</code> properties are accessible to all code in the
+ same file, plus any static methods and instance methods of any subclass
+ of a class that "owns" the property.</p>
+ <p>Note that these semantics differ from those of C++ and Java, in that
+ they grant private and protected access to all code in the same file,
+ not just in the same class or class hierarchy. Also, unlike in C++,
+ private properties cannot be overridden by a subclass.
+ </p>
+ <CODE_SNIPPET>
+ // File 1.
+
+ /** @constructor */
+ AA_PublicClass = function() {
+ /** @private */
+ this.privateProp_ = 2;
+
+ /** @protected */
+ this.protectedProp = 4;
+ };
+
+ /** @private */
+ AA_PublicClass.staticPrivateProp_ = 1;
+
+ /** @protected */
+ AA_PublicClass.staticProtectedProp = 31;
+
+ /** @private */
+ AA_PublicClass.prototype.privateMethod_ = function() {};
+
+ /** @protected */
+ AA_PublicClass.prototype.protectedMethod = function() {};
+
+ // File 2.
+
+ /**
+ * @return {number} The number of ducks we've arranged in a row.
+ */
+ AA_PublicClass.prototype.method = function() {
+ // Legal accesses of these two properties.
+ return this.privateProp_ + AA_PublicClass.staticPrivateProp_;
+ };
+
+ // File 3.
+
+ /**
+ * @constructor
+ * @extends {AA_PublicClass}
+ */
+ AA_SubClass = function() {
+ // Legal access of a protected static property.
+ AA_PublicClass.staticProtectedProp = this.method();
+ };
+ goog.inherits(AA_SubClass, AA_PublicClass);
+
+ /**
+ * @return {number} The number of ducks we've arranged in a row.
+ */
+ AA_SubClass.prototype.method = function() {
+ // Legal access of a protected instance property.
+ return this.protectedProp;
+ };
+ </CODE_SNIPPET>
+
+ <p>Notice that in JavaScript, there is no distinction between a type
+ (like <code>AA_PrivateClass_</code>) and the constructor for that
+ type. There is no way to express both that a type is public and its
+ constructor is private (because the constructor could easily be aliased
+ in a way that would defeat the privacy check).</p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="JavaScript Types">
+ <SUMMARY>Encouraged and enforced by the compiler.</SUMMARY>
+ <BODY>
+ <a name="JsTypes"/>
+ <p>When documenting a type in JSDoc, be as specific and accurate as
+ possible. The types we support are based on the
+ <a href="http://wiki.ecmascript.org/doku.php?id=spec:spec">
+ EcmaScript 4 spec</a>.</p>
+ <SUBSECTION title="The JavaScript Type Language">
+ <p>The ES4 proposal contained a language for specifying JavaScript
+ types. We use this language in JsDoc to express the types of
+ function parameters and return values.</p>
+
+ <p>As the ES4 proposal has evolved, this language has changed. The
+ compiler still supports old syntaxes for types, but those syntaxes
+ are deprecated.</p>
+
+ <p/>
+ <table border="1" style="border-collapse:collapse" cellpadding="4">
+ <thead>
+ <tr>
+ <th>Syntax Name</th>
+ <th>Syntax</th>
+ <th>Description</th>
+ <th>Deprecated Syntaxes</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Primitive Type</td>
+ <td>
+ There are 5 primitive types in JavaScript:
+ <code>{null}</code>,
+ <code>{undefined}</code>,
+ <code>{boolean}</code>,
+ <code>{number}</code>, and
+ <code>{string}</code>.
+ </td>
+ <td>Simply the name of a type.</td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>Instance Type</td>
+ <td>
+ <code>{Object}</code><br/>
+ An instance of Object or null.<p/>
+ <code>{Function}</code><br/>
+ An instance of Function or null.<p/>
+ <code>{EventTarget}</code><br/>
+ An instance of a constructor that implements the EventTarget
+ interface, or null.
+ </td>
+ <td>An instance of a constructor or interface function.<p/>
+
+ Constructor functions are functions defined with the
+ <code>@constructor</code> JSDoc tag.
+ Interface functions are functions defined with the
+ <code>@interface</code> JSDoc tag.<p/>
+
+ By default, instance types will accept null. This is the only
+ type syntax that makes the type nullable. Other type syntaxes
+ in this table will not accept null.
+ </td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>Enum Type</td>
+ <td>
+ <code>{goog.events.EventType}</code><br/>
+ One of the properties of the object literal initializer
+ of <code>goog.events.EventType</code>.
+ </td>
+ <td>An enum must be initialized as an object literal, or as
+ an alias of another enum, annotated with the <code>@enum</code>
+ JSDoc tag. The properties of this literal are the instances
+ of the enum. The syntax of the enum is defined
+ <a href="#enums">below</a>.<p/>
+
+ Note that this is one of the few things in our type system
+ that were not in the ES4 spec.
+ </td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>Type Application</td>
+ <td>
+ <code>{Array.<string>}</code><br/>An array of strings.<p/>
+ <code>{Object.<string, number>}</code>
+ <br/>An object in which the keys are strings and the values
+ are numbers.
+ </td>
+ <td>Parameterizes a type, by applying a set of type arguments
+ to that type. The idea is analogous to generics in Java.
+ </td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>Type Union</td>
+ <td>
+ <code>{(number|boolean)}</code><br/>A number or a boolean.
+ </td>
+ <td>Indicates that a value might have type A OR type B.<p/>
+
+ The parentheses may be omitted at the top-level
+ expression, but the parentheses should be included in
+ sub-expressions to avoid ambiguity.<br/>
+ <code>{number|boolean}</code><br/>
+ <code>{function(): (number|boolean)}</code>
+ </td>
+ <td>
+ <code>{(number,boolean)}</code>,<br/>
+ <code>{(number||boolean)}</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td>Nullable type</td>
+ <td>
+ <code>{?number}</code><br/> A number or null.
+ </td>
+ <td>Shorthand for the union of the null type with any
+ other type. This is just syntactic sugar.
+ </td>
+ <td>
+ <code>{number?}</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td>Non-nullable type</td>
+ <td>
+ <code>{!Object}</code><br/> An Object, but never the
+ <code>null</code> value.
+ </td>
+ <td>Filters null out of nullable types. Most often used
+ with instance types, which are nullable by default.
+ </td>
+ <td>
+ <code>{Object!}</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td>Record Type</td>
+ <td>
+ <code>{{myNum: number, myObject}}</code>
+ <br/>An anonymous type with the given type members.
+ </td>
+ <td>
+ <p>Indicates that the value has the specified members with the
+ specified types. In this case, <code>myNum</code> with a
+ type <code>number</code> and <code>myObject</code> with any
+ type.</p>
+ <p>Notice that the braces are part of the type syntax. For
+ example, to denote an <code>Array</code> of objects that
+ have a <code>length</code> property, you might write
+ <code>Array.<{length}></code>.</p>
+ </td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>Function Type</td>
+ <td>
+ <code>{function(string, boolean)}</code><br/>
+ A function that takes two arguments (a string and a boolean),
+ and has an unknown return value.<br/>
+ </td>
+ <td>Specifies a function.</td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>Function Return Type</td>
+ <td>
+ <code>{function(): number}</code><br/>
+ A function that takes no arguments and returns a number.<br/>
+ </td>
+ <td>Specifies a function return type.</td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>Function <code>this</code> Type</td>
+ <td>
+ <code>{function(this:goog.ui.Menu, string)}</code><br/>
+ A function that takes one argument (a string), and executes
+ in the context of a goog.ui.Menu.
+ </td>
+ <td>Specifies the context type of a function type.</td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>Function <code>new</code> Type</td>
+ <td>
+ <code>{function(new:goog.ui.Menu, string)}</code><br/>
+ A constructor that takes one argument (a string), and
+ creates a new instance of goog.ui.Menu when called
+ with the 'new' keyword.
+ </td>
+ <td>Specifies the constructed type of a constructor.</td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>Variable arguments</td>
+ <td>
+ <code>{function(string, ...[number]): number}</code><br/>
+ A function that takes one argument (a string), and then a
+ variable number of arguments that must be numbers.
+ </td>
+ <td>Specifies variable arguments to a function.</td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>
+ <a name="var-args-annotation"/>
+ Variable arguments (in <code>@param</code> annotations)
+ </td>
+ <td>
+ <code>@param {...number} var_args</code><br/>
+ A variable number of arguments to an annotated function.
+ </td>
+ <td>
+ Specifies that the annotated function accepts a variable
+ number of arguments.
+ </td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>Function <a href="#optional">optional arguments</a></td>
+ <td>
+ <code>{function(?string=, number=)}</code><br/>
+ A function that takes one optional, nullable string and one
+ optional number as arguments. The <code>=</code> syntax is
+ only for <code>function</code> type declarations.
+ </td>
+ <td>Specifies optional arguments to a function.</td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>
+ <a name="optional-arg-annotation"/>
+ Function <a href="#optional">optional arguments</a>
+ (in <code>@param</code> annotations)
+ </td>
+ <td>
+ <code>@param {number=} opt_argument</code><br/>
+ An optional parameter of type <code>number</code>.
+ </td>
+ <td>Specifies that the annotated function accepts an optional
+ argument.</td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>The ALL type</td>
+ <td><code>{*}</code></td>
+ <td>Indicates that the variable can take on any type.</td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>The UNKNOWN type</td>
+ <td><code>{?}</code></td>
+ <td>Indicates that the variable can take on any type,
+ and the compiler should not type-check any uses of it.</td>
+ <td/>
+ </tr>
+ </tbody>
+ </table>
+ </SUBSECTION>
+ <SUBSECTION title="Types in JavaScript">
+ <p/>
+ <table border="1" style="border-collapse:collapse" cellpadding="4">
+ <thead>
+ <tr>
+ <th>Type Example</th>
+ <th>Value Examples</th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+
+ <tr>
+ <td>number</td>
+ <td>
+ <CODE_SNIPPET>
+ 1
+ 1.0
+ -5
+ 1e5
+ Math.PI
+ </CODE_SNIPPET>
+ </td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>Number</td>
+ <td>
+ <CODE_SNIPPET>
+ new Number(true)
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ <a href="#Wrapper_objects_for_primitive_types">
+ Number object
+ </a>
+ </td>
+ </tr>
+
+ <tr>
+ <td>string</td>
+ <td>
+ <CODE_SNIPPET>
+ 'Hello'
+ "World"
+ String(42)
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ String value
+ </td>
+ </tr>
+
+ <tr>
+ <td>String</td>
+ <td>
+ <CODE_SNIPPET>
+ new String('Hello')
+ new String(42)
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ <a href="#Wrapper_objects_for_primitive_types">
+ String object
+ </a>
+ </td>
+ </tr>
+
+ <tr>
+ <td>boolean</td>
+ <td>
+ <CODE_SNIPPET>
+ true
+ false
+ Boolean(0)
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Boolean value
+ </td>
+ </tr>
+
+ <tr>
+ <td>Boolean</td>
+ <td>
+ <CODE_SNIPPET>
+ new Boolean(true)
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ <a href="#Wrapper_objects_for_primitive_types">
+ Boolean object
+ </a>
+ </td>
+ </tr>
+
+ <tr>
+ <td>RegExp</td>
+ <td>
+ <CODE_SNIPPET>
+ new RegExp('hello')
+ /world/g
+ </CODE_SNIPPET></td><td>
+ </td>
+ </tr>
+
+ <tr>
+ <td>Date</td>
+ <td>
+ <CODE_SNIPPET>
+ new Date
+ new Date()
+ </CODE_SNIPPET></td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>
+
+ null
+
+ </td>
+ <td>
+ <CODE_SNIPPET>
+ null
+ </CODE_SNIPPET>
+ </td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>
+
+ undefined
+
+ </td>
+ <td>
+ <CODE_SNIPPET>
+ undefined
+ </CODE_SNIPPET>
+ </td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>void</td>
+ <td>
+ <CODE_SNIPPET>
+ function f() {
+ return;
+ }
+ </CODE_SNIPPET>
+ </td>
+ <td>No return value</td>
+ </tr>
+
+ <tr>
+ <td>Array</td>
+ <td>
+ <CODE_SNIPPET>
+ ['foo', 0.3, null]
+ []
+ </CODE_SNIPPET>
+ </td>
+ <td>Untyped Array</td>
+ </tr>
+
+ <tr>
+ <td>Array.<number></td>
+ <td>
+ <CODE_SNIPPET>
+ [11, 22, 33]
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ An Array of numbers
+ </td>
+ </tr>
+
+ <tr>
+ <td>Array.<Array.<string>></td>
+ <td>
+ <CODE_SNIPPET>
+ [['one', 'two', 'three'], ['foo', 'bar']]
+ </CODE_SNIPPET>
+ </td>
+ <td>Array of Arrays of strings</td>
+ </tr>
+
+ <tr>
+ <td>Object</td>
+ <td>
+ <CODE_SNIPPET>
+ {}
+ {foo: 'abc', bar: 123, baz: null}
+ </CODE_SNIPPET>
+ </td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>Object.<string></td>
+ <td>
+ <CODE_SNIPPET>
+ {'foo': 'bar'}
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ An Object in which the values are strings.
+ </td>
+ </tr>
+
+ <tr>
+ <td>Object.<number, string></td>
+ <td>
+ <CODE_SNIPPET>
+ var obj = {};
+ obj[1] = 'bar';
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ An Object in which the keys are numbers and the values are
+ strings. <p/>Note that in JavaScript, the keys are always
+ implicitly converted to strings, so
+ <code>obj['1'] == obj[1]</code>.
+ So the key will always be a string in for...in loops. But the
+ compiler will verify the type of the key when indexing into
+ the object.
+ </td>
+ </tr>
+
+ <tr>
+ <td>Function</td>
+ <td>
+ <CODE_SNIPPET>
+ function(x, y) {
+ return x * y;
+ }
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ <a href="#Wrapper_objects_for_primitive_types">
+ Function object
+ </a>
+ </td>
+ </tr>
+
+ <tr>
+ <td>function(number, number): number</td>
+ <td>
+ <CODE_SNIPPET>
+ function(x, y) {
+ return x * y;
+ }
+ </CODE_SNIPPET>
+ </td>
+ <td>function value</td>
+ </tr>
+
+ <tr>
+ <td><a name="constructor-tag">SomeClass</a></td>
+ <td>
+ <CODE_SNIPPET>
+ /** @constructor */
+ function SomeClass() {}
+
+ new SomeClass();
+ </CODE_SNIPPET>
+ </td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>SomeInterface</td>
+ <td>
+ <CODE_SNIPPET>
+ /** @interface */
+ function SomeInterface() {}
+
+ SomeInterface.prototype.draw = function() {};
+ </CODE_SNIPPET>
+ </td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>project.MyClass</td>
+ <td>
+ <CODE_SNIPPET>
+ /** @constructor */
+ project.MyClass = function () {}
+
+ new project.MyClass()
+ </CODE_SNIPPET>
+ </td>
+ <td/>
+ </tr>
+
+ <tr>
+ <td>project.MyEnum</td>
+ <td>
+ <CODE_SNIPPET>
+ /** @enum {string} */
+ project.MyEnum = {
+ /** The color blue. */
+ BLUE: '#0000dd',
+ /** The color red. */
+ RED: '#dd0000'
+ };
+ </CODE_SNIPPET>
+ </td>
+ <td><a name="enums">Enumeration</a><p/>
+ JSDoc comments on enum values are optional.
+ </td>
+ </tr>
+
+ <tr>
+ <td>Element</td>
+ <td>
+ <CODE_SNIPPET>
+ document.createElement('div')
+ </CODE_SNIPPET>
+ </td>
+ <td>Elements in the DOM.</td>
+ </tr>
+
+ <tr>
+ <td>Node</td>
+ <td>
+ <CODE_SNIPPET>
+ document.body.firstChild
+ </CODE_SNIPPET>
+ </td>
+ <td>Nodes in the DOM.</td>
+ </tr>
+
+ <tr>
+ <td>HTMLInputElement</td>
+ <td>
+ <CODE_SNIPPET>
+ htmlDocument.getElementsByTagName('input')[0]
+ </CODE_SNIPPET>
+ </td>
+ <td>A specific type of DOM element.</td>
+ </tr>
+ </tbody>
+ </table>
+ </SUBSECTION>
+
+ <SUBSECTION title="Type Casts">
+ <p>In cases where type-checking doesn't accurately infer the type of
+ an expression, it is possible to add a type cast comment by adding a
+ type annotation comment and enclosing the expression in
+ parentheses. The parentheses are required.</p>
+
+ <CODE_SNIPPET>
+ /** @type {number} */ (x)
+ </CODE_SNIPPET>
+ </SUBSECTION>
+
+ <SUBSECTION title="Nullable vs. Optional Parameters and Properties">
+ <a name="optional"/>
+ <p>Because JavaScript is a loosely-typed language, it is very
+ important to understand the subtle differences between optional,
+ nullable, and undefined function parameters and class
+ properties.</p>
+
+ <p>Instances of classes and interfaces are nullable by default.
+ For example, the following declaration</p>
+
+ <CODE_SNIPPET>
+ /**
+ * Some class, initialized with a value.
+ * @param {Object} value Some value.
+ * @constructor
+ */
+ function MyClass(value) {
+ /**
+ * Some value.
+ * @type {Object}
+ * @private
+ */
+ this.myValue_ = value;
+ }
+ </CODE_SNIPPET>
+
+ <p>tells the compiler that the <code>myValue_</code> property holds
+ either an Object or null. If <code>myValue_</code> must never be
+ null, it should be declared like this:</p>
+
+ <CODE_SNIPPET>
+ /**
+ * Some class, initialized with a non-null value.
+ * @param {!Object} value Some value.
+ * @constructor
+ */
+ function MyClass(value) {
+ /**
+ * Some value.
+ * @type {!Object}
+ * @private
+ */
+ this.myValue_ = value;
+ }
+ </CODE_SNIPPET>
+
+ <p>This way, if the compiler can determine that somewhere in the code
+ <code>MyClass</code> is initialized with a null value, it will issue
+ a warning.</p>
+
+
+
+ <p>Optional parameters to functions may be undefined at runtime, so if
+ they are assigned to class properties, those properties must be
+ declared accordingly:</p>
+
+ <CODE_SNIPPET>
+ /**
+ * Some class, initialized with an optional value.
+ * @param {Object=} opt_value Some value (optional).
+ * @constructor
+ */
+ function MyClass(opt_value) {
+ /**
+ * Some value.
+ * @type {Object|undefined}
+ * @private
+ */
+ this.myValue_ = opt_value;
+ }
+ </CODE_SNIPPET>
+
+ <p>This tells the compiler that <code>myValue_</code> may hold an
+ Object, null, or remain undefined.</p>
+
+ <p>Note that the optional parameter <code>opt_value</code> is declared
+ to be of type <code>{Object=}</code>, not
+ <code>{Object|undefined}</code>. This is because optional
+ parameters may, by definition, be undefined. While there is no harm
+ in explicitly declaring an optional parameter as possibly undefined,
+ it is both unnecessary and makes the code harder to read.</p>
+
+ <p>Finally, note that being nullable and being optional are orthogonal
+ properties. The following four declarations are all different:</p>
+
+ <CODE_SNIPPET>
+ /**
+ * Takes four arguments, two of which are nullable, and two of which are
+ * optional.
+ * @param {!Object} nonNull Mandatory (must not be undefined), must not be null.
+ * @param {Object} mayBeNull Mandatory (must not be undefined), may be null.
+ * @param {!Object=} opt_nonNull Optional (may be undefined), but if present,
+ * must not be null!
+ * @param {Object=} opt_mayBeNull Optional (may be undefined), may be null.
+ */
+ function strangeButTrue(nonNull, mayBeNull, opt_nonNull, opt_mayBeNull) {
+ // ...
+ };
+ </CODE_SNIPPET>
+ </SUBSECTION>
+
+ <SUBSECTION title="Typedefs">
+ <a name="Typedefs"/>
+ <p>Sometimes types can get complicated. A function that accepts
+ content for an Element might look like:</p>
+
+ <CODE_SNIPPET>
+ /**
+ * @param {string} tagName
+ * @param {(string|Element|Text|Array.<Element>|Array.<Text>)} contents
+ * @return {!Element}
+ */
+ goog.createElement = function(tagName, contents) {
+ ...
+ };
+ </CODE_SNIPPET>
+
+ <p>You can define commonly used type expressions with a
+ <code>@typedef</code> tag. For example,</p>
+
+ <CODE_SNIPPET>
+ /** @typedef {(string|Element|Text|Array.<Element>|Array.<Text>)} */
+ goog.ElementContent;
+
+ /**
+ * @param {string} tagName
+ * @param {goog.ElementContent} contents
+ * @return {!Element}
+ */
+ goog.createElement = function(tagName, contents) {
+ ...
+ };
+ </CODE_SNIPPET>
+ </SUBSECTION>
+
+ <SUBSECTION title="Template types">
+ <a name="Template_types"/>
+ <p>The compiler has limited support for template types. It can only
+ infer the type of <code>this</code> inside an anonymous function
+ literal from the type of the <code>this</code> argument and whether the
+ <code>this</code> argument is missing.</p>
+
+ <CODE_SNIPPET>
+ /**
+ * @param {function(this:T, ...)} fn
+ * @param {T} thisObj
+ * @param {...*} var_args
+ * @template T
+ */
+ goog.bind = function(fn, thisObj, var_args) {
+ ...
+ };
+ // Possibly generates a missing property warning.
+ goog.bind(function() { this.someProperty; }, new SomeClass());
+ // Generates an undefined this warning.
+ goog.bind(function() { this.someProperty; });
+ </CODE_SNIPPET>
+ </SUBSECTION>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Comments">
+ <SUMMARY>Use JSDoc</SUMMARY>
+ <BODY>
+ <p>
+ We follow the
+ <a href="cppguide.html#Comments">
+ C++ style for comments</a> in spirit.
+ </p>
+
+ <p>All files, classes, methods and properties should be documented with
+ <a href="https://code.google.com/p/jsdoc-toolkit/">JSDoc</a>
+ comments with the appropriate <a href="#JSDoc_Tag_Reference">tags</a>
+ and <a href="#JsTypes">types</a>. Textual descriptions for properties,
+ methods, method parameters and method return values should be included
+ unless obvious from the property, method, or parameter name.
+ </p>
+
+ <p>Inline comments should be of the <code>//</code> variety.</p>
+
+ <p>Complete sentences are recommended but not required.
+ Complete sentences should use appropriate capitalization
+ and punctuation.</p>
+
+ <SUBSECTION title="Comment Syntax">
+ <p>The JSDoc syntax is based on
+ <a href="https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html">
+ JavaDoc</a>. Many tools extract metadata from JSDoc comments to
+ perform code validation and optimizations. These comments must be
+ well-formed.</p>
+
+ <CODE_SNIPPET>
+ /**
+ * A JSDoc comment should begin with a slash and 2 asterisks.
+ * Inline tags should be enclosed in braces like {@code this}.
+ * @desc Block tags should always start on their own line.
+ */
+ </CODE_SNIPPET>
+ </SUBSECTION>
+
+ <SUBSECTION title="JSDoc Indentation">
+ <p>If you have to line break a block tag, you should treat this as
+ breaking a code statement and indent it four spaces.</p>
+
+ <CODE_SNIPPET>
+ /**
+ * Illustrates line wrapping for long param/return descriptions.
+ * @param {string} foo This is a param with a description too long to fit in
+ * one line.
+ * @return {number} This returns something that has a description too long to
+ * fit in one line.
+ */
+ project.MyClass.prototype.method = function(foo) {
+ return 5;
+ };
+ </CODE_SNIPPET>
+
+ <p>You should not indent the <code>@fileoverview</code> command. You do not have to
+ indent the <code>@desc</code> command.</p>
+
+ <p>Even though it is not preferred, it is also acceptable to line up
+ the description.</p>
+
+ <CODE_SNIPPET>
+ /**
+ * This is NOT the preferred indentation method.
+ * @param {string} foo This is a param with a description too long to fit in
+ * one line.
+ * @return {number} This returns something that has a description too long to
+ * fit in one line.
+ */
+ project.MyClass.prototype.method = function(foo) {
+ return 5;
+ };
+ </CODE_SNIPPET>
+ </SUBSECTION>
+
+ <SUBSECTION title="HTML in JSDoc">
+ <p>Like JavaDoc, JSDoc supports many HTML tags, like <code>,
+ <pre>, <tt>, <strong>, <ul>, <ol>,
+ <li>, <a>, and others.</p>
+
+ <p>This means that plaintext formatting is not respected. So, don't
+ rely on whitespace to format JSDoc:</p>
+
+ <BAD_CODE_SNIPPET>
+ /**
+ * Computes weight based on three factors:
+ * items sent
+ * items received
+ * last timestamp
+ */
+ </BAD_CODE_SNIPPET>
+
+ <p>It'll come out like this:</p>
+
+ <BAD_CODE_SNIPPET>
+ Computes weight based on three factors: items sent items received last timestamp
+ </BAD_CODE_SNIPPET>
+
+ <p>Instead, do this:</p>
+
+ <CODE_SNIPPET>
+ /**
+ * Computes weight based on three factors:
+ * <ul>
+ * <li>items sent
+ * <li>items received
+ * <li>last timestamp
+ * </ul>
+ */
+ </CODE_SNIPPET>
+
+ The <a href="https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html">
+ JavaDoc</a> style guide is a useful resource on how to write
+ well-formed doc comments.
+ </SUBSECTION>
+
+ <SUBSECTION title="Top/File-Level Comments">
+ <p>
+
+ A <a href="copyright.html">copyright notice</a> and author information are optional.
+ File overviews are generally recommended whenever a file consists of
+ more than a single class definition. The top level comment is
+ designed to orient readers unfamiliar with the code to what is in
+ this file. If present, it should provide a description of the
+ file's contents and any dependencies or compatibility information.
+ As an example:
+ </p>
+
+ <CODE_SNIPPET>
+ /**
+ * @fileoverview Description of file, its uses and information
+ * about its dependencies.
+ */
+ </CODE_SNIPPET>
+
+
+ </SUBSECTION>
+
+ <SUBSECTION title="Class Comments">
+ <p>Classes must be documented with a description and a
+ <a href="#constructor-tag">type tag that
+ identifies the constructor</a>.
+ </p>
+
+ <CODE_SNIPPET>
+ /**
+ * Class making something fun and easy.
+ * @param {string} arg1 An argument that makes this more interesting.
+ * @param {Array.<number>} arg2 List of numbers to be processed.
+ * @constructor
+ * @extends {goog.Disposable}
+ */
+ project.MyClass = function(arg1, arg2) {
+ // ...
+ };
+ goog.inherits(project.MyClass, goog.Disposable);
+ </CODE_SNIPPET>
+ </SUBSECTION>
+
+ <SUBSECTION title="Method and Function Comments">
+ <p>Parameter and return types should be documented. The method
+ description may be omitted if it is obvious from the parameter
+ or return type descriptions. Method descriptions should start
+ with a sentence written in the third person declarative voice.</p>
+ <CODE_SNIPPET>
+ /**
+ * Operates on an instance of MyClass and returns something.
+ * @param {project.MyClass} obj Instance of MyClass which leads to a long
+ * comment that needs to be wrapped to two lines.
+ * @return {boolean} Whether something occurred.
+ */
+ function PR_someMethod(obj) {
+ // ...
+ }
+ </CODE_SNIPPET>
+ </SUBSECTION>
+
+ <SUBSECTION title="Property Comments">
+ <CODE_SNIPPET>
+ /** @constructor */
+ project.MyClass = function() {
+ /**
+ * Maximum number of things per pane.
+ * @type {number}
+ */
+ this.someProperty = 4;
+ }
+ </CODE_SNIPPET>
+ </SUBSECTION>
+
+ <SUBSECTION title="JSDoc Tag Reference">
+ <a name="JSDoc_Tag_Reference"/>
+ <p/>
+ <table border="1" style="border-collapse:collapse" cellpadding="4">
+ <thead>
+ <tr>
+ <th>Tag</th>
+ <th>Template & Examples</th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>
+ <a name="tag-author">@author</a>
+
+ </td>
+ <td>
+ <code>@author username@google.com (first last)</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * @fileoverview Utilities for handling textareas.
+ * @author kuth@google.com (Uthur Pendragon)
+ */
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Document the author of a file or the owner of a test,
+ generally only used in the <code>@fileoverview</code> comment.
+
+ </td>
+ </tr>
+
+
+
+ <tr>
+ <td><a name="tag-code">@code</a></td>
+ <td>
+ <code>{@code ...}</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * Moves to the next position in the selection.
+ * Throws {@code goog.iter.StopIteration} when it
+ * passes the end of the range.
+ * @return {Node} The node at the next position.
+ */
+ goog.dom.RangeIterator.prototype.next = function() {
+ // ...
+ };
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Indicates that a term in a JSDoc description is code so it may
+ be correctly formatted in generated documentation.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-const">@const</a></td>
+ <td>
+ <code>@const</code><br/>
+ <code>@const {type}</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /** @const */ var MY_BEER = 'stout';
+
+ /**
+ * My namespace's favorite kind of beer.
+ * @const {string}
+ */
+ mynamespace.MY_BEER = 'stout';
+
+ /** @const */ MyClass.MY_BEER = 'stout';
+
+ /**
+ * Initializes the request.
+ * @const
+ */
+ mynamespace.Request.prototype.initialize = function() {
+ // This method cannot be overridden in a subclass.
+ };
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ <p>Marks a variable (or property) as read-only and suitable
+ for inlining.</p>
+
+ <p>A <code>@const</code> variable is an immutable pointer to
+ a value. If a variable or property marked as
+ <code>@const</code> is overwritten, JSCompiler will give
+ warnings.</p>
+
+ <p>The type declaration of a constant value can be omitted
+ if it can be clearly inferred. An additional comment about
+ the variable is optional.</p>
+
+ <p>When <code>@const</code> is applied to a method, it
+ implies the method is not only not overwritable, but also
+ that the method is <em>finalized</em> —
+ not overridable in subclasses.</p>
+
+ <p>For more on <code>@const</code>, see the
+ <a href="#Constants">Constants</a> section.</p>
+
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-constructor">@constructor</a></td>
+ <td>
+ <code>@constructor</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * A rectangle.
+ * @constructor
+ */
+ function GM_Rect() {
+ ...
+ }
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Used in a class's documentation to indicate the constructor.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-define">@define</a></td>
+ <td>
+ <code>@define {Type} description</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /** @define {boolean} */
+ var TR_FLAGS_ENABLE_DEBUG = true;
+
+ /**
+ * @define {boolean} Whether we know at compile-time that
+ * the browser is IE.
+ */
+ goog.userAgent.ASSUME_IE = false;
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Indicates a constant that can be overridden by the compiler at
+ compile-time. In the example, the compiler flag
+ <code>--define='goog.userAgent.ASSUME_IE=true'</code>
+ could be specified in the BUILD file to indicate that the
+ constant <code>goog.userAgent.ASSUME_IE</code> should be replaced
+ with <code>true</code>.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-deprecated">@deprecated</a></td>
+ <td>
+ <code>@deprecated Description</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * Determines whether a node is a field.
+ * @return {boolean} True if the contents of
+ * the element are editable, but the element
+ * itself is not.
+ * @deprecated Use isField().
+ */
+ BN_EditUtil.isTopEditableField = function(node) {
+ // ...
+ };
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Used to tell that a function, method or property should not be
+ used any more. Always provide instructions on what callers
+ should use instead.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-dict">@dict</a></td>
+ <td>
+ <code>@dict Description</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * @constructor
+ * @dict
+ */
+ function Foo(x) {
+ this['x'] = x;
+ }
+ var obj = new Foo(123);
+ var num = obj.x; // warning
+
+ (/** @dict */ { x: 1 }).x = 123; // warning
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ When a constructor (<code>Foo</code> in the example) is
+ annotated with <code>@dict</code>, you can only use the
+ bracket notation to access the properties of <code>Foo</code>
+ objects.
+ The annotation can also be used directly on object literals.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-enum">@enum</a></td>
+ <td>
+ <code>@enum {Type}</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * Enum for tri-state values.
+ * @enum {number}
+ */
+ project.TriState = {
+ TRUE: 1,
+ FALSE: -1,
+ MAYBE: 0
+ };
+ </CODE_SNIPPET>
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-export">@export</a></td>
+ <td>
+ <code>@export</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /** @export */
+ foo.MyPublicClass.prototype.myPublicMethod = function() {
+ // ...
+ };
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ <p>Given the code on the left, when the compiler is run with
+ the <code>--generate_exports</code> flag, it will generate the
+ code:</p>
+ <CODE_SNIPPET>
+ goog.exportSymbol('foo.MyPublicClass.prototype.myPublicMethod',
+ foo.MyPublicClass.prototype.myPublicMethod);
+ </CODE_SNIPPET>
+ <p>which will export the symbols to uncompiled code.
+ Code that uses the <code>@export</code> annotation must either</p>
+ <ol>
+ <li>include <code>//javascript/closure/base.js</code>, or</li>
+ <li>define both <code>goog.exportSymbol</code> and
+ <code>goog.exportProperty</code> with the same method
+ signature in their own codebase.</li>
+ </ol>
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-expose">@expose</a></td>
+ <td>
+ <code>@expose</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /** @expose */
+ MyClass.prototype.exposedProperty = 3;
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ <p>
+ Declares an exposed property. Exposed properties
+ will not be removed, or renamed, or collapsed,
+ or optimized in any way by the compiler. No properties
+ with the same name will be able to be optimized either.
+ </p>
+
+ <p>
+ <code>@expose</code> should never be used in library code,
+ because it will prevent that property from ever getting
+ removed.
+ </p>
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-extends">@extends</a></td>
+ <td>
+ <code>
+ @extends Type<br/>
+ @extends {Type}
+ </code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * Immutable empty node list.
+ * @constructor
+ * @extends goog.ds.BasicNodeList
+ */
+ goog.ds.EmptyNodeList = function() {
+ ...
+ };
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Used with <code>@constructor</code> to indicate that a class
+ inherits from another class. Curly braces around the type are
+ optional.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-externs">@externs</a></td>
+ <td>
+ <code>@externs</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * @fileoverview This is an externs file.
+ * @externs
+ */
+
+ var document;
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ <p>
+ Declares an
+
+ externs file.
+ </p>
+
+
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-fileoverview">@fileoverview</a></td>
+ <td>
+ <code>@fileoverview Description</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * @fileoverview Utilities for doing things that require this very long
+ * but not indented comment.
+ * @author kuth@google.com (Uthur Pendragon)
+ */
+ </CODE_SNIPPET>
+ </td>
+ <td>Makes the comment block provide file level information.</td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-implements">@implements</a></td>
+ <td>
+ <code>
+ @implements Type<br/>
+ @implements {Type}
+ </code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * A shape.
+ * @interface
+ */
+ function Shape() {};
+ Shape.prototype.draw = function() {};
+
+ /**
+ * @constructor
+ * @implements {Shape}
+ */
+ function Square() {};
+ Square.prototype.draw = function() {
+ ...
+ };
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Used with <code>@constructor</code> to indicate that a class
+ implements an interface. Curly braces around the type are
+ optional.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-inheritDoc">@inheritDoc</a></td>
+ <td>
+ <code>@inheritDoc</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /** @inheritDoc */
+ project.SubClass.prototype.toString() {
+ // ...
+ };
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ <p style="font-weight:bold">Deprecated. Use
+ <code>@override</code> instead.</p>
+
+ Indicates that a method or property of a subclass
+ intentionally hides a method or property of the superclass,
+ and has exactly the same documentation. Notice that
+ <code>@inheritDoc</code> implies <code>@override</code>
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-interface">@interface</a></td>
+ <td>
+ <code>@interface</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * A shape.
+ * @interface
+ */
+ function Shape() {};
+ Shape.prototype.draw = function() {};
+
+ /**
+ * A polygon.
+ * @interface
+ * @extends {Shape}
+ */
+ function Polygon() {};
+ Polygon.prototype.getSides = function() {};
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Used to indicate that the function defines an interface.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-lends">@lends</a></td>
+ <td>
+ <code>@lends objectName</code><br/>
+ <code>@lends {objectName}</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ goog.object.extend(
+ Button.prototype,
+ /** @lends {Button.prototype} */ {
+ isButton: function() { return true; }
+ });
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Indicates that the keys of an object literal should
+ be treated as properties of some other object. This annotation
+ should only appear on object literals.<p/>
+
+ Notice that the name in braces is not a type name like
+ in other annotations. It's an object name. It names
+ the object on which the properties are "lent".
+ For example, <code>@type {Foo}</code> means "an instance of Foo",
+ but <code>@lends {Foo}</code> means "the constructor Foo".<p/>
+
+ The <a href="https://code.google.com/p/jsdoc-toolkit/wiki/TagLends">
+ JSDoc Toolkit docs</a> have more information on this
+ annotation.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-license">@license</a> or
+ <a name="tag-preserve">@preserve</a></td>
+ <td>
+ <code>@license Description</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * @preserve Copyright 2009 SomeThirdParty.
+ * Here is the full license text and copyright
+ * notice for this file. Note that the notice can span several
+ * lines and is only terminated by the closing star and slash:
+ */
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Anything marked by <code>@license</code> or
+ <code>@preserve</code> will be retained by the compiler and
+ output at the top of the compiled code for that file. This
+ annotation allows important notices (such as legal licenses or
+ copyright text) to survive compilation unchanged. Line breaks
+ are preserved.
+ </td>
+ </tr>
+
+
+
+
+
+ <tr>
+ <td><a name="tag-noalias">@noalias</a></td>
+ <td>
+ <code>@noalias</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /** @noalias */
+ function Range() {}
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Used in an externs file to indicate to the compiler that the
+ variable or function should not be aliased as part of the
+ alias externals pass of the compiler.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-nocompile">@nocompile</a></td>
+ <td>
+ <code>@nocompile</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /** @nocompile */
+
+ // JavaScript code
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Used at the top of a file to tell the compiler to parse this
+ file but not compile it.
+ Code that is not meant for compilation and should be omitted
+ from compilation tests (such as bootstrap code) uses this
+ annotation.
+ Use sparingly.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-nosideeffects">@nosideeffects</a></td>
+ <td>
+ <code>@nosideeffects</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /** @nosideeffects */
+ function noSideEffectsFn1() {
+ // ...
+ }
+
+ /** @nosideeffects */
+ var noSideEffectsFn2 = function() {
+ // ...
+ };
+
+ /** @nosideeffects */
+ a.prototype.noSideEffectsFn3 = function() {
+ // ...
+ };
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ This annotation can be used as part of function and
+ constructor declarations to indicate that calls to the
+ declared function have no side-effects. This annotation
+ allows the compiler to remove calls to these functions if the
+ return value is not used.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-override">@override</a></td>
+ <td>
+ <code>@override</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * @return {string} Human-readable representation of project.SubClass.
+ * @override
+ */
+ project.SubClass.prototype.toString = function() {
+ // ...
+ };
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Indicates that a method or property of a subclass
+ intentionally hides a method or property of the superclass. If
+ no other documentation is included, the method or property
+ also inherits documentation from its superclass.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-param">@param</a></td>
+ <td>
+ <code>@param {Type} varname Description</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * Queries a Baz for items.
+ * @param {number} groupNum Subgroup id to query.
+ * @param {string|number|null} term An itemName,
+ * or itemId, or null to search everything.
+ */
+ goog.Baz.prototype.query = function(groupNum, term) {
+ // ...
+ };
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Used with method, function and constructor calls to document
+ the arguments of a function.<p/>
+
+ <a href="#JsTypes">Type</a>
+ names must be enclosed in curly braces. If the type
+ is omitted, the compiler will not type-check the parameter.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-private">@private</a></td>
+ <td>
+ <code>@private</code><br/>
+ <code>@private {type}</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * Handlers that are listening to this logger.
+ * @private {!Array.<Function>}
+ */
+ this.handlers_ = [];
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Used in conjunction with a trailing underscore on the method
+ or property name to indicate that the member is
+ <a href="#Visibility__private_and_protected_fields_">private</a> and final.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-protected">@protected</a></td>
+ <td>
+ <code>@protected</code><br/>
+ <code>@protected {type}</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * Sets the component's root element to the given element.
+ * @param {Element} element Root element for the component.
+ * @protected
+ */
+ goog.ui.Component.prototype.setElementInternal = function(element) {
+ // ...
+ };
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Used to indicate that the member or property is
+ <a href="#Visibility__private_and_protected_fields_">protected</a>.
+ Should be used in conjunction with names with no trailing
+ underscore.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-public">@public</a></td>
+ <td>
+ <code>@public</code><br/>
+ <code>@public {type}</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * Whether to cancel the event in internal capture/bubble processing.
+ * @public {boolean}
+ * @suppress {visiblity} Referencing this outside this package is strongly
+ * discouraged.
+ */
+ goog.events.Event.prototype.propagationStopped_ = false;
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Used to indicate that the member or property is public. Variables and
+ properties are public by default, so this annotation is rarely necessary.
+ Should only be used in legacy code that cannot be easily changed to
+ override the visibility of members that were named as private variables.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-return">@return</a></td>
+ <td>
+ <code>@return {Type} Description</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * @return {string} The hex ID of the last item.
+ */
+ goog.Baz.prototype.getLastId = function() {
+ // ...
+ return id;
+ };
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Used with method and function calls to document the return
+ type. When writing descriptions for boolean parameters,
+ prefer "Whether the component is visible" to "True if the
+ component is visible, false otherwise". If there is no return
+ value, do not use an <code>@return</code> tag.<p/>
+
+ <a href="#JsTypes">Type</a>
+ names must be enclosed in curly braces. If the type
+ is omitted, the compiler will not type-check the return value.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-see">@see</a></td>
+ <td>
+ <code>@see Link</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * Adds a single item, recklessly.
+ * @see #addSafely
+ * @see goog.Collect
+ * @see goog.RecklessAdder#add
+ ...
+ </CODE_SNIPPET>
+ </td>
+ <td>Reference a lookup to another class function or method.</td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-struct">@struct</a></td>
+ <td>
+ <code>@struct Description</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * @constructor
+ * @struct
+ */
+ function Foo(x) {
+ this.x = x;
+ }
+ var obj = new Foo(123);
+ var num = obj['x']; // warning
+ obj.y = "asdf"; // warning
+
+ Foo.prototype = /** @struct */ {
+ method1: function() {}
+ };
+ Foo.prototype.method2 = function() {}; // warning
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ When a constructor (<code>Foo</code> in the example) is
+ annotated with <code>@struct</code>, you can only use the dot
+ notation to access the properties of <code>Foo</code> objects.
+ Also, you cannot add new properties to <code>Foo</code>
+ objects after they have been created.
+ The annotation can also be used directly on object literals.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-supported">@supported</a></td>
+ <td>
+ <code>@supported Description</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * @fileoverview Event Manager
+ * Provides an abstracted interface to the
+ * browsers' event systems.
+ * @supported So far tested in IE6 and FF1.5
+ */
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Used in a fileoverview to indicate what browsers are supported
+ by the file.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-suppress">@suppress</a></td>
+ <td>
+ <code>
+ @suppress {warning1|warning2}
+ </code>
+ <code>
+ @suppress {warning1,warning2}
+ </code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * @suppress {deprecated}
+ */
+ function f() {
+ deprecatedVersionOfF();
+ }
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Suppresses warnings from tools. Warning categories are
+ separated by <code>|</code> or <code>,</code>.
+
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-template">@template</a></td>
+ <td>
+ <code>@template</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * @param {function(this:T, ...)} fn
+ * @param {T} thisObj
+ * @param {...*} var_args
+ * @template T
+ */
+ goog.bind = function(fn, thisObj, var_args) {
+ ...
+ };
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ This annotation can be used to declare a
+ <a href="#Template_types">template typename</a>.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-this">@this</a></td>
+ <td>
+ <code>
+ @this Type<br/>
+ @this {Type}
+ </code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ pinto.chat.RosterWidget.extern('getRosterElement',
+ /**
+ * Returns the roster widget element.
+ * @this pinto.chat.RosterWidget
+ * @return {Element}
+ */
+ function() {
+ return this.getWrappedComponent_().getElement();
+ });
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ The type of the object in whose context a particular method is
+ called. Required when the <code>this</code> keyword is referenced
+ from a function that is not a prototype method.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-type">@type</a></td>
+ <td>
+ <code>
+ @type Type<br/>
+ @type {Type}
+ </code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /**
+ * The message hex ID.
+ * @type {string}
+ */
+ var hexId = hexId;
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ Identifies the <a href="#JsTypes">type</a> of a variable,
+ property, or expression. Curly braces are not required around
+ most types, but some projects mandate them for all types, for
+ consistency.
+ </td>
+ </tr>
+
+ <tr>
+ <td><a name="tag-typedef">@typedef</a></td>
+ <td>
+ <code>@typedef</code>
+ <p><i>For example:</i></p>
+ <CODE_SNIPPET>
+ /** @typedef {(string|number)} */
+ goog.NumberLike;
+
+ /** @param {goog.NumberLike} x A number or a string. */
+ goog.readNumber = function(x) {
+ ...
+ }
+ </CODE_SNIPPET>
+ </td>
+ <td>
+ This annotation can be used to declare an alias of a more
+ <a href="#Typedefs">complex type</a>.
+ </td>
+ </tr>
+
+
+
+ </tbody>
+ </table>
+
+
+
+ <p>
+ You may also see other types of JSDoc annotations in third-party
+ code. These annotations appear in the
+ <a href="https://code.google.com/p/jsdoc-toolkit/wiki/TagReference">
+ JSDoc Toolkit Tag Reference
+ </a>
+ but are currently discouraged in Google code. You should consider
+ them "reserved" names for future use. These include:
+ <ul>
+ <li>@augments</li>
+ <li>@argument</li>
+ <li>@borrows</li>
+ <li>@class</li>
+ <li>@constant</li>
+ <li>@constructs</li>
+ <li>@default</li>
+ <li>@event</li>
+ <li>@example</li>
+ <li>@field</li>
+ <li>@function</li>
+ <li>@ignore</li>
+ <li>@inner</li>
+ <li>@link</li>
+ <li>@memberOf</li>
+ <li>@name</li>
+ <li>@namespace</li>
+ <li>@property</li>
+ <li>@public</li>
+ <li>@requires</li>
+ <li>@returns</li>
+ <li>@since</li>
+ <li>@static</li>
+ <li>@version</li>
+ </ul>
+ </p>
+ </SUBSECTION>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Providing Dependencies With goog.provide">
+ <SUMMARY>
+ Only provide top-level symbols.
+ </SUMMARY>
+ <BODY>
+ <p>
+ All members defined on a class should be in the same file. So, only
+ top-level classes should be provided in a file that contains multiple
+ members defined on the same class (e.g. enums, inner classes, etc).
+ </p>
+ <p>Do this:</p>
+ <CODE_SNIPPET>
+ goog.provide('namespace.MyClass');
+ </CODE_SNIPPET>
+ <p>Not this:</p>
+ <BAD_CODE_SNIPPET>
+ goog.provide('namespace.MyClass');
+ goog.provide('namespace.MyClass.Enum');
+ goog.provide('namespace.MyClass.InnerClass');
+ goog.provide('namespace.MyClass.TypeDef');
+ goog.provide('namespace.MyClass.CONSTANT');
+ goog.provide('namespace.MyClass.staticMethod');
+ </BAD_CODE_SNIPPET>
+ <p>
+ Members on namespaces may also be provided:
+ </p>
+ <CODE_SNIPPET>
+ goog.provide('foo.bar');
+ goog.provide('foo.bar.method');
+ goog.provide('foo.bar.CONSTANT');
+ </CODE_SNIPPET>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Compiling">
+ <SUMMARY>Required</SUMMARY>
+ <BODY>
+
+
+ <p>Use of JS compilers such as the
+ <a href="https://code.google.com/closure/compiler/">Closure Compiler</a>
+ is required for all customer-facing code.</p>
+
+
+
+
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Tips and Tricks">
+ <SUMMARY>JavaScript tidbits</SUMMARY>
+ <BODY>
+ <SUBSECTION title="True and False Boolean Expressions">
+ <p>The following are all false in boolean expressions:</p>
+ <ul>
+ <li><code>null</code></li>
+ <li><code>undefined</code></li>
+ <li><code>''</code> the empty string</li>
+ <li><code>0</code> the number</li>
+ </ul>
+ <p>But be careful, because these are all true:</p>
+ <ul>
+ <li><code>'0'</code> the string</li>
+ <li><code>[]</code> the empty array</li>
+ <li><code>{}</code> the empty object</li>
+ </ul>
+
+ <p>This means that instead of this:</p>
+ <BAD_CODE_SNIPPET>
+ while (x != null) {
+ </BAD_CODE_SNIPPET>
+ <p>you can write this shorter code (as long as you don't expect x to
+ be 0, or the empty string, or false):</p>
+ <CODE_SNIPPET>
+ while (x) {
+ </CODE_SNIPPET>
+
+ <p>And if you want to check a string to see if it is null or empty,
+ you could do this:</p>
+ <BAD_CODE_SNIPPET>
+ if (y != null && y != '') {
+ </BAD_CODE_SNIPPET>
+ <p>But this is shorter and nicer:</p>
+ <CODE_SNIPPET>
+ if (y) {
+ </CODE_SNIPPET>
+
+ <p><strong>Caution:</strong> There are many unintuitive things about
+ boolean expressions. Here are some of them:</p>
+ <ul>
+ <li><code>
+ Boolean('0') == true<br/>
+ '0' != true</code></li>
+ <li><code>
+ 0 != null<br/>
+ 0 == []<br/>
+ 0 == false</code></li>
+ <li><code>
+ Boolean(null) == false<br/>
+ null != true<br/>
+ null != false</code></li>
+ <li><code>
+ Boolean(undefined) == false<br/>
+ undefined != true<br/>
+ undefined != false</code></li>
+ <li><code>
+ Boolean([]) == true<br/>
+ [] != true<br/>
+ [] == false</code></li>
+ <li><code>
+ Boolean({}) == true<br/>
+ {} != true<br/>
+ {} != false</code></li>
+ </ul>
+ </SUBSECTION>
+
+ <SUBSECTION title="Conditional (Ternary) Operator (?:)">
+ <p>Instead of this:</p>
+ <CODE_SNIPPET>
+ if (val) {
+ return foo();
+ } else {
+ return bar();
+ }
+ </CODE_SNIPPET>
+ <p>you can write this:</p>
+ <CODE_SNIPPET>
+ return val ? foo() : bar();
+ </CODE_SNIPPET>
+
+ <p>The ternary conditional is also useful when generating HTML:</p>
+ <CODE_SNIPPET>
+ var html = '<input type="checkbox"' +
+ (isChecked ? ' checked' : '') +
+ (isEnabled ? '' : ' disabled') +
+ ' name="foo">';
+ </CODE_SNIPPET>
+ </SUBSECTION>
+
+ <SUBSECTION title="&& and ||">
+ <p>These binary boolean operators are short-circuited, and evaluate
+ to the last evaluated term.</p>
+
+ <p>"||" has been called the 'default' operator, because instead of
+ writing this:</p>
+ <BAD_CODE_SNIPPET>
+ /** @param {*=} opt_win */
+ function foo(opt_win) {
+ var win;
+ if (opt_win) {
+ win = opt_win;
+ } else {
+ win = window;
+ }
+ // ...
+ }
+ </BAD_CODE_SNIPPET>
+ <p>you can write this:</p>
+ <CODE_SNIPPET>
+ /** @param {*=} opt_win */
+ function foo(opt_win) {
+ var win = opt_win || window;
+ // ...
+ }
+ </CODE_SNIPPET>
+
+ <p>"&&" is also useful for shortening code. For instance,
+ instead of this:</p>
+ <BAD_CODE_SNIPPET>
+ if (node) {
+ if (node.kids) {
+ if (node.kids[index]) {
+ foo(node.kids[index]);
+ }
+ }
+ }
+ </BAD_CODE_SNIPPET>
+
+ <p>you could do this:</p>
+ <CODE_SNIPPET>
+ if (node && node.kids && node.kids[index]) {
+ foo(node.kids[index]);
+ }
+ </CODE_SNIPPET>
+
+ <p>or this:</p>
+ <CODE_SNIPPET>
+ var kid = node && node.kids && node.kids[index];
+ if (kid) {
+ foo(kid);
+ }
+ </CODE_SNIPPET>
+
+ <p>However, this is going a little too far:</p>
+ <BAD_CODE_SNIPPET>
+ node && node.kids && node.kids[index] && foo(node.kids[index]);
+ </BAD_CODE_SNIPPET>
+ </SUBSECTION>
+
+ <SUBSECTION title="Iterating over Node Lists">
+ <p>Node lists are often implemented as node iterators with a filter.
+ This means that getting a property like length is O(n), and
+ iterating over the list by re-checking the length will be
+ O(n^2).</p>
+ <BAD_CODE_SNIPPET>
+ var paragraphs = document.getElementsByTagName('p');
+ for (var i = 0; i < paragraphs.length; i++) {
+ doSomething(paragraphs[i]);
+ }
+ </BAD_CODE_SNIPPET>
+
+ <p>It is better to do this instead:</p>
+ <CODE_SNIPPET>
+ var paragraphs = document.getElementsByTagName('p');
+ for (var i = 0, paragraph; paragraph = paragraphs[i]; i++) {
+ doSomething(paragraph);
+ }
+ </CODE_SNIPPET>
+
+ <p>This works well for all collections and arrays as long as the array
+ does not contain things that are treated as boolean false.</p>
+
+ <p>In cases where you are iterating over the childNodes you can also
+ use the firstChild and nextSibling properties.</p>
+ <CODE_SNIPPET>
+ var parentNode = document.getElementById('foo');
+ for (var child = parentNode.firstChild; child; child = child.nextSibling) {
+ doSomething(child);
+ }
+ </CODE_SNIPPET>
+ </SUBSECTION>
+ </BODY>
+ </STYLEPOINT>
+ </CATEGORY>
+
+
+
+ <PARTING_WORDS>
+ <p>
+ <em>BE CONSISTENT</em>.
+ </p>
+
+ <p>
+ If you're editing code, take a few minutes to look at the code
+ around you and determine its style. If they use spaces around
+ all their arithmetic operators, you should too. If their
+ comments have little boxes of hash marks around them, make your
+ comments have little boxes of hash marks around them too.
+ </p>
+
+ <p>
+ The point of having style guidelines is to have a common vocabulary
+ of coding so people can concentrate on what you're saying rather
+ than on how you're saying it. We present global style rules here so
+ people know the vocabulary, but local style is also important. If
+ code you add to a file looks drastically different from the existing
+ code around it, it throws readers out of their rhythm when they go to
+ read it. Avoid this.
+ </p>
+
+ </PARTING_WORDS>
+
+ <p align="right">
+ Revision 2.93
+ </p>
+
+
+ <address>
+ Aaron Whyte<br/>
+ Bob Jervis<br/>
+ Dan Pupius<br/>
+ Erik Arvidsson<br/>
+ Fritz Schneider<br/>
+ Robby Walker<br/>
+ </address>
+</GUIDE>
diff --git a/jsguide.html b/jsguide.html
new file mode 100644
index 0000000..c931a69
--- /dev/null
+++ b/jsguide.html
@@ -0,0 +1,2816 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Google JavaScript Style Guide</title>
+<link rel="stylesheet" href="javaguide.css">
+<script src="include/styleguide.js"></script>
+<link rel="shortcut icon" href="https://www.google.com/favicon.ico">
+<script src="include/jsguide.js"></script>
+</head>
+<body onload="initStyleGuide();">
+<div id="content">
+<h1>Google JavaScript Style Guide</h1>
+<h2 id="introduction">1 Introduction</h2>
+
+<p>This document serves as the <strong>complete</strong> definition of Google’s coding standards
+for source code in the JavaScript programming language. A JavaScript source file
+is described as being <em>in Google Style</em> if and only if it adheres to the rules
+herein.</p>
+
+<p>Like other programming style guides, the issues covered span not only aesthetic
+issues of formatting, but other types of conventions or coding standards as
+well. However, this document focuses primarily on the hard-and-fast rules that
+we follow universally, and avoids giving advice that isn't clearly enforceable
+(whether by human or tool). </p>
+
+<h3 id="terminology-notes">1.1 Terminology notes</h3>
+
+<p>In this document, unless otherwise clarified:</p>
+
+<ol>
+<li><p>The term <em>comment</em> always refers to <em>implementation</em> comments. We do not use
+the phrase <q>documentation comments</q>, instead using the common term “JSDoc”
+for both human-readable text and machine-readable annotations within
+<code>/** … */</code>.</p></li>
+<li><p>This Style Guide uses <a href="http://tools.ietf.org/html/rfc2119">RFC 2119</a> terminology when using the phrases <em>must</em>,
+<em>must not</em>, <em>should</em>, <em>should not</em>, and <em>may</em>. The terms <em>prefer</em> and
+<em>avoid</em> correspond to <em>should</em> and <em>should not</em>, respectively. Imperative
+and declarative statements are prescriptive and correspond to <em>must</em>.</p></li>
+</ol>
+
+<p>Other <q>terminology notes</q> will appear occasionally throughout the document.</p>
+
+<h3 id="guide-notes">1.2 Guide notes</h3>
+
+<p>Example code in this document is <strong>non-normative</strong>. That is, while the examples
+are in Google Style, they may not illustrate the <em>only</em> stylish way to represent
+the code. Optional formatting choices made in examples must not be enforced as
+rules.</p>
+
+<h2 id="source-file-basics">2 Source file basics</h2>
+
+<h3 id="file-name">2.1 File name</h3>
+
+<p>File names must be all lowercase and may include underscores (<code>_</code>) or dashes
+(<code>-</code>), but no additional punctuation. Follow the convention that your project
+uses. Filenames’ extension must be <code>.js</code>.</p>
+
+<h3 id="file-encoding">2.2 File encoding: UTF-8</h3>
+
+<p>Source files are encoded in <strong>UTF-8</strong>.</p>
+
+<h3 id="special-characters">2.3 Special characters</h3>
+
+<h4 id="whitespace-characters">2.3.1 Whitespace characters</h4>
+
+<p>Aside from the line terminator sequence, the ASCII horizontal space character
+(0x20) is the only whitespace character that appears anywhere in a source
+file. This implies that</p>
+
+<ol>
+<li><p>All other whitespace characters in string literals are escaped, and</p></li>
+<li><p>Tab characters are <strong>not</strong> used for indentation.</p></li>
+</ol>
+
+<h4 id="special-escape-sequences">2.3.2 Special escape sequences</h4>
+
+<p>For any character that has a special escape sequence (<code>\'</code>, <code>\"</code>, <code>\\</code>, <code>\b</code>,
+<code>\f</code>, <code>\n</code>, <code>\r</code>, <code>\t</code>, <code>\v</code>), that sequence is used rather than the
+corresponding numeric escape (e.g <code>\x0a</code>, <code>\u000a</code>, or <code>\u{a}</code>). Legacy octal
+escapes are never used.</p>
+
+<h4 id="non-ascii-characters">2.3.3 Non-ASCII characters</h4>
+
+<p>For the remaining non-ASCII characters, either the actual Unicode character
+(e.g. <code>∞</code>) or the equivalent hex or Unicode escape (e.g. <code>\u221e</code>) is used,
+depending only on which makes the code <strong>easier to read and understand</strong>.</p>
+
+<p>Tip: In the Unicode escape case, and occasionally even when actual Unicode
+characters are used, an explanatory comment can be very helpful.</p>
+
+<table>
+ <thead>
+ <tr>
+ <th>Example
+ </th><th>Discussion
+ </th></tr></thead><tbody>
+ <tr>
+ <td><code class="prettyprint lang-js">const units = 'μs';</code>
+ </td><td>Best: perfectly clear even without a comment.
+ </td></tr><tr>
+ <td>
+ <code class="prettyprint lang-js">const units = '\u03bcs'; // 'μs'
+ </code>
+ </td><td>Allowed, but there’s no reason to do this.
+ </td></tr><tr>
+ <td>
+ <code class="prettyprint lang-js">const units = '\u03bcs'; // Greek letter mu, 's'
+ </code>
+ </td><td>Allowed, but awkward and prone to mistakes.
+ </td></tr><tr>
+ <td><code class="badcode">const units = '\u03bcs';</code>
+ </td><td>Poor: the reader has no idea what this is.
+ </td></tr><tr>
+ <td>
+ <code class="prettyprint lang-js">return '\ufeff' + content; // byte order mark
+ </code>
+ </td><td>
+ Good: use escapes for non-printable characters, and comment if
+ necessary.
+</td></tr></tbody></table>
+
+<p>Tip: Never make your code less readable simply out of fear that some programs
+might not handle non-ASCII characters properly. If that happens, those programs
+are <strong>broken</strong> and they must be <strong>fixed</strong>.</p>
+
+<h2 id="source-file-structure">3 Source file structure</h2>
+
+<p>A source file consists of, <strong>in order</strong>:</p>
+
+<ol>
+<li>License or copyright information, if present</li>
+<li><code>@fileoverview</code> JSDoc, if present</li>
+<li><code>goog.module</code> statement</li>
+<li><code>goog.require</code> statements</li>
+<li>The file’s implementation</li>
+</ol>
+
+<p><strong>Exactly one blank line</strong> separates each section that is present, except the
+file's implementation, which may be preceded by 1 or 2 blank lines.</p>
+
+<h3 id="file-copyright">3.1 License or copyright information, if present</h3>
+
+<p>If license or copyright information belongs in a file, it belongs here.</p>
+
+<h3 id="file-fileoverview">3.2 <code>@fileoverview</code> JSDoc, if present</h3>
+
+<p>See <a href="#jsdoc-top-file-level-comments">??</a> for formatting rules.</p>
+
+<h3 id="file-goog-module">3.3 <code>goog.module</code> statement</h3>
+
+<p>All files must declare exactly one <code>goog.module</code> name on a single line: lines
+containing a <code>goog.module</code> declaration must not be wrapped, and are therefore an
+exception to the 80-column limit.</p>
+
+<p>The entire argument to goog.module is what defines a namespace. It is the
+package name (an identifier that reflects the fragment of the directory
+structure where the code lives) plus, optionally, the main class/enum/interface
+that it defines concatenated to the end.</p>
+
+<p>Example</p>
+
+<pre><code class="language-js prettyprint">goog.module('search.urlHistory.UrlHistoryService');
+</code></pre>
+
+<h4 id="naming-hierarchy">3.3.1 Hierarchy</h4>
+
+<p>Module namespaces may never be named as a <em>direct</em> child of another module's
+namespace.</p>
+
+<p>Illegal:</p>
+
+<pre><code class="language-js prettyprint badcode">goog.module('foo.bar'); // 'foo.bar.qux' would be fine, though
+goog.module('foo.bar.baz');
+</code></pre>
+
+<p>The directory hierarchy reflects the namespace hierarchy, so that deeper-nested
+children are subdirectories of higher-level parent directories. Note that this
+implies that owners of “parent” namespace groups are necessarily aware of all
+child namespaces, since they exist in the same directory.</p>
+
+<h4 id="file-set-test-only">3.3.2 <code>goog.setTestOnly</code></h4>
+
+<p>The single <code>goog.module</code> statement may optionally be followed by a call to
+goog.setTestOnly().</p>
+
+<h4 id="file-declare-legacy-namespace">3.3.3 <code>goog.module.declareLegacyNamespace</code></h4>
+
+<p>The single <code>goog.module</code> statement may optionally be followed by a call to
+<code>goog.module.declareLegacyNamespace();</code>. Avoid
+<code>goog.module.declareLegacyNamespace()</code> when possible.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">goog.module('my.test.helpers');
+goog.module.declareLegacyNamespace();
+goog.setTestOnly();
+</code></pre>
+
+<p><code>goog.module.declareLegacyNamespace</code> exists to ease the transition from
+traditional object hierarchy-based namespaces but comes with some naming
+restrictions. As the child module name must be created after the parent
+namespace, this name <strong>must not</strong> be a child or parent of any other
+<code>goog.module</code> (for example, <code>goog.module('parent');</code> and
+<code>goog.module('parent.child');</code> cannot both exist safely, nor can
+<code>goog.module('parent');</code> and <code>goog.module('parent.child.grandchild');</code>).</p>
+
+<h4 id="file-es6-modules">3.3.4 ES6 Modules</h4>
+
+<p>Do not use ES6 modules yet (i.e. the <code>export</code> and <code>import</code> keywords), as their
+semantics are not yet finalized. Note that this policy will be revisited once
+the semantics are fully-standard.</p>
+
+<h3 id="file-goog-require">3.4 <code>goog.require</code> statements</h3>
+
+<p>Imports are done with <code>goog.require</code> statements, grouped together immediately
+following the module declaration. Each <code>goog.require</code> is assigned to a single
+constant alias, or else destructured into several constant aliases. These
+aliases are the only acceptable way to refer to the <code>require</code>d dependency,
+whether in code or in type annotations: the fully qualified name is never used
+except as the argument to <code>goog.require</code>. Alias names should match the final
+dot-separated component of the imported module name when possible, though
+additional components may be included (with appropriate casing such that the
+alias' casing still correctly identifies its type) if necessary to
+disambiguate, or if it significantly improves readability. <code>goog.require</code>
+statements may not appear anywhere else in the file.</p>
+
+<p>If a module is imported only for its side effects, the assignment may be
+omitted, but the fully qualified name may not appear anywhere else in the file.
+A comment is required to explain why this is needed and suppress a compiler
+warning.</p>
+
+
+
+<p>The lines are sorted according to the following rules: All requires with a name
+on the left hand side come first, sorted alphabetically by those names. Then
+destructuring requires, again sorted by the names on the left hand side.
+Finally, any <code>goog.require</code> calls that are standalone (generally these are for
+modules imported just for their side effects).</p>
+
+<p>Tip: There’s no need to memorize this order and enforce it manually. You can
+rely on your IDE to report requires
+that are not sorted correctly.</p>
+
+<p>If a long alias or module name would cause a line to exceed the 80-column limit,
+it <strong>must not</strong> be wrapped: goog.require lines are an exception to the 80-column
+limit.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">const MyClass = goog.require('some.package.MyClass');
+const NsMyClass = goog.require('other.ns.MyClass');
+const googAsserts = goog.require('goog.asserts');
+const testingAsserts = goog.require('goog.testing.asserts');
+const than80columns = goog.require('pretend.this.is.longer.than80columns');
+const {clear, forEach, map} = goog.require('goog.array');
+/** @suppress {extraRequire} Initializes MyFramework. */
+goog.require('my.framework.initialization');
+</code></pre>
+
+<p>Illegal:</p>
+
+<pre><code class="language-js badcode prettyprint">const randomName = goog.require('something.else'); // name must match
+
+const {clear, forEach, map} = // don't break lines
+ goog.require('goog.array');
+
+function someFunction() {
+ const alias = goog.require('my.long.name.alias'); // must be at top level
+ // …
+}
+</code></pre>
+
+<h4 id="file-goog-forward-declare">3.4.1 <code>goog.forwardDeclare</code></h4>
+
+<p><code>goog.forwardDeclare</code> is not needed very often, but is a valuable tool to break
+circular dependencies or to reference late loaded code. These statements are
+grouped together and immediately follow any <code>goog.require</code> statements. A
+<code>goog.forwardDeclare</code> statement must follow the same style rules as a
+<code>goog.require</code> statement.</p>
+
+<h3 id="file-implementation">3.5 The file’s implementation</h3>
+
+<p>The actual implementation follows after all dependency information is declared
+(separated by at least one blank line).</p>
+
+<p>This may consist of any module-local declarations (constants, variables,
+classes, functions, etc), as well as any exported symbols.
+</p>
+
+<h2 id="formatting">4 Formatting</h2>
+
+<p><strong>Terminology Note</strong>: <em>block-like construct</em> refers to the body of a class,
+function, method, or brace-delimited block of code. Note that, by
+<a href="#features-array-literals">??</a> and <a href="#features-object-literals">??</a>, any array or
+object literal may optionally be treated as if it were a block-like construct.</p>
+
+<p>Tip: Use <code>clang-format</code>. The JavaScript community has invested effort to make
+sure clang-format <q>does the right thing</q> on JavaScript files. <code>clang-format</code> has
+integration with several popular
+editors.</p>
+
+<h3 id="formatting-braces">4.1 Braces</h3>
+
+<h4 id="formatting-braces-all">4.1.1 Braces are used for all control structures</h4>
+
+<p>Braces are required for all control structures (i.e. <code>if</code>, <code>else</code>, <code>for</code>, <code>do</code>,
+<code>while</code>, as well as any others), even if the body contains only a single
+statement. The first statement of a non-empty block must begin on its own line.</p>
+
+<p>Illegal:</p>
+
+<pre><code class="language-js badcode prettyprint">if (someVeryLongCondition())
+ doSomething();
+
+for (let i = 0; i < foo.length; i++) bar(foo[i]);
+</code></pre>
+
+<p><strong>Exception</strong>: A simple if statement that can fit entirely on a single line with
+no wrapping (and that doesn’t have an else) may be kept on a single line with no
+braces when it improves readability. This is the only case in which a control
+structure may omit braces and newlines.</p>
+
+<pre><code class="language-js prettyprint">if (shortCondition()) return;
+</code></pre>
+
+<h4 id="formatting-nonempty-blocks">4.1.2 Nonempty blocks: K&R style</h4>
+
+<p>Braces follow the Kernighan and Ritchie style (<q><a href="http://www.codinghorror.com/blog/2012/07/new-programming-jargon.html">Egyptian brackets</a></q>) for
+<em>nonempty</em> blocks and block-like constructs:</p>
+
+<ul>
+<li>No line break before the opening brace.</li>
+<li>Line break after the opening brace.</li>
+<li>Line break before the closing brace.</li>
+<li>Line break after the closing brace <em>if</em> that brace terminates a statement or
+the body of a function or class statement, or a class method. Specifically,
+there is <em>no</em> line break after the brace if it is followed by <code>else</code>, <code>catch</code>,
+<code>while</code>, or a comma, semicolon, or right-parenthesis.</li>
+</ul>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">class InnerClass {
+ constructor() {}
+
+ /** @param {number} foo */
+ method(foo) {
+ if (condition(foo)) {
+ try {
+ // Note: this might fail.
+ something();
+ } catch (err) {
+ recover();
+ }
+ }
+ }
+}
+</code></pre>
+
+<h4 id="formatting-empty-blocks">4.1.3 Empty blocks: may be concise</h4>
+
+<p>An empty block or block-like construct <em>may</em> be closed immediately after it is
+opened, with no characters, space, or line break in between (i.e. <code>{}</code>),
+<strong>unless</strong> it is a part of a <em>multi-block statement</em> (one that directly contains
+multiple blocks: <code>if</code>/<code>else</code> or <code>try</code>/<code>catch</code>/<code>finally</code>).</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">function doNothing() {}
+</code></pre>
+
+<p>Illegal:</p>
+
+<pre><code class="language-js prettyprint badcode">if (condition) {
+ // …
+} else if (otherCondition) {} else {
+ // …
+}
+
+try {
+ // …
+} catch (e) {}
+</code></pre>
+
+<h3 id="formatting-block-indentation">4.2 Block indentation: +2 spaces</h3>
+
+<p>Each time a new block or block-like construct is opened, the indent increases by
+two spaces. When the block ends, the indent returns to the previous indent
+level. The indent level applies to both code and comments throughout the
+block. (See the example in <a href="#formatting-nonempty-blocks">??</a>).</p>
+
+<h4 id="formatting-array-literals">4.2.1 Array literals: optionally <q>block-like</q></h4>
+
+<p>Any array literal may optionally be formatted as if it were a “block-like
+construct.” For example, the following are all valid (<strong>not</strong> an exhaustive
+list):</p>
+
+<pre><code class="language-js prettyprint columns">const a = [
+ 0,
+ 1,
+ 2,
+];
+
+const b =
+ [0, 1, 2];
+
+</code></pre>
+
+<pre><code class="language-js prettyprint columns">const c = [0, 1, 2];
+
+someMethod(foo, [
+ 0, 1, 2,
+], bar);
+</code></pre>
+
+<p>Other combinations are allowed, particularly when emphasizing semantic groupings
+between elements, but should not be used only to reduce the vertical size of
+larger arrays.</p>
+
+<h4 id="formatting-object-literals">4.2.2 Object literals: optionally <q>block-like</q></h4>
+
+<p>Any object literal may optionally be formatted as if it were a “block-like
+construct.” The same examples apply as <a href="#formatting-array-literals">??</a>. For
+example, the following are all valid (<strong>not</strong> an exhaustive list):</p>
+
+<pre><code class="language-js prettyprint columns">const a = {
+ a: 0,
+ b: 1,
+};
+
+const b =
+ {a: 0, b: 1};
+</code></pre>
+
+<pre><code class="language-js prettyprint columns">const c = {a: 0, b: 1};
+
+someMethod(foo, {
+ a: 0, b: 1,
+}, bar);
+</code></pre>
+
+<h4 id="formatting-class-literals">4.2.3 Class literals</h4>
+
+<p>Class literals (whether declarations or expressions) are indented as blocks. Do
+not add semicolons after methods, or after the closing brace of a class
+<em>declaration</em> (statements—such as assignments—that contain class <em>expressions</em>
+are still terminated with a semicolon). Use the <code>extends</code> keyword, but not the
+<code>@extends</code> JSDoc annotation unless the class extends a templatized type.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint columns">class Foo {
+ constructor() {
+ /** @type {number} */
+ this.x = 42;
+ }
+
+ /** @return {number} */
+ method() {
+ return this.x;
+ }
+}
+Foo.Empty = class {};
+</code></pre>
+
+<pre><code class="language-js prettyprint columns">/** @extends {Foo<string>} */
+foo.Bar = class extends Foo {
+ /** @override */
+ method() {
+ return super.method() / 2;
+ }
+};
+
+/** @interface */
+class Frobnicator {
+ /** @param {string} message */
+ frobnicate(message) {}
+}
+</code></pre>
+
+<h4 id="formatting-function-expressions">4.2.4 Function expressions</h4>
+
+<p>When declaring an anonymous function in the list of arguments for a function
+call, the body of the function is indented two spaces more than the preceding
+indentation depth.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">prefix.something.reallyLongFunctionName('whatever', (a1, a2) => {
+ // Indent the function body +2 relative to indentation depth
+ // of the 'prefix' statement one line above.
+ if (a1.equals(a2)) {
+ someOtherLongFunctionName(a1);
+ } else {
+ andNowForSomethingCompletelyDifferent(a2.parrot);
+ }
+});
+
+some.reallyLongFunctionCall(arg1, arg2, arg3)
+ .thatsWrapped()
+ .then((result) => {
+ // Indent the function body +2 relative to the indentation depth
+ // of the '.then()' call.
+ if (result) {
+ result.use();
+ }
+ });
+</code></pre>
+
+<h4 id="formatting-switch-statements">4.2.5 Switch statements</h4>
+
+<p>As with any other block, the contents of a switch block are indented +2.</p>
+
+
+
+<p>After a switch label, a newline appears, and the indentation level is increased
++2, exactly as if a block were being opened. An explicit block may be used if
+required by lexical scoping. The following switch label returns to the previous
+indentation level, as if a block had been closed.</p>
+
+<p>A blank line is optional between a <code>break</code> and the following case.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">switch (animal) {
+ case Animal.BANDERSNATCH:
+ handleBandersnatch();
+ break;
+
+ case Animal.JABBERWOCK:
+ handleJabberwock();
+ break;
+
+ default:
+ throw new Error('Unknown animal');
+}
+</code></pre>
+
+<h3 id="formatting-statements">4.3 Statements</h3>
+
+<h4 id="formatting-one-statement-perline">4.3.1 One statement per line</h4>
+
+<p>Each statement is followed by a line-break.</p>
+
+<h4 id="formatting-semicolons-are-required">4.3.2 Semicolons are required</h4>
+
+<p>Every statement must be terminated with a semicolon. Relying on automatic
+semicolon insertion is forbidden.</p>
+
+<h3 id="formatting-column-limit">4.4 Column limit: 80</h3>
+
+<p>JavaScript code has a column limit of 80 characters. Except as noted below, any
+line that would exceed this limit must be line-wrapped, as explained in
+<a href="#formatting-line-wrapping">??</a>.</p>
+
+<p><strong>Exceptions:</strong></p>
+
+<ol>
+<li>Lines where obeying the column limit is not possible (for example, a long URL
+in JSDoc or a shell command intended to be copied-and-pasted).</li>
+<li><code>goog.module</code> and <code>goog.require</code> statements (see <a href="#file-goog-module">??</a> and
+<a href="#file-goog-require">??</a>).</li>
+</ol>
+
+<h3 id="formatting-line-wrapping">4.5 Line-wrapping</h3>
+
+<p><strong>Terminology Note</strong>: <em>Line-wrapping</em> is defined as breaking a single expression
+into multiple lines.</p>
+
+<p>There is no comprehensive, deterministic formula showing <em>exactly</em> how to
+line-wrap in every situation. Very often there are several valid ways to
+line-wrap the same piece of code.</p>
+
+<p>Note: While the typical reason for line-wrapping is to avoid overflowing the
+column limit, even code that would in fact fit within the column limit may be
+line-wrapped at the author's discretion.</p>
+
+<p>Tip: Extracting a method or local variable may solve the problem without the
+need to line-wrap.</p>
+
+<h4 id="formatting-where-to-break">4.5.1 Where to break</h4>
+
+<p>The prime directive of line-wrapping is: prefer to break at a <strong>higher syntactic
+level</strong>. </p>
+
+<p>Preferred:</p>
+
+<pre><code class="language-js prettyprint">currentEstimate =
+ calc(currentEstimate + x * currentEstimate) /
+ 2.0f;
+</code></pre>
+
+<p>Discouraged:</p>
+
+<pre><code class="language-js prettyprint badcode">currentEstimate = calc(currentEstimate + x *
+ currentEstimate) / 2.0f;
+</code></pre>
+
+<p>In the preceding example, the syntactic levels from highest to lowest are as
+follows: assignment, division, function call, parameters, number constant.</p>
+
+<p>Operators are wrapped as follows:</p>
+
+<ol>
+<li>When a line is broken at an operator the break comes after the symbol. (Note
+that this is not the same practice used in Google style for Java.)
+<ol>
+<li>This does not apply to the <q>dot</q> (<code>.</code>), which is not actually an
+operator.</li>
+</ol></li>
+<li>A method or constructor name stays attached to the open parenthesis (<code>(</code>)
+that follows it.</li>
+<li>A comma (<code>,</code>) stays attached to the token that precedes it.</li>
+</ol>
+
+<blockquote>
+<p>Note: The primary goal for line wrapping is to have clear code, not
+necessarily code that fits in the smallest number of lines.</p>
+</blockquote>
+
+<h4 id="formatting-indent">4.5.2 Indent continuation lines at least +4 spaces</h4>
+
+<p>When line-wrapping, each line after the first (each <em>continuation line</em>) is
+indented at least +4 from the original line, unless it falls under the rules of
+block indentation.</p>
+
+<p>When there are multiple continuation lines, indentation may be varied beyond +4
+as appropriate. In general, continuation lines at a deeper syntactic level are
+indented by larger multiples of 4, and two lines use the same indentation level
+if and only if they begin with syntactically parallel elements.</p>
+
+<p><a href="#formatting-horizontal-alignment">??</a> addresses the discouraged practice of
+using a variable number of spaces to align certain tokens with previous lines.</p>
+
+<h3 id="formatting-whitespace">4.6 Whitespace</h3>
+
+<h4 id="formatting-vertical-whitespace">4.6.1 Vertical whitespace</h4>
+
+<p>A single blank line appears:</p>
+
+<ol>
+<li>Between consecutive methods in a class or object literal
+<ol>
+<li>Exception: A blank line between two consecutive properties definitions in
+an object literal (with no other code between them) is optional. Such
+blank lines are used as needed to create <em>logical groupings</em> of fields.</li>
+</ol></li>
+<li>Within method bodies, sparingly to create <em>logical groupings</em> of statements.
+Blank lines at the start or end of a function body are not allowed.</li>
+<li><em>Optionally</em> before the first or after the last method in a class or object
+literal (neither encouraged nor discouraged).</li>
+<li>As required by other sections of this document (e.g.
+<a href="#file-goog-require">??</a>).</li>
+</ol>
+
+<p><em>Multiple</em> consecutive blank lines are permitted, but never required (nor
+encouraged).</p>
+
+<h4 id="formatting-horizontal-whitespace">4.6.2 Horizontal whitespace</h4>
+
+<p>Use of horizontal whitespace depends on location, and falls into three broad
+categories: <em>leading</em> (at the start of a line), <em>trailing</em> (at the end of a
+line), and <em>internal</em>. Leading whitespace (i.e., indentation) is addressed
+elsewhere. Trailing whitespace is forbidden.</p>
+
+<p>Beyond where required by the language or other style rules, and apart from
+literals, comments, and JSDoc, a single internal ASCII space also appears in the
+following places <strong>only</strong>.</p>
+
+<ol>
+<li>Separating any reserved word (such as <code>if</code>, <code>for</code>, or <code>catch</code>) from an open
+parenthesis (<code>(</code>) that follows it on that line.</li>
+<li>Separating any reserved word (such as <code>else</code> or <code>catch</code>) from a closing
+curly brace (<code>}</code>) that precedes it on that line.</li>
+<li>Before any open curly brace (<code>{</code>), with two exceptions:
+<ol>
+<li>Before an object literal that is the first argument of a function or the
+first element in an array literal (e.g. <code>foo({a: [{c: d}]})</code>).</li>
+<li>In a template expansion, as it is forbidden by the language
+(e.g. <code>abc${1 + 2}def</code>).</li>
+</ol></li>
+<li>On both sides of any binary or ternary operator.</li>
+<li>After a comma (<code>,</code>) or semicolon (<code>;</code>). Note that spaces are <em>never</em> allowed
+before these characters.</li>
+<li>After the colon (<code>:</code>) in an object literal.</li>
+<li>On both sides of the double slash (<code>//</code>) that begins an end-of-line
+comment. Here, multiple spaces are allowed, but not required.</li>
+<li>After an open-JSDoc comment character and on both sides of close characters
+(e.g. for short-form type declarations or casts: <code>this.foo = /** @type
+{number} */ (bar);</code> or <code>function(/** string */ foo) {</code>).</li>
+</ol>
+
+<h4 id="formatting-horizontal-alignment">4.6.3 Horizontal alignment: discouraged</h4>
+
+<p><strong>Terminology Note</strong>: <em>Horizontal alignment</em> is the practice of adding a
+variable number of additional spaces in your code with the goal of making
+certain tokens appear directly below certain other tokens on previous lines.</p>
+
+<p>This practice is permitted, but it is <strong>generally discouraged</strong> by Google
+Style. It is not even required to <em>maintain</em> horizontal alignment in places
+where it was already used.</p>
+
+<p>Here is an example without alignment, followed by one with alignment. Both are
+allowed, but the latter is discouraged:</p>
+
+<pre><code class="language-js prettyprint">{
+ tiny: 42, // this is great
+ longer: 435, // this too
+};
+
+{
+ tiny: 42, // permitted, but future edits
+ longer: 435, // may leave it unaligned
+};
+</code></pre>
+
+<p>Tip: Alignment can aid readability, but it creates problems for future
+maintenance. Consider a future change that needs to touch just one line. This
+change may leave the formerly-pleasing formatting mangled, and that is
+allowed. More often it prompts the coder (perhaps you) to adjust whitespace on
+nearby lines as well, possibly triggering a cascading series of
+reformattings. That one-line change now has a <q>blast radius.</q> This can at worst
+result in pointless busywork, but at best it still corrupts version history
+information, slows down reviewers and exacerbates merge conflicts.</p>
+
+<h4 id="formatting-function-arguments">4.6.4 Function arguments</h4>
+
+<p>Prefer to put all function arguments on the same line as the function name. If doing so would exceed the 80-column limit, the arguments must be line-wrapped in a readable way. To save space, you may wrap as close to 80 as possible, or put each argument on its own line to enhance readability. Indentation should be four spaces. Aligning to the parenthesis is allowed, but discouraged. Below are the most common patterns for argument wrapping:</p>
+
+<pre><code class="language-js prettyprint">// Arguments start on a new line, indented four spaces. Preferred when the
+// arguments don't fit on the same line with the function name (or the keyword
+// "function") but fit entirely on the second line. Works with very long
+// function names, survives renaming without reindenting, low on space.
+doSomething(
+ descriptiveArgumentOne, descriptiveArgumentTwo, descriptiveArgumentThree) {
+ // …
+}
+
+// If the argument list is longer, wrap at 80. Uses less vertical space,
+// but violates the rectangle rule and is thus not recommended.
+doSomething(veryDescriptiveArgumentNumberOne, veryDescriptiveArgumentTwo,
+ tableModelEventHandlerProxy, artichokeDescriptorAdapterIterator) {
+ // …
+}
+
+// Four-space, one argument per line. Works with long function names,
+// survives renaming, and emphasizes each argument.
+doSomething(
+ veryDescriptiveArgumentNumberOne,
+ veryDescriptiveArgumentTwo,
+ tableModelEventHandlerProxy,
+ artichokeDescriptorAdapterIterator) {
+ // …
+}
+</code></pre>
+
+<h3 id="formatting-grouping-parentheses">4.7 Grouping parentheses: recommended</h3>
+
+<p>Optional grouping parentheses are omitted only when the author and reviewer
+agree that there is no reasonable chance that the code will be misinterpreted
+without them, nor would they have made the code easier to read. It is <em>not</em>
+reasonable to assume that every reader has the entire operator precedence table
+memorized.</p>
+
+<p>Do not use unnecessary parentheses around the entire expression following
+<code>delete</code>, <code>typeof</code>, <code>void</code>, <code>return</code>, <code>throw</code>, <code>case</code>, <code>in</code>, <code>of</code>, or <code>yield</code>.</p>
+
+<p>Parentheses are required for type casts: <code>/** @type {!Foo} */ (foo)</code>.</p>
+
+<h3 id="formatting-comments">4.8 Comments</h3>
+
+<p>This section addresses <em>implementation comments</em>. JSDoc is addressed separately
+in <a href="#jsdoc">??</a>.</p>
+
+<h4 id="formatting-block-comment-style">4.8.1 Block comment style</h4>
+
+<p>Block comments are indented at the same level as the surrounding code. They may
+be in <code>/* … */</code> or <code>//</code>-style. For multi-line <code>/* … */</code> comments, subsequent
+lines must start with * aligned with the <code>*</code> on the previous line, to make
+comments obvious with no extra context. “Parameter name” comments should appear
+after values whenever the value and method name do not sufficiently convey the
+meaning.</p>
+
+<pre><code class="language-js prettyprint">/*
+ * This is
+ * okay.
+ */
+
+// And so
+// is this.
+
+/* This is fine, too. */
+
+someFunction(obviousParam, true /* shouldRender */, 'hello' /* name */);
+</code></pre>
+
+<p>Comments are not enclosed in boxes drawn with asterisks or other characters.</p>
+
+<p>Do not use JSDoc (<code>/** … */</code>) for any of the above implementation comments.</p>
+
+<h2 id="language-features">5 Language features</h2>
+
+<p>JavaScript includes many dubious (and even dangerous) features. This section
+delineates which features may or may not be used, and any additional constraints
+on their use.</p>
+
+<h3 id="features-local-variable-declarations">5.1 Local variable declarations</h3>
+
+<h4 id="features-use-const-and-let">5.1.1 Use <code>const</code> and <code>let</code></h4>
+
+<p>Declare all local variables with either <code>const</code> or <code>let</code>. Use const by default,
+unless a variable needs to be reassigned. The <code class="badcode">var</code>
+keyword must not be used.</p>
+
+<h4 id="features-one-variable-per-declaration">5.1.2 One variable per declaration</h4>
+
+<p>Every local variable declaration declares only one variable: declarations such
+as <code class="badcode">let a = 1, b = 2;</code> are not used.</p>
+
+<h4 id="features-declared-when-needed">5.1.3 Declared when needed, initialized as soon as possible</h4>
+
+<p>Local variables are <strong>not</strong> habitually declared at the start of their containing
+block or block-like construct. Instead, local variables are declared close to
+the point they are first used (within reason), to minimize their scope.</p>
+
+<h4 id="features-declare-types-as-needed">5.1.4 Declare types as needed</h4>
+
+<p>JSDoc type annotations may be added either on the line above the declaration, or
+else inline before the variable name.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">const /** !Array<number> */ data = [];
+
+/** @type {!Array<number>} */
+const data = [];
+</code></pre>
+
+<p>Tip: There are many cases where the compiler can infer a templatized type but
+not its parameters. This is particularly the case when the initializing literal
+or constructor call does not include any values of the template parameter type
+(e.g., empty arrays, objects, <code>Map</code>s, or <code>Set</code>s), or if the variable is modified
+in a closure. Local variable type annotations are particularly helpful in these
+cases since otherwise the compiler will infer the template parameter as unknown.</p>
+
+<h3 id="features-array-literals">5.2 Array literals</h3>
+
+<h4 id="features-arrays-trailing-comma">5.2.1 Use trailing commas</h4>
+
+
+
+<p>Include a trailing comma whenever there is a line break between the final
+element and the closing bracket.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">const values = [
+ 'first value',
+ 'second value',
+];
+</code></pre>
+
+<h4 id="features-arrays-ctor">5.2.2 Do not use the variadic <code>Array</code> constructor</h4>
+
+<p>The constructor is error-prone if arguments are added or removed. Use a literal
+instead.</p>
+
+<p>Illegal:</p>
+
+<pre><code class="language-js prettyprint badcode">const a1 = new Array(x1, x2, x3);
+const a2 = new Array(x1, x2);
+const a3 = new Array(x1);
+const a4 = new Array();
+</code></pre>
+
+<p>This works as expected except for the third case: if <code>x1</code> is a whole number then
+<code>a3</code> is an array of size <code>x1</code> where all elements are <code>undefined</code>. If <code>x1</code> is any
+other number, then an exception will be thrown, and if it is anything else then
+it will be a single-element array.</p>
+
+<p>Instead, write</p>
+
+<pre><code class="language-js prettyprint">const a1 = [x1, x2, x3];
+const a2 = [x1, x2];
+const a3 = [x1];
+const a4 = [];
+</code></pre>
+
+<p>Explicitly allocating an array of a given length using <code>new Array(length)</code> is
+allowed when appropriate.</p>
+
+<h4 id="features-arrays-non-numeric-properties">5.2.3 Non-numeric properties</h4>
+
+<p>Do not define or use non-numeric properties on an array (other than
+<code>length</code>). Use a <code>Map</code> (or <code>Object</code>) instead.</p>
+
+<h4 id="features-arrays-destructuring">5.2.4 Destructuring</h4>
+
+<p>Array literals may be used on the left-hand side of an assignment to perform
+destructuring (such as when unpacking multiple values from a single array or
+iterable). A final <q>rest</q> element may be included (with no space between the
+<code>...</code> and the variable name). Elements should be omitted if they are unused.</p>
+
+<pre><code class="language-js prettyprint">const [a, b, c, ...rest] = generateResults();
+let [, b,, d] = someArray;
+</code></pre>
+
+<p>Destructuring may also be used for function parameters (note that a parameter
+name is required but ignored). Always specify <code>[]</code> as the default value if a
+destructured array parameter is optional, and provide default values on the left
+hand side:</p>
+
+<pre><code class="language-js prettyprint">/** @param {!Array<number>=} param1 */
+function optionalDestructuring([a = 4, b = 2] = []) { … };
+</code></pre>
+
+<p>Illegal:</p>
+
+<pre><code class="language-js prettyprint badcode">function badDestructuring([a, b] = [4, 2]) { … };
+</code></pre>
+
+<p>Tip: For (un)packing multiple values into a function’s parameter or return,
+prefer object destructuring to array destructuring when possible, as it allows
+naming the individual elements and specifying a different type for each.*</p>
+
+<h4 id="features-arrays-spread-operator">5.2.5 Spread operator</h4>
+
+<p>Array literals may include the spread operator (<code>...</code>) to flatten elements out
+of one or more other iterables. The spread operator should be used instead of
+more awkward constructs with <code>Array.prototype</code>. There is no space after the
+<code>...</code>.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">[...foo] // preferred over Array.prototype.slice.call(foo)
+[...foo, ...bar] // preferred over foo.concat(bar)
+</code></pre>
+
+<h3 id="features-object-literals">5.3 Object literals</h3>
+
+<h4 id="features-objects-use-trailing-comma">5.3.1 Use trailing commas</h4>
+
+<p>Include a trailing comma whenever there is a line break between the final
+property and the closing brace.</p>
+
+<h4 id="features-objects-ctor">5.3.2 Do not use the <code>Object</code> constructor</h4>
+
+<p>While <code>Object</code> does not have the same problems as <code>Array</code>, it is still
+disallowed for consistency. Use an object literal (<code>{}</code> or <code>{a: 0, b: 1, c: 2}</code>)
+instead.</p>
+
+<h4 id="features-objects-mixing-keys">5.3.3 Do not mix quoted and unquoted keys</h4>
+
+<p>Object literals may represent either <em>structs</em> (with unquoted keys and/or
+symbols) or <em>dicts</em> (with quoted and/or computed keys). Do not mix these key
+types in a single object literal.</p>
+
+<p>Illegal:</p>
+
+<pre><code class="language-js prettyprint badcode">{
+ a: 42, // struct-style unquoted key
+ 'b': 43, // dict-style quoted key
+}
+</code></pre>
+
+<h4 id="features-objects-computed-property-names">5.3.4 Computed property names</h4>
+
+<p>Computed property names (e.g., <code>{['key' + foo()]: 42}</code>) are allowed, and are
+considered dict-style (quoted) keys (i.e., must not be mixed with non-quoted
+keys) unless the computed property is a symbol (e.g., <code>[Symbol.iterator]</code>).
+Enum values may also be used for computed keys, but should not be mixed with
+non-enum keys in the same literal.</p>
+
+<h4 id="features-objects-method-shorthand">5.3.5 Method shorthand</h4>
+
+<p>Methods can be defined on object literals using the method shorthand (<code>{method()
+{… }}</code>) in place of a colon immediately followed by a <code>function</code> or arrow
+function literal.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">return {
+ stuff: 'candy',
+ method() {
+ return this.stuff; // Returns 'candy'
+ },
+};
+</code></pre>
+
+<p>Note that <code>this</code> in a method shorthand or <code>function</code> refers to the object
+literal itself whereas <code>this</code> in an arrow function refers to the scope outside
+the object literal.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">class {
+ getObjectLiteral() {
+ this.stuff = 'fruit';
+ return {
+ stuff: 'candy',
+ method: () => this.stuff, // Returns 'fruit'
+ };
+ }
+}
+</code></pre>
+
+<h4 id="features-objects-shorthand-properties">5.3.6 Shorthand properties</h4>
+
+<p>Shorthand properties are allowed on object literals.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">const foo = 1;
+const bar = 2;
+const obj = {
+ foo,
+ bar,
+ method() { return this.foo + this.bar; },
+};
+assertEquals(3, obj.method());
+</code></pre>
+
+<h4 id="features-objects-destructuring">5.3.7 Destructuring</h4>
+
+<p>Object destructuring patterns may be used on the left-hand side of an assignment
+to perform destructuring and unpack multiple values from a single object.</p>
+
+<p>Destructured objects may also be used as function parameters, but should be kept
+as simple as possible: a single level of unquoted shorthand properties. Deeper
+levels of nesting and computed properties may not be used in parameter
+destructuring. Specify any default values in the left-hand-side of the
+destructured parameter (<code>{str = 'some default'} = {}</code>, rather than <code class="badcode">{str} = {str: 'some default'}</code>), and if a destructured
+object is itself optional, it must default to <code>{}</code>. The JSDoc for the
+destructured parameter may be given any name (the name is unused but is required
+by the compiler).</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">/**
+ * @param {string} ordinary
+ * @param {{num: (number|undefined), str: (string|undefined)}=} param1
+ * num: The number of times to do something.
+ * str: A string to do stuff to.
+ */
+function destructured(ordinary, {num, str = 'some default'} = {})
+</code></pre>
+
+<p>Illegal:</p>
+
+<pre><code class="language-js prettyprint badcode">/** @param {{x: {num: (number|undefined), str: (string|undefined)}}} param1 */
+function nestedTooDeeply({x: {num, str}}) {};
+/** @param {{num: (number|undefined), str: (string|undefined)}=} param1 */
+function nonShorthandProperty({num: a, str: b} = {}) {};
+/** @param {{a: number, b: number}} param1 */
+function computedKey({a, b, [a + b]: c}) {};
+/** @param {{a: number, b: string}=} param1 */
+function nontrivialDefault({a, b} = {a: 2, b: 4}) {};
+</code></pre>
+
+<p>Destructuring may also be used for <code>goog.require</code> statements, and in this case
+must not be wrapped: the entire statement occupies one line, regardless of how
+long it is (see <a href="#file-goog-require">??</a>).</p>
+
+<h4 id="features-objects-enums">5.3.8 Enums</h4>
+
+<p>Enumerations are defined by adding the <code>@enum</code> annotation to an object literal.
+Additional properties may not be added to an enum after it is defined. Enums
+must be constant, and all enum values must be deeply immutable.</p>
+
+<pre><code class="language-js prettyprint">/**
+ * Supported temperature scales.
+ * @enum {string}
+ */
+const TemperatureScale = {
+ CELSIUS: 'celsius',
+ FAHRENHEIT: 'fahrenheit',
+};
+
+/**
+ * An enum with two options.
+ * @enum {number}
+ */
+const Option = {
+ /** The option used shall have been the first. */
+ FIRST_OPTION: 1,
+ /** The second among two options. */
+ SECOND_OPTION: 2,
+};
+</code></pre>
+
+<h3 id="features-classes">5.4 Classes</h3>
+
+<h4 id="features-classes-constructors">5.4.1 Constructors</h4>
+
+<p>Constructors are optional for concrete classes. Subclass constructors must call
+<code>super()</code> before setting any fields or otherwise accessing <code>this</code>. Interfaces
+must not define a constructor.</p>
+
+<h4 id="features-classes-fields">5.4.2 Fields</h4>
+
+<p>Set all of a concrete object’s fields (i.e. all properties other than methods)
+in the constructor. Annotate fields that are never reassigned with <code>@const</code>
+(these need not be deeply immutable). Private fields must be annotated with
+<code>@private</code> and their names must end with a trailing underscore. Fields are never
+set on a concrete class' <code>prototype</code>.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">class Foo {
+ constructor() {
+ /** @private @const {!Bar} */
+ this.bar_ = computeBar();
+ }
+}
+</code></pre>
+
+<p>Tip: Properties should never be added to or removed from an instance after the
+constructor is finished, since it significantly hinders VMs’ ability to
+optimize. If necessary, fields that are initialized later should be explicitly
+set to <code>undefined</code> in the constructor to prevent later shape changes. Adding
+<code>@struct</code> to an object will check that undeclared properties are not
+added/accessed. Classes have this added by default.</p>
+
+<h4 id="features-classes-computed-properties">5.4.3 Computed properties</h4>
+
+
+
+<p>Computed properties may only be used in classes when the property is a
+symbol. Dict-style properties (that is, quoted or computed non-symbol keys, as
+defined in <a href="#features-objects-mixing-keys">??</a>) are not allowed. A
+<code>[Symbol.iterator]</code> method should be defined for any classes that are logically
+iterable. Beyond this, <code>Symbol</code> should be used sparingly.</p>
+
+<p>Tip: be careful of using any other built-in symbols (e.g., <code>Symbol.isConcatSpreadable</code>) as they are not polyfilled by the compiler and will therefore not work in older browsers.</p>
+
+<h4 id="features-classes-static-methods">5.4.4 Static methods</h4>
+
+
+
+<p>Where it does not interfere with readability, prefer module-local functions over
+private static methods.</p>
+
+<p>Static methods should only be called on the base class itself. Static methods
+should not be called on variables containing a dynamic instance that may be
+either the constructor or a subclass constructor (and must be defined with
+<code>@nocollapse</code> if this is done), and must not be called directly on a subclass
+that doesn’t define the method itself.</p>
+
+<p>Illegal:</p>
+
+<pre><code class="language-js prettyprint badcode">class Base { /** @nocollapse */ static foo() {} }
+class Sub extends Base {}
+function callFoo(cls) { cls.foo(); } // discouraged: don't call static methods dynamically
+Sub.foo(); // illegal: don't call static methods on subclasses that don't define it themselves
+</code></pre>
+
+<h4 id="features-classes-old-style">5.4.5 Old-style class declarations</h4>
+
+<p>While ES6 classes are preferred, there are cases where ES6 classes may not be
+feasible. For example:</p>
+
+<ol>
+<li><p>If there exist or will exist subclasses, including frameworks that create
+subclasses, that cannot be immediately changed to use ES6 class syntax. If
+such a class were to use ES6 syntax, all downstream subclasses not using ES6
+class syntax would need to be modified.</p></li>
+<li><p>Frameworks that require a known <code>this</code> value before calling the superclass
+constructor, since constructors with ES6 super classes do not have
+access to the instance <code>this</code> value until the call to <code>super</code> returns.</p></li>
+</ol>
+
+<p>In all other ways the style guide still applies to this code: <code>let</code>, <code>const</code>,
+default parameters, rest, and arrow functions should all be used when
+appropriate.</p>
+
+<p><code>goog.defineClass</code> allows for a class-like definition similar to ES6 class
+syntax:</p>
+
+<pre><code class="language-javascript">let C = goog.defineClass(S, {
+ /**
+ * @param {string} value
+ */
+ constructor(value) {
+ S.call(this, 2);
+ /** @const */
+ this.prop = value;
+ },
+
+ /**
+ * @param {string} param
+ * @return {number}
+ */
+ method(param) {
+ return 0;
+ },
+});
+</code></pre>
+
+<p>Alternatively, while <code>goog.defineClass</code> should be preferred for all new code,
+more traditional syntax is also allowed.</p>
+
+<pre><code class="language-javascript">/**
+ * @constructor @extends {S}
+ * @param {string} value
+ */
+function C(value) {
+ S.call(this, 2);
+ /** @const */
+ this.prop = value;
+}
+goog.inherits(C, S);
+
+/**
+ * @param {string} param
+ * @return {number}
+ */
+C.prototype.method = function(param) {
+ return 0;
+};
+</code></pre>
+
+<p>Per-instance properties should be defined in the constructor after the call to the super class constructor, if there is a super class. Methods should be defined on the prototype of the constructor.</p>
+
+<p>Defining constructor prototype hierarchies correctly is harder than it first appears! For that reason, it is best to use <code>goog.inherits</code> from <a href="http://code.google.com/closure/library/">the Closure Library </a>.</p>
+
+<h4 id="features-classes-prototypes">5.4.6 Do not manipulate <code>prototype</code>s directly</h4>
+
+<p>The <code>class</code> keyword allows clearer and more readable class definitions than
+defining <code>prototype</code> properties. Ordinary implementation code has no business
+manipulating these objects, though they are still useful for defining <code>@record</code>
+interfaces and classes as defined in <a href="#features-classes-old-style">??</a>. Mixins
+and modifying the prototypes of builtin objects are
+explicitly forbidden.</p>
+
+<p><strong>Exception</strong>: Framework code (such as Polymer, or Angular) may need to use <code>prototype</code>s, and should not
+resort to even-worse workarounds to avoid doing so.</p>
+
+<p><strong>Exception</strong>: Defining fields in interfaces (see <a href="#features-classes-interfaces">??</a>).</p>
+
+<h4 id="features-classes-getters-and-setters">5.4.7 Getters and Setters</h4>
+
+<p>Do not use <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get">JavaScript getter and setter properties</a>. They are potentially
+surprising and difficult to reason about, and have limited support in the
+compiler. Provide ordinary methods instead.</p>
+
+<p><strong>Exception</strong>: when working with data binding frameworks (such as Angular and
+Polymer), getters and setters may be used sparingly. Note, however, that
+compiler support is limited. When they are used, they must be defined either
+with <code>get foo()</code> and <code>set foo(value)</code> in the class or object literal, or if that
+is not possible, with <code>Object.defineProperties</code>. Do not use
+<code>Object.defineProperty</code>, which interferes with property renaming. Getters
+<strong>must not</strong> change observable state.</p>
+
+<p>Illegal:</p>
+
+<pre><code class="language-js prettyprint badcode">class Foo {
+ get next() { return this.nextId++; }
+}
+</code></pre>
+
+<h4 id="features-classes-overriding-tostring">5.4.8 Overriding toString</h4>
+
+<p>The <code>toString</code> method may be overridden, but must always succeed and never have
+visible side effects.</p>
+
+<p>Tip: Beware, in particular, of calling other methods from toString, since
+exceptional conditions could lead to infinite loops.</p>
+
+<h4 id="features-classes-interfaces">5.4.9 Interfaces</h4>
+
+<p>Interfaces may be declared with <code>@interface</code> or <code>@record</code>. Interfaces declared
+with <code>@record</code> can be explicitly (i.e. via <code>@implements</code>) or implicitly
+implemented by a class or object literal.</p>
+
+<p>All non-static method bodies on an interface must be empty blocks. Fields must
+be defined after the interface body as stubs on the <code>prototype</code>.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">/**
+ * Something that can frobnicate.
+ * @record
+ */
+class Frobnicator {
+ /**
+ * Performs the frobnication according to the given strategy.
+ * @param {!FrobnicationStrategy} strategy
+ */
+ frobnicate(strategy) {}
+}
+
+/** @type {number} The number of attempts before giving up. */
+Frobnicator.prototype.attempts;
+</code></pre>
+
+<h3 id="features-functions">5.5 Functions</h3>
+
+<h4 id="features-functions-top-level-functions">5.5.1 Top-level functions</h4>
+
+<p>Exported functions may be defined directly on the <code>exports</code> object, or else
+declared locally and exported separately. Non-exported functions are encouraged
+and should not be declared <code>@private</code>.</p>
+
+<p>Examples:</p>
+
+<pre><code class="language-js prettyprint">/** @return {number} */
+function helperFunction() {
+ return 42;
+}
+/** @return {number} */
+function exportedFunction() {
+ return helperFunction() * 2;
+}
+/**
+ * @param {string} arg
+ * @return {number}
+ */
+function anotherExportedFunction(arg) {
+ return helperFunction() / arg.length;
+}
+/** @const */
+exports = {exportedFunction, anotherExportedFunction};
+</code></pre>
+
+<pre><code class="language-js prettyprint">/** @param {string} arg */
+exports.foo = (arg) => {
+ // do some stuff ...
+};
+</code></pre>
+
+<h4 id="features-functions-nested-functions">5.5.2 Nested functions and closures</h4>
+
+<p>Functions may contain nested function definitions. If it is useful to give the
+function a name, it should be assigned to a local <code>const</code>.</p>
+
+<h4 id="features-functions-arrow-functions">5.5.3 Arrow functions</h4>
+
+<p>Arrow functions provide a concise syntax and fix a number of difficulties with
+<code>this</code>. Prefer arrow functions over the <code>function</code> keyword, particularly for
+nested functions (but see <a href="#features-objects-method-shorthand">??</a>).</p>
+
+<p>Prefer using arrow functions over <code>f.bind(this)</code>, and especially over
+<code>goog.bind(f, this)</code>. Avoid writing <code>const self = this</code>. Arrow functions are
+particularly useful for callbacks, which sometimes pass unexpected additional
+arguments.</p>
+
+<p>The right-hand side of the arrow may be a single expression or a block.
+Parentheses around the arguments are optional if there is only a single
+non-destructured argument.</p>
+
+<p>Tip: It is a good practice to use parentheses even for single-argument arrows,
+since the code may still parse reasonably (but incorrectly) if the parentheses
+are forgotten when an additional argument is added.</p>
+
+<h4 id="features-functions-generators">5.5.4 Generators</h4>
+
+<p>Generators enable a number of useful abstractions and may be used as needed.</p>
+
+<p>When defining generator functions, attach the <code>*</code> to the <code>function</code> keyword when
+present, and separate it with a space from the name of the function. When using
+delegating yields, attach the <code>*</code> to the <code>yield</code> keyword.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">/** @return {!Iterator<number>} */
+function* gen1() {
+ yield 42;
+}
+
+/** @return {!Iterator<number>} */
+const gen2 = function*() {
+ yield* gen1();
+}
+
+class SomeClass {
+ /** @return {!Iterator<number>} */
+ * gen() {
+ yield 42;
+ }
+}
+</code></pre>
+
+<h4 id="features-functions-parameters">5.5.5 Parameters</h4>
+
+<p>Function parameters must be typed with JSDoc annotations in the JSDoc preceding
+the function’s definition, except in the case of same-signature <code>@override</code>s,
+where all types are omitted.</p>
+
+<p>Parameter types <em>may</em> be specified inline, immediately before the parameter name
+(as in <code>(/** number */ foo, /** string */ bar) => foo + bar</code>). Inline and
+<code>@param</code> type annotations <em>must not</em> be mixed in the same function definition.</p>
+
+<h5 id="features-functions-default-parameters">5.5.5.1 Default parameters</h5>
+
+<p>Optional parameters are permitted using the equals operator in the parameter
+list. Optional parameters must include spaces on both sides of the equals
+operator, be named exactly like required parameters (i.e., not prefixed with
+<code>opt_</code>), use the <code>=</code> suffix in their JSDoc type, come after required parameters,
+and not use initializers that produce observable side effects. All optional
+parameters must have a default value in the function declaration, even if that
+value is <code>undefined</code>.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">/**
+ * @param {string} required This parameter is always needed.
+ * @param {string=} optional This parameter can be omitted.
+ * @param {!Node=} node Another optional parameter.
+ */
+function maybeDoSomething(required, optional = '', node = undefined) {}
+</code></pre>
+
+<p>Use default parameters sparingly. Prefer destructuring (as in
+<a href="#features-objects-destructuring">??</a>) to create readable APIs when there
+are more than a small handful of optional parameters that do not have a natural
+order.</p>
+
+<p>Note: Unlike Python's default parameters, it is okay to use initializers that
+return new mutable objects (such as <code>{}</code> or <code>[]</code>) because the initializer is
+evaluated each time the default value is used, so a single object won't be
+shared across invocations.</p>
+
+<p>Tip: While arbitrary expressions including function calls may be used as
+initializers, these should be kept as simple as possible. Avoid initializers
+that expose shared mutable state, as that can easily introduce unintended
+coupling between function calls.</p>
+
+<h5 id="features-functions-rest-parameters">5.5.5.2 Rest parameters</h5>
+
+<p>Use a <em>rest</em> parameter instead of accessing <code>arguments</code>. Rest parameters are
+typed with a <code>...</code> prefix in their JSDoc. The rest parameter must be the last
+parameter in the list. There is no space between the <code>...</code> and the parameter
+name. Do not name the rest parameter <code>var_args</code>. Never name a local variable or
+parameter <code>arguments</code>, which confusingly shadows the built-in name.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">/**
+ * @param {!Array<string>} array This is an ordinary parameter.
+ * @param {...number} numbers The remainder of arguments are all numbers.
+ */
+function variadic(array, ...numbers) {}
+</code></pre>
+
+<h4 id="features-functions-returns">5.5.6 Returns</h4>
+
+<p>Function return types must be specified in the JSDoc directly above the function
+definition, except in the case of same-signature <code>@override</code>s where all types
+are omitted.</p>
+
+<h4 id="features-functions-generics">5.5.7 Generics</h4>
+
+<p>Declare generic functions and methods when necessary with <code>@template TYPE</code> in
+the JSDoc above the class definition.</p>
+
+<h4 id="features-functions-spread-operator">5.5.8 Spread operator</h4>
+
+<p>Function calls may use the spread operator (<code>...</code>). Prefer the spread operator
+to <code>Function.prototype.apply</code> when an array or iterable is unpacked into
+multiple parameters of a variadic function. There is no space after the <code>...</code>.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">function myFunction(...elements) {}
+myFunction(...array, ...iterable, ...generator());
+</code></pre>
+
+<h3 id="features-string-literals">5.6 String literals</h3>
+
+<h4 id="features-strings-use-single-quotes">5.6.1 Use single quotes</h4>
+
+<p>Ordinary string literals are delimited with single quotes (<code>'</code>), rather than
+double quotes (<code>"</code>).</p>
+
+<p>Tip: if a string contains a single quote character, consider using a template
+string to avoid having to escape the quote.</p>
+
+<p>Ordinary string literals may not span multiple lines.</p>
+
+<h4 id="features-strings-template-strings">5.6.2 Template strings</h4>
+
+<p>Use template strings (delimited with <code>`</code>) over complex string
+concatenation, particularly if multiple string literals are involved. Template
+strings may span multiple lines.</p>
+
+<p>If a template string spans multiple lines, it does not need to follow the
+indentation of the enclosing block, though it may if the added whitespace does
+not matter.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">function arithmetic(a, b) {
+ return `Here is a table of arithmetic operations:
+${a} + ${b} = ${a + b}
+${a} - ${b} = ${a - b}
+${a} * ${b} = ${a * b}
+${a} / ${b} = ${a / b}`;
+}
+</code></pre>
+
+<h4 id="features-strings-no-line-continuations">5.6.3 No line continuations</h4>
+
+<p>Do not use <em>line continuations</em> (that is, ending a line inside a string literal
+with a backslash) in either ordinary or template string literals. Even though
+ES5 allows this, it can lead to tricky errors if any trailing whitespace comes
+after the slash, and is less obvious to readers.</p>
+
+<p>Illegal:</p>
+
+<pre><code class="language-js prettyprint badcode">const longString = 'This is a very long string that far exceeds the 80 \
+ column limit. It unfortunately contains long stretches of spaces due \
+ to how the continued lines are indented.';
+</code></pre>
+
+<p>Instead, write</p>
+
+<pre><code class="language-js prettyprint">const longString = 'This is a very long string that far exceeds the 80 ' +
+ 'column limit. It does not contain long stretches of spaces since ' +
+ 'the concatenated strings are cleaner.';
+</code></pre>
+
+<h3 id="features-number-literals">5.7 Number literals</h3>
+
+<p>Numbers may be specified in decimal, hex, octal, or binary. Use exactly <code>0x</code>,
+<code>0o</code>, and <code>0b</code> prefixes, with lowercase letters, for hex, octal, and binary,
+respectively. Never include a leading zero unless it is immediately followed by
+<code>x</code>, <code>o</code>, or <code>b</code>.</p>
+
+<h3 id="features-control-structures">5.8 Control structures</h3>
+
+<h4 id="features-for-loops">5.8.1 For loops</h4>
+
+<p>With ES6, the language now has three different kinds of <code>for</code> loops. All may be
+used, though <code>for</code>-<code>of</code> loops should be preferred when possible.</p>
+
+<p><code>for</code>-<code>in</code> loops may only be used on dict-style objects (see
+<a href="#features-objects-mixing-keys">??</a>), and should not be used to iterate over an
+array. <code>Object.prototype.hasOwnProperty</code> should be used in <code>for</code>-<code>in</code> loops to
+exclude unwanted prototype properties. Prefer <code>for</code>-<code>of</code> and <code>Object.keys</code> over
+<code>for</code>-<code>in</code> when possible.</p>
+
+<h4 id="features-exceptions">5.8.2 Exceptions</h4>
+
+<p>Exceptions are an important part of the language and should be used whenever
+exceptional cases occur. Always throw <code>Error</code>s or subclasses of <code>Error</code>: never
+throw string literals or other objects. Always use <code>new</code> when constructing an
+<code>Error</code>.</p>
+
+<p>Custom exceptions provide a great way to convey additional error information
+from functions. They should be defined and used wherever the native <code>Error</code>
+type is insufficient.</p>
+
+<p>Prefer throwing exceptions over ad-hoc error-handling approaches (such as
+passing an error container reference type, or returning an object with an error
+property).</p>
+
+<h5 id="features-empty-catch-blocks">5.8.2.1 Empty catch blocks</h5>
+
+<p>It is very rarely correct to do nothing in response to a caught exception. When
+it truly is appropriate to take no action whatsoever in a catch block, the
+reason this is justified is explained in a comment.</p>
+
+<pre><code class="language-js prettyprint">try {
+ return handleNumericResponse(response);
+} catch (ok) {
+ // it's not numeric; that's fine, just continue
+}
+return handleTextResponse(response);
+</code></pre>
+
+<p>Illegal:</p>
+
+<pre><code class="language-js prettyprint badcode"> try {
+ shouldFail();
+ fail('expected an error');
+ }
+ catch (expected) {}
+</code></pre>
+
+<p>Tip: Unlike in some other languages, patterns like the above simply don’t work
+since this will catch the error thrown by <code>fail</code>. Use <code>assertThrows()</code> instead.</p>
+
+<h4 id="features-switch-statements">5.8.3 Switch statements</h4>
+
+<p>Terminology Note: Inside the braces of a switch block are one or more statement groups. Each statement group consists of one or more switch labels (either <code>case FOO:</code> or <code>default:</code>), followed by one or more statements.</p>
+
+<h5 id="features-switch-fall-through">5.8.3.1 Fall-through: commented</h5>
+
+<p>Within a switch block, each statement group either terminates abruptly (with a
+<code>break</code>, <code>return</code> or <code>throw</code>n exception), or is marked with a comment to
+indicate that execution will or might continue into the next statement
+group. Any comment that communicates the idea of fall-through is sufficient
+(typically <code>// fall through</code>). This special comment is not required in the last
+statement group of the switch block.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">switch (input) {
+ case 1:
+ case 2:
+ prepareOneOrTwo();
+ // fall through
+ case 3:
+ handleOneTwoOrThree();
+ break;
+ default:
+ handleLargeNumber(input);
+}
+</code></pre>
+
+<h5 id="features-switch-default-case">5.8.3.2 The <code>default</code> case is present</h5>
+
+<p>Each switch statement includes a <code>default</code> statement group, even if it contains
+no code.</p>
+
+<h3 id="features-this">5.9 this</h3>
+
+<p>Only use <code>this</code> in class constructors and methods, or in arrow functions defined
+within class constructors and methods. Any other uses of <code>this</code> must have an
+explicit <code>@this</code> declared in the immediately-enclosing function’s JSDoc.</p>
+
+<p>Never use <code>this</code> to refer to the global object, the context of an <code>eval</code>, the
+target of an event, or unnecessarily <code>call()</code>ed or <code>apply()</code>ed functions.</p>
+
+<h3 id="disallowed-features">5.10 Disallowed features</h3>
+
+<h4 id="disallowed-features-with">5.10.1 with</h4>
+
+<p>Do not use the <code>with</code> keyword. It makes your code harder to understand and has
+been banned in strict mode since ES5.</p>
+
+<h4 id="disallowed-features-dynamic-code-evaluation">5.10.2 Dynamic code evaluation</h4>
+
+<p>Do not use <code>eval</code> or the <code>Function(...string)</code> constructor (except for code
+loaders). These features are potentially dangerous and simply do not work in
+CSP environments.</p>
+
+<h4 id="disallowed-features-automatic-semicolon-insertion">5.10.3 Automatic semicolon insertion</h4>
+
+<p>Always terminate statements with semicolons (except function and class
+declarations, as noted above).</p>
+
+<h4 id="disallowed-features-non-standard-features">5.10.4 Non-standard features</h4>
+
+<p>Do not use non-standard features. This includes old features that have been
+removed (e.g., <code>WeakMap.clear</code>), new features that are not yet standardized
+(e.g., the current TC39 working draft, proposals at any stage, or proposed but
+not-yet-complete web standards), or proprietary features that are only
+implemented in some browsers. Use only features defined in the current ECMA-262
+or WHATWG standards. (Note that projects writing against specific APIs, such as
+Chrome extensions or Node.js, can obviously use those APIs). Non-standard
+language “extensions” (such as those provided by some external transpilers) are
+forbidden.</p>
+
+<h4 id="disallowed-features-wrapper-objects">5.10.5 Wrapper objects for primitive types</h4>
+
+<p>Never use <code>new</code> on the primitive object wrappers (<code>Boolean</code>, <code>Number</code>, <code>String</code>,
+<code>Symbol</code>), nor include them in type annotations.</p>
+
+<p>Illegal:</p>
+
+<pre><code class="language-js prettyprint badcode">const /** Boolean */ x = new Boolean(false);
+if (x) alert(typeof x); // alerts 'object' - WAT?
+</code></pre>
+
+<p>The wrappers may be called as functions for coercing (which is preferred over
+using <code>+</code> or concatenating the empty string) or creating symbols.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">const /** boolean */ x = Boolean(0);
+if (!x) alert(typeof x); // alerts 'boolean', as expected
+</code></pre>
+
+<h4 id="disallowed-features-modifying-builtin-objects">5.10.6 Modifying builtin objects</h4>
+
+<p>Never modify builtin types, either by adding methods to their constructors or to
+their prototypes. Avoid depending on libraries that do this. Note that the
+JSCompiler’s runtime library will provide standards-compliant polyfills where
+possible; nothing else may modify builtin objects.</p>
+
+<p>Do not add symbols to the global object unless absolutely necessary
+(e.g. required by a third-party API).</p>
+
+<h2 id="naming">6 Naming</h2>
+
+<h3 id="naming-rules-common-to-all-identifiers">6.1 Rules common to all identifiers</h3>
+
+<p>Identifiers use only ASCII letters and digits, and, in a small number of cases
+noted below, underscores and very rarely (when required by frameworks like
+Angular) dollar signs.</p>
+
+<p>Give as descriptive a name as possible, within reason. Do not worry about saving
+horizontal space as it is far more important to make your code immediately
+understandable by a new reader. Do not use abbreviations that are ambiguous or
+unfamiliar to readers outside your project, and do not abbreviate by deleting
+letters within a word.</p>
+
+<pre><code class="language-js prettyprint">priceCountReader // No abbreviation.
+numErrors // "num" is a widespread convention.
+numDnsConnections // Most people know what "DNS" stands for.
+</code></pre>
+
+<p>Illegal:</p>
+
+<pre><code class="language-js prettyprint badcode">n // Meaningless.
+nErr // Ambiguous abbreviation.
+nCompConns // Ambiguous abbreviation.
+wgcConnections // Only your group knows what this stands for.
+pcReader // Lots of things can be abbreviated "pc".
+cstmrId // Deletes internal letters.
+kSecondsPerDay // Do not use Hungarian notation.
+</code></pre>
+
+<h3 id="naming-rules-by-identifier-type">6.2 Rules by identifier type</h3>
+
+<h4 id="naming-package-names">6.2.1 Package names</h4>
+
+<p>Package names are all <code>lowerCamelCase</code>. For example,
+<code>my.exampleCode.deepSpace</code>, but not <code class="badcode">my.examplecode.deepspace</code> or <code class="badcode">my.example_code.deep_space</code>.</p>
+
+<h4 id="naming-class-names">6.2.2 Class names</h4>
+
+<p>Class, interface, record, and typedef names are written in <code>UpperCamelCase</code>.
+Unexported classes are simply locals: they are not marked <code>@private</code> and
+therefore are not named with a trailing underscore.</p>
+
+<p>Type names are typically nouns or noun phrases. For example, <code>Request</code>,
+<code>ImmutableList</code>, or <code>VisibilityMode</code>. Additionally, interface names may
+sometimes be adjectives or adjective phrases instead (for example, <code>Readable</code>).</p>
+
+<h4 id="naming-method-names">6.2.3 Method names</h4>
+
+<p>Method names are written in <code>lowerCamelCase</code>. Private methods’ names must end
+with a trailing underscore.</p>
+
+<p>Method names are typically verbs or verb phrases. For example, <code>sendMessage</code> or
+<code>stop_</code>. Getter and setter methods for properties are never required, but if
+they are used they should be named <code>getFoo</code> (or optionally <code>isFoo</code> or <code>hasFoo</code>
+for booleans), or <code>setFoo(value)</code> for setters.</p>
+
+<p>Underscores may also appear in JsUnit test method names to separate logical
+components of the name. One typical pattern is <code>test<MethodUnderTest>_<state></code>,
+for example <code>testPop_emptyStack</code>. There is no One Correct Way to name test
+methods.</p>
+
+<h4 id="naming-enum-names">6.2.4 Enum names</h4>
+
+<p>Enum names are written in <code>UpperCamelCase</code>, similar to classes, and should
+generally be singular nouns. Individual items within the enum are named in
+<code>CONSTANT_CASE</code>.</p>
+
+<h4 id="naming-constant-names">6.2.5 Constant names</h4>
+
+<p>Constant names use <code>CONSTANT_CASE</code>: all uppercase letters, with words separated
+by underscores. There is no reason for a constant to be named with a trailing
+underscore, since private static properties can be replaced by (implicitly
+private) module locals.</p>
+
+<h5 id="naming-definition-of-constant">6.2.5.1 Definition of “constant”</h5>
+
+<p>Every constant is a <code>@const</code> static property or a module-local <code>const</code>
+declaration, but not all <code>@const</code> static properties and module-local <code>const</code>s
+are constants. Before choosing constant case, consider whether the field really
+feels like a <em>deeply immutable</em> constant. For example, if any of that instance's
+observable state can change, it is almost certainly not a constant. Merely
+intending to never mutate the object is generally not enough.</p>
+
+<p>Examples:</p>
+
+<pre><code class="language-js prettyprint">// Constants
+const NUMBER = 5;
+/** @const */ exports.NAMES = ImmutableList.of('Ed', 'Ann');
+/** @enum */ exports.SomeEnum = { ENUM_CONSTANT: 'value' };
+
+// Not constants
+let letVariable = 'non-const';
+class MyClass { constructor() { /** @const */ this.nonStatic = 'non-static'; } };
+/** @type {string} */ MyClass.staticButMutable = 'not @const, can be reassigned';
+const /** Set<String> */ mutableCollection = new Set();
+const /** ImmutableSet<SomeMutableType> */ mutableElements = ImmutableSet.of(mutable);
+const Foo = goog.require('my.Foo'); // mirrors imported name
+const logger = log.getLogger('loggers.are.not.immutable');
+</code></pre>
+
+<p>Constants’ names are typically nouns or noun phrases.</p>
+
+<h5 id="naming-local-aliases">6.2.5.1 Local aliases</h5>
+
+<p>Local aliases should be used whenever they improve readability over
+fully-qualified names. Follow the same rules as <code>goog.require</code>s
+(<a href="#file-goog-require">??</a>), maintaining the last part of the aliased name.
+Aliases may also be used within functions. Aliases must be <code>const</code>.</p>
+
+<p>Examples:</p>
+
+<pre><code class="language-js prettyprint">const staticHelper = importedNamespace.staticHelper;
+const CONSTANT_NAME = ImportedClass.CONSTANT_NAME;
+const {assert, assertInstanceof} = asserts;
+</code></pre>
+
+<h4 id="naming-non-constant-field-names">6.2.6 Non-constant field names</h4>
+
+<p>Non-constant field names (static or otherwise) are written in <code>lowerCamelCase</code>,
+with a trailing underscore for private fields.</p>
+
+<p>These names are typically nouns or noun phrases. For example, <code>computedValues</code>
+or <code>index_</code>.</p>
+
+<h4 id="naming-parameter-names">6.2.7 Parameter names</h4>
+
+<p>Parameter names are written in <code>lowerCamelCase</code>. Note that this applies even if
+the parameter expects a constructor.</p>
+
+<p>One-character parameter names should not be used in public methods.</p>
+
+<p><strong>Exception</strong>: When required by a third-party framework, parameter names may
+begin with a <code>$</code>. This exception does not apply to any other identifiers
+(e.g. local variables or properties).</p>
+
+<h4 id="naming-local-variable-names">6.2.8 Local variable names</h4>
+
+<p>Local variable names are written in <code>lowerCamelCase</code>, except for module-local
+(top-level) constants, as described above. Constants in function scopes are
+still named in <code>lowerCamelCase</code>. Note that lowerCamelCase applies even if the
+variable holds a constructor.</p>
+
+<h4 id="naming-template-parameter-names">6.2.9 Template parameter names</h4>
+
+<p>Template parameter names should be concise, single-word or single-letter
+identifiers, and must be all-caps, such as <code>TYPE</code> or <code>THIS</code>.</p>
+
+<h3 id="naming-camel-case-defined">6.3 Camel case: defined</h3>
+
+<p>Sometimes there is more than one reasonable way to convert an English phrase
+into camel case, such as when acronyms or unusual constructs like <q>IPv6</q> or
+<q>iOS</q> are present. To improve predictability, Google Style specifies the
+following (nearly) deterministic scheme.</p>
+
+<p>Beginning with the prose form of the name:</p>
+
+<ol>
+<li>Convert the phrase to plain ASCII and remove any apostrophes. For example,
+<q>Müller's algorithm</q> might become <q>Muellers algorithm</q>.</li>
+<li>Divide this result into words, splitting on spaces and any remaining
+punctuation (typically hyphens).
+<ol>
+<li>Recommended: if any word already has a conventional camel case
+appearance in common usage, split this into its constituent parts (e.g.,
+<q>AdWords</q> becomes <q>ad words</q>). Note that a word such as <q>iOS</q> is not
+really in camel case per se; it defies any convention, so this
+recommendation does not apply.</li>
+</ol></li>
+<li>Now lowercase everything (including acronyms), then uppercase only the first
+character of:
+<ol>
+<li>… each word, to yield upper camel case, or</li>
+<li>… each word except the first, to yield lower camel case</li>
+</ol></li>
+<li>Finally, join all the words into a single identifier.</li>
+</ol>
+
+<p>Note that the casing of the original words is almost entirely disregarded.</p>
+
+<p>Examples:</p>
+
+<table>
+<thead>
+<tr>
+<th style="text-align: center">Prose form</th>
+<th style="text-align: center">Correct</th>
+<th style="text-align: center">Incorrect</th>
+</tr>
+</thead>
+
+<tbody>
+<tr>
+<td style="text-align: center"><q>XML HTTP request</q></td>
+<td style="text-align: center">XmlHttpRequest</td>
+<td style="text-align: center">XMLHTTPRequest</td>
+</tr>
+<tr>
+<td style="text-align: center"><q>new customer ID</q></td>
+<td style="text-align: center">newCustomerId</td>
+<td style="text-align: center">newCustomerID</td>
+</tr>
+<tr>
+<td style="text-align: center"><q>inner stopwatch</q></td>
+<td style="text-align: center">innerStopwatch</td>
+<td style="text-align: center">innerStopWatch</td>
+</tr>
+<tr>
+<td style="text-align: center"><q>supports IPv6 on iOS?</q></td>
+<td style="text-align: center">supportsIpv6OnIos</td>
+<td style="text-align: center">supportsIPv6OnIOS</td>
+</tr>
+<tr>
+<td style="text-align: center"><q>YouTube importer</q></td>
+<td style="text-align: center">YouTubeImporter</td>
+<td style="text-align: center">YoutubeImporter*</td>
+</tr>
+</tbody>
+</table>
+
+<p>*Acceptable, but not recommended.</p>
+
+<p>Note: Some words are ambiguously hyphenated in the English language: for example <q>nonempty</q> and <q>non-empty</q> are both correct, so the method names checkNonempty and checkNonEmpty are likewise both correct.</p>
+
+<h2 id="jsdoc">7 JSDoc</h2>
+
+<p><a href="https://developers.google.com/closure/compiler/docs/js-for-compiler">JSDoc</a> is used on all classes, fields, and methods.</p>
+
+<h3 id="jsdoc-general-form">7.1 General form</h3>
+
+<p>The basic formatting of JSDoc blocks is as seen in this example:</p>
+
+<pre><code class="language-js prettyprint">/**
+ * Multiple lines of JSDoc text are written here,
+ * wrapped normally.
+ * @param {number} arg A number to do something to.
+ */
+function doSomething(arg) { … }
+</code></pre>
+
+<p>or in this single-line example:</p>
+
+<pre><code class="language-js prettyprint">/** @const @private {!Foo} A short bit of JSDoc. */
+this.foo_ = foo;
+</code></pre>
+
+<p>If a single-line comment overflows into multiple lines, it must use the
+multi-line style with <code>/**</code> and <code>*/</code> on their own lines.</p>
+
+<p>Many tools extract metadata from JSDoc comments to perform code validation and
+optimization. As such, these comments <strong>must</strong> be well-formed.</p>
+
+<h3 id="jsdoc-markdown">7.2 Markdown</h3>
+
+<p>JSDoc is written in Markdown, though it may include HTML when necessary.</p>
+
+<p>Note that tools that automatically extract JSDoc (e.g. <a href="https://github.com/jleyba/js-dossier">JsDossier</a>) will often
+ignore plain text formatting, so if you did this:</p>
+
+<pre><code class="language-js prettyprint badcode">/**
+ * Computes weight based on three factors:
+ * items sent
+ * items received
+ * last timestamp
+ */
+</code></pre>
+
+<p>it would come out like this:</p>
+
+<pre><code>Computes weight based on three factors: items sent items received last timestamp
+</code></pre>
+
+<p>Instead, write a Markdown list:</p>
+
+<pre><code class="language-js prettyprint">/**
+ * Computes weight based on three factors:
+ * - items sent
+ * - items received
+ * - last timestamp
+ */
+</code></pre>
+
+<h3 id="jsdoc-tags">7.3 JSDoc tags</h3>
+
+<p>Google style allows a subset of JSDoc tags. See
+<a href="#appendices-jsdoc-tag-reference">??</a> for the complete list. Most tags must
+occupy their own line, with the tag at the beginning of the line.</p>
+
+<p>Illegal:</p>
+
+<pre><code class="language-js prettyprint badcode">/**
+ * The "param" tag must occupy its own line and may not be combined.
+ * @param {number} left @param {number} right
+ */
+function add(left, right) { ... }
+</code></pre>
+
+<p>Simple tags that do not require any additional data (such as <code>@private</code>,
+<code>@const</code>, <code>@final</code>, <code>@export</code>) may be combined onto the same line, along with an
+optional type when appropriate.</p>
+
+<pre><code class="language-js prettyprint">/**
+ * Place more complex annotations (like "implements" and "template")
+ * on their own lines. Multiple simple tags (like "export" and "final")
+ * may be combined in one line.
+ * @export @final
+ * @implements {Iterable<TYPE>}
+ * @template TYPE
+ */
+class MyClass {
+ /**
+ * @param {!ObjType} obj Some object.
+ * @param {number=} num An optional number.
+ */
+ constructor(obj, num = 42) {
+ /** @private @const {!Array<!ObjType|number>} */
+ this.data_ = [obj, num];
+ }
+}
+</code></pre>
+
+<p>There is no hard rule for when to combine tags, or in which order, but be
+consistent.</p>
+
+<p>For general information about annotating types in JavaScript see
+<a href="https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler">Annotating JavaScript for the Closure Compiler</a> and <a href="https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System">Types in the Closure Type
+System</a>.</p>
+
+<h3 id="jsdoc-line-wrapping">7.4 Line wrapping</h3>
+
+<p>Line-wrapped block tags are indented four spaces. Wrapped description text may
+be lined up with the description on previous lines, but this horizontal
+alignment is discouraged.</p>
+
+<pre><code class="language-js prettyprint">/**
+ * Illustrates line wrapping for long param/return descriptions.
+ * @param {string} foo This is a param with a description too long to fit in
+ * one line.
+ * @return {number} This returns something that has a description too long to
+ * fit in one line.
+ */
+exports.method = function(foo) {
+ return 5;
+};
+</code></pre>
+
+<p>Do not indent when wrapping a <code>@fileoverview</code> description.</p>
+
+<h3 id="jsdoc-top-file-level-comments">7.5 Top/file-level comments</h3>
+
+<p>A file may have a top-level file overview. A copyright notice , author information, and
+default <a href="#jsdoc-visibility-annotations">visibility level</a> are optional. File overviews are generally recommended whenever a
+file consists of more than a single class definition. The top level comment is
+designed to orient readers unfamiliar with the code to what is in this file. If
+present, it may provide a description of the file's contents and any
+dependencies or compatibility information. Wrapped lines are not indented.</p>
+
+<p>Example:</p>
+
+<pre><code class="language-js prettyprint">/**
+ * @fileoverview Description of file, its uses and information
+ * about its dependencies.
+ * @package
+ */
+</code></pre>
+
+<h3 id="jsdoc-class-comments">7.6 Class comments</h3>
+
+<p>Classes, interfaces and records must be documented with a description and any
+template parameters, implemented interfaces, visibility, or other appropriate
+tags. The class description should provide the reader with enough information to
+know how and when to use the class, as well as any additional considerations
+necessary to correctly use the class. Textual descriptions may be omitted on the
+constructor. <code>@constructor</code> and <code>@extends</code> annotations are not used with the
+<code>class</code> keyword unless the class is being used to declare an <code>@interface</code> or
+it extends a generic class.</p>
+
+<pre><code class="language-js prettyprint">/**
+ * A fancier event target that does cool things.
+ * @implements {Iterable<string>}
+ */
+class MyFancyTarget extends EventTarget {
+ /**
+ * @param {string} arg1 An argument that makes this more interesting.
+ * @param {!Array<number>} arg2 List of numbers to be processed.
+ */
+ constructor(arg1, arg2) {
+ // ...
+ }
+};
+
+/**
+ * Records are also helpful.
+ * @extends {Iterator<TYPE>}
+ * @record
+ * @template TYPE
+ */
+class Listable {
+ /** @return {TYPE} The next item in line to be returned. */
+ next() {}
+}
+</code></pre>
+
+<h3 id="jsdoc-enum-and-typedef-comments">7.7 Enum and typedef comments</h3>
+
+<p>Enums and typedefs must be documented. Public enums and typedefs must have a
+non-empty description. Individual enum items may be documented with a JSDoc
+comment on the preceding line.</p>
+
+<pre><code class="language-js prettyprint">/**
+ * A useful type union, which is reused often.
+ * @typedef {!Bandersnatch|!BandersnatchType}
+ */
+let CoolUnionType;
+
+
+/**
+ * Types of bandersnatches.
+ * @enum {string}
+ */
+const BandersnatchType = {
+ /** This kind is really frumious. */
+ FRUMIOUS: 'frumious',
+ /** The less-frumious kind. */
+ MANXOME: 'manxome',
+};
+</code></pre>
+
+<p>Typedefs are useful for defining short record types, or aliases for unions,
+complex functions, or generic types.
+Typedefs should be avoided for record types with many fields, since they do not
+allow documenting individual fields, nor using templates or recursive
+references.
+For large record types, prefer <code>@record</code>.</p>
+
+<h3 id="jsdoc-method-and-function-comments">7.8 Method and function comments</h3>
+
+<p>Parameter and return types must be documented. The <code>this</code> type should be
+documented when necessary. Method, parameter, and return descriptions (but not
+types) may be omitted if they are obvious from the rest of the method’s JSDoc or
+from its signature. Method descriptions should start with a sentence written in
+the third person declarative voice. If a method overrides a superclass method,
+it must include an <code>@override</code> annotation. Overridden methods must include all
+<code>@param</code> and <code>@return</code> annotations if any types are refined, but should omit
+them if the types are all the same.</p>
+
+<pre><code class="language-js prettyprint">/** This is a class. */
+class SomeClass extends SomeBaseClass {
+ /**
+ * Operates on an instance of MyClass and returns something.
+ * @param {!MyClass} obj An object that for some reason needs detailed
+ * explanation that spans multiple lines.
+ * @param {!OtherClass} obviousOtherClass
+ * @return {boolean} Whether something occurred.
+ */
+ someMethod(obj, obviousOtherClass) { ... }
+
+ /** @override */
+ overriddenMethod(param) { ... }
+}
+
+/**
+ * Demonstrates how top-level functions follow the same rules. This one
+ * makes an array.
+ * @param {TYPE} arg
+ * @return {!Array<TYPE>}
+ * @template TYPE
+ */
+function makeArray(arg) { ... }
+</code></pre>
+
+
+
+<p>Anonymous functions do not require JSDoc, though parameter types may be specified inline if the automatic type inference is insufficient.</p>
+
+<pre><code class="language-js prettyprint">promise.then(
+ (/** !Array<number|string> */ items) => {
+ doSomethingWith(items);
+ return /** @type {string} */ (items[0]);
+ });
+</code></pre>
+
+<h3 id="jsdoc-property-comments">7.9 Property comments</h3>
+
+<p>Property types must be documented. The description may be omitted for private
+properties, if name and type provide enough documentation for understanding the
+code.</p>
+
+<p>Publicly exported constants are commented the same way as properties. Explicit
+types may be omitted for <code>@const</code> properties initialized from an expression with
+an obviously known type.</p>
+
+<p>Tip: A <code>@const</code> property’s type can be considered “obviously known” if it is
+assigned directly from a constructor parameter with a declared type, or directly
+from a function call with a declared return type. Non-const properties and
+properties assigned from more complex expressions should have their types
+declared explicitly.</p>
+
+<pre><code class="language-js prettyprint">/** My class. */
+class MyClass {
+ /** @param {string=} someString */
+ constructor(someString = 'default string') {
+ /** @private @const */
+ this.someString_ = someString;
+
+ /** @private @const {!OtherType} */
+ this.someOtherThing_ = functionThatReturnsAThing();
+
+ /**
+ * Maximum number of things per pane.
+ * @type {number}
+ */
+ this.someProperty = 4;
+ }
+}
+
+/**
+ * The number of times we'll try before giving up.
+ * @const
+ */
+MyClass.RETRY_COUNT = 33;
+</code></pre>
+
+<h3 id="jsdoc-type-annotations">7.10 Type annotations</h3>
+
+<p>Type annotations are found on <code>@param</code>, <code>@return</code>, <code>@this</code>, and <code>@type</code> tags,
+and optionally on <code>@const</code>, <code>@export</code>, and any visibility tags. Type
+annotations attached to JSDoc tags must always be enclosed in braces.</p>
+
+<h4 id="jsdoc-nullability">7.10.1 Nullability</h4>
+
+<p>The type system defines modifiers <code>!</code> and <code>?</code> for non-null and nullable,
+respectively. Primitive types (<code>undefined</code>, <code>string</code>, <code>number</code>, <code>boolean</code>,
+<code>symbol</code>, and <code>function(...): ...</code>) and record literals (<code>{foo: string, bar:
+number}</code>) are non-null by default. Do not add an explicit <code>!</code> to these types.
+Object types (<code>Array</code>, <code>Element</code>, <code>MyClass</code>, etc) are nullable by default, but
+cannot be immediately distinguished from a name that is <code>@typedef</code>’d to a
+non-null-by-default type. As such, all types except primitives and record
+literals must be annotated explicitly with either <code>?</code> or <code>!</code> to indicate whether
+they are nullable or not.</p>
+
+<h4 id="jsdoc-type-casts">7.10.2 Type Casts</h4>
+
+<p>In cases where type checking doesn't accurately infer the type of an expression,
+it is possible to tighten the type by adding a type annotation comment and
+enclosing the expression in parentheses. Note that the parentheses are required.</p>
+
+<pre><code class="language-js prettyprint">/** @type {number} */ (x)
+</code></pre>
+
+<h4 id="jsdoc-template-parameter-types">7.10.3 Template Parameter Types</h4>
+
+<p>Always specify template parameters. This way compiler can do a better job and it
+makes it easier for readers to understand what code does.</p>
+
+<p>Bad:</p>
+
+<pre><code class="language-js prettyprint badcode">const /** !Object */ users = {};
+const /** !Array */ books = [];
+const /** !Promise */ response = ...;
+</code></pre>
+
+<p>Good:</p>
+
+<pre><code class="language-js prettyprint">const /** !Object<string, !User> */ users = {};
+const /** !Array<string> */ books = [];
+const /** !Promise<!Response> */ response = ...;
+
+const /** !Promise<undefined> */ thisPromiseReturnsNothingButParameterIsStillUseful = ...;
+const /** !Object<string, *> */ mapOfEverything = {};
+</code></pre>
+
+<p>Cases when template parameters should not be used:</p>
+
+<ul>
+<li><code>Object</code> is used for type hierarchy and not as map-like structure.</li>
+</ul>
+
+<h3 id="jsdoc-visibility-annotations">7.11 Visibility annotations</h3>
+
+<p>Visibility annotations (<code>@private</code>, <code>@package</code>, <code>@protected</code>) may be specified
+in a <code>@fileoverview</code> block, or on any exported symbol or property. Do not
+specify visibility for local variables, whether within a function or at the top
+level of a module. All <code>@private</code> names must end with an underscore.</p>
+
+<h2 id="policies">8 Policies</h2>
+
+<h3 id="policies-be-consistent">8.1 Issues unspecified by Google Style: Be Consistent!</h3>
+
+<p>For any style question that isn't settled definitively by this specification,
+prefer to do what the other code in the same file is already doing. If that
+doesn't resolve the question, consider emulating the other files in the same
+package.</p>
+
+<h3 id="policies-compiler-warnings">8.2 Compiler warnings</h3>
+
+<h4 id="policies-use-a-standard-warning-set">8.2.1 Use a standard warning set</h4>
+
+<p>
+As far as possible projects should use <code>--warning_level=VERBOSE</code>.
+</p>
+
+<h4 id="policies-how-to-handle-a-warning">8.2.2 How to handle a warning</h4>
+
+<p>Before doing anything, make sure you understand exactly what the warning is
+telling you. If you're not positive why a warning is appearing, ask for help
+.</p>
+
+<p>Once you understand the warning, attempt the following solutions in order:</p>
+
+<ol>
+<li><strong>First, fix it or work around it.</strong> Make a strong attempt to actually
+address the warning, or find another way to accomplish the task that avoids
+the situation entirely.</li>
+<li><strong>Otherwise, determine if it's a false alarm.</strong> If you are convinced that
+the warning is invalid and that the code is actually safe and correct, add a
+comment to convince the reader of this fact and apply the <code>@suppress</code>
+annotation.</li>
+<li><strong>Otherwise, leave a TODO comment.</strong> This is a <strong>last resort</strong>. If you do
+this, <strong>do not suppress the warning.</strong> The warning should be visible until
+it can be taken care of properly.</li>
+</ol>
+
+<h4 id="policies-suppress-a-warning-at-the-narrowest-reasonable-scope">8.2.3 Suppress a warning at the narrowest reasonable scope</h4>
+
+<p>Warnings are suppressed at the narrowest reasonable scope, usually that of a single local variable or very small method. Often a variable or method is extracted for that reason alone.</p>
+
+<p>Example</p>
+
+<pre><code class="language-js prettyprint">/** @suppress {uselessCode} Unrecognized 'use asm' declaration */
+function fn() {
+ 'use asm';
+ return 0;
+}
+</code></pre>
+
+<p>Even a large number of suppressions in a class is still better than blinding the
+entire class to this type of warning.</p>
+
+<h3 id="policies-deprecation">8.3 Deprecation</h3>
+
+<p>Mark deprecated methods, classes or interfaces with <code>@deprecated</code> annotations. A
+deprecation comment must include simple, clear directions for people to fix
+their call sites.</p>
+
+<h3 id="policies-code-not-in-google-style">8.4 Code not in Google Style</h3>
+
+<p>You will occasionally encounter files in your codebase that are not in proper
+Google Style. These may have come from an acquisition, or may have been written
+before Google Style took a position on some issue, or may be in non-Google Style
+for any other reason.</p>
+
+<h4 id="policies-reformatting-existing-code">8.4.1 Reformatting existing code</h4>
+
+<p>When updating the style of existing code, follow these guidelines.</p>
+
+<ol>
+<li>It is not required to change all existing code to meet current style
+guidelines. Reformatting existing code is a trade-off between code churn
+and consistency. Style rules evolve over time and these kinds of tweaks to
+maintain compliance would create unnecessary churn. However, if significant
+changes are being made to a file it is expected that the file will be in
+Google Style.</li>
+<li>Be careful not to allow opportunistic style fixes to muddle the focus of a
+CL. If you find yourself making a lot of style changes that aren’t critical
+to the central focus of a CL, promote those changes to a separate CL.</li>
+</ol>
+
+<h4 id="policies-newly-added-code-use-google-style">8.4.2 Newly added code: use Google Style</h4>
+
+<p>Brand new files use Google Style, regardless of the style choices of other files
+in the same package.</p>
+
+<p>When adding new code to a file that is not in Google Style, reformatting the
+existing code first is recommended, subject to the advice in
+<a href="#policies-reformatting-existing-code">??</a>.</p>
+
+<p>If this reformatting is not done, then new code should be as consistent as
+possible with existing code in the same file, but must not violate the style
+guide.</p>
+
+<h3 id="policies-local-style-rules">8.5 Local style rules</h3>
+
+<p>Teams and projects may adopt additional style rules beyond those in this
+document, but must accept that cleanup changes may not abide by these additional
+rules, and must not block such cleanup changes due to violating any additional
+rules. Beware of excessive rules which serve no purpose. The style guide does
+not seek to define style in every possible scenario and neither should you.</p>
+
+<h3 id="policies-generated-code-mostly-exempt">8.6 Generated code: mostly exempt</h3>
+
+<p>Source code generated by the build process is not required to be in Google
+Style. However, any generated identifiers that will be referenced from
+hand-written source code must follow the naming requirements. As a special
+exception, such identifiers are allowed to contain underscores, which may help
+to avoid conflicts with hand-written identifiers.</p>
+
+<h2 id="appendices">9 Appendices</h2>
+
+<h3 id="appendices-jsdoc-tag-reference">9.1 JSDoc tag reference</h3>
+
+<p>JSDoc serves multiple purposes in JavaScript. In addition to being used to
+generate documentation it is also used to control tooling. The best known are
+the Closure Compiler type annotations.</p>
+
+<h4 id="appendices-type-annotations">9.1.1 Type annotations and other Closure Compiler annotations</h4>
+
+<p>Documentation for JSDoc used by the Closure Compiler is described in
+<a href="https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler">Annotating JavaScript for the Closure Compiler</a> and <a href="https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System">Types in the Closure Type
+System</a>.</p>
+
+<h4 id="appendices-documentation-annotations">9.1.2 Documentation annotations</h4>
+
+<p>In addition to the JSDoc described in <a href="https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler">Annotating JavaScript for the Closure
+Compiler</a> the following tags are common and well supported by various
+documentation generations tools (such as <a href="https://github.com/jleyba/js-dossier">JsDossier</a>) for purely documentation
+purposes.
+<table>
+ <thead>
+ <tr>
+ <th>Tag
+ </th><th>Template & Examples
+ </th><th>Description
+ </th></tr></thead><tbody>
+ <tr>
+ <td><code>@author</code> or <code>@owner</code>
+ </td><td><code>@author username@google.com (First Last)</code>
+ <p><em>For example:</em>
+ </p><pre class="prettyprint lang-js">
+/**
+ * @fileoverview Utilities for handling textareas.
+ * @author <a href="mailto:kuth@google.com">kuth@google.com</a> (Uthur Pendragon)
+ */
+ </pre>
+ </td><td>Document the author of a file or the owner of a test, generally only
+ used in the <code>@fileoverview</code> comment. The <code>@owner</code> tag is used by the
+ unit test dashboard to determine who owns the test results.
+ <p>Not recommended.
+ </p></td></tr><tr>
+ <td><code>@bug</code>
+ </td><td><code>@bug bugnumber</code>
+ <p><em>For example:</em>
+ </p><pre class="prettyprint lang-js">
+/** @bug 1234567 */
+function testSomething() {
+ // …
+}
+
+<p>/**
+ * @bug 1234568
+ * @bug 1234569
+ */
+function testTwoBugs() {
+ // …
+}
+</p></pre>
+ </td><td>Indicates what bugs the given test function regression tests.
+ <p>Multiple bugs should each have their own <code>@bug</code> line, to make
+ searching for regression tests as easy as possible.
+ </p></td></tr><tr>
+ <td><code>@code</code>
+ </td><td><code>{@code ...}</code>
+ <p><em>For example:</em>
+ </p><pre class="prettyprint lang-js">
+/**
+ * Moves to the next position in the selection.
+ * Throws {@code goog.iter.StopIteration} when it
+ * passes the end of the range.
+ * @return {!Node} The node at the next position.
+ */
+goog.dom.RangeIterator.prototype.next = function() {
+ // …
+};
+</pre>
+ </td><td>Indicates that a term in a JSDoc description is code so it may be
+ correctly formatted in generated documentation.
+ </td></tr><tr>
+ <td><code>@see</code>
+ </td><td><code>@see Link</code>
+ <p><em>For example:</em>
+ </p><pre class="prettyprint lang-js">
+/**
+ * Adds a single item, recklessly.
+ * @see #addSafely
+ * @see goog.Collect
+ * @see goog.RecklessAdder#add
+ */
+ </pre>
+ </td><td>Reference a lookup to another class function or method.
+ </td></tr><tr>
+ <td><code>@supported</code>
+ </td><td><code>@supported Description</code>
+ <p><em>For example:</em>
+ </p><pre class="prettyprint lang-js">
+/**
+ * @fileoverview Event Manager
+ * Provides an abstracted interface to the
+ * browsers' event systems.
+ * @supported IE10+, Chrome, Safari
+ */
+</pre>
+ </td><td>Used in a fileoverview to indicate what browsers are supported by
+ the file.
+ </td></tr><tr>
+ <td><code>@desc</code>
+ </td><td><code>@desc Message description</code>
+ <p><em>For example:</em>
+ </p><pre class="prettyprint lang-js">
+/** @desc Notifying a user that their account has been created. */
+exports.MSG_ACCOUNT_CREATED = goog.getMsg(
+ 'Your account has been successfully created.');
+ </pre>
+ </td></tr></tbody></table></p>
+
+<p>You may also see other types of JSDoc annotations in third-party code. These
+annotations appear in the <a href="http://code.google.com/p/jsdoc-toolkit/wiki/TagReference">JSDoc Toolkit Tag Reference</a> but are not considered
+part of valid Google style.</p>
+
+<h4 id="appendices-framework-specific-annotations">9.1.3 Framework specific annotations</h4>
+
+<p>The following annotations are specific to a particular framework.
+<table>
+ <thead>
+ <tr>
+ <th>Framework
+ </th><th>Tag
+ </th><th>Documentation
+ </th></tr></thead><tbody>
+ <tr>
+ <td>Angular 1
+ </td><td><code>@ngInject</code>
+ </td></tr><tr>
+ <td>Polymer
+ </td><td><code>@polymerBehavior</code>
+ </td><td>
+
+ <a href="https://github.com/google/closure-compiler/wiki/Polymer-Pass">https://github.com/google/closure-compiler/wiki/Polymer-Pass</a>
+
+ </td></tr></tbody></table></p>
+
+<h4 id="appendices-notes-about-standard-closure-compiler-annotations">9.1.4 Notes about standard Closure Compiler annotations</h4>
+
+<p>The following tags used to be standard but are now deprecated.
+<table>
+ <thead>
+ <tr>
+ <th>Tag
+ </th><th>Template & Examples
+ </th><th>Description
+ </th></tr></thead><tbody>
+ <tr>
+ <td><code>@expose</code>
+ </td><td><code>@expose</code>
+ </td><td><strong>Deprecated. Do not use. Use <code>@export</code> and/or <code>@nocollapse</code>
+ instead.</strong>
+ </td></tr><tr>
+ <td><code>@inheritDoc</code>
+ </td><td><code>@inheritDoc</code>
+ </td><td><strong>Deprecated. Do not use. Use <code>@override</code> instead.</strong>
+</td></tr></tbody></table></p>
+
+<h3 id="appendices-commonly-misunderstood-style-rules">9.2 Commonly misunderstood style rules</h3>
+
+<p>Here is a collection of lesser-known or commonly misunderstood facts about
+Google Style for JavaScript. (The following are true statements; this is not a
+list of <q>myths.</q>)</p>
+
+<ul>
+<li>Neither a copyright statement nor <code>@author</code> credit is required in a source
+file. (Neither is explicitly recommended, either.)</li>
+<li>Aside from the constructor coming first
+(<a href="#features-classes-constructors">??</a>), there is no <q>hard and fast</q> rule
+governing how to order the members of a class (<a href="#features-classes">??</a>).</li>
+<li>Empty blocks can usually be represented concisely as <code>{}</code>, as detailed in
+(<a href="#formatting-empty-blocks">??</a>).</li>
+<li>The prime directive of line-wrapping is: prefer to break at a higher
+syntactic level (<a href="#formatting-where-to-break">??</a>).</li>
+<li>Non-ASCII characters are allowed in string literals, comments and Javadoc,
+and in fact are recommended when they make the code easier to read than the
+equivalent Unicode escape would (<a href="#non-ascii-characters">??</a>).</li>
+</ul>
+
+<h3 id="appendices-style-related-tools">9.3 Style-related tools</h3>
+
+<p>The following tools exist to support various aspects of Google Style.</p>
+
+<h4 id="appendices-tools-closure-compiler">9.3.1 Closure Compiler</h4>
+
+<p>This program performs type checking and other checks,
+optimizations and other transformations (such as ECMAScript 6 to ECMAScript 5
+code lowering).</p>
+
+<h4 id="appendices-clang-format">9.3.2 <code>clang-format</code></h4>
+
+<p>This program reformats
+JavaScript source code into Google Style, and also follows a number of
+non-required but frequently readability-enhancing formatting practices.</p>
+
+<p><code>clang-format</code> is not required. Authors are allowed to change its output, and
+reviewers are allowed to ask for such changes; disputes are worked out in the
+usual way. However, subtrees may choose to opt in to such enforcement locally.</p>
+
+<h4 id="appendices-closure-compiler-linter">9.3.3 Closure compiler linter</h4>
+
+<p>This program checks for a
+variety of missteps and anti-patterns.
+</p>
+
+<h4 id="appendices-conformance-framework">9.3.4 Conformance framework</h4>
+
+<p>The JS Conformance Framework is a tool that is part of the Closure Compiler that
+provides developers a simple means to specify a set of additional checks to be
+run against their code base above the standard checks. Conformance checks can,
+for example, forbid access to a certain property, or calls to a certain
+function, or missing type information (unknowns).</p>
+
+<p>These rules are commonly used to enforce critical restrictions (such as defining
+globals, which could break the codebase) and security patterns (such as using
+<code>eval</code> or assigning to <code>innerHTML</code>), or more loosely to improve code quality.</p>
+
+<p>For additional information see the official documentation for the
+<a href="https://github.com/google/closure-compiler/wiki/JS-Conformance-Framework">JS Conformance Framework</a>.</p>
+
+<h3 id="appendices-legacy-exceptions">9.4 Exceptions for legacy platforms</h3>
+
+<h4 id="appendices-legacy-exceptions-overview">9.4.1 Overview</h4>
+
+<p>This section describes exceptions and additional rules to be followed when
+modern ECMAScript 6 syntax is not available to the code authors. Exceptions to
+the recommended style are required when ECMAScript 6 syntax is not possible and
+are outlined here:</p>
+
+<ul>
+<li>Use of <code>var</code> declarations is allowed</li>
+<li>Use of <code>arguments</code> is allowed</li>
+<li>Optional parameters without default values are allowed</li>
+</ul>
+
+<h4 id="appendices-legacy-exceptions-var">9.4.2 Use <code>var</code></h4>
+
+<h5 id="appendices-legacy-exceptions-var-scope">9.4.2.1 <code>var</code> declarations are NOT block-scoped</h5>
+
+<p><code>var</code> declarations are scoped to the beginning of the nearest enclosing
+function, script or module, which can cause unexpected behavior, especially with
+function closures that reference <code>var</code> declarations inside of loops. The
+following code gives an example:</p>
+
+<pre><code class="language-js prettyprint badcode">for (var i = 0; i < 3; ++i) {
+ var iteration = i;
+ setTimeout(function() { console.log(iteration); }, i*1000);
+}
+
+// logs 2, 2, 2 -- NOT 0, 1, 2
+// because `iteration` is function-scoped, not local to the loop.
+
+</code></pre>
+
+<h5 id="appendices-legacy-exceptions-var-declare">9.4.2.2 Declare variables as close as possible to first use</h5>
+
+<p>Even though <code>var</code> declarations are scoped to the beginning of the enclosing
+function, <code>var</code> declarations should be as close as possible to their first use,
+for readability purposes. However, do not put a <code>var</code> declaration inside a block
+if that variable is referenced outside the block. For example:</p>
+
+<pre><code class="language-js prettyprint">function sillyFunction() {
+ var count = 0;
+ for (var x in y) {
+ // "count" could be declared here, but don't do that.
+ count++;
+ }
+ console.log(count + ' items in y');
+}
+</code></pre>
+
+<h5 id="appendices-legacy-exceptions-var-const">9.4.2.3 Use @const for constants variables</h5>
+
+<p>For global declarations where the <code>const</code> keyword would be used, if it were
+available, annotate the <code>var</code> declaration with @const instead (this is optional
+for local variables).</p>
+
+<h4 id="appendices-legacy-exceptions-function">9.4.3 Do not use block scoped functions declarations</h4>
+
+<p>Do <strong>not</strong> do this:</p>
+
+<pre><code class="language-js prettyprint badcode">if (x) {
+ function foo() {}
+}
+</code></pre>
+
+<p>While most JavaScript VMs implemented before ECMAScript 6 support function
+declarations within blocks it was not standardized. Implementations were
+inconsistent with each other and with the now-standard ECMAScript 6 behavior for
+block scoped function declaration. ECMAScript 5 and prior only allow for
+function declarations in the root statement list of a script or function and
+explicitly ban them in block scopes in strict mode.</p>
+
+<p>To get consistent behavior, instead use a <code>var</code> initialized with a function
+expression to define a function within a block:</p>
+
+<pre><code class="language-js prettyprint">if (x) {
+ var foo = function() {};
+}
+</code></pre>
+
+<h4 id="appendices-legacy-exceptions-goog-provide">9.4.4 Dependency management with <code>goog.provide</code>/<code>goog.require</code></h4>
+
+<p><strong><code>goog.provide</code> is deprecated. All new files should use <code>goog.module</code>, even in
+projects with existing <code>goog.provide</code> usage. The following rules are for
+pre-existing goog.provide files, only.</strong></p>
+
+<h5 id="appendices-legacy-exceptions-goog-provide-summary">9.4.4.1 Summary</h5>
+
+<ul>
+<li>Place all <code>goog.provide</code>s first, <code>goog.require</code>s second. Separate provides
+from requires with an empty line.</li>
+<li>Sort the entries alphabetically (uppercase first).</li>
+<li>Don't wrap <code>goog.provide</code> and <code>goog.require</code> statements. Exceed 80 columns
+if necessary.</li>
+<li>Only provide top-level symbols.</li>
+</ul>
+
+<p>As of Oct 2016, <strong><code>goog.provide</code>/<code>goog.require</code> dependency management is
+deprecated</strong>. All new files, even in projects using <code>goog.provide</code> for older
+files, should use
+<a href="#source-file-structure"><code>goog.module</code></a>.</p>
+
+<p><code>goog.provide</code> statements should be grouped together and placed first. All
+<code>goog.require</code> statements should follow. The two lists should be separated with
+an empty line.</p>
+
+<p>Similar to import statements in other languages, <code>goog.provide</code> and
+<code>goog.require</code> statements should be written in a single line, even if they
+exceed the 80 column line length limit.</p>
+
+<p>The lines should be sorted alphabetically, with uppercase letters coming first:</p>
+
+<pre><code class="language-js prettyprint">goog.provide('namespace.MyClass');
+goog.provide('namespace.helperFoo');
+
+goog.require('an.extremelyLongNamespace.thatSomeoneThought.wouldBeNice.andNowItIsLonger.Than80Columns');
+goog.require('goog.dom');
+goog.require('goog.dom.TagName');
+goog.require('goog.dom.classes');
+goog.require('goog.dominoes');
+
+</code></pre>
+
+<p>All members defined on a class should be in the same file. Only top-level
+classes should be provided in a file that contains multiple members defined on
+the same class (e.g. enums, inner classes, etc).</p>
+
+<p>Do this:</p>
+
+<pre><code class="language-js prettyprint">goog.provide('namespace.MyClass');
+</code></pre>
+
+<p>Not this:</p>
+
+<pre><code class="language-js prettyprint badcode">goog.provide('namespace.MyClass');
+goog.provide('namespace.MyClass.CONSTANT');
+goog.provide('namespace.MyClass.Enum');
+goog.provide('namespace.MyClass.InnerClass');
+goog.provide('namespace.MyClass.TypeDef');
+goog.provide('namespace.MyClass.staticMethod');
+</code></pre>
+
+<p>Members on namespaces may also be provided:</p>
+
+<pre><code class="language-js prettyprint">goog.provide('foo.bar');
+goog.provide('foo.bar.CONSTANT');
+goog.provide('foo.bar.method');
+</code></pre>
+
+<h5 id="appendices-legacy-exceptions-goog-scope">9.4.4.2 Aliasing with <code>goog.scope</code></h5>
+
+<p><strong><code>goog.scope</code> is deprecated. New files should not use <code>goog.scope</code> even in
+projects with existing goog.scope usage.</strong></p>
+
+<p><code>goog.scope</code> may be used to shorten references to namespaced symbols in
+code using <code>goog.provide</code>/<code>goog.require</code> dependency management.</p>
+
+<p>Only one <code>goog.scope</code> invocation may be added per file. Always place it in
+the global scope.</p>
+
+<p>The opening <code>goog.scope(function() {</code> invocation must be preceded by exactly one
+blank line and follow any <code>goog.provide</code> statements, <code>goog.require</code> statements,
+or top-level comments. The invocation must be closed on the last line in the
+file. Append <code>// goog.scope</code> to the closing statement of the scope. Separate the
+comment from the semicolon by two spaces.</p>
+
+<p>Similar to C++ namespaces, do not indent under <code>goog.scope</code> declarations.
+Instead, continue from the 0 column.</p>
+
+<p>Only make aliases for names that will not be re-assigned to another object
+(e.g., most constructors, enums, and namespaces). Do not do this (see below for
+how to alias a constructor):</p>
+
+<pre><code class="language-js prettyprint badcode">goog.scope(function() {
+var Button = goog.ui.Button;
+
+Button = function() { ... };
+...
+</code></pre>
+
+<p>Names must be the same as the last property of the global that they are aliasing.</p>
+
+<pre><code class="language-js prettyprint">goog.provide('my.module.SomeType');
+
+goog.require('goog.dom');
+goog.require('goog.ui.Button');
+
+goog.scope(function() {
+var Button = goog.ui.Button;
+var dom = goog.dom;
+
+// Alias new types after the constructor declaration.
+my.module.SomeType = function() { ... };
+var SomeType = my.module.SomeType;
+
+// Declare methods on the prototype as usual:
+SomeType.prototype.findButton = function() {
+ // Button as aliased above.
+ this.button = new Button(dom.getElement('my-button'));
+};
+...
+}); // goog.scope
+</code></pre>
+
+</div>
+</body>
+</html>
diff --git a/jsoncstyleguide.html b/jsoncstyleguide.html
new file mode 100644
index 0000000..1bef466
--- /dev/null
+++ b/jsoncstyleguide.html
@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html>
+<head>
+ <meta charset="utf8">
+ <meta http-equiv="content-type" content="text/html;charset=utf-8">
+ <meta http-equiv="refresh" content="1; url=jsoncstyleguide.xml">
+ <title>Redirecting</title>
+</head>
+<!-- The BODY onLoad redirect is the best: it preserves #fragments and
+ ?queries. But it requires javascript. If that fails, the
+ meta-refresh kicks in; it works more generally, but loses fragments
+ and queries, takes a second, and pollutes the browser history.
+ If they both fail, we let the user manually click on the new link.
+-->
+ <body onload="location.replace(location.href.replace('.html', '.xml'))">
+ Redirecting you to <a href="jsoncstyleguide.xml">jsoncstyleguide.xml</a>.
+</body>
+</html>
diff --git a/jsoncstyleguide.xml b/jsoncstyleguide.xml
new file mode 100644
index 0000000..3a2ac25
--- /dev/null
+++ b/jsoncstyleguide.xml
@@ -0,0 +1,1187 @@
+<?xml version="1.0"?>
+<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
+<GUIDE title="Google JSON Style Guide">
+
+<p align="right">
+Revision 0.9
+</p>
+
+<address>
+</address>
+
+<OVERVIEW>
+<CATEGORY title="Important Note">
+<STYLEPOINT title="Display Hidden Details in this Guide">
+<SUMMARY>
+This style guide contains many details that are initially hidden from view. They are marked by the triangle icon, which you see here on your left. Click it now. You should see "Hooray" appear below.
+</SUMMARY>
+<BODY>
+<p>Hooray! Now you know you can expand points to get more details. Alternatively, there's an "expand all" at the top of this document.</p>
+</BODY>
+</STYLEPOINT>
+</CATEGORY>
+<CATEGORY title="Introduction">
+<p>This style guide documents guidelines and recommendations for building JSON APIs at Google. In general, JSON APIs should follow the spec found at <a href="http://www.json.org">JSON.org</a>. This style guide clarifies and standardizes specific cases so that JSON APIs from Google have a standard look and feel. These guidelines are applicable to JSON requests and responses in both RPC-based and REST-based APIs.</p>
+</CATEGORY>
+<CATEGORY title="Definitions">
+<p>For the purposes of this style guide, we define the following terms:</p><ul><li><b>property</b> - a name/value pair inside a JSON object.</li><li><b>property name</b> - the name (or key) portion of the property.</li><li><b>property value</b> - the value portion of the property.</li></ul>
+<CODE_SNIPPET>
+{
+ // The name/value pair together is a "property".
+ "propertyName": "propertyValue"
+}
+
+</CODE_SNIPPET>
+<p>Javascript's <code>number</code> type encompasses all floating-point numbers, which is a broad designation. In this guide, <code>number</code> will refer to JavaScript's <code>number</code> type, while <code>integer</code> will refer to integers.</p>
+</CATEGORY>
+</OVERVIEW>
+<CATEGORY title="General Guidelines">
+<STYLEPOINT title="Comments">
+<SUMMARY>
+No comments in JSON objects.
+</SUMMARY>
+<BODY>
+<p>Comments should not be included in JSON objects. Some of the examples in this style guide include comments. However this is only to clarify the examples.</p>
+<BAD_CODE_SNIPPET>
+{
+ // You may see comments in the examples below,
+ // But don't include comments in your JSON.
+ "propertyName": "propertyValue"
+}
+
+</BAD_CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="Double Quotes">
+<SUMMARY>
+Use double quotes.
+</SUMMARY>
+<BODY>
+<p>If a property requires quotes, double quotes must be used. All property names must be surrounded by double quotes. Property values of type string must be surrounded by double quotes. Other value types (like boolean or number) should not be surrounded by double quotes.</p>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="Flattened data vs Structured Hierarchy">
+<SUMMARY>
+Data should not be arbitrarily grouped for convenience.
+</SUMMARY>
+<BODY>
+<p>Data elements should be "flattened" in the JSON representation. Data should not be arbitrarily grouped for convenience.</p><p>In some cases, such as a collection of properties that represents a single structure, it may make sense to keep the structured hierarchy. These cases should be carefully considered, and only used if it makes semantic sense. For example, an address could be represented two ways, but the structured way probably makes more sense for developers:</p>
+<p>Flattened Address:</p>
+<CODE_SNIPPET>
+{
+ "company": "Google",
+ "website": "https://www.google.com/",
+ "addressLine1": "111 8th Ave",
+ "addressLine2": "4th Floor",
+ "state": "NY",
+ "city": "New York",
+ "zip": "10011"
+}
+</CODE_SNIPPET>
+<p>Structured Address:</p>
+<CODE_SNIPPET>
+{
+ "company": "Google",
+ "website": "https://www.google.com/",
+ "address": {
+ "line1": "111 8th Ave",
+ "line2": "4th Floor",
+ "state": "NY",
+ "city": "New York",
+ "zip": "10011"
+ }
+}
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+</CATEGORY>
+<CATEGORY title="Property Name Guidelines">
+<STYLEPOINT title="Property Name Format">
+<SUMMARY>
+Choose meaningful property names.
+</SUMMARY>
+<BODY>
+<p>Property names must conform to the following guidelines:</p><ul><li>Property names should be meaningful names with defined semantics.</li><li>Property names must be camel-cased, ascii strings.</li><li>The first character must be a letter, an underscore (_) or a dollar sign ($).</li><li>Subsequent characters can be a letter, a digit, an underscore, or a dollar sign.</li><li>Reserved JavaScript keywords should be avoided (A list of reserved JavaScript keywords can be found below).</li></ul><p>These guidelines mirror the guidelines for naming JavaScript identifiers. This allows JavaScript clients to access properties using dot notation. (for example, <code>result.thisIsAnInstanceVariable</code>). Here's an example of an object with one property:</p>
+<CODE_SNIPPET>
+{
+ "thisPropertyIsAnIdentifier": "identifier value"
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="Key Names in JSON Maps">
+<SUMMARY>
+JSON maps can use any Unicode character in key names.
+</SUMMARY>
+<BODY>
+<p>The property name naming rules do not apply when a JSON object is used as a map. A map (also referred to as an associative array) is a data type with arbitrary key/value pairs that use the keys to access the corresponding values. JSON objects and JSON maps look the same at runtime; this distinction is relevant to the design of the API. The API documentation should indicate when JSON objects are used as maps.</p><p>The keys of a map do not have to obey the naming guidelines for property names. Map keys may contain any Unicode characters. Clients can access these properties using the square bracket notation familiar for maps (for example, <code>result.thumbnails["72"]</code>).</p>
+<CODE_SNIPPET>
+{
+ // The "address" property is a sub-object
+ // holding the parts of an address.
+ "address": {
+ "addressLine1": "123 Anystreet",
+ "city": "Anytown",
+ "state": "XX",
+ "zip": "00000"
+ },
+ // The "thumbnails" property is a map that maps
+ // a pixel size to the thumbnail url of that size.
+ "thumbnails": {
+ "72": "http://url.to.72px.thumbnail",
+ "144": "http://url.to.144px.thumbnail"
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="Reserved Property Names">
+<SUMMARY>
+Certain property names are reserved for consistent use across services.
+</SUMMARY>
+<BODY>
+<p>Details about reserved property names, along with the full list, can be found later on in this guide. Services should avoid using these property names for anything other than their defined semantics.</p>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="Singular vs Plural Property Names">
+<SUMMARY>
+Array types should have plural property names. All other property names should be singular.
+</SUMMARY>
+<BODY>
+<p>Arrays usually contain multiple items, and a plural property name reflects this. An example of this can be seen in the reserved names below. The <code>items</code> property name is plural because it represents an array of item objects. Most of the other fields are singular.</p><p>There may be exceptions to this, especially when referring to numeric property values. For example, in the reserved names, <code>totalItems</code> makes more sense than <code>totalItem</code>. However, technically, this is not violating the style guide, since <code>totalItems</code> can be viewed as <code>totalOfItems</code>, where <code>total</code> is singular (as per the style guide), and <code>OfItems</code> serves to qualify the total. The field name could also be changed to <code>itemCount</code> to look singular.</p>
+<CODE_SNIPPET>
+{
+ // Singular
+ "author": "lisa",
+ // An array of siblings, plural
+ "siblings": [ "bart", "maggie"],
+ // "totalItem" doesn't sound right
+ "totalItems": 10,
+ // But maybe "itemCount" is better
+ "itemCount": 10,
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="Naming Conflicts">
+<SUMMARY>
+Avoid naming conflicts by choosing a new property name or versioning the API.
+</SUMMARY>
+<BODY>
+<p>New properties may be added to the reserved list in the future. There is no concept of JSON namespacing. If there is a naming conflict, these can usually be resolved by choosing a new property name or by versioning. For example, suppose we start with the following JSON object:</p>
+<CODE_SNIPPET>
+{
+ "apiVersion": "1.0",
+ "data": {
+ "recipeName": "pizza",
+ "ingredients": ["tomatoes", "cheese", "sausage"]
+ }
+}
+
+</CODE_SNIPPET>
+<p>If in the future we wish to make <code>ingredients</code> a reserved word, we can do one of two things:</p><p>1) Choose a different name:</p>
+<CODE_SNIPPET>
+{
+ "apiVersion": "1.0",
+ "data": {
+ "recipeName": "pizza",
+ "ingredientsData": "Some new property",
+ "ingredients": ["tomatoes", "cheese", "sausage"]
+ }
+}
+
+</CODE_SNIPPET>
+<p>2) Rename the property on a major version boundary:</p>
+<CODE_SNIPPET>
+{
+ "apiVersion": "2.0",
+ "data": {
+ "recipeName": "pizza",
+ "ingredients": "Some new property",
+ "recipeIngredients": ["tomatos", "cheese", "sausage"]
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+</CATEGORY>
+<CATEGORY title="Property Value Guidelines">
+<STYLEPOINT title="Property Value Format">
+<SUMMARY>
+Property values must be Unicode booleans, numbers, strings, objects, arrays, or <code>null</code>.
+</SUMMARY>
+<BODY>
+<p>The spec at <a href="http://www.json.org">JSON.org</a> specifies exactly what type of data is allowed in a property value. This includes Unicode booleans, numbers, strings, objects, arrays, and <code>null</code>. JavaScript expressions are not allowed. APIs should support that spec for all values, and should choose the data type most appropriate for a particular property (numbers to represent numbers, etc.).</p><p>Good:</p>
+<CODE_SNIPPET>
+{
+ "canPigsFly": null, // null
+ "areWeThereYet": false, // boolean
+ "answerToLife": 42, // number
+ "name": "Bart", // string
+ "moreData": {}, // object
+ "things": [] // array
+}
+
+</CODE_SNIPPET>
+<p>Bad:</p>
+<BAD_CODE_SNIPPET>
+{
+ "aVariableName": aVariableName, // Bad - JavaScript identifier
+ "functionFoo": function() { return 1; } // Bad - JavaScript function
+}
+
+</BAD_CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="Empty/Null Property Values">
+<SUMMARY>
+Consider removing empty or <code>null</code> values.
+</SUMMARY>
+<BODY>
+<p>If a property is optional or has an empty or <code>null</code> value, consider dropping the property from the JSON, unless there's a strong semantic reason for its existence.</p>
+<CODE_SNIPPET>
+{
+ "volume": 10,
+
+ // Even though the "balance" property's value is zero, it should be left in,
+ // since "0" signifies "even balance" (the value could be "-1" for left
+ // balance and "+1" for right balance.
+ "balance": 0,
+
+ // The "currentlyPlaying" property can be left out since it is null.
+ // "currentlyPlaying": null
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="Enum Values">
+<SUMMARY>
+Enum values should be represented as strings.
+</SUMMARY>
+<BODY>
+<p>As APIs grow, enum values may be added, removed or changed. Using strings as enum values ensures that downstream clients can gracefully handle changes to enum values.</p><p>Java code:</p>
+<CODE_SNIPPET>
+public enum Color {
+ WHITE,
+ BLACK,
+ RED,
+ YELLOW,
+ BLUE
+}
+
+</CODE_SNIPPET>
+<p>JSON object:</p>
+<CODE_SNIPPET>
+{
+ "color": "WHITE"
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+</CATEGORY>
+<CATEGORY title="Property Value Data Types">
+<p>As mentioned above, property value types must be booleans, numbers, strings, objects, arrays, or <code>null</code>. However, it is useful define a set of standard data types when dealing with certain values. These data types will always be strings, but they will be formatted in a specific manner so that they can be easily parsed.</p>
+<STYLEPOINT title="Date Property Values">
+<SUMMARY>
+Dates should be formatted as recommended by RFC 3339.
+</SUMMARY>
+<BODY>
+<p>Dates should be strings formatted as recommended by <a href="https://www.ietf.org/rfc/rfc3339.txt">RFC 3339</a></p>
+<CODE_SNIPPET>
+{
+ "lastUpdate": "2007-11-06T16:34:41.000Z"
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="Time Duration Property Values">
+<SUMMARY>
+Time durations should be formatted as recommended by ISO 8601.
+</SUMMARY>
+<BODY>
+<p>Time duration values should be strings formatted as recommended by <a href="https://en.wikipedia.org/wiki/ISO_8601#Durations">ISO 8601</a>.</p>
+<CODE_SNIPPET>
+{
+ // three years, six months, four days, twelve hours,
+ // thirty minutes, and five seconds
+ "duration": "P3Y6M4DT12H30M5S"
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="Latitude/Longitude Property Values">
+<SUMMARY>
+Latitudes/Longitudes should be formatted as recommended by ISO 6709.
+</SUMMARY>
+<BODY>
+<p>Latitude/Longitude should be strings formatted as recommended by <a href="https://en.wikipedia.org/wiki/ISO_6709">ISO 6709</a>. Furthermore, they should favor the ±DD.DDDD±DDD.DDDD degrees format.</p>
+<CODE_SNIPPET>
+{
+ // The latitude/longitude location of the statue of liberty.
+ "statueOfLiberty": "+40.6894-074.0447"
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+</CATEGORY>
+<CATEGORY title="JSON Structure & Reserved Property Names">
+<p>In order to maintain a consistent interface across APIs, JSON objects should follow the structure outlined below. This structure applies to both requests and responses made with JSON. Within this structure, there are certain property names that are reserved for specific uses. These properties are NOT required; in other words, each reserved property may appear zero or one times. But if a service needs these properties, this naming convention is recommend. Here is a schema of the JSON structure, represented in <a href="https://www.google.com/url?sa=D&q=http%3A%2F%2Forderly-json.org%2F">Orderly</a> format (which in turn can be compiled into a <a href="https://www.google.com/url?sa=D&q=http%3A%2F%2Fjson-schema.org%2F">JSONSchema</a>). You can few examples of the JSON structure at the end of this guide.</p>
+<CODE_SNIPPET>
+object {
+ string apiVersion?;
+ string context?;
+ string id?;
+ string method?;
+ object {
+ string id?
+ }* params?;
+ object {
+ string kind?;
+ string fields?;
+ string etag?;
+ string id?;
+ string lang?;
+ string updated?; # date formatted RFC 3339
+ boolean deleted?;
+ integer currentItemCount?;
+ integer itemsPerPage?;
+ integer startIndex?;
+ integer totalItems?;
+ integer pageIndex?;
+ integer totalPages?;
+ string pageLinkTemplate /^https?:/ ?;
+ object {}* next?;
+ string nextLink?;
+ object {}* previous?;
+ string previousLink?;
+ object {}* self?;
+ string selfLink?;
+ object {}* edit?;
+ string editLink?;
+ array [
+ object {}*;
+ ] items?;
+ }* data?;
+ object {
+ integer code?;
+ string message?;
+ array [
+ object {
+ string domain?;
+ string reason?;
+ string message?;
+ string location?;
+ string locationType?;
+ string extendedHelp?;
+ string sendReport?;
+ }*;
+ ] errors?;
+ }* error?;
+}*;
+
+</CODE_SNIPPET>
+<p>The JSON object has a few top-level properties, followed by either a <code>data</code> object or an <code>error</code> object, but not both. An explanation of each of these properties can be found below.</p>
+</CATEGORY>
+<CATEGORY title="Top-Level Reserved Property Names">
+<p>The top-level of the JSON object may contain the following properties.</p>
+<STYLEPOINT title="apiVersion">
+<SUMMARY>
+Property Value Type: string<br />Parent: -
+</SUMMARY>
+<BODY>
+<p>Represents the desired version of the service API in a request, and the version of the service API that's served in the response. <code>apiVersion</code> should always be present. This is not related to the version of the data. Versioning of data should be handled through some other mechanism such as etags.</p><p>Example:</p>
+<CODE_SNIPPET>
+{ "apiVersion": "2.1" }
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="context">
+<SUMMARY>
+Property Value Type: string<br />Parent: -
+</SUMMARY>
+<BODY>
+<p>Client sets this value and server echos data in the response. This is useful in JSON-P and batch situations , where the user can use the <code>context</code> to correlate responses with requests. This property is a top-level property because the <code>context</code> should present regardless of whether the response was successful or an error. <code>context</code> differs from <code>id</code> in that <code>context</code> is specified by the user while <code>id</code> is assigned by the service.</p><p>Example:</p><p>Request #1:</p>
+<CODE_SNIPPET>
+https://www.google.com/myapi?context=bart
+
+</CODE_SNIPPET>
+<p>Request #2:</p>
+<CODE_SNIPPET>
+https://www.google.com/myapi?context=lisa
+
+</CODE_SNIPPET>
+<p>Response #1:</p>
+<CODE_SNIPPET>
+{
+ "context": "bart",
+ "data": {
+ "items": []
+ }
+}
+
+</CODE_SNIPPET>
+<p>Response #2:</p>
+<CODE_SNIPPET>
+{
+ "context": "lisa",
+ "data": {
+ "items": []
+ }
+}
+
+</CODE_SNIPPET>
+<p>Common JavaScript handler code to process both responses:</p>
+<CODE_SNIPPET>
+function handleResponse(response) {
+ if (response.result.context == "bart") {
+ // Update the "Bart" section of the page.
+ } else if (response.result.context == "lisa") {
+ // Update the "Lisa" section of the page.
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="id">
+<SUMMARY>
+Property Value Type: string<br />Parent: -
+</SUMMARY>
+<BODY>
+<p>A server supplied identifier for the response (regardless of whether the response is a success or an error). This is useful for correlating server logs with individual responses received at a client.</p><p>Example:</p>
+<CODE_SNIPPET>
+{ "id": "1" }
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="method">
+<SUMMARY>
+Property Value Type: string<br />Parent: -
+</SUMMARY>
+<BODY>
+<p>Represents the operation to perform, or that was performed, on the data. In the case of a JSON request, the <code>method</code> property can be used to indicate which operation to perform on the data. In the case of a JSON response, the <code>method</code> property can indicate the operation performed on the data.</p><p>One example of this is in JSON-RPC requests, where <code>method</code> indicates the operation to perform on the <code>params</code> property:</p>
+<CODE_SNIPPET>
+{
+ "method": "people.get",
+ "params": {
+ "userId": "@me",
+ "groupId": "@self"
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="params">
+<SUMMARY>
+Property Value Type: object<br />Parent: -
+</SUMMARY>
+<BODY>
+<p>This object serves as a map of input parameters to send to an RPC request. It can be used in conjunction with the <code>method</code> property to execute an RPC function. If an RPC function does not need parameters, this property can be omitted.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "method": "people.get",
+ "params": {
+ "userId": "@me",
+ "groupId": "@self"
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data">
+<SUMMARY>
+Property Value Type: object<br />Parent: -
+</SUMMARY>
+<BODY>
+<p>Container for all the data from a response. This property itself has many reserved property names, which are described below. Services are free to add their own data to this object. A JSON response should contain either a <code>data</code> object or an <code>error</code> object, but not both. If both <code>data</code> and <code>error</code> are present, the <code>error</code> object takes precedence.</p>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="error">
+<SUMMARY>
+Property Value Type: object<br />Parent: -
+</SUMMARY>
+<BODY>
+<p>Indicates that an error has occurred, with details about the error. The error format supports either one or more errors returned from the service. A JSON response should contain either a <code>data</code> object or an <code>error</code> object, but not both. If both <code>data</code> and <code>error</code> are present, the <code>error</code> object takes precedence.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "apiVersion": "2.0",
+ "error": {
+ "code": 404,
+ "message": "File Not Found",
+ "errors": [{
+ "domain": "Calendar",
+ "reason": "ResourceNotFoundException",
+ "message": "File Not Found
+ }]
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+</CATEGORY>
+<CATEGORY title="Reserved Property Names in the data object">
+<p>The <code>data</code> property of the JSON object may contain the following properties.</p>
+<STYLEPOINT title="data.kind">
+<SUMMARY>
+Property Value Type: string<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>The <code>kind</code> property serves as a guide to what type of information this particular object stores. It can be present at the <code>data</code> level, or at the <code>items</code> level, or in any object where its helpful to distinguish between various types of objects. If the <code>kind</code> object is present, it should be the first property in the object (See the "Property Ordering" section below for more details).</p><p>Example:</p>
+<CODE_SNIPPET>
+// "Kind" indicates an "album" in the Picasa API.
+{"data": {"kind": "album"}}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data.fields">
+<SUMMARY>
+Property Value Type: string<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>Represents the fields present in the response when doing a partial GET, or the fields present in a request when doing a partial PATCH. This property should only exist during a partial GET/PATCH, and should not be empty.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "data": {
+ "kind": "user",
+ "fields": "author,id",
+ "id": "bart",
+ "author": "Bart"
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data.etag">
+<SUMMARY>
+Property Value Type: string<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>Represents the etag for the response. Details about ETags in the GData APIs can be found here: <a href="https://code.google.com/apis/gdata/docs/2.0/reference.html#ResourceVersioning">https://code.google.com/apis/gdata/docs/2.0/reference.html#ResourceVersioning</a></p><p>Example:</p>
+<CODE_SNIPPET>
+{"data": {"etag": "W/"C0QBRXcycSp7ImA9WxRVFUk.""}}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data.id">
+<SUMMARY>
+Property Value Type: string<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>A globally unique string used to reference the object. The specific details of the <code>id</code> property are left up to the service.</p><p>Example:</p>
+<CODE_SNIPPET>
+{"data": {"id": "12345"}}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data.lang">
+<SUMMARY>
+Property Value Type: string (formatted as specified in BCP 47)<br />Parent: <code>data (or any child element)</code>
+</SUMMARY>
+<BODY>
+<p>Indicates the language of the rest of the properties in this object. This property mimics HTML's <code>lang</code> property and XML's <code>xml:lang</code> properties. The value should be a language value as defined in <a href="https://www.rfc-editor.org/rfc/bcp/bcp47.txt">BCP 47</a>. If a single JSON object contains data in multiple languages, the service is responsible for developing and documenting an appropriate location for the <code>lang</code> property.</p><p>Example:</p>
+<CODE_SNIPPET>
+{"data": {
+ "items": [
+ { "lang": "en",
+ "title": "Hello world!" },
+ { "lang": "fr",
+ "title": "Bonjour monde!" }
+ ]}
+}
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data.updated">
+<SUMMARY>
+Property Value Type: string (formatted as specified in RFC 3339)<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>Indicates the last date/time (<a href="https://www.ietf.org/rfc/rfc3339.txt">RFC 3339</a>) the item was updated, as defined by the service.</p><p>Example:</p>
+<CODE_SNIPPET>
+{"data": {"updated": "2007-11-06T16:34:41.000Z"}}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data.deleted">
+<SUMMARY>
+Property Value Type: boolean<br />Parent: <code>data (or any child element)</code>
+</SUMMARY>
+<BODY>
+<p>A marker element, that, when present, indicates the containing entry is deleted. If deleted is present, its value must be <code>true</code>; a value of <code>false</code> can cause confusion and should be avoided.</p><p>Example:</p>
+<CODE_SNIPPET>
+{"data": {
+ "items": [
+ { "title": "A deleted entry",
+ "deleted": true
+ }
+ ]}
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data.items">
+<SUMMARY>
+Property Value Type: array<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>The property name <code>items</code> is reserved to represent an array of items (for example, photos in Picasa, videos in YouTube). This construct is intended to provide a standard location for collections related to the current result. For example, the JSON output could be plugged into a generic pagination system that knows to page on the <code>items</code> array. If <code>items</code> exists, it should be the last property in the <code>data</code> object (See the "Property Ordering" section below for more details).</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "data": {
+ "items": [
+ { /* Object #1 */ },
+ { /* Object #2 */ },
+ ...
+ ]
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+</CATEGORY>
+<CATEGORY title="Reserved Property Names for Paging">
+<p>The following properties are located in the <code>data</code> object, and help page through a list of items. Some of the language and concepts are borrowed from the <a href="http://www.opensearch.org/Home">OpenSearch specification</a>.</p><p>The paging properties below allow for various styles of paging, including:</p><ul><li>Previous/Next paging - Allows user's to move forward and backward through a list, one page at a time. The <code>nextLink</code> and <code>previousLink</code> properties (described in the "Reserved Property Names for Links" section below) are used for this style of paging.</li><li>Index-based paging - Allows user's to jump directly to a specific item position within a list of items. For example, to load 10 items starting at item 200, the developer may point the user to a url with the query string <code>?startIndex=200</code>.</li><li>Page-based paging - Allows user's to jump directly to a specific page within the items. This is similar to index-based paging, but saves the developer the extra step of having to calculate the item index for a new page of items. For example, rather than jump to item number 200, the developer could jump to page 20. The urls during page-based paging could use the query string <code>?page=1</code> or <code>?page=20</code>. The <code>pageIndex</code> and <code>totalPages</code> properties are used for this style of paging.</li></ul><p>An example of how to use these properties to implement paging can be found at the end of this guide.</p>
+<STYLEPOINT title="data.currentItemCount">
+<SUMMARY>
+Property Value Type: integer<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>The number of items in this result set. Should be equivalent to items.length, and is provided as a convenience property. For example, suppose a developer requests a set of search items, and asks for 10 items per page. The total set of that search has 14 total items. The first page of items will have 10 items in it, so both <code>itemsPerPage</code> and <code>currentItemCount</code> will equal "10". The next page of items will have the remaining 4 items; <code>itemsPerPage</code> will still be "10", but <code>currentItemCount</code> will be "4".</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "data": {
+ // "itemsPerPage" does not necessarily match "currentItemCount"
+ "itemsPerPage": 10,
+ "currentItemCount": 4
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data.itemsPerPage">
+<SUMMARY>
+Property Value Type: integer<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>The number of items in the result. This is not necessarily the size of the data.items array; if we are viewing the last page of items, the size of data.items may be less than <code>itemsPerPage</code>. However the size of data.items should not exceed <code>itemsPerPage</code>.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "data": {
+ "itemsPerPage": 10
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data.startIndex">
+<SUMMARY>
+Property Value Type: integer<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>The index of the first item in data.items. For consistency, <code>startIndex</code> should be 1-based. For example, the first item in the first set of items should have a <code>startIndex</code> of 1. If the user requests the next set of data, the <code>startIndex</code> may be 10.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "data": {
+ "startIndex": 1
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data.totalItems">
+<SUMMARY>
+Property Value Type: integer<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>The total number of items available in this set. For example, if a user has 100 blog posts, the response may only contain 10 items, but the <code>totalItems</code> would be 100.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "data": {
+ "totalItems": 100
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data.pagingLinkTemplate">
+<SUMMARY>
+Property Value Type: string<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>A URI template indicating how users can calculate subsequent paging links. The URI template also has some reserved variable names: <code>{index}</code> representing the item number to load, and <code>{pageIndex}</code>, representing the page number to load.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "data": {
+ "pagingLinkTemplate": "https://www.google.com/search/hl=en&q=chicago+style+pizza&start={index}&sa=N"
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data.pageIndex">
+<SUMMARY>
+Property Value Type: integer<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>The index of the current page of items. For consistency, <code>pageIndex</code> should be 1-based. For example, the first page of items has a <code>pageIndex</code> of 1. <code>pageIndex</code> can also be calculated from the item-based paging properties: <code>pageIndex = floor(startIndex / itemsPerPage) + 1</code>.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "data": {
+ "pageIndex": 1
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data.totalPages">
+<SUMMARY>
+Property Value Type: integer<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>The total number of pages in the result set. <code>totalPages</code> can also be calculated from the item-based paging properties above: <code>totalPages = ceiling(totalItems / itemsPerPage)</code>.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "data": {
+ "totalPages": 50
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+</CATEGORY>
+<CATEGORY title="Reserved Property Names for Links">
+<p>The following properties are located in the <code>data</code> object, and represent references to other resources. There are two forms of link properties: 1) objects, which can contain any sort of reference (such as a JSON-RPC object), and 2) URI strings, which represent URIs to resources (and will always be suffixed with "Link").</p>
+<STYLEPOINT title="data.self / data.selfLink">
+<SUMMARY>
+Property Value Type: object / string<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>The self link can be used to retrieve the item's data. For example, in a list of a user's Picasa album, each album object in the <code>items</code> array could contain a <code>selfLink</code> that can be used to retrieve data related to that particular album.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "data": {
+ "self": { },
+ "selfLink": "https://www.google.com/feeds/album/1234"
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data.edit / data.editLink">
+<SUMMARY>
+Property Value Type: object / string<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>The edit link indicates where a user can send update or delete requests. This is useful for REST-based APIs. This link need only be present if the user can update/delete this item.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "data": {
+ "edit": { },
+ "editLink": "https://www.google.com/feeds/album/1234/edit"
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data.next / data.nextLink">
+<SUMMARY>
+Property Value Type: object / string<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>The next link indicates how more data can be retrieved. It points to the location to load the next set of data. It can be used in conjunction with the <code>itemsPerPage</code>, <code>startIndex</code> and <code>totalItems</code> properties in order to page through data.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "data": {
+ "next": { },
+ "nextLink": "https://www.google.com/feeds/album/1234/next"
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="data.previous / data.previousLink">
+<SUMMARY>
+Property Value Type: object / string<br />Parent: <code>data</code>
+</SUMMARY>
+<BODY>
+<p>The previous link indicates how more data can be retrieved. It points to the location to load the previous set of data. It can be used in conjunction with the <code>itemsPerPage</code>, <code>startIndex</code> and <code>totalItems</code> properties in order to page through data.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "data": {
+ "previous": { },
+ "previousLink": "https://www.google.com/feeds/album/1234/next"
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+</CATEGORY>
+<CATEGORY title="Reserved Property Names in the error object">
+<p>The <code>error</code> property of the JSON object may contain the following properties.</p>
+<STYLEPOINT title="error.code">
+<SUMMARY>
+Property Value Type: integer<br />Parent: <code>error</code>
+</SUMMARY>
+<BODY>
+<p>Represents the code for this error. This property value will usually represent the HTTP response code. If there are multiple errors, <code>code</code> will be the error code for the first error.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "error":{
+ "code": 404
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="error.message">
+<SUMMARY>
+Property Value Type: string<br />Parent: <code>error</code>
+</SUMMARY>
+<BODY>
+<p>A human readable message providing more details about the error. If there are multiple errors, <code>message</code> will be the message for the first error.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "error":{
+ "message": "File Not Found"
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="error.errors">
+<SUMMARY>
+Property Value Type: array<br />Parent: <code>error</code>
+</SUMMARY>
+<BODY>
+<p>Container for any additional information regarding the error. If the service returns multiple errors, each element in the <code>errors</code> array represents a different error.</p><p>Example:</p>
+<CODE_SNIPPET>
+{ "error": { "errors": [] } }
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="error.errors[].domain">
+<SUMMARY>
+Property Value Type: string<br />Parent: <code>error.errors</code>
+</SUMMARY>
+<BODY>
+<p>Unique identifier for the service raising this error. This helps distinguish service-specific errors (i.e. error inserting an event in a calendar) from general protocol errors (i.e. file not found).</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "error":{
+ "errors": [{"domain": "Calendar"}]
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="error.errors[].reason">
+<SUMMARY>
+Property Value Type: string<br />Parent: <code>error.errors</code>
+</SUMMARY>
+<BODY>
+<p>Unique identifier for this error. Different from the <code>error.code</code> property in that this is not an http response code.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "error":{
+ "errors": [{"reason": "ResourceNotFoundException"}]
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="error.errors[].message">
+<SUMMARY>
+Property Value Type: string<br />Parent: <code>error.errors</code>
+</SUMMARY>
+<BODY>
+<p>A human readable message providing more details about the error. If there is only one error, this field will match <code>error.message</code>.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "error":{
+ "code": 404
+ "message": "File Not Found",
+ "errors": [{"message": "File Not Found"}]
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="error.errors[].location">
+<SUMMARY>
+Property Value Type: string<br />Parent: <code>error.errors</code>
+</SUMMARY>
+<BODY>
+<p>The location of the error (the interpretation of its value depends on <code>locationType</code>).</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "error":{
+ "errors": [{"location": ""}]
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="error.errors[].locationType">
+<SUMMARY>
+Property Value Type: string<br />Parent: <code>error.errors</code>
+</SUMMARY>
+<BODY>
+<p>Indicates how the <code>location</code> property should be interpreted.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "error":{
+ "errors": [{"locationType": ""}]
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="error.errors[].extendedHelp">
+<SUMMARY>
+Property Value Type: string<br />Parent: <code>error.errors</code>
+</SUMMARY>
+<BODY>
+<p>A URI for a help text that might shed some more light on the error.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "error":{
+ "errors": [{"extendedHelper": "http://url.to.more.details.example.com/"}]
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="error.errors[].sendReport">
+<SUMMARY>
+Property Value Type: string<br />Parent: <code>error.errors</code>
+</SUMMARY>
+<BODY>
+<p>A URI for a report form used by the service to collect data about the error condition. This URI should be preloaded with parameters describing the request.</p><p>Example:</p>
+<CODE_SNIPPET>
+{
+ "error":{
+ "errors": [{"sendReport": "https://report.example.com/"}]
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+</CATEGORY>
+<CATEGORY title="Property Ordering">
+<p>Properties can be in any order within the JSON object. However, in some cases the ordering of properties can help parsers quickly interpret data and lead to better performance. One example is a pull parser in a mobile environment, where performance and memory are critical, and unnecessary parsing should be avoided.</p>
+<STYLEPOINT title="Kind Property">
+<SUMMARY>
+<code>kind</code> should be the first property
+</SUMMARY>
+<BODY>
+<p>Suppose a parser is responsible for parsing a raw JSON stream into a specific object. The <code>kind</code> property guides the parser to instantiate the appropriate object. Therefore it should be the first property in the JSON object. This only applies when objects have a <code>kind</code> property (usually found in the <code>data</code> and <code>items</code> properties).</p>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="Items Property">
+<SUMMARY>
+<code>items</code> should be the last property in the <code>data</code> object
+</SUMMARY>
+<BODY>
+<p>This allows all of the collection's properties to be read before reading each individual item. In cases where there are a lot of items, this avoids unnecessarily parsing those items when the developer only needs fields from the data.</p>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="Property Ordering Example">
+<BODY>
+<CODE_SNIPPET>
+// The "kind" property distinguishes between an "album" and a "photo".
+// "Kind" is always the first property in its parent object.
+// The "items" property is the last property in the "data" object.
+{
+ "data": {
+ "kind": "album",
+ "title": "My Photo Album",
+ "description": "An album in the user's account",
+ "items": [
+ {
+ "kind": "photo",
+ "title": "My First Photo"
+ }
+ ]
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+</CATEGORY>
+<CATEGORY title="Examples">
+<STYLEPOINT title="YouTube JSON API">
+<SUMMARY>
+Here's an example of the YouTube JSON API's response object. You can learn more about YouTube's JSON API here: <a href="https://code.google.com/apis/youtube/2.0/developers_guide_jsonc.html">https://code.google.com/apis/youtube/2.0/developers_guide_jsonc.html</a>.
+</SUMMARY>
+<BODY>
+<CODE_SNIPPET>
+{
+ "apiVersion": "2.0",
+ "data": {
+ "updated": "2010-02-04T19:29:54.001Z",
+ "totalItems": 6741,
+ "startIndex": 1,
+ "itemsPerPage": 1,
+ "items": [
+ {
+ "id": "BGODurRfVv4",
+ "uploaded": "2009-11-17T20:10:06.000Z",
+ "updated": "2010-02-04T06:25:57.000Z",
+ "uploader": "docchat",
+ "category": "Animals",
+ "title": "From service dog to SURFice dog",
+ "description": "Surf dog Ricochets inspirational video ...",
+ "tags": [
+ "Surf dog",
+ "dog surfing",
+ "dog",
+ "golden retriever",
+ ],
+ "thumbnail": {
+ "default": "https://i.ytimg.com/vi/BGODurRfVv4/default.jpg",
+ "hqDefault": "https://i.ytimg.com/vi/BGODurRfVv4/hqdefault.jpg"
+ },
+ "player": {
+ "default": "https://www.youtube.com/watch?v=BGODurRfVv4&feature=youtube_gdata",
+ "mobile": "https://m.youtube.com/details?v=BGODurRfVv4"
+ },
+ "content": {
+ "1": "rtsp://v5.cache6.c.youtube.com/CiILENy73wIaGQn-Vl-0uoNjBBMYDSANFEgGUgZ2aWRlb3MM/0/0/0/video.3gp",
+ "5": "https://www.youtube.com/v/BGODurRfVv4?f=videos&app=youtube_gdata",
+ "6": "rtsp://v7.cache7.c.youtube.com/CiILENy73wIaGQn-Vl-0uoNjBBMYESARFEgGUgZ2aWRlb3MM/0/0/0/video.3gp"
+ },
+ "duration": 315,
+ "rating": 4.96,
+ "ratingCount": 2043,
+ "viewCount": 1781691,
+ "favoriteCount": 3363,
+ "commentCount": 1007,
+ "commentsAllowed": true
+ }
+ ]
+ }
+}
+
+</CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+<STYLEPOINT title="Paging Example">
+<SUMMARY>
+This example demonstrates how the Google search items could be represented as a JSON object, with special attention to the paging variables.
+</SUMMARY>
+<BODY>
+<p>This sample is for illustrative purposes only. The API below does not actually exist.</p><p>Here's a sample Google search results page:<br /><img src="jsoncstyleguide_example_01.png" /><br /><img src="jsoncstyleguide_example_02.png" /></p><p>Here's a sample JSON representation of this page:</p>
+<CODE_SNIPPET>
+{
+ "apiVersion": "2.1",
+ "id": "1",
+ "data": {
+ "query": "chicago style pizza",
+ "time": "0.1",
+ "currentItemCount": 10,
+ "itemsPerPage": 10,
+ "startIndex": 11,
+ "totalItems": 2700000,
+ "nextLink": "https://www.google.com/search?hl=en&q=chicago+style+pizza&start=20&sa=N"
+ "previousLink": "https://www.google.com/search?hl=en&q=chicago+style+pizza&start=0&sa=N",
+ "pagingLinkTemplate": "https://www.google.com/search/hl=en&q=chicago+style+pizza&start={index}&sa=N",
+ "items": [
+ {
+ "title": "Pizz'a Chicago Home Page"
+ // More fields for the search results
+ }
+ // More search results
+ ]
+ }
+}
+
+</CODE_SNIPPET>
+<p>Here's how each of the colored boxes from the screenshot would be represented (the background colors correspond to the colors in the images above):</p><ul><li>Results <span style="background-color:rgb(180, 167, 214)">11</span> - 20 of about 2,700,000 = startIndex</li><li>Results 11 - <span style="background-color:rgb(255, 217, 102)">20</span> of about 2,700,000 = startIndex + currentItemCount - 1</li><li>Results 11 - 20 of about <span style="background-color:rgb(246, 178, 107)">2,700,000</span> = totalItems</li><li><span style="background-color:rgb(234, 153, 153)">Search results</span> = items (formatted appropriately)</li><li><span style="background-color:rgb(182, 215, 168)">Previous/Next</span> = previousLink / nextLink</li><li><span style="background-color:rgb(159, 197, 232)">Numbered links in "Gooooooooooogle"</span> = Derived from "pageLinkTemplate". The developer is responsible for calculating the values for {index} and substituting those values into the "pageLinkTemplate". The pageLinkTemplate's {index} variable is calculated as follows:<ul><li>Index #1 = 0 * itemsPerPage = 0</li><li>Index #2 = 2 * itemsPerPage = 10</li><li>Index #3 = 3 * itemsPerPage = 20</li><li>Index #N = N * itemsPerPage</li></ul></li></ul>
+</BODY>
+</STYLEPOINT>
+</CATEGORY>
+<CATEGORY title="Appendix">
+<STYLEPOINT title="Appendix A: Reserved JavaScript Words">
+<SUMMARY>
+A list of reserved JavaScript words that should be avoided in property names.
+</SUMMARY>
+<BODY>
+<p>The words below are reserved by the JavaScript language and cannot be referred to using dot notation. The list represents best knowledge of keywords at this time; the list may change or vary based on your specific execution environment.</p><p>From the <a href="https://www.google.com/url?sa=D&q=http%3A%2F%2Fwww.ecma-international.org%2Fpublications%2Fstandards%2FEcma-262.htm">ECMAScript Language Specification 5th Edition</a></p>
+<BAD_CODE_SNIPPET>
+abstract
+boolean break byte
+case catch char class const continue
+debugger default delete do double
+else enum export extends
+false final finally float for function
+goto
+if implements import in instanceof int interface
+let long
+native new null
+package private protected public
+return
+short static super switch synchronized
+this throw throws transient true try typeof
+var volatile void
+while with
+yield
+</BAD_CODE_SNIPPET>
+</BODY>
+</STYLEPOINT>
+</CATEGORY>
+<HR/>
+
+<p align="center">
+Except as otherwise <a href="https://code.google.com/policies.html">noted</a>, the content of this page is licensed under the <a href="https://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 License</a>, and code samples are licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache 2.0 License</a>.
+</p>
+<p align="right">
+Revision 0.9
+</p>
+
+<address>
+</address>
+
+</GUIDE>
diff --git a/jsoncstyleguide_example_01.png b/jsoncstyleguide_example_01.png
new file mode 100644
index 0000000..d7a86ee
--- /dev/null
+++ b/jsoncstyleguide_example_01.png
Binary files differ
diff --git a/jsoncstyleguide_example_02.png b/jsoncstyleguide_example_02.png
new file mode 100644
index 0000000..d3e8243
--- /dev/null
+++ b/jsoncstyleguide_example_02.png
Binary files differ
diff --git a/lispguide.xml b/lispguide.xml
new file mode 100644
index 0000000..519e1a0
--- /dev/null
+++ b/lispguide.xml
@@ -0,0 +1,3887 @@
+<?xml version="1.0"?>
+<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
+<GUIDE title="Google Common Lisp Style Guide">
+
+
+<p align="right">
+
+Revision 1.28
+</p>
+
+
+<address>
+Robert Brown
+</address>
+<address>
+ <a HREF="mailto:tunes@google.com">François-René Rideau</a>
+</address>
+
+<address>
+ In memoriam Dan Weinreb
+</address>
+
+<p align="center">
+<cite>Patterns mean "I have run out of language."</cite> — Rich Hickey
+</p>
+
+
+<OVERVIEW>
+<CATEGORY title="Important Note">
+ <STYLEPOINT title="Note: Displaying Hidden Details in this Guide">
+ <SUMMARY>
+ This style guide contains many details
+ that are initially hidden from view.
+ They are marked by the triangle icon, which you see here on your left.
+ Click it now. You should see "Hooray" appear below.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Hooray! Now you know you can expand points to get more details.
+ Alternatively, there's an "expand all" at the top of this document.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+</CATEGORY>
+<CATEGORY title="Background">
+ <p>
+ Common Lisp is a powerful multiparadigm programming language.
+ With great power comes great responsibility.
+ </p>
+ <p>
+ This guide recommends formatting and stylistic choices
+ designed to make your code easier for other people to understand.
+ For those internal applications and free software libraries that
+ we develop at Google,
+ you should keep within these guidelines when making changes.
+ Note however that each project has its own rules and customs
+ that complement or override these general guidelines;
+ the speed-oriented QPX low fare search engine notably
+ has a very different style and feel from the QRes reservation system.
+ </p>
+ <p>
+ If you're writing Common Lisp code outside Google,
+ we invite you to consider these guidelines.
+ You may find some of them useful
+ where they don't conflict with other priorities you have.
+ We welcome remarks and constructive feedback
+ on how to improve our guide, and
+ on what alternate styles work for you and why.
+ </p>
+
+ <p>
+ This guide is not a Common Lisp tutorial.
+ For basic information about the language, please consult
+ <a HREF="http://www.gigamonkeys.com/book/">Practical Common Lisp</a>.
+ For a language reference, please consult the
+ <a HREF="http://www.lispworks.com/documentation/HyperSpec/Front/index.htm">Common Lisp HyperSpec</a>.
+ For more detailed style guidance, take (with a pinch of salt)
+ a look at Peter Norvig and Kent Pitman's
+ <a HREF="http://norvig.com/luv-slides.ps">style guide</a>.
+ </p>
+</CATEGORY>
+</OVERVIEW>
+<CATEGORY title="Meta-Guide">
+ <STYLEPOINT title="Must, Should, May, or Not">
+ <SUMMARY>
+ Each guideline's level of importance is indicated
+ by use of the following keywords and phrases, adapted from
+ <a href="https://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>.
+ </SUMMARY>
+ <BODY>
+ <table>
+ <tr>
+ <th valign="top">MUST</th>
+ <td>
+ <p>
+ This word, or the terms "REQUIRED" or "SHALL",
+ means that the guideline is an absolute requirement.
+ You must ask permission to violate a MUST.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <th valign="top">MUST NOT</th>
+ <td>
+ <p>
+ This phrase, or the phrase "SHALL NOT",
+ means that the guideline is an absolute prohibition.
+ You must ask permission to violate a MUST NOT.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <th valign="top">SHOULD</th>
+ <td>
+ <p>
+ This word, or the adjective "RECOMMENDED", means that
+ there may exist valid reasons in particular circumstances
+ to ignore the demands of the guideline, but
+ the full implications must be understood and carefully weighed
+ before choosing a different course.
+ You must ask forgiveness for violating a SHOULD.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <th valign="top">SHOULD NOT</th>
+ <td>
+ <p>
+ This phrase, or the phrase "NOT RECOMMENDED", means that
+ there may exist valid reasons in particular circumstances
+ to ignore the prohibitions of this guideline, but
+ the full implications should be understood and carefully weighed
+ before choosing a different course.
+ You must ask forgiveness for violating a SHOULD NOT.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <th valign="top">MAY</th>
+ <td>
+ <p>
+ This word, or the adjective "OPTIONAL",
+ means that an item is truly optional.
+ </p>
+ </td>
+ </tr>
+ </table>
+ <p>
+ Unlike RFCs, we don't capitalize every instance of one of the above
+ keywords when it is used.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Permission and Forgiveness">
+ <SUMMARY>
+ There are cases where transgression of some of these rules
+ is useful or even necessary.
+ In some cases, you must seek permission or obtain forgiveness
+ from the proper people.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Permission comes from the owners of your project.
+ </p>
+
+ <p>
+ Forgiveness is requested in a comment
+ near the point of guideline violation,
+ and is granted by your code reviewer.
+ The original comment should be signed by you, and
+ the reviewer should add a signed approval to the comment at review time.
+ </p>
+
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Conventions">
+ <SUMMARY>
+ You MUST follow conventions. They are not optional.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Some of these guidelines are motivated by universal principles of good programming.
+ Some guidelines are motivated by technical peculiarities of Common Lisp.
+ Some guidelines were once motivated by a technical reason,
+ but the guideline remained after the reason subsided.
+ Some guidelines, such those about as comments and indentation,
+ are based purely on convention, rather than on clear technical merit.
+ Whatever the case may be, you must still follow these guidelines,
+ as well as other conventional guidelines
+ that have not been formalized in this document.
+ </p>
+ <p>
+ You MUST follow conventions.
+ They are important for readability.
+ When conventions are followed by default,
+ violations of the convention are a signal
+ that something notable is happening and deserves attention.
+ When conventions are systematically violated,
+ violations of the convention are a distracting noise
+ that needs to be ignored.
+ </p>
+ <p>
+ Conventional guidelines <em>are</em> indoctrination.
+ Their purpose is to make you follow the mores of the community,
+
+ so you can more effectively cooperate with existing members.
+ It is still useful to distinguish the parts that are technically motivated
+ from the parts that are mere conventions,
+ so you know when best to defy conventions for good effect,
+ and when not to fall into the pitfalls that the conventions are there to help avoid.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Old Code">
+ <SUMMARY>
+ Fix old code as you go.
+ </SUMMARY>
+ <BODY>
+ <p>
+ A lot of our code was written before these guidelines existed.
+ You should fix violations as you encounter them
+ in the course of your normal coding.
+ </p>
+ <p>
+ You must not fix violations en masse
+ without warning other developers and coordinating with them,
+ so as not to make the merging of large branches
+ more difficult than it already is.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Future Topics">
+ <SUMMARY>
+ There are many topics for additional standardization
+ not covered by current version of this document,
+ but deferred to future versions.
+ </SUMMARY>
+ <BODY>
+ <ul>
+ <li>
+ File and directory structure
+ </li>
+ <li>
+ Packages and modularity
+ </li>
+ <li>
+ Threads and locking
+ </li>
+ <li>
+ How to add configurable components
+ </li>
+ <li>
+ CLOS style: initforms, slot and accessor names, etc.
+ </li>
+ <li>
+ Recommendations on max number of slots per class.
+ </li>
+ <li>
+ More concrete examples of good code:
+ <ul>
+ <li>
+ exceptions
+ </li>
+ <li>
+ transactions, with retry
+ </li>
+ <li>
+ XML
+ </li>
+ <li>
+ typing
+ </li>
+ <li>
+ encapsulation / abstraction
+ </li>
+ <li>
+ class and slot names
+ </li>
+ <li>
+ etc.
+ </li>
+ </ul>
+ </li>
+ <li>
+ When (not) to use conditional compilation:
+ <ul>
+ <li>
+ modifying the product
+ </li>
+ <li>
+ conditional debugging/console output/etc.
+ </li>
+ <li>
+ "temporarily" commenting-out blocks of code
+ </li>
+ <li>
+ etc.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </BODY>
+ </STYLEPOINT>
+ </CATEGORY>
+<CATEGORY title="General Guidelines">
+ <STYLEPOINT title="Principles">
+ <SUMMARY>
+ There are some basic principles for team software development
+ that every developer must keep in mind.
+ Whenever the detailed guidelines are inadequate, confusing or contradictory,
+ refer back to these principles for guidance:
+ <ul>
+ <li>
+ Every developer's code must be easy for another developer
+ to read, understand, and modify
+ — even if the first developer isn't around to explain it.
+ (This is the "hit by a truck" principle.)
+ </li>
+ <li>
+ Everybody's code should look the same.
+ Ideally, there should be no way to look at lines of code
+ and recognize it as "Fred's code" by its style.
+ </li>
+ <li>
+ Be precise.
+ </li>
+ <li>
+ Be concise.
+ </li>
+ <li>
+ KISS — Keep It Simple, Stupid.
+ </li>
+ <li>
+ Use the smallest hammer for the job.
+ </li>
+ <li>
+ Use common sense.
+ </li>
+ <li>
+ Keep related code together.
+ Minimize the amount of jumping around
+ someone has to do to understand an area of code.
+ </li>
+ </ul>
+ </SUMMARY>
+ <BODY>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Priorities">
+ <SUMMARY>
+ <p>
+ When making decisions about how to write a given piece of
+ code, aim for the following -ilities in this priority order:
+ </p>
+ <ul>
+ <li>
+ Usability by the customer
+ </li>
+ <li>
+ Debuggability/Testability
+ </li>
+ <li>
+ Readability/Comprehensibility
+ </li>
+ <li>
+ Extensibility/Modifiability
+ </li>
+ <li>
+ Efficiency (of the Lisp code at runtime)
+ </li>
+ </ul>
+ </SUMMARY>
+ <BODY>
+ <p>
+ Most of these are obvious.
+ </p>
+ <p>
+ Usability by the customer means that the system has to do what the
+ customer requires; it has to handle the customer's transaction
+ volumes, uptime requirements; etc.
+ </p>
+ <p>
+ For the Lisp efficiency point,
+ given two options of equivalent complexity,
+ pick the one that performs better.
+ (This is often the same as the one that conses less,
+ i.e. allocates less storage from the heap.)
+ </p>
+ <p>
+ Given two options where one is more complex than the other,
+ pick the simpler option and revisit the decision only if
+ profiling shows it to be a performance bottleneck.
+ </p>
+ <p>
+ However, avoid premature optimization.
+ Don't add complexity to speed up something that runs rarely,
+ since in the long run, it matters less whether such code is fast.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Architecture">
+ <SUMMARY>
+ To build code that is robust and maintainable,
+ it matters a lot how the code is divided into components,
+ how these components communicate,
+ how changes propagate as they evolve,
+ and more importantly
+ how the programmers who develop these components communicate
+ as these components evolve.
+ </SUMMARY>
+ <BODY>
+ <p>
+ If your work affects other groups, might be reusable across groups,
+ adds new components, has an impact on other groups
+ (including QA or Ops), or otherwise isn't purely local,
+ you must write it up using at least a couple of paragraphs,
+ and get a design approval from the other parties involved
+ before starting to write code — or be ready to scratch what you have
+ when they object.
+ </p>
+ <p>
+ If you don't know or don't care about these issues,
+ ask someone who does.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Using Libraries">
+ <SUMMARY>
+ Often, the smallest hammer is to use an existing library.
+ Or one that doesn't exist yet.
+ In such cases, you are encouraged to use or develop such a library,
+ but you must take appropriate precautions.
+ </SUMMARY>
+ <BODY>
+ <ul>
+ <li>
+ You MUST NOT start a new library
+ unless you established that none is already available
+ that can be fixed or completed into becoming what you need.
+ That's a rule against the NIH syndrome ("Not Invented Here"),
+ which is particularly strong amongst Lisp hackers.
+ </li>
+ <li>
+ Whichever library, old or new, you pick, you MUST get permission
+ to incorporate third-party code into the code base.
+ You must discuss the use of such library
+ in the appropriate mailing-list,
+ and have your code reviewed by people knowledgeable in the domain
+ and/or the Lisp library ecosystem (if any).
+ Please be ready to argue why this particular solution makes sense
+ as compared to other available libraries.
+ </li>
+ <li>
+ Some libraries are distributed under licenses not compatible
+ with the software you're writing, and
+ must not be considered available for use.
+ Be aware of these issues, or consult with people who are.
+ </li>
+ </ul>
+
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Open-Sourcing Code">
+ <SUMMARY>
+ <p>
+ If you write a general-purpose library,
+ or modify an existing open-source library,
+ you are encouraged to publish the result
+ separate from your main project and then
+ have your project import it like any other open-source library.
+ </p>
+
+ </SUMMARY>
+ <BODY>
+ <p>
+ Use your judgment to distinguish
+ general-purpose versus business-specific code,
+ and open-source the general-purpose parts,
+ while keeping the business-specific parts a trade secret.
+ </p>
+
+ <p>
+ Open-Sourcing code has many advantages,
+ including being able to leverage third parties for development,
+ letting the development of features be user-directed,
+ and keeping you honest with respect to code quality.
+ Whatever code you write, you will have to maintain anyway,
+ and make sure its quality is high enough to sustain use in production.
+ There should therefore be no additional burden to Open-Sourcing,
+ even of code that (at least initially)
+ is not directly usable by third parties.
+ </p>
+
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Development Process">
+ <SUMMARY>
+ Development process is outside the scope of this document.
+ However, developers should remember at least these bits:
+ get reviewed, write tests, eliminate warnings, run tests, avoid mass-changes.
+ </SUMMARY>
+ <BODY>
+ <p>
+ </p>
+ <ul>
+ <li>
+ All code changes must be reviewed.
+ You should expect that your code will be reviewed by other hackers,
+ and that you will be assigned other hackers' code to review.
+ Part of the review criteria will be that code obeys
+ the coding standards in this document.
+ </li>
+ <li>
+ You must write and check-in tests for new code that you write and old bugs you fix.
+ There must be a unit test for every API function,
+ and any previously failing case.
+ Your work is not truly done until this activity is complete.
+ Estimating tasks must include the time it takes to produce such tests.
+ </li>
+ <li>
+ Your code must compile
+ without any compilation error or warning messages whatsoever.
+ If the compiler issues warnings that should be ignored,
+ muffle those warnings using the
+ <code>UIOP:WITH-MUFFLED-COMPILER-CONDITIONS</code> and
+ <code>UIOP:*UNINTERESTING-COMPILER-CONDITIONS*</code>
+ framework (part of <code>UIOP</code>, part of <code>ASDF 3</code>),
+ either around the entire project, or around individual files
+ (using <code>ASDF</code>'s <code>:around-compile</code> hooks).
+ </li>
+ <li>
+ All code should be checked in an appropriate source control system,
+ in a way that allows for complete reproducibility of
+ build, test and execution of
+ the code that is, has been or may be deployed.
+ </li>
+ <li>
+ You must run the "precheckin" tests, and each component must pass
+ its unit tests successfully before you commit any code.
+ </li>
+ <li>
+ You should incorporate code coverage into your testing process.
+ Tests are not sufficient
+ if they do not cover all new and updated code;
+ code that for whatever reason cannot be included in coverage results
+ should be clearly marked as such including the reason.
+ </li>
+ <li>
+ Many people develop on branches.
+ You must get permission to undertake mass-changes
+ (e.g. mass reindentations)
+ so that we can coordinate in advance,
+ and give branch residents time to get back on the mainline
+ </li>
+ </ul>
+ </BODY>
+ </STYLEPOINT>
+</CATEGORY>
+<CATEGORY title="Formatting">
+ <STYLEPOINT title="Spelling and Abbreviations">
+ <SUMMARY>
+ <p>
+ You must use correct spelling in your comments,
+ and most importantly in your identifiers.
+ </p>
+ <p>
+ When several correct spellings exist (including American vs English),
+ and there isn't a consensus amongst developers as which to use,
+ you should choose the shorter spelling.
+ </p>
+ <p>
+ You must use only common and domain-specific abbreviations, and
+ must be consistent with these abbreviations. You may abbreviate
+ lexical variables of limited scope in order to avoid overly-long
+ symbol names.
+ </p>
+ </SUMMARY>
+ <BODY>
+ <p>
+ If you're not sure, consult a dictionary,
+ Google for alternative spellings,
+ or ask a local expert.
+ </p>
+ <p>
+ Here are examples of choosing the correct spelling:
+ </p>
+ <ul>
+ <li>
+ Use "complimentary" in the sense of a meal or beverage
+ that is not paid for by the recipient, not "complementary".
+ </li>
+ <li>
+ Use "existent" and "nonexistent", not "existant".
+ Use "existence", not "existance".
+ </li>
+ <li>
+ Use "hierarchy" not "heirarchy".
+ </li>
+ <li>
+ Use "precede" not "preceed".
+ </li>
+ <li>
+ Use "weird", not "wierd".
+ </li>
+ </ul>
+ <p>
+ Here are examples of choosing the shorter spelling:
+ </p>
+ <ul>
+ <li>
+ Use "canceled", not "cancelled"
+ </li>
+ <li>
+ Use "queuing", not "queueing".
+ </li>
+ <li>
+ Use "signaled", not "signalled";
+ </li>
+ <li>
+ Use "traveled", not "travelled".
+ </li>
+ <li>
+ Use "aluminum", not "aluminium"
+ </li>
+ <li>
+ Use "oriented", not "orientated"
+ </li>
+ <li>
+ Use "color", not "colour"
+ </li>
+ <li>
+ Use "behavior", not "behaviour"
+ </li>
+ </ul>
+ <p>
+ Make appropriate exceptions for industry standard nomenclature/jargon,
+ including plain misspellings.
+ For instance:
+ </p>
+ <ul>
+ <li>
+ Use "referer", not "referrer", in the context of the HTTP protocol.
+ </li>
+ </ul>
+
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Line length">
+ <SUMMARY>
+ You should format source code so that no line is longer than 100 characters.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Some line length restriction is better than none at all.
+ While old text terminals used to make 80 columns the standard,
+ these days, allowing 100 columns seems better,
+ since good style encourages the use of
+ descriptive variables and function names.
+ </p>
+
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Indentation">
+ <SUMMARY>
+ <p>
+ Indent your code the way a properly configured GNU Emacs does.
+ </p>
+ <p>
+ Maintain a consistent indentation style throughout a project.
+ </p>
+ <p>
+ Indent carefully to make the code easier to understand.
+ </p>
+ </SUMMARY>
+ <BODY>
+ <p>
+ Common Lisp indentation in Emacs is provided by the cl-indent library.
+ The latest version of cl-indent is packaged with
+ <a HREF="https://www.common-lisp.net/project/slime/">SLIME</a>
+ (under contrib/slime-cl-indent.el). After installing SLIME, set up Emacs
+ to load SLIME automatically using
+ <a HREF="https://www.common-lisp.net/project/slime/doc/html/Loading-Contribs.html">these instructions</a>, adding slime-indentation to the list of
+ contrib libraries to be loaded in the call to slime-setup.
+ </p>
+ <p>
+ Ideally, use the default indentation settings provided by
+ slime-indentation. If necessary, customize indentation parameters to
+ maintain a consistent indentation style throughout an existing project.
+ Parameters can be customized using the :variables setting in
+ define-common-lisp-style. Indentation of specific forms can be
+ customized using the :indentation setting of define-common-lisp-style.
+ This is particularly useful when creating forms that behave like macros
+ or special operators that are indented differently than standard
+ function calls (e.g. defun, labels, or let). Add a
+ <a HREF="https://www.gnu.org/software/emacs/manual/html_node/emacs/Hooks.html">hook</a> to 'lisp-mode-hook that calls common-lisp-set-style to set
+ the appropriate style automatically.
+ </p>
+
+
+ <p>
+ Use indentation to make complex function applications easier to read.
+ When an application does not fit on one line
+ or the function takes many arguments,
+ consider inserting newlines between the arguments
+ so that each one is on a separate line.
+ However, do not insert newlines in a way that makes it hard to tell
+ how many arguments the function takes
+ or where an argument form starts and ends.
+ </p>
+ <BAD_CODE_SNIPPET>
+ ;; Bad
+ (do-something first-argument second-argument (lambda (x)
+ (frob x)) fourth-argument last-argument)
+ </BAD_CODE_SNIPPET>
+ <CODE_SNIPPET>
+ ;; Better
+ (do-something first-argument
+ second-argument
+ #'(lambda (x) (frob x))
+ fourth-argument
+ last-argument)
+ </CODE_SNIPPET>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="File Header">
+ <SUMMARY>
+ <p>
+ You should include a description at the top of each source file.
+ </p>
+ <p>
+ You should include neither authorship nor copyright information in a source file.
+ </p>
+ </SUMMARY>
+ <BODY>
+ <p>
+ Every source file should begin with a brief description
+ of the contents of that file.
+ </p>
+ <p>
+ After that description, every file should start the code itself with an
+ <code>(in-package :<em>package-name</em>)</code> form.
+ </p>
+ <p>
+ After that <code>in-package</code> form,
+ every file should follow with any file-specific
+ <code>(declaim (optimize ...))</code> declaration
+ that is not covered by an <code>ASDF</code> <code>:around-compile</code> hook.
+ </p>
+ <CODE_SNIPPET>
+ ;;;; Variable length encoding for integers and floating point numbers.
+
+ (in-package #:varint)
+ (declaim #.*optimize-default*)
+ </CODE_SNIPPET>
+ <p>
+ You should not include authorship information at the top of a file:
+ better information is available from version control,
+ and such a mention will only cause confusion and grief.
+ Indeed, whoever was the main author at the time such a mention was included
+ might not be who eventually made the most significant contributions to the file,
+ and even less who is responsible for the file at the moment.
+
+ </p>
+ <p>
+ You should not include copyright information in individual source code files.
+ An exception is made for files meant to be disseminated as standalone.
+ </p>
+
+
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Vertical white space">
+ <SUMMARY>
+ Vertical white space: one blank line between top-level forms.
+ </SUMMARY>
+ <BODY>
+ <p>
+ You should include one blank line between top-level forms,
+ such as function definitions.
+ Exceptionally, blank lines can be omitted
+ between simple, closely related defining forms of the same kind,
+ such as a group of related type declarations or constant definitions.
+ </p>
+ <CODE_SNIPPET>
+ (defconstant +mix32+ #x12b9b0a1 "pi, an arbitrary number")
+ (defconstant +mix64+ #x2b992ddfa23249d6 "more digits of pi")
+
+ (defconstant +golden-ratio32+ #x9e3779b9 "the golden ratio")
+ (defconstant +golden-ratio64+ #xe08c1d668b756f82 "more digits of the golden ratio")
+
+ (defmacro incf32 (x y)
+ "Like INCF, but for integers modulo 2**32"
+ `(setf ,x (logand (+ ,x ,y) #xffffffff)))
+ (defmacro incf64 (x y)
+ "Like INCF, but for integers modulo 2**64"
+ `(setf ,x (logand (+ ,x ,y) #xffffffffffffffff)))
+ </CODE_SNIPPET>
+ <p>
+ Blank lines can be used to separate parts of a complicated function.
+ Generally, however, you should break a large function into smaller ones
+ instead of trying to make it more readable by adding vertical space.
+ If you can't, you should document with a <code>;;</code> comment
+ what each of the separated parts of the function does.
+ </p>
+ <p>
+ You should strive to keep top-level forms,
+ including comments but excluding the documentation string, of
+ appropriate length; preferrably short. Forms extending beyond a
+ single page should be rare and their use should be justfied.
+ This applies to each of the forms in an <code>eval-when</code>,
+ rather than to the <code>eval-when</code> itself.
+ Additionally, <code>defpackage</code> forms may be longer,
+ since they may include long lists of symbols.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Horizontal white space">
+ <SUMMARY>
+ Horizontal white space: none around parentheses. No tabs.
+ </SUMMARY>
+ <BODY>
+ <p>
+ You must not include extra horizontal whitespace
+ before or after parentheses or around symbols.
+ </p>
+ <p>
+ You must not place right parentheses by themselves on a line.
+ A set of consecutive trailing parentheses must appear on the same line.
+ </p>
+ <BAD_CODE_SNIPPET>
+ ;; Very Bad
+ ( defun factorial ( limit )
+ ( let (( product 1 ))
+ ( loop for i from 1 upto limit
+ do (setf product ( * product i ) ) )
+ product
+ )
+ )
+ </BAD_CODE_SNIPPET>
+ <CODE_SNIPPET>
+ ;; Better
+ (defun factorial (limit)
+ (let ((product 1))
+ (loop for i from 1 upto limit
+ do (setf product (* product i)))
+ product))
+ </CODE_SNIPPET>
+ <p>
+ You should use only one space between forms.
+ </p>
+ <p>
+ You should not use spaces to vertically align forms
+ in the middle of consecutive lines.
+ An exception is made when the code possesses
+ an important yet otherwise not visible symmetry
+ that you want to emphasize.
+ </p>
+ <BAD_CODE_SNIPPET>
+ ;; Bad
+ (let* ((low 1)
+ (high 2)
+ (sum (+ (* low low) (* high high))))
+ ...)
+ </BAD_CODE_SNIPPET>
+ <CODE_SNIPPET>
+ ;; Better
+ (let* ((low 1)
+ (high 2)
+ (sum (+ (* low low) (* high high))))
+ ...))
+ </CODE_SNIPPET>
+ <p>
+ You must align nested forms if they occur across more than one line.
+ </p>
+ <BAD_CODE_SNIPPET>
+ ;; Bad
+ (defun munge (a b c)
+ (* (+ a b)
+ c))
+ </BAD_CODE_SNIPPET>
+ <CODE_SNIPPET>
+ ;; Better
+ (defun munge (a b c)
+ (* (+ a b)
+ c))
+ </CODE_SNIPPET>
+ <p>
+ The convention is that the body of a binding form
+ is indented two spaces after the form.
+ Any binding data before the body is usually indented four spaces.
+ Arguments to a function call are aligned with the first argument;
+ if the first argument is on its own line,
+ it is aligned with the function name.
+ </p>
+ <CODE_SNIPPET>
+ (multiple-value-bind (a b c d)
+ (function-returning-four-values x y)
+ (declare (ignore c))
+ (something-using a)
+ (also-using b d))
+ </CODE_SNIPPET>
+ <p>
+ An exception to the rule against lonely parentheses
+ is made for an <code>eval-when</code> form around several definitions;
+ in this case, include a comment <code>; eval-when</code>
+ after the closing parenthesis.
+ </p>
+ <p>
+ You must set your editor to
+ avoid inserting tab characters in the files you edit.
+ Tabs cause confusion when editors disagree
+ on how many spaces they represent.
+ In Emacs, do <code>(setq-default indent-tabs-mode nil)</code>.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+</CATEGORY>
+
+<CATEGORY title="Documentation">
+ <STYLEPOINT title="Document everything">
+ <SUMMARY>
+ You should use document strings on all visible functions
+ to explain how to use your code.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Unless some bit of code is painfully self-explanatory,
+ document it with a documentation string (also known as docstring).
+ </p>
+ <p>
+ Documentation strings are destined to be read
+ by the programmers who use your code.
+ They can be extracted from functions, types, classes, variables and macros,
+ and displayed by programming tools, such as IDEs,
+ or by REPL queries such as <code>(describe 'foo)</code>;
+ web-based documentation or other reference works
+ can be created based on them.
+ Documentation strings are thus the perfect locus to document your API.
+ They should describe how to use the code
+ (including what pitfalls to avoid),
+ as opposed to how the code works (and where more work is needed),
+ which is what you'll put in comments.
+ </p>
+ <p>
+ Supply a documentation string when defining
+ top-level functions, types, classes, variables and macros.
+ Generally, add a documentation string wherever the language allows.
+ </p>
+ <p>
+ For functions, the docstring should describe the function's contract:
+ what the function does,
+ what the arguments mean,
+ what values are returned,
+ what conditions the function can signal.
+ It should be expressed at the appropriate level of abstraction,
+ explaining the intended meaning rather than, say, just the syntax.
+ In documentation strings, capitalize the names of Lisp symbols,
+ such as function arguments.
+ For example, "The value of LENGTH should be an integer."
+ </p>
+ <CODE_SNIPPET>
+ (defun small-prime-number-p (n)
+ "Return T if N, an integer, is a prime number. Otherwise, return NIL."
+ (cond ((or (< n 2))
+ nil)
+ ((= n 2)
+ t)
+ ((divisorp 2 n)
+ nil)
+ (t
+ (loop for i from 3 upto (sqrt n) by 2
+ never (divisorp i n)))))
+ </CODE_SNIPPET>
+ <CODE_SNIPPET>
+ (defgeneric table-clear (table)
+ (:documentation
+ "Like clrhash, empties the TABLE of all
+ associations, and returns the table itself."))
+ </CODE_SNIPPET>
+ <p>
+ A long docstring may usefully
+ begin with a short, single-sentence summary,
+ followed by the larger body of the docstring.
+ </p>
+ <p>
+ When the name of a type is used,
+ the symbol may be quoted by surrounding it with
+ a back quote at the beginning and a single quote at the end.
+ Emacs will highlight the type, and the highlighting serves
+ as a cue to the reader that <kbd>M-.</kbd>
+ will lead to the symbol's definition.
+ </p>
+ <CODE_SNIPPET>
+ (defun bag-tag-expected-itinerary (bag-tag)
+ "Return a list of `legacy-pnr-pax-segment' objects representing
+ the expected itinerary of the `bag-tag' object, BAG-TAG."
+ ...)
+ </CODE_SNIPPET>
+ <p>
+ Every method of a generic function should be independently documented
+ when the specialization affects what the method does,
+ beyond what is described in its generic function's docstring.
+ </p>
+ <p>
+ When you fix a bug,
+ consider whether what the fixed code does is obviously correct or not;
+ if not, you must add a comment explaining
+ the reason for the code in terms of fixing the bug.
+ Adding the bug number, if any, is also recommended.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Comment semicolons">
+ <SUMMARY>
+ You must use the appropriate number of semicolons to introduce comments.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Comments are explanations to the future maintainers of the code.
+ Even if you're the only person who will ever see and touch the code,
+ even if you're either immortal and never going to quit,
+ or unconcerned with what happens after you leave
+ (and have your code self-destruct in such an eventuality),
+ you may find it useful to comment your code.
+ Indeed, by the time you revisit your code,
+ weeks, months or years later,
+ you will find yourself a different person from the one who wrote it,
+ and you will be grateful to that previous self
+ for making the code readable.
+ </p>
+ <p>
+ You must comment anything complicated
+ so that the next developer can understand what's going on.
+ (Again, the "hit by a truck" principle.)
+ </p>
+ <p>
+ Also use comments as a way to guide those who read the code,
+ so they know what to find where.
+ </p>
+ <ul>
+ <li>
+ File headers and important comments
+ that apply to large sections of code in a source file
+ should begin with four semicolons.
+ </li>
+ <li>
+ You should use three semicolons
+ to begin comments that apply to just
+ one top-level form or small group of top-level forms.
+ </li>
+ <li>
+ Inside a top-level form, you should use two semicolons
+ to begin a comment if it appears between lines.
+ </li>
+ <li>
+ You should use one semicolon if it is a parenthetical remark
+ and occurs at the end of a line.
+ You should use spaces to separate the comment
+ from the code it refers to so the comment stands out.
+ You should try to vertically align
+ consecutive related end-of-line comments.
+ </li>
+ </ul>
+ <CODE_SNIPPET>
+ ;;;; project-euler.lisp
+ ;;;; File-level comments or comments for large sections of code.
+
+ ;;; Problems are described in more detail here: https://projecteuler.net/
+
+ ;;; Divisibility
+ ;;; Comments that describe a group of definitions.
+
+ (defun divisorp (d n)
+ (zerop (mod n d)))
+
+ (defun proper-divisors (n)
+ ...)
+
+ (defun divisors (n)
+ (cons n (proper-divisors n)))
+
+ ;;; Prime numbers
+
+ (defun small-prime-number-p (n)
+ (cond ((or (< n 2))
+ nil)
+ ((= n 2) ; parenthetical remark here
+ t) ; continuation of the remark
+ ((divisorp 2 n)
+ nil) ; different remark
+ ;; Comment that applies to a section of code.
+ (t
+ (loop for i from 3 upto (sqrt n) by 2
+ never (divisorp i n)))))
+ </CODE_SNIPPET>
+ <p>
+ You should include a space between the semicolon and the text of the comment.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Grammar and punctuation">
+ <SUMMARY>
+ You should punctuate documentation correctly.
+ </SUMMARY>
+ <BODY>
+ <p>
+ When a comment is a full sentence,
+ you should capitalize the initial letter of the first word
+ and end the comment with a period.
+ In general, you should use correct punctuation.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Attention Required">
+ <SUMMARY>
+ You must follow the convention of using TODO comments
+ for code requiring special attention.
+ For code using unobvious forms, you must include a comment.
+ </SUMMARY>
+ <BODY>
+ <p>
+ For comments requiring special attention, such as
+ incomplete code, todo items, questions, breakage, and danger,
+ include a TODO comment indicating the type of problem,
+ its nature, and any notes on how it may be addressed.
+ </p>
+ <p>
+ The comments begin with <code>TODO</code> in all capital letters,
+ followed by the
+
+ name, e-mail address, or other identifier
+ of the person
+ with the best context about the problem referenced by the <code>TODO</code>.
+ The main purpose is to have a consistent <code>TODO</code> that
+ can be searched to find out how to get more details upon
+ request. A <code>TODO</code> is not a commitment that the
+ person referenced will fix the problem. Thus when you create
+ a <code>TODO</code>,
+ it is almost always your
+ name
+ that is given.
+ </p>
+ <p>
+ When signing comments,
+ you should use your username (for code within the company)
+ or full email address (for code visible outside the company),
+ not just initials.
+
+ </p>
+ <CODE_SNIPPET>
+ ;;--- TODO(george@gmail.com): Refactor to provide a better API.
+ </CODE_SNIPPET>
+ <p>
+ Be specific when indicating times or software releases
+ in a TODO comment and use
+ <a HREF="https://www.w3.org/TR/NOTE-datetime">YYYY-MM-DD</a>
+ format for dates to make automated processing of such dates easier,
+ e.g., 2038-01-20 for the end of the 32-bit signed <code>time_t</code>.
+ </p>
+ <CODE_SNIPPET>
+ ;;--- TODO(brown): Remove this code after release 1.7 or before 2012-11-30.
+ </CODE_SNIPPET>
+ <p>
+ For code that uses unobvious forms to accomplish a task, you must include a comment
+ stating the purpose of the form and the task it accomplishes.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Domain-Specific Languages">
+ <SUMMARY>
+ You should document DSLs and
+ any terse program in a DSL.
+ </SUMMARY>
+ <BODY>
+ <p>
+ You should design your Domain Specific Language
+ to be easy to read and understand by people familiar with the domain.
+ </p>
+ <p>
+ You must properly document all your Domain Specific Language.
+ </p>
+ <p>
+ Sometimes, your DSL is designed for terseness.
+ In that case, it is important to document what each program does,
+ if it's not painfully obvious from the context.
+ </p>
+ <p>
+ Notably, when you use regular expressions
+ (e.g. with the <code>CL-PPCRE</code> package),
+ you MUST ALWAYS put in a comment
+ (usually a two-semicolon comment on the previous line)
+ explaining, at least basically, what the regular expression does,
+ or what the purpose of using it is.
+ The comment need not spell out every bit of the syntax, but
+ it should be possible for someone to follow the logic of the code
+ without actually parsing the regular expression.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+</CATEGORY>
+
+<CATEGORY title="Naming">
+ <STYLEPOINT title="Symbol guidelines">
+ <SUMMARY>
+ You should use lower case.
+ You should follow the rules for <a href="#Spelling_and_Abbreviations">Spelling and Abbreviations</a>
+ You should follow punctuation conventions.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Use lower case for all symbols.
+ Consistently using lower case makes searching for symbol names easier
+ and is more readable.
+ </p>
+ <p>
+ Note that Common Lisp is case-converting,
+ and that the <code>symbol-name</code> of your symbols
+ will be upper case.
+ Because of this case-converting,
+ attempts to distinguish symbols by case are defeated,
+ and only result in confusion.
+ While it is possible to escape characters in symbols
+ to force lower case,
+ you should not use this capability
+ unless this is somehow necessary
+ to interoperate with third-party software.
+ </p>
+ <p>
+ Place hyphens between all the words in a symbol.
+ If you can't easily say an identifier out loud,
+ it is probably badly named.
+ </p>
+ <p>
+ You must not use <code>"/"</code> or <code>"."</code>
+ instead of <code>"-"</code>
+ unless you have a well-documented overarching reason to,
+ and permission from other hackers who review your proposal.
+ </p>
+ <p>
+ See the section on <a href="#Spelling_and_Abbreviations">Spelling and Abbreviations</a>
+ for guidelines on using abbreviations.
+ </p>
+ <BAD_CODE_SNIPPET>
+ ;; Bad
+ (defvar *default-username* "Ann")
+ (defvar *max-widget-cnt* 200)
+ </BAD_CODE_SNIPPET>
+ <CODE_SNIPPET>
+ ;; Better
+ (defvar *default-user-name* "Ann")
+ (defvar *maximum-widget-count* 200)
+ </CODE_SNIPPET>
+ <p>
+ There are conventions in Common Lisp
+ for the use of punctuation in symbols.
+ You should not use punctuation in symbols outside these conventions.
+ </p>
+ <p>
+ Unless the scope of a variable is very small,
+ do not use overly short names like
+ <code>i</code> and <code>zq</code>.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Denote intent, not content">
+ <SUMMARY>
+ Name your variables according to their intent,
+ not their content.
+ </SUMMARY>
+ <BODY>
+ <p>
+ You should name a variable according
+ to the high-level concept that it represents,
+ not according to the low-level implementation details
+ of how the concept is represented.
+ </p>
+ <p>
+ Thus, you should avoid embedding
+ data structure or aggregate type names,
+ such as <code>list</code>, <code>array</code>, or
+ <code>hash-table</code> inside variable names,
+ unless you're writing a generic algorithm that applies to
+ arbitrary lists, arrays, hash-tables, etc.
+ In that case it's perfectly OK to name a variable
+ <code>list</code> or <code>array</code>.
+ </p>
+ <p>
+ Indeed, you should be introducing new abstract data types
+ with <code>DEFCLASS</code> or <code>DEFTYPE</code>,
+ whenever a new kind of intent appears for objects in your protocols.
+ Functions that manipulate such objects generically may then
+ use variables the name of which reflect that abstract type.
+ </p>
+ <p>
+ For example, if a variable's value is always a row
+ (or is either a row or <code>NIL</code>),
+ it's good to call it <code>row</code> or <code>first-row</code>
+ or something like that.
+ It is alright is <code>row</code> has been
+ <code>DEFTYPE</code>'d to <code>STRING</code> —
+ precisely because you have abstracted the detail away,
+ and the remaining salient point is that it is a row.
+ You should not name the variable <code>STRING</code> in this context,
+ except possibly in low-level functions that specifically manipulate
+ the innards of rows to provide the suitable abstraction.
+ </p>
+ <p>
+ Be consistent.
+ If a variable is named <code>row</code> in one function,
+ and its value is being passed to a second function,
+ then call it <code>row</code> rather than, say, <code>value</code>
+ (this was a real case).
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Global variables and constants">
+ <SUMMARY>
+ Name globals according to convention.
+ </SUMMARY>
+ <BODY>
+ <p>
+ The names of global constants should start and end
+ with plus characters.
+ </p>
+ <p>
+ Global variable names should start and end with asterisks
+ (also known in this context as earmuffs).
+ </p>
+ <p>
+ In some projects, parameters that are not meant
+ to be usually modified or bound under normal circumstances
+ (but may be during experimentation or exceptional situations)
+ should start (but do not end) with a dollar sign.
+ If such a convention exists within your project,
+ you should follow it consistently.
+ Otherwise, you should avoid naming variables like this.
+ </p>
+ <p>
+ Common Lisp does not have global lexical variables,
+ so a naming convention is used to ensure that globals,
+ which are dynamically bound,
+ never have names that overlap with local variables.
+ It is possible to fake global lexical variables
+ with a differently named global variable
+ and a <code>DEFINE-SYMBOL-MACRO</code>.
+ You should not use this trick,
+ unless you first publish a library that abstracts it away.
+ </p>
+ <CODE_SNIPPET>
+ (defconstant +hash-results+ #xbd49d10d10cbee50)
+
+ (defvar *maximum-search-depth* 100)
+ </CODE_SNIPPET>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Predicate names">
+ <SUMMARY>
+ Names of predicate functions and variables end with a <code>"P"</code>.
+ </SUMMARY>
+ <BODY>
+ <p>
+ You should name boolean-valued functions and variables with a
+ trailing <code>"P"</code> or <code>"-P"</code>,
+ to indicate they are predicates.
+ Generally, you should use
+ <code>"P"</code> when the rest of the function name is one word
+ and <code>"-P"</code> when it is more than one word.
+ </p>
+ <p>
+ A rationale for this convention is given in
+ <a href="http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node69.html">the CLtL2 chapter on predicates</a>.
+ </p>
+ <p>
+ For uniformity, you should follow the convention above,
+ and not one of the alternatives below.
+ </p>
+ <p>
+ An alternative rule used in some existing packages
+ is to always use <code>"-P"</code>.
+ Another alternative rule used in some existing packages
+ is to always use <code>"?"</code>.
+ When you develop such a package,
+ you must be consistent with the rest of the package.
+ When you start a new package,
+ you should not use such an alternative rule
+ without a very good documented reason.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Omit library prefixes">
+ <SUMMARY>
+ You should not include a library or package name
+ as a prefix within the name of symbols.
+ </SUMMARY>
+ <BODY>
+ <p>
+ When naming a symbol (external or internal) in a package,
+ you should not include the package name
+ as a prefix within the name of the symbol.
+ Naming a symbol this way makes it awkward to use
+ from a client package accessing the symbol
+ by qualifying it with a package prefix,
+ where the package name then appears twice
+ (once as a package prefix,
+ another time as a prefix within the symbol name).
+ </p>
+ <BAD_CODE_SNIPPET>
+ ;; Bad
+ (in-package #:varint)
+ (defun varint-length64 () ... )
+
+ (in-package #:client-code)
+ (defconst +padding+ (varint:varint-length64 +end-token+))
+ </BAD_CODE_SNIPPET>
+ <CODE_SNIPPET>
+ ;; Better
+ (in-package #:varint)
+ (defun length64 () ... )
+
+ (in-package #:client-code)
+ (defconst +padding+ (varint:length64 +end-token+))
+ </CODE_SNIPPET>
+ <p>
+ An exception to the above rule would be to include a prefix
+ for the names of variables that would otherwise be expected to clash
+ with variables in packages that use the current one.
+ For instance, <code>ASDF</code> exports a variable <code>*ASDF-VERBOSE*</code>
+ that controls the verbosity of <code>ASDF</code> only,
+ rather than of the entire Lisp program.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Packages">
+ <SUMMARY>
+ Use packages appropriately.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Lisp packages are used to demarcate namespaces.
+ Usually, each system has its own namespace.
+ A package has a set of external symbols,
+ which are intended to be used from outside the package,
+ in order to allow other modules to use this module's facilities.
+ </p>
+ <p>
+ The internal symbols of a package
+ should never be referred to from other packages.
+ That is, you should never have to use
+ the double-colon <code>::</code> construct.
+ (e.g. <code>QUAKE::HIDDEN-FUNCTION</code>).
+ If you need to use double-colons to write real production code,
+ something is wrong and needs to be fixed.
+ </p>
+ <p>
+ As an exception,
+ unit tests may use the internals of the package being tested.
+ So when you refactor, watch out for
+ internals used by the package's unit tests.
+ </p>
+ <p>
+ The <code>::</code> construct is also useful for very temporary hacks,
+ and at the REPL.
+ But if the symbol really is part of
+ the externally-visible definition of the package,
+ export it.
+ </p>
+ <p>
+ You may find that some internal symbols represent concepts
+ you usually want to abstract away and hide under the hood,
+ yet at times are necessary to expose for various extensions.
+ For the former reason, you do not want to export them,
+ yet for the latter reason, you have to export them.
+ The solution is to have two different packages,
+ one for your normal users to use, and
+ another for the implementation and its extenders to use.
+ </p>
+ <p>
+ Each package is one of two types:
+ </p>
+ <ul>
+ <li>
+ Intended to be included
+ in the <code>:use</code> specification of other packages.
+ If package <code>A</code> "uses" package <code>B</code>,
+ then the external symbols of package <code>B</code>
+ can be referenced from within package <code>A</code>
+ without a package prefix.
+ We mainly use this for low-level modules
+ that provide widely-used facilities.
+ </li>
+ <li>
+ Not intended to be "used".
+ To reference a facility provided by package <code>B</code>,
+ code in package <code>A</code> must use an explicit package prefix,
+ e.g. <code>B:DO-THIS</code>.
+ </li>
+ </ul>
+ <p>
+ If you add a new package, it should always be of the second type,
+ unless you have a special reason and get permission.
+ Usually a package is designed to be one or the other,
+ by virtue of the names of the functions.
+ For example, if you have an abstraction called <code>FIFO</code>,
+ and it were in a package of the first type
+ you'd have functions named things like
+ <code>FIFO-ADD-TO</code> and <code>FIFO-CLEAR-ALL</code>.
+ If you used a package of the second type,
+ you'd have names like <code>ADD-TO</code> and <code>CLEAR-ALL</code>,
+ because the callers would be saying
+ <code>FIFO:ADD-TO</code> and <code>FIFO:CLEAR-ALL</code>.
+ (<code>FIFO:FIFO-CLEAR-ALL</code> is redundant and ugly.)
+ </p>
+ <p>
+ Another good thing about packages is that
+ your symbol names won't "collide" with the names of other packages,
+ except the ones your packages "uses".
+ So you have to stay away from symbols
+ that are part of the Lisp implementation (since you always "use" that)
+ and that are part of any other packages you "use",
+ but otherwise you are free to make up your own names,
+ even short ones, and not worry about some else
+ having used the same name.
+ You're isolated from each other.
+ </p>
+ <p>
+ Your package must not shadow (and thus effectively redefine)
+ symbols that are part of the Common Lisp language.
+ There are certain exceptions,
+ but they should be very well-justified and extremely rare:
+ </p>
+ <ul>
+ <li>
+ If you are explicitly replacing a Common Lisp symbol
+ by a safer or more featureful version.
+ </li>
+ <li>
+ If you are defining a package not meant to be "used",
+ and have a good reason to export a symbol
+ that clashes with Common Lisp,
+ such as <code>log:error</code> and <code>log:warn</code>
+ and so on.
+ </li>
+ </ul>
+ </BODY>
+ </STYLEPOINT>
+</CATEGORY>
+
+<CATEGORY title="Language usage guidelines">
+ <STYLEPOINT title="Mostly Functional Style">
+ <SUMMARY>
+ You should avoid side-effects when they are not necessary.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Lisp is best used as a "mostly functional" language.
+ </p>
+ <p>
+ Avoid modifying local variables, try rebinding instead.
+ </p>
+ <p>
+ Avoid creating objects and the SETFing their slots.
+ It's better to set the slots during initialization.
+ </p>
+ <p>
+ Make classes as immutable as possible, that is, avoid giving slots
+ setter functions if at all possible.
+ </p>
+ <p>
+ Using a mostly functional style makes it much easier
+ to write concurrent code that is thread-safe.
+ It also makes it easier to test the code.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Recursion">
+ <SUMMARY>
+ You should favor iteration over recursion.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Common Lisp systems are not required to implement
+ function calls from tail positions without leaking stack space
+ — which is known as proper tail calls (PTC),
+ tail call elimination (TCE),
+ or tail call optimization (TCO).
+ This means that indefinite recursion through tail calls
+ may quickly blow out the stack,
+ which hampers functional programming.
+ Still, most serious implementations (including SBCL and CCL)
+ do implement proper tail calls, but with restrictions:
+ </p>
+ <ul>
+ <li>
+ The <code>(DECLARE (OPTIMIZE ...))</code> settings
+ must favor <code>SPEED</code> enough and
+ not favor <code>DEBUG</code> too much,
+ for some compiler-dependent meanings of "enough" and "too much".
+ (For instance, in SBCL, you should avoid <code>(SPEED 0)</code>
+ and <code>(DEBUG 3)</code> to achieve proper tail calls.)
+ </li>
+ <li>
+ There should not be dynamic bindings around the call
+ (even though some Scheme compilers are able to properly treat
+ such dynamic bindings, called parameters in Scheme parlance).
+ </li>
+ </ul>
+ <p>
+ For compatibility with all compilers and optimization settings,
+ and to avoid stack overflow when debugging,
+ you should prefer iteration or the built in mapping functions
+ to relying on proper tail calls.
+ </p>
+ <p>
+ If you do rely on proper tail calls,
+ you must prominently document the fact,
+ and take appropriate measures to ensure an appropriate compiler is used
+ with appropriate optimization settings.
+ For fully portable code, you may have to use trampolines instead.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Special variables">
+ <SUMMARY>
+ Use special variables sparingly.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Using Lisp "special" (dynamically bound) variables
+ as implicit arguments to functions should be used sparingly,
+ and only in cases where it won't surprise the person reading the code,
+ and where it offers significant benefits.
+ </p>
+ <p>
+ Indeed, each special variable constitutes state.
+ Developers have to mentally track the state of all relevant variables
+ when trying to understand what the code does and how it does it;
+ tests have to be written and run with all relevant combinations;
+ to isolate some activity, care has to be taken to locally bind
+ all relevant variables, including those of indirectly used modules.
+ They can hide precious information from being printed in a backtrace.
+ Not only is there overhead associated to each new variable,
+ but interactions between variables
+ can make the code exponentially more complex
+ as the number of such variables increases.
+ The benefits have to match the costs.
+ </p>
+ <p>
+ Note though that a Lisp special variable is not a global variable
+ in the sense of a global variable in, say, BASIC or C.
+ As special variables can be dynamically bound to a local value,
+ they are much more powerful than
+ global value cells where all users necessarily interfere with each other.
+ </p>
+ <p>
+ Good candidates for such special variables
+ are items for which "the current" can be naturally used as prefix,
+ such as "the current database connection" or
+ "the current business data source".
+ They are singletons as far as the rest of the code is concerned,
+ and often passing them as an explicit argument
+ does not add anything to the readability or maintainability
+ of the source code in question.
+ </p>
+ <p>
+ They can make it easier to write code that can be refactored.
+ If you have a request processing chain,
+ with a number of layers that all operate upon a "current" request,
+ passing the request object explicitly to every function
+ requires that every function in the chain have a request argument.
+ Factoring out code into new functions often requires
+ that these functions also have this argument,
+ which clutters the code with boilerplate.
+ </p>
+ <p>
+ You should treat special variables
+ as though they are per-thread variables.
+ By default, you should leave a special variable
+ with no top-level binding at all,
+ and each thread of control
+ that needs the variable should bind it explicitly.
+ This will mean that any incorrect use of the variable
+ will result in an "unbound variable" error, and
+ each thread will see its own value for the variable.
+ Variables with a default global value should usually be
+ locally bound at thread creation time.
+ You should use suitable infrastructure
+ to automate the appropriate declaration of such variables.
+ </p>
+
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Assignment">
+ <SUMMARY>
+ Be consistent in assignment forms.
+ </SUMMARY>
+ <BODY>
+ <p>
+ There are several styles for dealing with assignment and side-effects;
+ whichever a given package is using,
+ keep using the same consistently when hacking said package.
+ Pick a style that makes sense when starting a new package.
+ </p>
+ <p>
+ Regarding multiple assignment in a same form, there are two schools:
+ the first style groups as many assignments as possible into a single
+ <code>SETF</code> or <code>PSETF</code> form
+ thus minimizing the number of forms with side-effects;
+ the second style splits assignments into as many individual
+ <code>SETF</code> (or <code>SETQ</code>, see below) forms as possible,
+ to maximize the chances of locating forms that modify a kind of place
+ by grepping for <code>(setf (foo ...</code>.
+ A grep pattern must actually contain as many place-modifying forms
+ as you may use in your programs, which may make this rationale either
+ convincing or moot depending on the rest of the style of your code.
+ You should follow the convention used in the package you are hacking.
+ We recommend the first convention for new packages.
+ </p>
+ <p>
+ Regarding <code>SETF</code> and <code>SETQ</code>,
+ there are two schools:
+ this first regards <code>SETQ</code>
+ as an archaic implementation detail,
+ and avoids it entirely in favor of <code>SETF</code>;
+ the second regards <code>SETF</code>
+ as an additional layer of complexity,
+ and avoids it in favor of <code>SETQ</code> whenever possible
+ (i.e. whenever the assigned place is a variable or symbol-macro).
+ You should follow the convention used in the package you are hacking.
+ We recommend the first convention for new packages.
+ </p>
+ <p>
+ In the spirit of a mostly pure functional style,
+ which makes testing and maintenance easier,
+ we invite you to consider how to do things with the fewest assignments required.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Assertions and Conditions">
+ <SUMMARY>
+ You must make proper usage of assertions and conditions.
+ </SUMMARY>
+ <BODY>
+ <ul>
+ <li>
+ <code>ASSERT</code> should be used ONLY to detect internal bugs.
+ Code should <code>ASSERT</code> invariants whose failure indicates
+ that the software is itself broken.
+ Incorrect input should be handled properly at runtime,
+ and must not cause an assertion violation.
+ The audience for an <code>ASSERT</code> failure is a developer.
+ Do not use the data-form and argument-form in <code>ASSERT</code>
+ to specify a condition to signal.
+ It's fine to use them to print out a message for debugging purposes
+ (and since it's only for debugging, there's no issue of
+ internationalization).
+ </li>
+ <li>
+ <code>CHECK-TYPE</code>,
+ <code>ETYPECASE</code> are also forms of assertion.
+ When one of these fails, that's a detected bug.
+ You should prefer to use <code>CHECK-TYPE</code>
+ over (DECLARE (TYPE ...))
+ for the inputs of functions.
+ </li>
+ <li>
+ Your code should use assertions and type checks liberally.
+ The sooner a bug is discovered, the better!
+ Only code in the critical path for performance
+ and internal helpers should eschew
+ explicit assertions and type checks.
+ </li>
+ <li>
+ Invalid input, such as files that are read
+ but do not conform to the expected format,
+ should not be treated as assertion violations.
+ Always check to make sure that input is valid,
+ and take appropriate action if it is not,
+ such as signalling a real error.
+ </li>
+ <li>
+ <code>ERROR</code> should be used
+ to detect problems with user data, requests, permissions, etc.,
+ or to report "unusual outcomes" to the caller.
+ </li>
+ <li>
+ <code>ERROR</code> should always be called
+ with an explicit condition type;
+ it should never simply be called with a string.
+ This enables internationalization.
+ </li>
+ <li>
+ Functions that report unusual outcomes
+ by signaling a condition should say so explicitly in their contracts
+ (their textual descriptions, in documentation and docstrings etc.).
+ When a function signals a condition
+ that is not specified by its contract, that's a bug.
+ The contract should specify the condition class(es) clearly.
+ The function may then signal any condition
+ that is a type-of any of those conditions.
+ That is, signaling instances of subclasses
+ of the documented condition classes is fine.
+ </li>
+ <li>
+ Complex bug-checks may need to use <code>ERROR</code>
+ instead of <code>ASSERT</code>.
+
+ </li>
+ <li>
+ When writing a server, you must not call <code>WARN</code>.
+ Instead, you should use the appropriate logging framework.
+
+ </li>
+ <li>
+ Code must not call <code>SIGNAL</code>.
+ Instead, use <code>ERROR</code> or <code>ASSERT</code>.
+ </li>
+ <li>
+ Code should not use <code>THROW</code> and <code>CATCH</code>;
+ instead use the <code>restart</code> facility.
+ </li>
+ <li>
+ Code should not generically handle all conditions,
+ e.g. type <code>T</code>, or use <code>IGNORE-ERRORS</code>.
+ Instead, let unknown conditions propagate to
+ the standard ultimate handler for processing.
+
+ </li>
+ <li>
+ There are a few places where handling all conditions is appropriate,
+ but they are rare.
+ The problem is that handling all conditions can mask program bugs.
+ If you <em>do</em> need to handle "all conditions",
+ you MUST handle only <code>ERROR</code>, <em>not</em> <code>T</code>
+ and not <code>SERIOUS-CONDITION</code>.
+ (This is notably because CCL's process shutdown
+ depends on being able to signal <code>process-reset</code>
+ and have it handled by CCL's handler,
+ so we must not interpose our own handler.)
+ </li>
+ <li>
+ <code>(error (make-condition 'foo-error ...))</code>
+ is equivalent to <code>(error 'foo-error ...)</code> —
+ code must use the shorter form.
+ </li>
+ <li>
+ Code should not signal conditions from inside the cleanup form of
+ <code>UNWIND-PROTECT</code>
+ (unless they are always handled inside the cleanup form),
+ or otherwise do non-local exits from cleanup handlers
+ outside of the handler e.g. <code>INVOKE-RESTART</code>.
+ </li>
+ <li>
+ Do not clean up by resignaling.
+ If you do that, and the condition is not handled,
+ the stack trace will halt at the point of the resignal,
+ hiding the rest.
+ And the rest is the part we really care about!
+ <BAD_CODE_SNIPPET>
+ ;; Bad
+ (handler-case
+ (catch 'ticket-at
+ (etd-process-blocks))
+ (error (c)
+ (reset-parser-values)
+ (error c)))
+ </BAD_CODE_SNIPPET>
+ <CODE_SNIPPET>
+ ;; Better
+ (unwind-protect
+ (catch 'ticket-at
+ (etd-process-blocks))
+ (reset-parser-values))
+ </CODE_SNIPPET>
+ </li>
+ </ul>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Type Checking">
+ <SUMMARY>
+ If you know the type of something, you should make it explicit
+ in order to enable compile-time and run-time sanity-checking.
+ </SUMMARY>
+ <BODY>
+
+ <p>
+ If your function is using a special variable as an implicit argument,
+ it's good to put in a <code>CHECK-TYPE</code> for the special variable,
+ for two reasons:
+ to clue in the person reading the code
+ that this variable is being used implicitly as an argument,
+ and also to help detect bugs.
+ </p>
+
+ <p>
+ Using <code>(declare (type ...))</code>
+ is the least-desirable mechanism to use
+ because, as Scott McKay puts it:
+ </p>
+ <blockquote>
+ <p>
+ The fact is, <code>(declare (type ...))</code> does different things
+ depending on the compiler settings of speed, safety, etc.
+ In some compilers, when speed is greater than safety,
+ <code>(declare (type ...))</code> will tell the compiler
+ "please assume that these variables have these types"
+ <em>without</em> generating any type-checks.
+ That is, if some variable has the value <code>1432</code> in it,
+ and you declare it to be of type <code>string</code>,
+ the compiler might just go ahead and use it as though it's a string.
+ </p>
+ <p>
+ Moral: don't use <code>(declare (type ...))</code>
+ to declare the contract of any API functions,
+ it's not the right thing.
+ Sure, use it for "helper" functions, but not API functions.
+ </p>
+ </blockquote>
+ <p>
+ You should, of course, use appropriate declarations
+ in internal low-level functions
+ where these declarations are used for optimization.
+ When you do, however, see our recommendations for
+ <a href="#Unsafe_Operations">Unsafe Operations</a>.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="CLOS">
+ <SUMMARY>
+ Use CLOS appropriately.
+ </SUMMARY>
+ <BODY>
+ <p>
+ When a generic function is intended to be called from other
+ modules (other parts of the code), there should be an
+ explicit <code>DEFGENERIC</code> form,
+ with a <code>:DOCUMENTATION</code> string
+ explaining the generic contract of the function
+ (as opposed to its behavior for some specific class).
+ It's generally good to do explicit <code>DEFGENERIC</code> forms,
+ but for module entry points it is mandatory.
+ </p>
+ <p>
+ When the argument list of a generic function includes
+ <code>&KEY</code>,
+ the <code>DEFGENERIC</code> should always explicitly list
+ all of the keyword arguments that are acceptable,
+ and explain what they mean.
+ (Common Lisp does not require this, but it is good form,
+ and it may avoid spurious warnings on SBCL.)
+ </p>
+ <p>
+ You should avoid <code>SLOT-VALUE</code> and <code>WITH-SLOTS</code>,
+ unless you absolutely intend to circumvent
+ any sort of method combination that might be in effect for the slot.
+ Rare exceptions include <code>INITIALIZE-INSTANCE</code>
+ and <code>PRINT-OBJECT</code> methods and
+ accessing normally hidden slots in the low-level implementation of
+ methods that provide user-visible abstractions.
+ Otherwise, you should use accessors,
+ <code>WITH-ACCESSORS</code>
+ </p>
+
+ <p>
+ Accessor names generally follow a convention of
+ <code><protocol-name>-<slot-name></code>,
+ where a "protocol" in this case loosely indicates
+ a set of functions with well-defined behavior.
+ </p>
+ <p>
+ No implication of a formal "protocol" concept is necessarily intended,
+ much less first-class "protocol" objects.
+ However, there may indeed be an abstract CLOS class
+ or an
+ <a href="https://common-lisp.net/~frideau/lil-ilc2012/lil-ilc2012.html">Interface-Passing Style</a> interface
+ that embodies the protocol.
+ Further (sub)classes or (sub)interfaces may then implement
+ all or part of a protocol by defining
+ some methods for (generic) functions in the protocol,
+ including readers and writers.
+ </p>
+ <p>
+ For example, if there were a notional protocol called
+ is <code>pnr</code> with accessors <code>pnr-segments</code>
+ and <code>pnr-passengers</code>, then
+ the classes <code>air-pnr</code>, <code>hotel-pnr</code> and
+ <code>car-pnr</code> could each reasonably implement
+ methods for <code>pnr-segments</code> and <code>pnr-passengers</code>
+ as accessors.
+ </p>
+ <p>
+ By default, an abstract base class name is used
+ as the notional protocol name, so accessor names default
+ to <code><class-name>-<slot-name></code>;
+ while such names are thus quite prevalent,
+ this form is neither required nor even preferred.
+ In general, it contributes to "symbol bloat",
+ and in many cases has led to a proliferation of "trampoline" methods.
+ </p>
+ <p>
+ Accessors named <code><slot-name>-of</code> should not be used.
+ </p>
+ <p>
+ Explicit <code>DEFGENERIC</code> forms should be used when there are
+ (or it is anticipated that there will be)
+ more than one <code>DEFMETHOD</code> for that generic function.
+ The reason is that the documentation for the generic function
+ explains the abstract contract for the function,
+ as opposed to explaining what an individual method does for
+ some specific class(es).
+ </p>
+ <p>
+ You must not use generic functions where there is no notional protocol.
+ To put it more concretely,
+ if you have more than one generic function that specializes its Nth argument,
+ the specializing classes should all be descendants of a single class.
+ Generic functions must not be used for "overloading",
+ i.e. simply to use the same name for two entirely unrelated types.
+ </p>
+ <p>
+ More precisely, it's not really
+ whether they descend from a common superclass,
+ but whether they obey the same "protocol".
+ That is, the two classes should handle the same set of generic functions,
+ as if there were an explicit <code>DEFGENERIC</code> for each method.
+ </p>
+ <p>
+ Here's another way to put it.
+ Suppose you have two classes, A and B, and a generic function F.
+ There are two methods for F,
+ which dispatch on an argument being of types A and B.
+ Is it plausible that there might be a function call somewhere
+ in the program that calls F,
+ in which the argument might sometimes, at runtime,
+ be of class A and other times be of class B?
+ If not, you probably are overloading and
+ should not be using a single generic function.
+ </p>
+ <p>
+ We allow one exception to this rule:
+ it's OK to do overloading
+ if the corresponding argument "means" the same thing.
+ Typically one overloading allows an X object,
+ and the other allows the name of an X object,
+ which might be a symbol or something.
+ </p>
+ <p>
+ You must not use MOP "intercessory" operations at runtime.
+ You should not use MOP "intercessory" operations at compile-time.
+ At runtime, they are at worst a danger, at best a performance issue.
+ At compile-time, it is usually cleaner that
+ macros should set things up the right way in one pass
+ than have to require a second pass of fixups through intercession;
+ but sometimes, fixups are necessary to resolve forward references,
+ and intercession is allowed then.
+ MOP intercession is a great tool for interactive development,
+ and you may enjoy it while developping and debugging;
+ but you should not use it in normal applications.
+ </p>
+ <p>
+ If a class definition creates a method
+ as a <code>:READER</code>, <code>:WRITER</code>,
+ or <code>:ACCESSOR</code>,
+ do not redefine that method.
+ It's OK to add <code>:BEFORE</code>, <code>:AFTER</code>,
+ and <code>:AROUND</code> methods,
+ but don't override the primary method.
+ </p>
+ <p>
+ In methods with keyword arguments,
+ you must always use <code>&KEY</code>,
+ even if the method does not care about the values of any keys,
+ and you should never use <code>&ALLOW-OTHER-KEYS</code>.
+ As long as a keyword is accepted by any method of a generic function,
+ it's OK to use it in the generic function,
+ even if the other methods of the same generic function
+ don't mention it explicitly.
+ This is particularly important
+ for <code>INITIALIZE-INSTANCE</code> methods,
+ since if you did use <code>&ALLOW-OTHER-KEYS</code>,
+ it would disable error checking for misspelled or wrong keywords
+ in <code>MAKE-INSTANCE</code> calls!
+ </p>
+
+ <p>
+ A typical <code>PRINT-OBJECT</code> method might look like this:
+ </p>
+ <CODE_SNIPPET>
+ (defmethod print-object ((p person) stream)
+ (print-unprintable-object (p stream :type t :identity t)
+ (with-slots (first-name last-name) p
+ (safe-format stream "~a ~a" first-name last-name))))
+ </CODE_SNIPPET>
+ </BODY>
+ </STYLEPOINT>
+</CATEGORY>
+
+<CATEGORY title="Meta-language guidelines">
+ <STYLEPOINT title="Macros">
+ <SUMMARY>
+ Use macros when appropriate, which is often.
+ Define macros when appropriate, which is seldom.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Macros bring syntactic abstraction, which is a wonderful thing.
+ It helps make your code clearer, by describing your intent
+ without getting bogged in implementation details
+ (indeed abstracting those details away).
+ It helps make your code more concise and more readable,
+ by eliminating both redundancy and irrelevant details.
+ But it comes at a cost to the reader,
+ which is learning a new syntactic concept for each macro.
+ And so it should not be abused.
+ </p>
+ <p>
+ The general conclusion is that there shouldn't be
+ any recognizable <em>design pattern</em>
+ in a good Common Lisp program.
+ The one and only pattern is: <em>use the language</em>,
+ which includes defining and using syntactic abstractions.
+ </p>
+ <p>
+ Existing macros must be used
+ whenever they make code clearer
+ by conveying intent in a more concise way,
+ which is often.
+ When a macro is available in your project
+ that expresses the concept you're using,
+ you must not write the expansion rather than use the macro.
+ </p>
+ <p>
+ New macros should be defined as appropriate,
+ which should be seldom,
+ for common macros have already been provided
+ by the language and its various libraries,
+ and your program typically only needs few new ones
+ relative to its size.
+ </p>
+ <p>
+ You should follow the OAOOM rule of thumb
+ for deciding when to create a new abstraction,
+ whether syntactic or not:
+ if a particular pattern is used more than twice,
+ it should probably be abstracted away.
+ A more refined rule to decide when to use abstraction
+ should take into account
+ the benefit in term of number of uses and gain at each use,
+ to the costs in term of having to get used to reading the code.
+ For syntactic abstractions, costs and benefits to the reader
+ is usually more important than costs and benefits to the writer,
+ because good code is usually written once
+ and read many times by many people
+ (including the same programmer
+ who has to maintain the program after having forgotten it).
+ Yet the cost to the writer of the macro
+ should also be taken into account;
+ however, in doing so it should rather be compared
+ to the cost of the programmer writing other code instead
+ that may have higher benefits.
+ </p>
+ <p>
+ Using Lisp macros properly requires taste.
+ Avoid writing complicated macros
+ unless the benefit clearly outweighs the cost.
+ It takes more effort for your fellow developers to learn your macro,
+ so you should only use a macro if the gain in expressiveness
+ is big enough to justify that cost.
+ As usual, feel free to consult your colleagues if you're not sure,
+ since without a lot of Lisp experience,
+ it can be hard to make this judgment.
+ </p>
+ <p>
+ You must never use a macro where a function will do.
+ That is, if the semantics of what you are writing
+ conforms to the semantics of a function,
+ then you must write it as a function rather than a macro.
+ </p>
+ <p>
+ You must not transform a function into a macro for performance reasons.
+ If profiling shows that you have a performance problem
+ with a specific function <code>FOO</code>,
+ document the need and profiling-results appropriately,
+ and
+ <code>(declaim (inline foo))</code>.
+ </p>
+
+ <p>
+ You can also use a compiler-macro
+ as a way to speed up function execution
+ by specifying a source-to-source transformation.
+ Beware that it interferes with tracing the optimized function.
+ </p>
+ <p>
+ When you write a macro-defining macro
+ (a macro that generates macros),
+ document and comment it particularly clearly,
+ since these are harder to understand.
+ </p>
+ <p>
+ You must not install new reader macros
+ without a consensus among the developers of your system.
+ Reader macros must not leak out of the system that uses them
+ to clients of that system or other systems used in the same project.
+ You must use software such as
+ <code>cl-syntax</code> or <code>named-readtables</code>
+ to control how reader macros are used.
+ This clients who desire it may use the same reader macros as you do.
+ In any case, your system must be usable
+ even to clients who do not use these reader macros.
+ </p>
+ <p>
+ If your macro has a parameter that is a Lisp form
+ that will be evaluated when the expanded code is run,
+ you should name the parameter with the suffix <code>-form</code>.
+ This convention helps make it clearer to the macro's user
+ which parameters are Lisp forms to be evaluated, and which are not.
+ The common names <code>body</code> and <code>end</code> are
+ exceptions to this rule.
+ </p>
+ <p>
+ You should follow the so-called <code>CALL-WITH</code> style when it applies.
+ This style is explained at length in
+ <a href="http://random-state.net/log/3390120648.html">http://random-state.net/log/3390120648.html</a>.
+ The general principle is that the macro is strictly limited to processing the syntax,
+ and as much of the semantics as possible is kept in normal functions.
+ Therefore, a macro <code>WITH-<em>FOO</em></code> is often limited to
+ generating a call to an auxiliary function
+ <code>CALL-WITH-<em>FOO</em></code>
+ with arguments deduced from the macro arguments.
+ Macro <code>&body</code> arguments are typically
+ wrapped into a lambda expression of which they become the body,
+ which is passed as one of the arguments of the auxiliary function.
+ </p>
+ <p>
+ The separation of syntactic and semantic concerns
+ is a general principle of style that applies
+ beyond the case of <code>WITH-</code> macros.
+ Its advantages are many.
+ By keeping semantics outside the macro,
+ the macro is made simpler, easier to get right, and less subject to change,
+ which makes it easier to develop and maintain.
+ The semantics is written in a simpler language — one without staging —
+ which also makes it easier to develop and maintain.
+ It becomes possible to debug and update the semantic function
+ without having to recompile all clients of the macro.
+ The semantic function appears in the stack trace
+ which also helps debug client functions.
+ The macro expansion is made shorter and
+ each expansion shares more code with other expansions,
+ which reduces memory pressure which in turn usually makes things faster.
+ It also makes sense to write the semantic functions first,
+ and write the macros last as syntactic sugar on top.
+ You should use this style unless the macro is used
+ in tight loops where performance matters;
+ and even then, see our rules regarding optimization.
+ </p>
+ <p>
+ Any functions (closures) created by the macro should be named,
+ which can be done using <code>FLET</code>.
+
+ This also allows you to declare the function to be of dynamic extent
+ (if it is — and often it is; yet see below regarding
+ <a href="#DYNAMIC-EXTENT">DYNAMIC-EXTENT</a>).
+ </p>
+ <p>
+ If a macro call contains a form,
+ and the macro expansion includes more than one copy of that form,
+ the form can be evaluated more than once,
+ and code it contains macro-expanded and compiled more than once.
+ If someone uses the macro and calls it
+ with a form that has side effects or that takes a long time to compute,
+ the behavior will be undesirable
+ (unless you're intentionally writing
+ a control structure such as a loop).
+ A convenient way to avoid this problem
+ is to evaluate the form only once,
+ and bind a (generated) variable to the result.
+ There is a very useful macro called <code>ALEXANDRIA:ONCE-ONLY</code>
+ that generates code to do this.
+ See also <code>ALEXANDRIA:WITH-GENSYMS</code>,
+ to make some temporary variables in the generated code.
+ Note that if you follow our <code>CALL-WITH</code> style,
+ you typically expand the code only once, as either
+ an argument to the auxiliary function, or
+ the body of a lambda passed as argument to it;
+ you therefore avoid the above complexity.
+ </p>
+ <p>
+ When you write a macro with a body,
+ such as a <code>WITH-xxx</code> macro,
+ even if there aren't any parameters,
+ you should leave space for them anyway.
+ For example, if you invent <code>WITH-LIGHTS-ON</code>,
+ do not make the call to it look like
+ <code>(defmacro with-lights-on (&body b) ...)</code>.
+ Instead, do <code>(defmacro with-lights-on (() &body b) ...)</code>.
+ That way, if parameters are needed in the future,
+ you can add them without necessarily having to change
+ all the uses of the macro.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="EVAL-WHEN">
+ <SUMMARY>
+ When using <code>EVAL-WHEN</code>, you should almost always use all of
+ <code>(:compile-toplevel :load-toplevel :execute)</code>.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Lisp evaluation happens at several times,
+ some of them interleaved.
+ Be aware of them when writing macros.
+ <a href="https://fare.livejournal.com/146698.html">EVAL-WHEN considered harmful to your mental health</a>.
+ </p>
+ <p>
+ In summary of the article linked above,
+ unless you're doing truly advanced macrology,
+ the only valid combination in an <code>EVAL-WHEN</code>
+ is to include all of
+ <code>(eval-when (:compile-toplevel :load-toplevel :execute) ...)</code>
+ </p>
+ <p>
+ You must use
+ <code>(eval-when (:compile-toplevel :load-toplevel :execute) ...)</code>
+ whenever you define functions, types, classes, constants, variables, etc.,
+ that are going to be used in macros.
+ </p>
+ <p>
+ It is usually an error to omit the <code>:execute</code>,
+ because it prevents <code>LOAD</code>ing the source rather than the fasl.
+ It is usually an error to omit the <code>:load-toplevel</code>
+ (except to modify e.g. readtables and compile-time settings),
+ because it prevents <code>LOAD</code>ing future files
+ or interactively compiling code
+ that depends on the effects that happen at compile-time,
+ unless the current file was <code>COMPILE-FILE</code>d
+ within the same Lisp session.
+ </p>
+ <p>
+ Regarding variables, note that because macros may or may not
+ be expanded in the same process that runs the expanded code,
+ you must not depend on compile-time and runtime effects
+ being either visible or invisible at the other time.
+ There are still valid uses of variables in macros:
+ </p>
+ <ul>
+ <li>
+ Some variables may hold dictionaries
+ for some new kind of definition and other meta-data.
+ If such meta-data is to be visible at runtime and/or in other files,
+ you must make sure that the macro expands into code that
+ will register the definitions to those meta-data structures
+ at load-time,
+ in addition to effecting the registration at compile-time.
+ Typically, your top-level definitions expand
+ to code that does the registration.
+ if your code doesn't expand at the top-level,
+ you can sometimes use <code>LOAD-TIME-VALUE</code> for good effect.
+ In extreme cases, you may have to use
+ <code>ASDF-FINALIZERS:EVAL-AT-TOPLEVEL</code>.
+ </li>
+ <li>
+ Some variables may hold temporary data
+ that is only used at compile-time in the same file,
+ and can be cleaned up at the end of the file's compilation.
+ Predefined such variables would include <code>*readtable*</code>
+ or compiler-internal variables holding
+ the current optimization settings.
+ You can often manage existing and new such variables using
+ the <code>:AROUND-COMPILE</code> hooks of <code>ASDF</code>.
+ </li>
+ </ul>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Read-time evaluation">
+ <SUMMARY>
+ You should use <code>#.</code> sparingly,
+ and you must avoid read-time side-effects.
+ </SUMMARY>
+ <BODY>
+ <p>
+ The <code>#.</code> standard read-macro
+ will read one object, evaluate the object, and
+ have the reader return the resulting value.
+ </p>
+ <p>
+ You must not use it where other idioms will do, such as
+ using <code>EVAL-WHEN</code> to evaluate side-effects at compile-time,
+ using a regular macro to return an expression computed at compile-time,
+ using <code>LOAD-TIME-VALUE</code> to compute it at load-time.
+ </p>
+ <p>
+ Read-time evaluation is often used as a quick way
+ to get something evaluated at compile time
+ (actually "read time" but it amounts to the same thing).
+ If you use this, the evaluation MUST NOT have any side effects
+ and MUST NOT depend on any variable global state.
+ The <code>#.</code> should be treated as a way
+ to force "constant-folding"
+ that a sufficiently-clever compiler
+ could have figure out all by itself,
+ when the compiler isn't sufficiently-clever
+ and the difference matters.
+ </p>
+ <p>
+ Another use of <code>#.</code> is to expand the equivalent of macros
+ in places that are neither expressions nor (quasi)quotations,
+ such as lambda-lists. However, if you find yourself using it a lot,
+ it might be time to instead define macros to replace your consumers
+ of lambda-lists with something that recognizes an extension.
+ </p>
+ <p>
+ Whenever you are going to use <code>#.</code>,
+ you should consider using <code>DEFCONSTANT</code> and its variants,
+ possibly in an <code>EVAL-WHEN</code>,
+ to give the value a name explaining what it means.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="EVAL">
+ <SUMMARY>
+ You must not use <code>EVAL</code> at runtime.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Places where it is actually appropriate to use <code>EVAL</code>
+ are so few and far between that you must consult with your reviewers;
+ it's easily misused.
+ </p>
+ <p>
+ If your code manipulates symbols at runtime
+ and needs to get the value of a symbol,
+ use <code>SYMBOL-VALUE</code>, not <code>EVAL</code>.
+ </p>
+ <p>
+ Often, what you really need is to write a macro,
+ not to use <code>EVAL</code>.
+ </p>
+ <p>
+ You may be tempted to use <code>EVAL</code> as a shortcut
+ to evaluating expressions in a safe subset of the language.
+ But it often requires more scrutiny to properly check and sanitize
+ all possible inputs to such use of <code>EVAL</code>
+ than to build a special-purpose evaluator.
+ You must not use <code>EVAL</code> in this way at runtime.
+ </p>
+ <p>
+ Places where it is OK to use <code>EVAL</code> are:
+ </p>
+ <ul>
+ <li>
+ The implementation of an interactive development tool.
+ </li>
+ <li>
+ The build infrastructure.
+ </li>
+ <li>
+ Backdoors that are part of testing frameworks.
+ (You MUST NOT have such backdoors in production code.)
+ </li>
+ <li>
+ Macros that fold constants at compile-time.
+ </li>
+ <li>
+ Macros that register definitions to meta-data structures;
+ the registration form is sometimes evaluated at compile-time
+ as well as included in the macro-expansion,
+ so it is immediately available to other macros.
+ </li>
+ </ul>
+ <p>
+ Note that in the latter case,
+ if the macro isn't going to be used at the top-level,
+ it might not be possible to make these definitions available
+ as part of the expansion.
+ The same phenomenon may happen in a <code>DEFTYPE</code> expansion,
+ or in helper functions used by macros.
+ In these cases, you may actually have to use
+ <code>ASDF-FINALIZERS:EVAL-AT-TOPLEVEL</code> in your macro.
+ It will not only <code>EVAL</code> your definitions
+ at macro-expansion time for immediate availability,
+ it will also save the form aside, for inclusion in a
+ <code>(ASDF-FINALIZERS:FINAL-FORMS)</code>
+ that you need to include at the end of the file being compiled
+ (or before the form is needed).
+ This way, the side-effects are present when loading the fasl
+ without having compiled it as well as while compiling it;
+ in either case, the form is made available at load-time.
+ <code>ASDF-FINALIZERS</code> ensures that the form is present,
+ by throwing an error if you omit it.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="INTERN and UNINTERN">
+ <SUMMARY>
+ You must not use <code>INTERN</code> or <code>UNINTERN</code> at runtime.
+ </SUMMARY>
+ <BODY>
+ <p>
+ You must not use <code>INTERN</code> at runtime.
+ Not only does it cons,
+ it either creates a permanent symbol that won't be collected
+ or gives access to internal symbols.
+ This creates opportunities for memory leaks, denial of service attacks,
+ unauthorized access to internals, clashes with other symbols.
+ </p>
+ <p>
+ You must not <code>INTERN</code> a string
+ just to compare it to a keyword;
+ use <code>STRING=</code> or <code>STRING-EQUAL</code>.
+ </p>
+ <BAD_CODE_SNIPPET>
+ (member (intern str :keyword) $keys) ; Bad
+ </BAD_CODE_SNIPPET>
+ <CODE_SNIPPET>
+ (member str $keys :test #'string-equal) ; Better
+ </CODE_SNIPPET>
+ <p>
+ You must not use <code>UNINTERN</code> at runtime.
+ It can break code that relies on dynamic binding.
+ It makes things harder to debug.
+ You must not dynamically intern any new symbol,
+ and therefore you need not dynamically unintern anything.
+ </p>
+ <p>
+ You may of course use <code>INTERN</code> at compile-time,
+ in the implementation of some macros.
+ Even so, it is usually more appropriate
+ to use abstractions on top of it, such as
+ <code>ALEXANDRIA:SYMBOLICATE</code> or
+ <code>ALEXANDRIA:FORMAT-SYMBOL</code>
+ to create the symbols you need.
+ </p>
+
+ </BODY>
+ </STYLEPOINT>
+</CATEGORY>
+
+<CATEGORY title="Data Representation">
+ <STYLEPOINT title="NIL: empty-list, false and I Don't Know">
+ <SUMMARY>
+ Appropriately use or avoid using <code>NIL</code>.
+ </SUMMARY>
+ <BODY>
+ <p>
+ <code>NIL</code> can have several different interpretations:
+ </p>
+ <ul>
+ <li>
+ "False."
+ In this case, use <code>NIL</code>.
+ You should test for false <code>NIL</code>
+ using the operator <code>NOT</code> or
+ using the predicate function <code>NULL</code>.
+ </li>
+ <li>
+ "Empty-list."
+ In this case, use <code>'()</code>.
+ (Be careful about quoting the empty-list when calling macros.)
+ You should use <code>ENDP</code> to test for the empty list
+ when the argument is known to be a proper list,
+ or with <code>NULL</code> otherwise.
+ </li>
+ <li>
+ A statement about some value being unspecified.
+ In this case, you may use <code>NIL</code>
+ if there is no risk of ambiguity anywhere in your code;
+ otherwise you should use an explicit, descriptive symbol.
+ </li>
+ <li>
+ A statement about some value being known not to exist.
+ In this case, you should use an explicit, descriptive symbol
+ instead of <code>NIL</code>.
+ </li>
+ </ul>
+ <p>
+ You must not introduce ambiguity in your data representations
+ that will cause headaches for whoever has to debug code.
+ If there is any risk of ambiguity,
+ you should use an explicit, descriptive symbol or keyword
+ for each case,
+ instead of using <code>NIL</code> for either.
+ If you do use <code>NIL</code>,
+ you must make sure that the distinction is well documented.
+ </p>
+ <p>
+ In many contexts,
+ instead of representing "I don't know" as a particular value,
+ you should instead use multiple values,
+ one for the value that is known if any,
+ and one to denote whether the value was known or found.
+ </p>
+
+ <p>
+ When working with database classes, keep in mind that
+ <code>NIL</code> need not always map to <code>'NULL'</code>
+ (and vice-versa)!
+ The needs of the database may differ from the needs of the Lisp.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Do not abuse lists">
+ <SUMMARY>
+ You must select proper data representation.
+ You must not abuse the <code>LIST</code> data structure.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Even though back in 1958, LISP was short for "LISt Processing",
+ its successor Common Lisp has been a modern programming language
+ with modern data structures since the 1980s.
+ You must use the proper data structures in your programs.
+ </p>
+ <p>
+ You must not abuse the builtin (single-linked) <code>LIST</code>
+ data structure where it is not appropriate,
+ even though Common Lisp makes it especially easy to use it.
+ </p>
+ <p>
+ You must only use lists
+ when their performance characteristics
+ is appropriate for the algorithm at hand:
+ sequential iteration over the entire contents of the list.
+ </p>
+ <p>
+ An exception where it is appropriate to use lists
+ is when it is known in advance
+ that the size of the list will remain very short
+ (say, less than 16 elements).
+ </p>
+ <p>
+ List data structures are often (but not always)
+ appropriate for macros and functions used by macros at compile-time:
+ indeed, not only is source code passed as lists in Common Lisp,
+ but the macro-expansion and compilation processes
+ will typically walk over the entire source code, sequentially, once.
+ (Note that advanced macro systems don't directly use lists, but instead
+ use abstract syntax objects that track source code location and scope;
+ however there is no such advanced macro system
+ in Common Lisp at this time.)
+ </p>
+ <p>
+ Another exception where it is appropriate to use lists is
+ for introducing literal constants
+ that will be transformed into more appropriate data structures
+ at compile-time or load-time.
+ It is a good to have a function with a relatively short name
+ to build your program's data structures from such literals.
+ </p>
+ <p>
+ In the many cases when lists are not the appropriate data structure,
+ various libraries such as
+ <a href="http://cliki.net/cl-containers">cl-containers</a> or
+ <a href="http://cliki.net/lisp-interface-library">lisp-interface-library</a>
+ provide plenty of different data structures
+ that should fulfill all the basic needs of your programs.
+ If the existing libraries are not satisfactory, see above about
+ <a href="#Using_Libraries">Using Libraries</a> and
+ <a href="#Open-Sourcing_Code">Open-Sourcing Code</a>.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Lists vs. structures vs. multiple values">
+ <SUMMARY>
+ You should use the appropriate representation for product types.
+ </SUMMARY>
+ <BODY>
+ <p>
+ You should avoid using a list as anything
+ besides a container of elements of like type.
+ You must not use a list as method of passing
+ multiple separate values of different types
+ in and out of function calls.
+ Sometimes it is convenient to use a list
+ as a little ad hoc structure,
+ i.e. "the first element of the list is a FOO, and the second is a BAR",
+ but this should be used minimally
+ since it gets harder to remember the little convention.
+ You must only use a list that way
+ when destructuring the list of arguments from a function,
+ or creating a list of arguments
+ to which to <code>APPLY</code> a function.
+ </p>
+ <p>
+ The proper way to pass around an object
+ comprising several values of heterogeneous types
+ is to use a structure as defined by <code>DEFSTRUCT</code>
+ or <code>DEFCLASS</code>.
+ </p>
+ <p>
+ You should use multiple values only
+ when function returns a small number of values
+ that are meant to be destructured immediately by the caller,
+ rather than passed together as arguments to further functions.
+ </p>
+ <p>
+ You should not return a condition object
+ as one of a set of multiple values.
+ Instead, you should signal the condition to denote an unusual outcome.
+ </p>
+ <p>
+ You should signal a condition to denote an unusual outcome,
+ rather than relying on a special return type.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Lists vs. Pairs">
+ <SUMMARY>
+ Use the appropriate functions when manipulating lists.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Use <code>FIRST</code> to access the first element of a list,
+ <code>SECOND</code> to access the second element, etc.
+ Use <code>REST</code> to access the tail of a list.
+ Use <code>ENDP</code> to test for the end of the list.
+ </p>
+ <p>
+ Use <code>CAR</code> and <code>CDR</code>
+ when the cons cell is not being used to implement a proper list
+ and is instead being treated as a pair of more general objects.
+ Use <code>NULL</code> to test for <code>NIL</code> in this context.
+ </p>
+ <p>
+ The latter case should be rare outside of alists,
+ since you should be using structures and classes where they apply,
+ and data structure libraries when you want trees.
+ </p>
+ <p>
+ Exceptionally, you may use <code>CDADR</code> and other variants
+ on lists when manually destructuring them,
+ instead of using a combination of several list accessor functions.
+ In this context, using <code>CAR</code> and <code>CDR</code>
+ instead of <code>FIRST</code> and <code>REST</code> also makes sense.
+ However, keep in mind that it might be more appropriate in such cases
+ to use higher-level constructs such as
+ <code>DESTRUCTURING-BIND</code> or <code>OPTIMA:MATCH</code>.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Lists vs. Arrays">
+ <SUMMARY>
+ You should use arrays rather than lists where random access matters.
+ </SUMMARY>
+ <BODY>
+ <p>
+ <code>ELT</code> has <i>O(n)</i> behavior when used on lists.
+ If you are to use random element access on an object,
+ use arrays and <code>AREF</code> instead.
+ </p>
+ <p>
+ The exception is for code outside the critical path
+ where the list is known to be small anyway.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Lists vs. Sets">
+ <SUMMARY>
+ You should only use lists as sets for very small lists.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Using lists as representations of sets is a bad idea
+ unless you know the lists will be small,
+ for accessors are <i>O(n)</i> instead of <i>O(log n)</i>.
+ For arbitrary big sets, use balanced binary trees,
+ for instance using <code>lisp-interface-library</code>.
+ </p>
+ <p>
+ If you still use lists as sets,
+ you should not <code>UNION</code> lists just to search them.
+ </p>
+ <BAD_CODE_SNIPPET>
+ (member foo (union list-1 list-2)) ; Bad
+ </BAD_CODE_SNIPPET>
+ <CODE_SNIPPET>
+ (or (member foo list-1) (member foo list-2)) ; Better
+ </CODE_SNIPPET>
+ <p>
+ Indeed, <code>UNION</code> not only conses unnecessarily,
+ but it can be <i>O(n^2)</i> on some implementations,
+ and is rather slow even when it's <i>O(n)</i>.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+</CATEGORY>
+
+<CATEGORY title="Proper Forms">
+ <p>
+ You must follow the proper usage regarding
+ well-known functions, macros and special forms.
+ </p>
+ <STYLEPOINT title="Defining Constants">
+ <SUMMARY>
+ You must use proper defining forms for constant values.
+ </SUMMARY>
+ <BODY>
+ <p>
+ The Lisp system we primarily use, SBCL, is very picky and
+ signals a condition whenever a constant is redefined to a value not
+ <code>EQL</code> to its previous setting.
+ You must not use <code>DEFCONSTANT</code>
+ when defining variables that are not
+ numbers, characters, or symbols (including booleans and keywords).
+ Instead, consistently use whichever alternative
+ is recommended for your project.
+ </p>
+ <BAD_CODE_SNIPPET>
+ ;; Bad
+ (defconstant +google-url+ "https://www.google.com/")
+ (defconstant +valid-colors+ '(red green blue))
+ </BAD_CODE_SNIPPET>
+
+
+
+
+ <p>
+ Open-Source libraries may use
+ <code>ALEXANDRIA:DEFINE-CONSTANT</code>
+ for constants other than numbers, characters and symbols
+ (including booleans and keywords).
+ You may use the <code>:TEST</code> keyword argument
+ to specify an equality predicate.
+ </p>
+ <CODE_SNIPPET>
+ ;; Better, for Open-Source code:
+ (define-constant +google-url+ "https://www.google.com/" :test #'string=)
+ (define-constant +valid-colors+ '(red green blue))
+ </CODE_SNIPPET>
+ <p>
+ Note that with optimizing implementations, such as SBCL or CMUCL,
+ defining constants this way precludes any later redefinition
+ short of <code>UNINTERN</code>ing the symbol
+ and recompiling all its clients.
+ This may make it "interesting" to debug things at the REPL
+ or to deploy live code upgrades.
+ If there is a chance that your "constants" are not going to be constant
+ over the lifetime of your server processes
+ after taking into consideration scheduled and unscheduled code patches,
+ you should consider using
+ <code>DEFPARAMETER</code> or <code>DEFVAR</code> instead,
+ or possibly a variant of <code>DEFINE-CONSTANT</code>
+ that builds upon some future library implementing global lexicals
+ rather than <code>DEFCONSTANT</code>.
+ You may keep the <code>+plus+</code> convention in these cases
+ to document the intent of the parameter as a constant.
+ </p>
+ <p>
+ Also note that <code>LOAD-TIME-VALUE</code> may help you
+ avoid the need for defined constants.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Defining Functions">
+ <SUMMARY>
+ You should make proper use of
+ <code>&OPTIONAL</code> and
+ <code>&KEY</code> arguments.
+ You should not use <code>&AUX</code> arguments.
+ </SUMMARY>
+ <BODY>
+ <p>
+ You should avoid using <code>&ALLOW-OTHER-KEYS</code>,
+ since it blurs the contract of a function.
+ Almost any real function (generic or not) allows a certain
+ fixed set of keywords, as far as its caller is concerned,
+ and those are part of its contract.
+ If you are implementing a method of a generic function,
+ and it does not need to know
+ the values of some of the keyword arguments,
+ you should explicitly <code>(DECLARE (IGNORE ...))</code>
+ all the arguments that you are not using.
+ You must not use <code>&ALLOW-OTHER-KEYS</code>
+ unless you explicitly want to disable checking of allowed keys
+ for all methods when invoking the generic function on arguments
+ that match this particular method.
+ Note that the contract of a generic function belongs in
+ the <code>DEFGENERIC</code>, not in the <code>DEFMETHOD</code>
+ which is basically an "implementation detail" of the generic function
+ as far as the caller of the generic is concerned.
+ </p>
+ <p>
+ A case where <code>&ALLOW-OTHER-KEYS</code> is appropriate
+ is when you write a wrapper function to other some other functions
+ that may vary (within the computation or during development),
+ and pass around a plist as a <code>&REST</code> argument.
+ </p>
+ <p>
+ You should avoid using <code>&AUX</code> arguments.
+ </p>
+ <p>
+ You should avoid having both <code>&OPTIONAL</code>
+ and <code>&KEY</code> arguments,
+ unless it never makes sense to specify keyword arguments
+ when the optional arguments are not all specified.
+ You must not have non-<code>NIL</code> defaults
+ to your <code>&OPTIONAL</code> arguments
+ when your function has both <code>&OPTIONAL</code>
+ and <code>&KEY</code> arguments.
+ </p>
+ <p>
+ For maximum portability of a library, it is good form
+ that <code>DEFMETHOD</code> definitions should
+ <code>(DECLARE (IGNORABLE ...))</code>
+ all the required arguments that they are not using.
+ Indeed, some implementations will issue a warning
+ if you <code>(DECLARE (IGNORE ...))</code> those arguments,
+ whereas other implementations will issue a warning
+ if you fail to <code>(DECLARE (IGNORE ...))</code> them.
+ <code>(DECLARE (IGNORABLE ...))</code> works on all implementations.
+ </p>
+ <p>
+ You should avoid excessive nesting of binding forms inside a function.
+ If your function ends up with massive nesting,
+ you should probably break it up into several functions or macros.
+ If it is really a single conceptual unit,
+ consider using a macro such as <code>FARE-UTILS:NEST</code>
+ to at least reduce the amount of indentation required.
+ It is bad form to use <code>NEST</code> in typical short functions
+ with 4 or fewer levels of nesting,
+ but also bad form not to use it in the exceptional long functions
+ with 10 or more levels of nesting.
+ Use your judgment and consult your reviewers.
+ </p>
+
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Conditional Expressions">
+ <SUMMARY>
+ Use the appropriate conditional form.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Use <code>WHEN</code> and <code>UNLESS</code>
+ when there is only one alternative.
+ Use <code>IF</code> when there are two alternatives
+ and <code>COND</code> when there are several.
+ </p>
+ <p>
+ However, don't use <code>PROGN</code> for an <code>IF</code> clause
+ — use <code>COND</code>, <code>WHEN</code>, or <code>UNLESS</code>.
+ </p>
+ <p>
+ Note that in Common Lisp,
+ <code>WHEN</code> and <code>UNLESS</code> return <code>NIL</code>
+ when the condition is not met.
+ You may take advantage of it.
+ Nevertheless, you may use an <code>IF</code>
+ to explicitly return <code>NIL</code>
+ if you have a specific reason to insist on the return value.
+ You may similarly include a fall-through clause <code>(t nil)</code>
+ as the last in your <cond>COND</cond>,
+ or <code>(otherwise nil)</code> as the last in your <cond>CASE</cond>,
+ to insist on the fact that the value returned by the conditional matters
+ and that such a case is going to be used.
+ You should omit the fall-through clause
+ when the conditional is used for side-effects.
+ </p>
+ <p>
+ You should prefer <code>AND</code> and <code>OR</code>
+ when it leads to more concise code than using
+ <code>IF</code>, <code>COND</code>,
+ <code>WHEN</code> or <code>UNLESS</code>,
+ and there are no side-effects involved.
+ You may also use an <code>ERROR</code>
+ as a side-effect in the final clause of an <code>OR</code>.
+ </p>
+ <p>
+ You should only use <code>CASE</code> and <code>ECASE</code>
+ to compare numbers, characters or symbols
+ (including booleans and keywords).
+ Indeed, <code>CASE</code> uses <code>EQL</code> for comparisons,
+ so strings, pathnames and structures may not compare the way you expect,
+ and <code>1</code> will differ from <code>1.0</code>.
+ </p>
+ <p>
+ You should use <code>ECASE</code> and <code>ETYPECASE</code>
+ in preference to <code>CASE</code> and <code>TYPECASE</code>.
+ It is better to catch erroneous values early.
+ </p>
+ <p>
+ You should not use <code>CCASE</code> or <code>CTYPECASE</code> at all.
+ At least, you should not use them in server processes,
+ unless you have quite robust error handling infrastructure
+ and make sure not to leak sensitive data this way.
+ These are meant for interactive use,
+ and can cause interesting damage
+ if they cause data or control to leak to attackers.
+ </p>
+ <p>
+ You must not use gratuitous single quotes in <code>CASE</code> forms.
+ This is a common error:
+ </p>
+ <BAD_CODE_SNIPPET>
+ (case x ; Bad: silently returns NIL on mismatch
+ ('bar :bar) ; Bad: catches QUOTE
+ ('baz :baz)) ; Bad: also would catch QUOTE
+ </BAD_CODE_SNIPPET>
+ <CODE_SNIPPET>
+ (ecase x ; Better: will error on mismatch
+ ((bar) :bar) ; Better: won't match QUOTE
+ ((baz) :baz)) ; Better: same reason
+ </CODE_SNIPPET>
+ <p>
+ <code>'BAR</code> there is <code>(QUOTE BAR)</code>,
+ meaning this leg of the case will be executed
+ if <code>X</code> is <code>QUOTE</code>...
+ and ditto for the second leg
+ (though <code>QUOTE</code> will be caught by the first clause).
+ This is unlikely to be what you really want.
+ </p>
+ <p>
+ In <code>CASE</code> forms,
+ you must use <code>otherwise</code> instead of <code>t</code>
+ when you mean "execute this clause if the others fail".
+ You must use <code>((t) ...)</code>
+ when you mean "match the symbol T" rather than "match anything".
+ You must also use <code>((nil) ...)</code>
+ when you mean "match the symbol NIL" rather than "match nothing".
+ </p>
+ <p>
+ Therefore, if you want to map booleans <code>NIL</code> and <code>T</code>
+ to respective symbols <code>:BAR</code> and <code>:QUUX</code>,
+ you should avoid the former way and do it the latter way:
+ </p>
+ <BAD_CODE_SNIPPET>
+ (ecase x ; Bad: has no actual error case!
+ (nil :bar)) ; Bad: matches nothing
+ (t :quux)) ; Bad: matches anything
+ </BAD_CODE_SNIPPET>
+ <CODE_SNIPPET>
+ (ecase x ; Better: will actually catch non-booleans
+ ((nil) :bar)) ; Better: matches NIL
+ ((t) :quux)) ; Better: matches T
+ </CODE_SNIPPET>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Identity, Equality and Comparisons">
+ <SUMMARY>
+ You should the appropriate predicates when comparing objects.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Lisp provides four general equality predicates:
+ <code>EQ</code>, <code>EQL</code>, <code>EQUAL</code>,
+ and <code>EQUALP</code>,
+ which subtly vary in semantics.
+ Additionally, Lisp provides the type-specific predicates
+ <code>=</code>, <code>CHAR=</code>, <code>CHAR-EQUAL</code>,
+ <code>STRING=</code>, and <code>STRING-EQUAL</code>.
+ Know the distinction!
+ </p>
+ <p>
+ You should use <code>EQL</code> to compare objects and symbols
+ for <em>identity</em>.
+ </p>
+ <p>
+ You must not use <code>EQ</code> to compare numbers or characters.
+ Two numbers or characters that are <code>EQL</code>
+ are not required by Common Lisp to be <code>EQ</code>.
+ </p>
+ <p>
+ When choosing between <code>EQ</code> and <code>EQL</code>,
+ you should use <code>EQL</code> unless you are writing
+ performance-critical low-level code.
+ <code>EQL</code> reduces the opportunity
+ for a class of embarrassing errors
+ (i.e. if numbers or characters are ever compared).
+ There may a tiny performance cost relative to <code>EQ</code>,
+ although under SBCL, it often compiles away entirely.
+ <code>EQ</code> is equivalent to <code>EQL</code> and type declarations,
+ and use of it for optimization should be treated just like
+ any such <a href="#Unsafe_Operations">unsafe operations</a>.
+ </p>
+ <p>
+ You should use <code>CHAR=</code>
+ for case-dependent character comparisons,
+ and <code>CHAR-EQUAL</code> for case-ignoring character comparisons.
+ </p>
+ <p>
+ You should use <code>STRING=</code>
+ for case-dependent string comparisons,
+ and <code>STRING-EQUAL</code> for case-ignoring string comparisons.
+ </p>
+ <p>
+ A common mistake when using <code>SEARCH</code> on strings
+ is to provide <code>STRING=</code> or <code>STRING-EQUAL</code>
+ as the <code>:TEST</code> function.
+ The <code>:TEST</code> function
+ is given two sequence elements to compare.
+ If the sequences are strings,
+ the <code>:TEST</code> function is called on two characters,
+ so the correct tests are <code>CHAR=</code> or <code>CHAR-EQUAL</code>.
+ If you use <code>STRING=</code> or <code>STRING-EQUAL</code>,
+ the result is what you expect,
+ but in some Lisp implementations it's much slower.
+ CCL (at least as of 8/2008)
+ creates a one-character string upon each comparison, for example,
+ which is very expensive.
+ </p>
+ <p>
+ Also, you should use <code>:START</code> and <code>:END</code> arguments
+ to <code>STRING=</code> or <code>STRING-EQUAL</code>
+ instead of using <code>SUBSEQ</code>;
+ e.g. <code>(string-equal (subseq s1 2 6) s2)</code> should instead be
+ <code>(string-equal s1 s2 :start1 2 :end1 6)</code>
+ This is preferable because it does not cons.
+ </p>
+ <p>
+ You should use <code>ZEROP</code>,
+ <code>PLUSP</code>, or <code>MINUSP</code>,
+ instead of comparing a value to <code>0</code> or <code>0.0</code>.
+ </p>
+ <p>
+ You must not use exact comparison on floating point numbers,
+ since the vague nature of floating point arithmetic
+ can produce little "errors" in numeric value.
+ You should compare absolute values to a threshhold.
+ </p>
+ <p>
+ You must use <code>=</code> to compare numbers,
+ unless you really mean for <code>0</code>,
+ <code>0.0</code> and <code>-0.0</code> to compare unequal,
+ in which case you should use <code>EQL</code>.
+ Then again, you must not usually use exact comparison
+ on floating point numbers.
+ </p>
+ <p>
+ Monetary amounts should be using decimal (rational) numbers
+ to avoid the complexities and rounding errors
+ of floating-point arithmetic.
+ Libraries such as
+ <a href="http://wukix.com/lisp-decimals">wu-decimal</a>
+ may help you;
+ once again, if this library is not satisfactory, see above about
+ <a href="#Using_Libraries">Using Libraries</a> and
+ <a href="#Open-Sourcing_Code">Open-Sourcing Code</a>.
+ </p>
+
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Iteration">
+ <SUMMARY>
+ Use the appropriate form for iteration.
+ </SUMMARY>
+ <BODY>
+ <p>
+ You should use simpler forms such as
+ <code>DOLIST</code> or <code>DOTIMES</code>
+ instead of <code>LOOP</code>
+ in simple cases when you're not going to use any
+ of the <code>LOOP</code> facilities such as
+ bindings, collection or block return.
+ </p>
+ <p>
+ Use the <code>WITH</code> clause of <code>LOOP</code>
+ when it will avoid a level of nesting with <code>LET</code>.
+ You may use <code>LET</code> if it makes it clearer
+ to return one of bound variables after the <code>LOOP</code>,
+ rather than use a clumsy <code>FINALLY (RETURN ...)</code> form.
+ </p>
+ <p>
+ In the body of a <code>DOTIMES</code>,
+ do not set the iteration variable.
+ (CCL will issue a compiler warning if you do.)
+ </p>
+ <p>
+ Most systems use unadorned symbols in the current package
+ as <code>LOOP</code> keywords.
+ Other systems use actual <code>:keywords</code>
+ from the <code>KEYWORD</code> package
+ as <code>LOOP</code> keywords.
+ You must be consistent with the convention used in your system.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="I/O">
+ <SUMMARY>
+ Use the appropriate I/O functions.
+ </SUMMARY>
+ <BODY>
+ <p>
+ When writing a server,
+ code must not send output to the standard streams such as
+ <code>*STANDARD-OUTPUT*</code> or <code>*ERROR-OUTPUT*</code>.
+ Instead, code must use the proper logging framework
+ to output messages for debugging.
+ We are running as a server, so there is no console!
+ </p>
+ <p>
+ Code must not use <code>PRINT-OBJECT</code>
+ to communicate with a user —
+ <code>PRINT-OBJECT</code> is for debugging purposes only.
+ Modifying any <code>PRINT-OBJECT</code> method
+ must not break any public interfaces.
+ </p>
+ <p>
+ You should not use a sequence of <code>WRITE-XXX</code>
+ where a single <code>FORMAT</code> string could be used.
+ Using format allows you
+ to parameterize the format control string in the future
+ if the need arises.
+ </p>
+ <p>
+ You should use <code>WRITE-CHAR</code> to emit a character
+ rather than <code>WRITE-STRING</code>
+ to emit a single-character string.
+ </p>
+ <p>
+ You should not use <code>(format nil "~A" value)</code>;
+ you should use <code>PRINC-TO-STRING</code> instead.
+ </p>
+ <p>
+ You should use <code>~<Newline></code>
+ or <code>~@<Newline></code> in format strings
+ to keep them from wrapping in 100-column editor windows,
+ or to indent sections or clauses to make them more readable.
+ </p>
+ <p>
+ You should not use <code>STRING-UPCASE</code>
+ or <code>STRING-DOWNCASE</code>
+ on format control parameters;
+ instead, it should use <code>"~:@(~A~)"</code> or <code>"~(~A~)"</code>.
+ </p>
+ <p>
+ Be careful when using the <code>FORMAT</code> conditional directive.
+ The parameters are easy to forget.
+ </p>
+ <dl>
+ <dt>No parameters, e.g. <code>"~[Siamese~;Manx~;Persian~] Cat"</code></dt>
+ <dd>
+ Take one format argument, which should be an integer.
+ Use it to choose a clause. Clause numbers are zero-based.
+ If the number is out of range, just print nothing.
+ You can provide a default value
+ by putting a <code>":"</code> in front of the last <code>";"</code>.
+ E.g. in <code>"~[Siamese~;Manx~;Persian~:;Alley~] Cat"</code>,
+ an out-of-range arg prints <code>"Alley"</code>.
+ </dd>
+ <dt><code>:</code> parameter, e.g. <code>"~:[Siamese~;Manx~]"</code></dt>
+ <dd>
+ Take one format argument. If it's <code>NIL</code>,
+ use the first clause, otherwise use the second clause.
+ </dd>
+ <dt><code>@</code> parameter, e.g. <code>"~@[Siamese ~a~]"</code></dt>
+ <dd>
+ If the next format argument is true,
+ use the choice, but do NOT take the argument.
+ If it's false, take one format argument and print nothing.
+ (Normally the clause uses the format argument.)
+ </dd>
+ <dt><code>#</code> parameter, e.g. <code>"~#[ none~; ~s~; ~s and ~s~]"</code></dt>
+ <dd>
+ Use the number of arguments to format
+ as the number to choose a clause.
+ The same as no parameters in all other ways.
+ Here's the full hairy example:
+ <code>"Items:~#[ none~; ~S~; ~S and ~S~:;~@{~#[~; and~] ~S~^ ,~}~]."</code>
+ </dd>
+ </dl>
+ </BODY>
+ </STYLEPOINT>
+</CATEGORY>
+
+<CATEGORY title="Optimization">
+ <STYLEPOINT title="Avoid Allocation">
+ <SUMMARY>
+ You should avoid unnecessary allocation of memory.
+ </SUMMARY>
+ <BODY>
+ <p>
+ In a language with automatic storage management (such as Lisp or Java),
+ the colloquial phrase "memory leak" refers to situation
+ where storage that is not actually needed
+ nevertheless does not get deallocated,
+ because it is still reachable.
+ </p>
+ <p>
+ You should be careful that when you create objects,
+ you don't leave them reachable after they are no longer needed!
+ </p>
+ <p>
+ Here's a particular trap-for-the-unwary in Common Lisp.
+ If you make an array with a fill pointer, and put objects in it,
+ and then set the fill pointer back to zero,
+ those objects are still reachable as far as Lisp goes
+ (the Common Lisp spec says that it's still OK
+ to refer to the array entries past the end of the fill pointer).
+ </p>
+ <p>
+ Don't cons (i.e., allocate) unnecessarily.
+ Garbage collection is not magic.
+ Excessive allocation is usually a performance problem.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Unsafe Operations">
+ <SUMMARY>
+ You must only use faster unsafe operations
+ when there is a clear performance need
+ and you can document why it's correct.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Common Lisp implementations often provide backdoors
+ to compute some operations faster in an unsafe way.
+ For instance, some libraries provide arithmetic operations
+ that are designed to be used with fixnums only,
+ and yield the correct result faster if provided proper arguments.
+ The downside is that the result of such operations
+ is incorrect in case of overflow, and can
+ have undefined behavior when called with anything but fixnums.
+ </p>
+
+ <p>
+ More generally, unsafe operations
+ will yield the correct result faster
+ than would the equivalent safe operation
+ if the arguments satisfy some invariant such as
+ being of the correct type and small enough;
+ however if the arguments fail to satisfy the required invariants,
+ then the operation may have undefined behavior,
+ such as crashing the software, or,
+ which is sometimes worse, silently giving wrong answers.
+ Depending on whether the software is piloting an aircraft
+ or other life-critical device,
+ or whether it is accounting for large amounts money,
+ such undefined behavior can kill or bankrupt people.
+ Yet proper speed can sometimes make the difference between
+ software that's unusably slow and software that does its job,
+ or between software that is a net loss
+ and software that can yield a profit.
+ </p>
+ <p>
+ You must not define or use unsafe operations without both
+ profiling results indicating the need for this optimization,
+ and careful documentation explaining why it is safe to use them.
+ Unsafe operations should be restricted to internal functions;
+ you should carefully documented how unsafe it is
+ to use these functions with the wrong arguments.
+ You should only use unsafe operations
+ inside functions internal to a package and
+ you should document the use of the declarations,
+ since calling the functions with arguments of the wrong type
+ can lead to undefined behavior.
+ Use <code>check-type</code> in functions exported from a package
+ to sanitize input arguments,
+ so that internal functions are never passed illegal values.
+ </p>
+ <p>
+ On some compilers,
+ new unsafe operations
+ can usually be defined by combining
+ type declarations with an <code>OPTIMIZE</code> declaration
+ that has sufficiently high <code>SPEED</code> and low <code>SAFETY</code>.
+ In addition to providing more speed for production code,
+ such declarations may more helpful
+ than <code>check-type</code> assertions
+ for finding bugs at compile-time,
+ on compilers that have type inference.
+ These compilers may interpret those declarations as assertions
+ if you switch to safer and slower optimize settings;
+ this is good to locate a dynamic error in your code during development,
+ but is not to be used for production code since
+ it defeats the purpose of declarations as a performance trick.
+ </p>
+
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="DYNAMIC-EXTENT">
+ <SUMMARY>
+ You should only use <code>DYNAMIC-EXTENT</code>
+ where it matters for performance,
+ and you can document why it is correct.
+ </SUMMARY>
+ <BODY>
+ <p>
+ <code>DYNAMIC-EXTENT</code> declarations are
+ a particular case of
+ <a href="#Unsafe_Operations">unsafe operations</a>.
+ </p>
+ <p>
+ The purpose of a <code>DYNAMIC-EXTENT</code> declaration
+ is to improve performance by reducing garbage collection
+ in cases where it appears to be obvious that an object's lifetime
+ is within the "dynamic extent" of a function.
+ That means the object is created at some point
+ after the function is called, and
+ the object is always inaccessible after the function exits by any means.
+ </p>
+ <p>
+ By declaring a variable or a local function <code>DYNAMIC-EXTENT</code>,
+ the programmer <em>asserts</em> to Lisp
+ that any object that is ever a value of that variable
+ or the closure that is the definition of the function
+ has a lifetime within the dynamic extent of the (innermost) function
+ that declares the variable.
+ </p>
+ <p>
+ The Lisp implementation is then free to use that information
+ to make the program faster.
+ Typically, Lisp implementations can take advantage of this knowledge
+ to stack-allocate:
+ </p>
+ <ul>
+ <li>
+ The lists created to store <code>&REST</code> parameters.
+ </li>
+ <li>
+ Lists, vectors and structures allocated within a function.
+ </li>
+ <li>
+ Closures.
+ </li>
+ </ul>
+ <p>
+ If the assertion is wrong, i.e. if the programmer's claim is not true,
+ the results can be <em>catastrophic</em>:
+ Lisp can terminate any time after the function returns,
+ or it can hang forever, or — worst of all —
+ it can produce incorrect results without any runtime error!
+ </p>
+ <p>
+ Even if the assertion is correct,
+ future changes to the function might introduce
+ a violation of the assertion.
+ This increases the danger.
+ </p>
+ <p>
+ In most cases, such objects are ephemeral.
+ Modern Lisp implementations use generational garbage collectors,
+ which are quite efficient under these circumstances.
+ </p>
+ <p>
+ Therefore, <code>DYNAMIC-EXTENT</code> declarations
+ should be used sparingly. You must only use them if:
+ </p>
+ <ol>
+ <li>
+ There is some good reason to think that the overall effect
+ on performance is noticeable, and
+ </li>
+ <li>
+ It is absolutely clear that the assertion is true.
+ </li>
+ <li>
+ It is quite unlikely that the code will be changed
+ in ways that cause the declaration to become false.
+ </li>
+ </ol>
+ <p>
+ Point (1) is a special case of
+ the principle of avoiding premature optimization.
+ An optimization like this only matters if such objects
+ are allocated at a very high rate, e.g. "inside an inner loop".
+ </p>
+ <p>
+ Note that is relatively easy to ascertain that
+ a function will not escape the dynamic extent of the current call frame
+ by analyzing where the function is called and
+ what other functions it is passed to;
+ therefore, you should somewhat wary of declaring a function
+ <code>DYNAMIC-EXTENT</code>, but this is not a high-stress declaration.
+ On the other hand, it is much harder to ascertain that
+ none of the objects ever bound or assigned to that variable
+ and none of their sub-objects
+ will escape the dynamic extent of the current call frame,
+ and that they still won't in any future modification of a function.
+ Therefore, you should be extremely wary
+ of declaring a variable <code>DYNAMIC-EXTENT</code>.
+ </p>
+ <p>
+ It's usually hard to predict the effect of such optimization on performance.
+ When writing a function or macro
+ that is part of a library of reusable code,
+ there's no a priori way to know how often the code will run.
+ Ideally, tools would be available to discover
+ the availability and suitability of using such an optimization
+ based on running simulations and test cases, but
+ in practice this isn't as easy as it ought to be.
+ It's a tradeoff.
+ If you're very, very sure that the assertion is true
+ (that any object bound to the variable and any of its sub-objects
+ are only used within the dynamic extent of the specified scope),
+ and it's not obvious how much time will be saved
+ and it's not easy to measure,
+ then it may be better to put in the declaration than to leave it out.
+ (Ideally it would be easier to make such measurements
+ than it actually is.)
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="REDUCE vs APPLY">
+ <SUMMARY>
+ You should use <code>REDUCE</code>
+ instead of <code>APPLY</code> where appropriate.
+ </SUMMARY>
+ <BODY>
+ <p>
+ You should use <code>REDUCE</code>
+ instead of <code>APPLY</code> and a consed-up list,
+ where the semantics of the first operator argument
+ otherwise guarantees the same semantics.
+ Of course, you must use <code>APPLY</code>
+ if it does what you want and <code>REDUCE</code> doesn't.
+ For instance:
+ </p>
+ <BAD_CODE_SNIPPET>
+ ;; Bad
+ (apply #'+ (mapcar #'acc frobs))
+ </BAD_CODE_SNIPPET>
+ <CODE_SNIPPET>
+ ;; Better
+ (reduce #'+ frobs :key #'acc :initial-value 0)
+ </CODE_SNIPPET>
+ <p>
+ This is preferable because it does not do extra consing,
+ and does not risk going beyond <code>CALL-ARGUMENTS-LIMIT</code>
+ on implementations where that limit is small,
+ which could blow away the stack on long lists
+ (we want to avoid gratuitous non-portability in our code).
+ </p>
+ <p>
+ However, you must be careful not to use <code>REDUCE</code>
+ in ways that needlessly increase
+ the complexity class of the computation.
+ For instance, <code>(REDUCE 'STRCAT ...)</code> is <i>O(n^2)</i>
+ when an appropriate implementation is only <i>O(n)</i>.
+ Moreover, <code>(REDUCE 'APPEND ...)</code>
+ is also <i>O(n^2)</i> unless you specify <code>:FROM-END T</code>.
+ In such cases, you MUST NOT use <code>REDUCE</code>,
+ and you MUST NOT use <code>(APPLY 'STRCAT ...)</code>
+ or <code>(APPLY 'APPEND ...)</code> either.
+ Instead you MUST use proper abstractions
+ from a suitable library (that you may have to contribute to)
+ that properly handles those cases
+ without burdening users with implementation details.
+ See for instance <code>UIOP:REDUCE/STRCAT</code>.
+ </p>
+
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Avoid NCONC">
+ <SUMMARY>
+ You should not use <code>NCONC</code>;
+ you should use <code>APPEND</code> instead,
+ or better, better data structures.
+ </SUMMARY>
+ <BODY>
+ <p>
+ You should almost never use <code>NCONC</code>.
+ You should use <code>APPEND</code>
+ when you don't depend on any side-effect.
+ You should use <code>ALEXANDRIA:APPENDF</code>
+ when you need to update a variable.
+ You should probably not depend on games
+ being played with the <code>CDR</code>
+ of the current CONS cell
+ (which some might argue is suggested but not guaranteed by the specification);
+ if you do, you must include a prominent
+ comment explaining the use of <code>NCONC</code>;
+ and you should probably reconsider your data representation strategy.
+ </p>
+ <p>
+ By extension, you should avoid <code>MAPCAN</code>
+ or the <code>NCONC</code> feature of <code>LOOP</code>.
+ You should instead respectively use
+ <code>ALEXANDRIA:MAPPEND</code>
+ and the <code>APPEND</code> feature of <code>LOOP</code>.
+ </p>
+ <p>
+ <code>NCONC</code> is very seldom a good idea,
+ since its time complexity class is no better than <code>APPEND</code>,
+ its space complexity class also is no better than <code>APPEND</code>
+ in the common case where no one else is sharing the side-effected list,
+ and its bug complexity class is way higher than <code>APPEND</code>.
+ </p>
+ <p>
+ If the small performance hit due
+ to <code>APPEND</code> vs. <code>NCONC</code>
+ is a limiting factor in your program,
+ you have a big problem and are probably using the wrong data structure:
+ you should be using sequences with constant-time append
+ (see Okasaki's book, and add them to lisp-interface-library),
+ or more simply you should be accumulating data in a tree
+ that will get flattened once in linear time
+ after the accumulation phase is complete.
+ </p>
+ <p>
+ You may only use <code>NCONC</code>, <code>MAPCAN</code>
+ or the <code>NCONC</code> feature of <code>LOOP</code>
+ in low-level functions where performance matters,
+ where the use of lists as a data structure has been vetted
+ because these lists are known to be short,
+ and when the function or expression the result of which are accumulated
+ explicitly promises in its contract that it only returns fresh lists
+ (in particular, it can't be a constant quote or backquote expression).
+ Even then, the use of such primitives must be rare,
+ and accompanied by justifying documentation.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+</CATEGORY>
+
+<CATEGORY title="Pitfalls">
+ <STYLEPOINT title="#'FUN vs. 'FUN">
+ <SUMMARY>
+ You should usually refer to a function as <code>#'FUN</code> rather than <code>'FUN</code>.
+ </SUMMARY>
+ <BODY>
+ <p>
+ The former, which reads as <code>(FUNCTION FUN)</code>,
+ refers to the function object, and is lexically scoped.
+ The latter, which reads as <code>(QUOTE FUN)</code>,
+ refers to the symbol, which when called
+ uses the global <code>FDEFINITION</code> of the symbol.
+ </p>
+ <p>
+ When using functions that take a functional argument
+ (e.g., <code>MAPCAR</code>, <code>APPLY</code>,
+ <code>:TEST</code> and <code>:KEY</code> arguments),
+ you should use the <code>#'</code> to refer to the function,
+ not just single quote.
+ </p>
+ <p>
+ An exception is when you explicitly want dynamic linking,
+ because you anticipate that
+ the global function binding will be updated.
+ </p>
+ <p>
+ Another exception is when you explicitly want to access
+ a global function binding,
+ and avoid a possible shadowing lexical binding.
+ This shouldn't happen often, as it is usually a bad idea
+ to shadow a function when you will want to use the shadowed function;
+ just use a different name for the lexical function.
+ </p>
+ <p>
+ You must consistently use either <code>#'(lambda ...)</code>
+ or <code>(lambda ...)</code> without <code>#'</code> everywhere.
+ Unlike the case of <code>#'symbol</code> vs <code>'symbol</code>,
+ it is only a syntactic difference with no semantic impact,
+ except that the former works on Genera and the latter doesn't.
+
+ You must use the former style if your code is intended as a library
+ with maximal compatibility to all Common Lisp implementations;
+ otherwise, it is optional which style you use.
+ <code>#'</code> may be seen as a hint
+ that you're introducing a function in expression context;
+ but the <code>lambda</code> itself is usually sufficient hint,
+ and concision is good.
+ Choose wisely, but above all,
+ consistently with yourself and other developers,
+ within a same file, package, system, project, etc.
+ </p>
+ <p>
+ Note that if you start writing a new system
+ in a heavily functional style,
+ you may consider using
+ <a href="http://cliki.net/lambda-reader">lambda-reader</a>,
+ a system that lets you use the unicode character <code>λ</code>
+ instead of <code>LAMBDA</code>.
+ But you must not start using such a syntactic extension
+ in an existing system without getting permission from other developers.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Pathnames">
+ <SUMMARY>
+ Common Lisp pathnames are tricky. Be aware of pitfalls. Use <code>UIOP</code>.
+ </SUMMARY>
+ <BODY>
+ <p>
+ It is surprisingly hard to properly deal with pathnames in Common Lisp.
+ </p>
+ <p>
+ <code>ASDF 3</code> comes with a portability library <code>UIOP</code>
+ that makes it <em>much</em> easier to deal with pathnames
+ portably — and correctly — in Common Lisp.
+ You should use it when appropriate.
+ </p>
+ <p>
+ First, be aware of the discrepancies between
+ the syntax of Common Lisp pathnames,
+ which depends on which implementation and operating system
+ you are using,
+ and the native syntax of pathnames on your operating system.
+ The Lisp syntax may involves quoting of special characters
+ such as <code>#\.</code> and <code>#\*</code>, etc.,
+ in addition to the quoting of
+ <code>#\\</code> and <code>#\"</code> within strings.
+ By contrast, your operating system's other
+ system programming languages
+ (shell, C, scripting languages)
+ may only have one layer of quoting, into strings.
+ </p>
+ <p>
+ Second, when using <code>MERGE-PATHNAMES</code>,
+ be wary of the treatment of the <code>HOST</code> component,
+ which matters a lot on non-Unix platforms
+ (and even on some Unix implementations).
+ You probably should be using
+ <code>UIOP:MERGE-PATHNAMES*</code> or <code>UIOP:SUBPATHNAME</code>
+ instead of <code>MERGE-PATHNAMES</code>,
+ especially if your expectations for relative pathnames
+ are informed by the way they work in Unix or Windows;
+ otherwise you might hit weird bugs whereby on some implementations,
+ merging a relative pathnames with an absolute pathname
+ results in overriding the absolute pathname's host
+ and replace it with the host from the value of
+ <code>*DEFAULT-PATHNAME-DEFAULTS*</code>
+ at the time the relative pathname was created.
+ </p>
+ <p>
+ Third, be aware that <code>DIRECTORY</code>
+ is not portable across implementations
+ in how it handles wildcards, sub-directories, symlinks, etc.
+ There again, <code>UIOP</code> provides several
+ common abstractions to deal with pathnames,
+ but only does so good a job.
+ For a complete portable solution, use IOLib —
+ though its Windows support lags behind.
+ </p>
+ <p>
+ <code>LOGICAL-PATHNAME</code>s are not a portable abstraction,
+ and should not be used in portable code.
+ Many implementations have bugs in them, when they are supported at all.
+ SBCL implements them very well,
+ but strictly enforces the limitations on characters
+ allowed by the standard, which restricts their applicability.
+ Other implementations allow arbitrary characters in such pathnames,
+ but in doing so are not being conformant,
+ and are still incompatible with each other in many ways.
+ You should use other pathname abstractions,
+ such as <code>ASDF:SYSTEM-RELATIVE-PATHNAME</code> or
+ the underlying <code>UIOP:SUBPATHNAME</code> and
+ <code>UIOP:PARSE-UNIX-NAMESTRING</code>.
+ </p>
+
+ <p>
+ Finally, be aware that paths may change between
+ the time you build the Lisp image for your application,
+ and the time you run the application from its image.
+ You should be careful to reset your image
+ to forget irrelevant build-time paths and
+ reinitialize any search path from current environment variables.
+ <code>ASDF</code> for instance requires you to reset its paths
+ with <code>UIOP:CLEAR-CONFIGURATION</code>.
+ <code>UIOP</code> provides hooks
+ to call functions before an image is dumped,
+ from which to reset or <code>makunbound</code> relevant variables.
+ </p>
+
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="SATISFIES">
+ <SUMMARY>
+ You must be careful when using a <code>SATISFIES</code> clause in a type specifier.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Most Common Lisp implementations can't optimize
+ based on a <code>SATISFIES</code> type,
+ but many of them offer simple optimizations
+ based on a type of the form
+ <code>(AND FOO (SATISFIES BAR-P))</code>
+ where the first term of the <code>AND</code> clause
+ describes the structure of the object
+ without any <code>SATISFIES</code>
+ and the second term is the <code>SATISFIES</code>.
+ </p>
+ <BAD_CODE_SNIPPET>
+ (deftype prime-number () (satisfies prime-number-p)) ; Bad
+ </BAD_CODE_SNIPPET>
+ <CODE_SNIPPET>
+ (deftype prime-number () (and integer (satisfies prime-number-p)) ; Better
+ </CODE_SNIPPET>
+ <p>
+ However, <code>AND</code> in the <code>DEFTYPE</code> language
+ isn't a left-to-right short-circuit operator
+ as in the expression language;
+ it is a symmetrical connector that allows for reordering subterms
+ and doesn't guarantee short-circuiting.
+ Therefore, in the above example,
+ you cannot rely on the test for <code>INTEGER</code>ness
+ to protect the function <code>PRIME-NUMBER-P</code>
+ from being supplied non-integer arguments
+ to test for being of instances of the type.
+ Implementations may, and some <em>will</em>,
+ invoke <code>SATISFIES</code>-specified function
+ at compile-time to test various relevant objects.
+ </p>
+ <p>
+ That is why any function specified in a <code>SATISFIES</code> clause
+ MUST accept objects of any type as argument to the function,
+ and MUST be defined within an <code>EVAL-WHEN</code>
+ (as well as any variable it uses or function it calls):
+ </p>
+ <BAD_CODE_SNIPPET>
+ (defun prime-number-p (n) ; Doubly bad!
+ (let ((m (abs n)))
+ (if (<= m *prime-number-cutoff*)
+ (small-prime-number-p m)
+ (big-prime-number-p m))))
+ </BAD_CODE_SNIPPET>
+ <CODE_SNIPPET>
+ (eval-when (:compile-toplevel :load-toplevel :execute) ; Better
+ (defun prime-number-p (n)
+ (when (integerp n) ; Better
+ (let ((m (abs n)))
+ (if (<= m *prime-number-cutoff*)
+ (small-prime-number-p m)
+ (big-prime-number-p m))))))
+ </CODE_SNIPPET>
+ <p>
+ In particular, the above means that the
+ <a href="https://www.lispworks.com/documentation/HyperSpec/Body/t_satisf.htm">example</a>
+ used in the Common Lisp Standard is erroneous:
+ <code>(and integer (satisfies evenp))</code>
+ is <em>not</em> a safe, conformant type specifier to use,
+ because <code>EVENP</code> will throw an error
+ rather than return <code>NIL</code>
+ when passed a non-integer as an argument.
+ </p>
+ <p>
+ Finally, there is a catch when your <code>DEFTYPE</code> code expands
+ to a <code>SATISFIES</code> with a dynamically generated function:
+ </p>
+ <ul>
+ <li>
+ You cannot control when implementations will or will not
+ expand a <code>DEFTYPE</code>.
+ </li>
+ <li>
+ The expansion itself cannot contain a function definition
+ or any code in the expression language.
+ </li>
+ <li>
+ You cannot control when the expansion is used,
+ it may happen in a different process
+ that didn't expand the definition.
+ </li>
+ </ul>
+ <p>
+ Therefore, you cannot merely create the function
+ as a side-effect of expansion
+ using <code>EVAL</code> at type-expansion time.
+ The solution is to use
+ <code>ASDF-FINALIZERS:EVAL-AT-TOPLEVEL</code> instead.
+ See the very last point
+ in the discussion about <a href="#EVAL">EVAL</a>.
+ </p>
+ <p>
+ Common Lisp is hard to satisfy.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+</CATEGORY>
+
+<HR/>
+
+<small>Credits:
+ Adam Worrall, Dan Pierson, Matt Marjanovic, Matt Reklaitis,
+ Paul Weiss, Scott McKay, Sundar Narasimhan,
+ and several other people contributed.
+ Special thanks to Steve Hain,
+ and to the previous editors,
+ in reverse chronological order Dan Weinreb and Jeremy Brown.
+</small>
+
+<p align="right">
+Revision 1.28
+</p>
+
+
+<address>
+Robert Brown
+</address>
+
+<address>
+ <a HREF="mailto:tunes@google.com">François-René Rideau</a>
+</address>
+
+
+
+</GUIDE>
diff --git a/objcguide.md b/objcguide.md
new file mode 100644
index 0000000..7d965ce
--- /dev/null
+++ b/objcguide.md
@@ -0,0 +1,1661 @@
+# Google Objective-C Style Guide
+
+
+> Objective-C is a dynamic, object-oriented extension of C. It's designed to be
+> easy to use and read, while enabling sophisticated object-oriented design. It
+> is the primary development language for applications on OS X and on iOS.
+>
+> Apple has already written a very good, and widely accepted, [Cocoa Coding
+> Guidelines](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html)
+> for Objective-C. Please read it in addition to this guide.
+>
+>
+> The purpose of this document is to describe the Objective-C (and
+> Objective-C++) coding guidelines and practices that should be used for iOS and
+> OS X code. These guidelines have evolved and been proven over time on other
+> projects and teams.
+> Open-source projects developed by Google conform to the requirements in this guide.
+>
+> Note that this guide is not an Objective-C tutorial. We assume that the reader
+> is familiar with the language. If you are new to Objective-C or need a
+> refresher, please read [Programming with
+> Objective-C](https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html).
+
+
+## Principles
+
+### Optimize for the reader, not the writer
+
+Codebases often have extended lifetimes and more time is spent reading the code
+than writing it. We explicitly choose to optimize for the experience of our
+average software engineer reading, maintaining, and debugging code in our
+codebase rather than the ease of writing said code. For example, when something
+surprising or unusual is happening in a snippet of code, leaving textual hints
+for the reader is valuable.
+
+### Be consistent
+
+When the style guide allows multiple options it is preferable to pick one option
+over mixed usage of multiple options. Using one style consistently throughout a
+codebase lets engineers focus on other (more important) issues. Consistency also
+enables better automation because consistent code allows more efficient
+development and operation of tools that format or refactor code. In many cases,
+rules that are attributed to "Be Consistent" boil down to "Just pick one and
+stop worrying about it"; the potential value of allowing flexibility on these
+points is outweighed by the cost of having people argue over them.
+
+### Be consistent with Apple SDKs
+
+Consistency with the way Apple SDKs use Objective-C has value for the same
+reasons as consistency within our code base. If an Objective-C feature solves a
+problem that's an argument for using it. However, sometimes language features
+and idioms are flawed, or were just designed with assumptions that are not
+universal. In those cases it is appropriate to constrain or ban language
+features or idioms.
+
+### Style rules should pull their weight
+
+The benefit of a style rule must be large enough to justify asking engineers to
+remember it. The benefit is measured relative to the codebase we would get
+without the rule, so a rule against a very harmful practice may still have a
+small benefit if people are unlikely to do it anyway. This principle mostly
+explains the rules we don’t have, rather than the rules we do: for example, goto
+contravenes many of the following principles, but is not discussed due to its
+extreme rarity.
+
+## Example
+
+They say an example is worth a thousand words, so let's start off with an
+example that should give you a feel for the style, spacing, naming, and so on.
+
+Here is an example header file, demonstrating the correct commenting and spacing
+for an `@interface` declaration.
+
+```objectivec
+// GOOD:
+
+#import <Foundation/Foundation.h>
+
+@class Bar;
+
+/**
+ * A sample class demonstrating good Objective-C style. All interfaces,
+ * categories, and protocols (read: all non-trivial top-level declarations
+ * in a header) MUST be commented. Comments must also be adjacent to the
+ * object they're documenting.
+ */
+@interface Foo : NSObject
+
+/** The retained Bar. */
+@property(nonatomic) Bar *bar;
+
+/** The current drawing attributes. */
+@property(nonatomic, copy) NSDictionary<NSString *, NSNumber *> *attributes;
+
+/**
+ * Convenience creation method.
+ * See -initWithBar: for details about @c bar.
+ *
+ * @param bar The string for fooing.
+ * @return An instance of Foo.
+ */
++ (instancetype)fooWithBar:(Bar *)bar;
+
+/**
+ * Designated initializer.
+ *
+ * @param bar A string that represents a thing that does a thing.
+ */
+- (instancetype)initWithBar:(Bar *)bar;
+
+/**
+ * Does some work with @c blah.
+ *
+ * @param blah
+ * @return YES if the work was completed; NO otherwise.
+ */
+- (BOOL)doWorkWithBlah:(NSString *)blah;
+
+@end
+```
+
+An example source file, demonstrating the correct commenting and spacing for the
+`@implementation` of an interface.
+
+```objectivec
+// GOOD:
+
+#import "Shared/Util/Foo.h"
+
+@implementation Foo {
+ /** The string used for displaying "hi". */
+ NSString *_string;
+}
+
++ (instancetype)fooWithBar:(Bar *)bar {
+ return [[self alloc] initWithBar:bar];
+}
+
+- (instancetype)init {
+ // Classes with a custom designated initializer should always override
+ // the superclass's designated initializer.
+ return [self initWithBar:nil];
+}
+
+- (instancetype)initWithBar:(Bar *)bar {
+ self = [super init];
+ if (self) {
+ _bar = [bar copy];
+ _string = [[NSString alloc] initWithFormat:@"hi %d", 3];
+ _attributes = @{
+ @"color" : [UIColor blueColor],
+ @"hidden" : @NO
+ };
+ }
+ return self;
+}
+
+- (BOOL)doWorkWithBlah:(NSString *)blah {
+ // Work should be done here.
+ return NO;
+}
+
+@end
+```
+
+## Spacing and Formatting
+
+### Spaces vs. Tabs
+
+Use only spaces, and indent 2 spaces at a time. We use spaces for indentation.
+Do not use tabs in your code.
+
+You should set your editor to emit spaces when you hit the tab key, and to trim
+trailing spaces on lines.
+
+### Line Length
+
+The maximum line length for Objective-C files is 100 columns.
+
+You can make violations easier to spot by enabling *Preferences > Text Editing >
+Page guide at column: 100* in Xcode.
+
+### Method Declarations and Definitions
+
+One space should be used between the `-` or `+` and the return type, and no
+spacing in the parameter list except between parameters.
+
+Methods should look like this:
+
+```objectivec
+// GOOD:
+
+- (void)doSomethingWithString:(NSString *)theString {
+ ...
+}
+```
+
+The spacing before the asterisk is optional. When adding new code, be consistent
+with the surrounding file's style.
+
+If you have too many parameters to fit on one line, giving each its own line is
+preferred. If multiple lines are used, align each using the colon before the
+parameter.
+
+```objectivec
+// GOOD:
+
+- (void)doSomethingWithFoo:(GTMFoo *)theFoo
+ rect:(NSRect)theRect
+ interval:(float)theInterval {
+ ...
+}
+```
+
+When the second or later parameter name is longer than the first, indent the
+second and later lines by at least four spaces, maintaining colon alignment:
+
+```objectivec
+// GOOD:
+
+- (void)short:(GTMFoo *)theFoo
+ longKeyword:(NSRect)theRect
+ evenLongerKeyword:(float)theInterval
+ error:(NSError **)theError {
+ ...
+}
+```
+
+### Conditionals
+
+Include a space after `if`, `while`, `for`, and `switch`, and around comparison
+operators.
+
+```objectivec
+// GOOD:
+
+for (int i = 0; i < 5; ++i) {
+}
+
+while (test) {};
+```
+
+Braces may be omitted when a loop body or conditional statement fits on a single
+line.
+
+```objectivec
+// GOOD:
+
+if (hasSillyName) LaughOutLoud();
+
+for (int i = 0; i < 10; i++) {
+ BlowTheHorn();
+}
+```
+
+```objectivec
+// AVOID:
+
+if (hasSillyName)
+ LaughOutLoud(); // AVOID.
+
+for (int i = 0; i < 10; i++)
+ BlowTheHorn(); // AVOID.
+```
+
+If an `if` clause has an `else` clause, both clauses should use braces.
+
+```objectivec
+// GOOD:
+
+if (hasBaz) {
+ foo();
+} else {
+ bar();
+}
+```
+
+```objectivec
+// AVOID:
+
+if (hasBaz) foo();
+else bar(); // AVOID.
+
+if (hasBaz) {
+ foo();
+} else bar(); // AVOID.
+```
+
+Intentional fall-through to the next case should be documented with a comment
+unless the case has no intervening code before the next case.
+
+```objectivec
+// GOOD:
+
+switch (i) {
+ case 1:
+ ...
+ break;
+ case 2:
+ j++;
+ // Falls through.
+ case 3: {
+ int k;
+ ...
+ break;
+ }
+ case 4:
+ case 5:
+ case 6: break;
+}
+```
+
+### Expressions
+
+Use a space around binary operators and assignments. Omit a space for a unary
+operator. Do not add spaces inside parentheses.
+
+```objectivec
+// GOOD:
+
+x = 0;
+v = w * x + y / z;
+v = -y * (x + z);
+```
+
+Factors in an expression may omit spaces.
+
+```objectivec
+// GOOD:
+
+v = w*x + y/z;
+```
+
+### Method Invocations
+
+Method invocations should be formatted much like method declarations.
+
+When there's a choice of formatting styles, follow the convention already used
+in a given source file. Invocations should have all arguments on one line:
+
+```objectivec
+// GOOD:
+
+[myObject doFooWith:arg1 name:arg2 error:arg3];
+```
+
+or have one argument per line, with colons aligned:
+
+```objectivec
+// GOOD:
+
+[myObject doFooWith:arg1
+ name:arg2
+ error:arg3];
+```
+
+Don't use any of these styles:
+
+```objectivec
+// AVOID:
+
+[myObject doFooWith:arg1 name:arg2 // some lines with >1 arg
+ error:arg3];
+
+[myObject doFooWith:arg1
+ name:arg2 error:arg3];
+
+[myObject doFooWith:arg1
+ name:arg2 // aligning keywords instead of colons
+ error:arg3];
+```
+
+As with declarations and definitions, when the first keyword is shorter than the
+others, indent the later lines by at least four spaces, maintaining colon
+alignment:
+
+```objectivec
+// GOOD:
+
+[myObj short:arg1
+ longKeyword:arg2
+ evenLongerKeyword:arg3
+ error:arg4];
+```
+
+Invocations containing multiple inlined blocks may have their parameter names
+left-aligned at a four space indent.
+
+### Function Calls
+
+Function calls should include as many parameters as fit on each line, except
+where shorter lines are needed for clarity or documentation of the parameters.
+
+Continuation lines for function parameters may be indented to align with the
+opening parenthesis, or may have a four-space indent.
+
+```objectivec
+// GOOD:
+
+CFArrayRef array = CFArrayCreate(kCFAllocatorDefault, objects, numberOfObjects,
+ &kCFTypeArrayCallBacks);
+
+NSString *string = NSLocalizedStringWithDefaultValue(@"FEET", @"DistanceTable",
+ resourceBundle, @"%@ feet", @"Distance for multiple feet");
+
+UpdateTally(scores[x] * y + bases[x], // Score heuristic.
+ x, y, z);
+
+TransformImage(image,
+ x1, x2, x3,
+ y1, y2, y3,
+ z1, z2, z3);
+```
+
+Use local variables with descriptive names to shorten function calls and reduce
+nesting of calls.
+
+```objectivec
+// GOOD:
+
+double scoreHeuristic = scores[x] * y + bases[x];
+UpdateTally(scoreHeuristic, x, y, z);
+```
+
+### Exceptions
+
+Format exceptions with `@catch` and `@finally` labels on the same line as the
+preceding `}`. Add a space between the `@` label and the opening brace (`{`), as
+well as between the `@catch` and the caught object declaration. If you must use
+Objective-C exceptions, format them as follows. However, see Avoid Throwing
+Exceptions for reasons why you should not be using exceptions.
+
+```objectivec
+// GOOD:
+
+@try {
+ foo();
+} @catch (NSException *ex) {
+ bar(ex);
+} @finally {
+ baz();
+}
+```
+
+### Function Length
+
+Prefer small and focused functions.
+
+Long functions and methods are occasionally appropriate, so no hard limit is
+placed on function length. If a function exceeds about 40 lines, think about
+whether it can be broken up without harming the structure of the program.
+
+Even if your long function works perfectly now, someone modifying it in a few
+months may add new behavior. This could result in bugs that are hard to find.
+Keeping your functions short and simple makes it easier for other people to read
+and modify your code.
+
+When updating legacy code, consider also breaking long functions into smaller
+and more manageable pieces.
+
+### Vertical Whitespace
+
+Use vertical whitespace sparingly.
+
+To allow more code to be easily viewed on a screen, avoid putting blank lines
+just inside the braces of functions.
+
+Limit blank lines to one or two between functions and between logical groups of
+code.
+
+## Naming
+
+Names should be as descriptive as possible, within reason. Follow standard
+[Objective-C naming
+rules](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html).
+
+Avoid non-standard abbreviations. Don't worry about saving horizontal space as
+it is far more important to make your code immediately understandable by a new
+reader. For example:
+
+```objectivec
+// GOOD:
+
+// Good names.
+int numberOfErrors = 0;
+int completedConnectionsCount = 0;
+tickets = [[NSMutableArray alloc] init];
+userInfo = [someObject object];
+port = [network port];
+NSDate *gAppLaunchDate;
+```
+
+```objectivec
+// AVOID:
+
+// Names to avoid.
+int w;
+int nerr;
+int nCompConns;
+tix = [[NSMutableArray alloc] init];
+obj = [someObject object];
+p = [network port];
+```
+
+Any class, category, method, function, or variable name should use all capitals
+for acronyms and
+[initialisms](https://en.wikipedia.org/wiki/Initialism)
+within the name. This follows Apple's standard of using all capitals within a
+name for acronyms such as URL, ID, TIFF, and EXIF.
+
+Names of C functions and typedefs should be capitalized and use camel case as
+appropriate for the surrounding code.
+
+### File Names
+
+File names should reflect the name of the class implementation that they
+contain—including case.
+
+Follow the convention that your project uses.
+File extensions should be as follows:
+
+Extension | Type
+--------- | ---------------------------------
+.h | C/C++/Objective-C header file
+.m | Objective-C implementation file
+.mm | Objective-C++ implementation file
+.cc | Pure C++ implementation file
+.c | C implementation file
+
+Files containing code that may be shared across projects or used in a large
+project should have a clearly unique name, typically including the project or
+class prefix.
+
+File names for categories should include the name of the class being extended,
+like GTMNSString+Utils.h or NSTextView+GTMAutocomplete.h
+
+### Class Names
+
+Class names (along with category and protocol names) should start as uppercase
+and use mixed case to delimit words.
+
+When designing code to be shared across multiple applications, prefixes are
+acceptable and recommended (e.g. GTMSendMessage). Prefixes are also recommended
+for classes of large applications that depend on external libraries.
+
+### Category Names
+
+Category names should start with a 3 character prefix identifying the category
+as part of a project or open for general use.
+
+The category name should incorporate the name of the class it's extending. For
+example, if we want to create a category on `NSString` for parsing, we would put
+the category in a file named `NSString+GTMParsing.h`, and the category itself
+would be named `GTMNSStringParsingAdditions`. The file name and the category may
+not match, as this file could have many separate categories related to parsing.
+Methods in that category should share the prefix
+(`gtm_myCategoryMethodOnAString:`) in order to prevent collisions in
+Objective-C's global namespace.
+
+There should be a single space between the class name and the opening
+parenthesis of the category.
+
+```objectivec
+// GOOD:
+
+/** A category that adds parsing functionality to NSString. */
+@interface NSString (GTMNSStringParsingAdditions)
+- (NSString *)gtm_parsedString;
+@end
+```
+
+### Objective-C Method Names
+
+Method and parameter names typically start as lowercase and then use mixed case.
+
+Proper capitalization should be respected, including at the beginning of names.
+
+```objectivec
+// GOOD:
+
++ (NSURL *)URLWithString:(NSString *)URLString;
+```
+
+The method name should read like a sentence if possible, meaning you should
+choose parameter names that flow with the method name. Objective-C method names
+tend to be very long, but this has the benefit that a block of code can almost
+read like prose, thus rendering many implementation comments unnecessary.
+
+Use prepositions and conjunctions like "with", "from", and "to" in the second
+and later parameter names only where necessary to clarify the meaning or
+behavior of the method.
+
+```objectivec
+// GOOD:
+
+- (void)addTarget:(id)target action:(SEL)action; // GOOD; no conjunction needed
+- (CGPoint)convertPoint:(CGPoint)point fromView:(UIView *)view; // GOOD; conjunction clarifies parameter
+- (void)replaceCharactersInRange:(NSRange)aRange
+ withAttributedString:(NSAttributedString *)attributedString; // GOOD.
+```
+
+A method that returns an object should have a name beginning with a noun
+identifying the object returned:
+
+```objectivec
+// GOOD:
+
+- (Sandwich *)sandwich; // GOOD.
+```
+
+```objectivec
+// AVOID:
+
+- (Sandwich *)makeSandwich; // AVOID.
+```
+
+An accessor method should be named the same as the object it's getting, but it
+should not be prefixed with the word `get`. For example:
+
+```objectivec
+// GOOD:
+
+- (id)delegate; // GOOD.
+```
+
+```objectivec
+// AVOID:
+
+- (id)getDelegate; // AVOID.
+```
+
+Accessors that return the value of boolean adjectives have method names
+beginning with `is`, but property names for those methods omit the `is`.
+
+Dot notation is used only with property names, not with method names.
+
+```objectivec
+// GOOD:
+
+@property(nonatomic, getter=isGlorious) BOOL glorious;
+- (BOOL)isGlorious;
+
+BOOL isGood = object.glorious; // GOOD.
+BOOL isGood = [object isGlorious]; // GOOD.
+```
+
+```objectivec
+// AVOID:
+
+BOOL isGood = object.isGlorious; // AVOID.
+```
+
+```objectivec
+// GOOD:
+
+NSArray<Frog *> *frogs = [NSArray<Frog *> arrayWithObject:frog];
+NSEnumerator *enumerator = [frogs reverseObjectEnumerator]; // GOOD.
+```
+
+```objectivec
+// AVOID:
+
+NSEnumerator *enumerator = frogs.reverseObjectEnumerator; // AVOID.
+```
+
+See [Apple's Guide to Naming
+Methods](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingMethods.html#//apple_ref/doc/uid/20001282-BCIGIJJF)
+for more details on Objective-C naming.
+
+These guidelines are for Objective-C methods only. C++ method names continue to
+follow the rules set in the C++ style guide.
+
+### Function Names
+
+Regular functions have mixed case.
+
+Ordinarily, functions should start with a capital letter and have a capital
+letter for each new word (a.k.a. "[Camel
+Case](https://en.wikipedia.org/wiki/Camel_case)" or "Pascal case").
+
+```objectivec
+// GOOD:
+
+static void AddTableEntry(NSString *tableEntry);
+static BOOL DeleteFile(char *filename);
+```
+
+Because Objective-C does not provide namespacing, non-static functions should
+have a prefix that minimizes the chance of a name collision.
+
+```objectivec
+// GOOD:
+
+extern NSTimeZone *GTMGetDefaultTimeZone();
+extern NSString *GTMGetURLScheme(NSURL *URL);
+```
+
+### Variable Names
+
+Variable names typically start with a lowercase and use mixed case to delimit
+words.
+
+Instance variables have leading underscores. File scope or global variables have
+a prefix `g`. For example: `myLocalVariable`, `_myInstanceVariable`,
+`gMyGlobalVariable`.
+
+#### Common Variable Names
+
+Readers should be able to infer the variable type from the name, but do not use
+Hungarian notation for syntactic attributes, such as the static type of a
+variable (int or pointer).
+
+File scope or global variables (as opposed to constants) declared outside the
+scope of a method or function should be rare, and should have the prefix g.
+
+```objectivec
+// GOOD:
+
+static int gGlobalCounter;
+```
+
+#### Instance Variables
+
+Instance variable names are mixed case and should be prefixed with an
+underscore, like `_usernameTextField`.
+
+NOTE: Google's previous convention for Objective-C ivars was a trailing
+underscore. Existing projects may opt to continue using trailing underscores in
+new code in order to maintain consistency within the project codebase.
+Consistency of prefix or suffix underscores should be maintained within each
+class.
+
+#### Constants
+
+Constant symbols (const global and static variables and constants created
+with #define) should use mixed case to delimit words.
+
+Global and file scope constants should have an appropriate prefix.
+
+```objectivec
+// GOOD:
+
+extern NSString *const GTLServiceErrorDomain;
+
+typedef NS_ENUM(NSInteger, GTLServiceError) {
+ GTLServiceErrorQueryResultMissing = -3000,
+ GTLServiceErrorWaitTimedOut = -3001,
+};
+```
+
+Because Objective-C does not provide namespacing, constants with external
+linkage should have a prefix that minimizes the chance of a name collision,
+typically like `ClassNameConstantName` or `ClassNameEnumName`.
+
+For interoperability with Swift code, enumerated values should have names that
+extend the typedef name:
+
+```objectivec
+// GOOD:
+
+typedef NS_ENUM(NSInteger, DisplayTinge) {
+ DisplayTingeGreen = 1,
+ DisplayTingeBlue = 2,
+};
+```
+
+Constants may use a lowercase k prefix when appropriate:
+
+```objectivec
+// GOOD:
+
+static const int kFileCount = 12;
+static NSString *const kUserKey = @"kUserKey";
+```
+
+## Types and Declarations
+
+### Local Variables
+
+Declare variables in the narrowest practical scopes, and close to their use.
+Initialize variables in their declarations.
+
+```objectivec
+// GOOD:
+
+CLLocation *location = [self lastKnownLocation];
+for (int meters = 1; meters < 10; meters++) {
+ reportFrogsWithinRadius(location, meters);
+}
+```
+
+Occasionally, efficiency will make it more appropriate to declare a variable
+outside the scope of its use. This example declares meters separate from
+initialization, and needlessly sends the lastKnownLocation message each time
+through the loop:
+
+```objectivec
+// AVOID:
+
+int meters; // AVOID.
+for (meters = 1; meters < 10; meters++) {
+ CLLocation *location = [self lastKnownLocation]; // AVOID.
+ reportFrogsWithinRadius(location, meters);
+}
+```
+
+Under Automatic Reference Counting, pointers to Objective-C objects are by
+default initialized to `nil`, so explicit initialization to `nil` is not
+required.
+
+### Unsigned Integers
+
+Avoid unsigned integers except when matching types used by system interfaces.
+
+Subtle errors crop up when doing math or counting down to zero using unsigned
+integers. Rely only on signed integers in math expressions except when matching
+NSUInteger in system interfaces.
+
+```objectivec
+// GOOD:
+
+NSUInteger numberOfObjects = array.count;
+for (NSInteger counter = numberOfObjects - 1; counter > 0; --counter)
+```
+
+```objectivec
+// AVOID:
+
+for (NSUInteger counter = numberOfObjects - 1; counter > 0; --counter) // AVOID.
+```
+
+Unsigned integers may be used for flags and bitmasks, though often NS_OPTIONS or
+NS_ENUM will be more appropriate.
+
+### Types with Inconsistent Sizes
+
+Due to sizes that differ in 32- and 64-bit builds, avoid types long, NSInteger,
+NSUInteger, and CGFloat except when matching system interfaces.
+
+Types long, NSInteger, NSUInteger, and CGFloat vary in size between 32- and
+64-bit builds. Use of these types is appropriate when handling values exposed by
+system interfaces, but they should be avoided for most other computations.
+
+```objectivec
+// GOOD:
+
+int32_t scalar1 = proto.intValue;
+
+int64_t scalar2 = proto.longValue;
+
+NSUInteger numberOfObjects = array.count;
+
+CGFloat offset = view.bounds.origin.x;
+```
+
+```objectivec
+// AVOID:
+
+NSInteger scalar2 = proto.longValue; // AVOID.
+```
+
+File and buffer sizes often exceed 32-bit limits, so they should be declared
+using `int64_t`, not with `long`, `NSInteger`, or `NSUInteger`.
+
+## Comments
+
+Comments are absolutely vital to keeping our code readable. The following rules
+describe what you should comment and where. But remember: while comments are
+important, the best code is self-documenting. Giving sensible names to types and
+variables is much better than using obscure names and then trying to explain
+them through comments.
+
+Pay attention to punctuation, spelling, and grammar; it is easier to read
+well-written comments than badly written ones.
+
+Comments should be as readable as narrative text, with proper capitalization and
+punctuation. In many cases, complete sentences are more readable than sentence
+fragments. Shorter comments, such as comments at the end of a line of code, can
+sometimes be less formal, but use a consistent style.
+When writing your comments, write for your audience: the next contributor who will need to understand your code. Be generous—the next one may be you!
+
+### File Comments
+
+A file may optionally start with a description of its contents.
+Every file may contain the following items, in order:
+ * License boilerplate if necessary. Choose the appropriate boilerplate for the license used by the project.
+ * A basic description of the contents of the file if necessary.
+
+If you make significant changes to a file with an author line, consider deleting
+the author line since revision history already provides a more detailed and
+accurate record of authorship.
+
+
+### Declaration Comments
+
+Every non-trivial interface, public and private, should have an accompanying
+comment describing its purpose and how it fits into the larger picture.
+
+Comments should be used to document classes, properties, ivars, functions,
+categories, protocol declarations, and enums.
+
+```objectivec
+// GOOD:
+
+/**
+ * A delegate for NSApplication to handle notifications about app
+ * launch and shutdown. Owned by the main app controller.
+ */
+@interface MyAppDelegate : NSObject {
+ /**
+ * The background task in progress, if any. This is initialized
+ * to the value UIBackgroundTaskInvalid.
+ */
+ UIBackgroundTaskIdentifier _backgroundTaskID;
+}
+
+/** The factory that creates and manages fetchers for the app. */
+@property(nonatomic) GTMSessionFetcherService *fetcherService;
+
+@end
+```
+
+Doxygen-style comments are encouraged for interfaces as they are parsed by Xcode
+to display formatted documentation. There is a wide variety of Doxygen commands;
+use them consistently within a project.
+
+If you have already described an interface in detail in the comments at the top
+of your file, feel free to simply state, "See comment at top of file for a
+complete description", but be sure to have some sort of comment.
+
+Additionally, each method should have a comment explaining its function,
+arguments, return value, thread or queue assumptions, and any side effects.
+Documentation comments should be in the header for public methods, or
+immediately preceding the method for non-trivial private methods.
+
+Use descriptive form ("Opens the file") rather than imperative form ("Open the
+file") for method and function comments. The comment describes the function; it
+does not tell the function what to do.
+
+Document the thread usage assumptions the class, properties, or methods make, if
+any. If an instance of the class can be accessed by multiple threads, take extra
+care to document the rules and invariants surrounding multithreaded use.
+
+Any sentinel values for properties and ivars, such as `NULL` or `-1`, should be
+documented in comments.
+
+Declaration comments explain how a method or function is used. Comments
+explaining how a method or function is implemented should be with the
+implementation rather than with the declaration.
+
+### Implementation Comments
+
+Provide comments explaining tricky, subtle, or complicated sections of code.
+
+```objectivec
+// GOOD:
+
+// Set the property to nil before invoking the completion handler to
+// avoid the risk of reentrancy leading to the callback being
+// invoked again.
+CompletionHandler handler = self.completionHandler;
+self.completionHandler = nil;
+handler();
+```
+
+When useful, also provide comments about implementation approaches that were
+considered or abandoned.
+
+End-of-line comments should be separated from the code by at least 2 spaces. If
+you have several comments on subsequent lines, it can often be more readable to
+line them up.
+
+```objectivec
+// GOOD:
+
+[self doSomethingWithALongName]; // Two spaces before the comment.
+[self doSomethingShort]; // More spacing to align the comment.
+```
+
+### Disambiguating Symbols
+
+Where needed to avoid ambiguity, use backticks or vertical bars to quote
+variable names and symbols in comments in preference to using quotation marks
+or naming the symbols inline.
+
+In Doxygen-style comments, prefer demarcating symbols with a monospace text
+command, such as `@c`.
+
+Demarcation helps provide clarity when a symbol is a common word that might make
+the sentence read like it was poorly constructed. A common example is the symbol
+`count`:
+
+```objectivec
+// GOOD:
+
+// Sometimes `count` will be less than zero.
+```
+
+or when quoting something which already contains quotes
+
+```objectivec
+// GOOD:
+
+// Remember to call `StringWithoutSpaces("foo bar baz")`
+```
+
+Backticks or vertical bars are not needed when a symbol is self-apparent.
+
+```objectivec
+// GOOD:
+
+// This class serves as a delegate to GTMDepthCharge.
+```
+
+Doxygen formatting is also suitable for identifying symbols.
+
+```objectivec
+// GOOD:
+
+/** @param maximum The highest value for @c count. */
+```
+
+### Object Ownership
+
+For objects not managed by ARC, make the pointer ownership model as explicit as
+possible when it falls outside the most common Objective-C usage idioms.
+
+#### Manual Reference Counting
+
+Instance variables for NSObject-derived objects are presumed to be retained; if
+they are not retained, they should be either commented as weak or declared with
+the `__weak` lifetime qualifier.
+
+An exception is in Mac software for instance variables labeled as `@IBOutlets`,
+which are presumed to not be retained.
+
+Where instance variables are pointers to Core Foundation, C++, and other
+non-Objective-C objects, they should always be declared with strong and weak
+comments to indicate which pointers are and are not retained. Core Foundation
+and other non-Objective-C object pointers require explicit memory management,
+even when building for automatic reference counting.
+
+Examples of strong and weak declarations:
+
+```objectivec
+// GOOD:
+
+@interface MyDelegate : NSObject
+
+@property(nonatomic) NSString *doohickey;
+@property(nonatomic, weak) NSString *parent;
+
+@end
+
+
+@implementation MyDelegate {
+ IBOutlet NSButton *_okButton; // Normal NSControl; implicitly weak on Mac only
+
+ AnObjcObject *_doohickey; // My doohickey
+ __weak MyObjcParent *_parent; // To send messages back (owns this instance)
+
+ // non-NSObject pointers...
+ CWackyCPPClass *_wacky; // Strong, some cross-platform object
+ CFDictionaryRef *_dict; // Strong
+}
+@end
+```
+
+#### Automatic Reference Counting
+
+Object ownership and lifetime are explicit when using ARC, so no additional
+comments are required for automatically retained objects.
+
+## C Language Features
+
+### Macros
+
+Avoid macros, especially where `const` variables, enums, XCode snippets, or C
+functions may be used instead.
+
+Macros make the code you see different from the code the compiler sees. Modern C
+renders traditional uses of macros for constants and utility functions
+unnecessary. Macros should only be used when there is no other solution
+available.
+
+Where a macro is needed, use a unique name to avoid the risk of a symbol
+collision in the compilation unit. If practical, keep the scope limited by
+`#undefining` the macro after its use.
+
+Macro names should use `SHOUTY_SNAKE_CASE`—all uppercase letters with
+underscores between words. Function-like macros may use C function naming
+practices. Do not define macros that appear to be C or Objective-C keywords.
+
+```objectivec
+// GOOD:
+
+#define GTM_EXPERIMENTAL_BUILD ... // GOOD
+
+// Assert unless X > Y
+#define GTM_ASSERT_GT(X, Y) ... // GOOD, macro style.
+
+// Assert unless X > Y
+#define GTMAssertGreaterThan(X, Y) ... // GOOD, function style.
+```
+
+```objectivec
+// AVOID:
+
+#define kIsExperimentalBuild ... // AVOID
+
+#define unless(X) if(!(X)) // AVOID
+```
+
+Avoid macros that expand to unbalanced C or Objective-C constructs. Avoid macros
+that introduce scope, or may obscure the capturing of values in blocks.
+
+Avoid macros that generate class, property, or method definitions in
+headers to be used as public API. These only make the code hard to
+understand, and the language already has better ways of doing this.
+
+Avoid macros that generate method implementations, or that generate declarations
+of variables that are later used outside of the macro. Macros shouldn't make
+code hard to understand by hiding where and how a variable is declared.
+
+```objectivec
+// AVOID:
+
+#define ARRAY_ADDER(CLASS) \
+ -(void)add ## CLASS ## :(CLASS *)obj toArray:(NSMutableArray *)array
+
+ARRAY_ADDER(NSString) {
+ if (array.count > 5) { // AVOID -- where is 'array' defined?
+ ...
+ }
+}
+```
+
+Examples of acceptable macro use include assertion and debug logging macros
+that are conditionally compiled based on build settings—often, these are
+not compiled into release builds.
+
+### Nonstandard Extensions
+
+Nonstandard extensions to C/Objective-C may not be used unless otherwise
+specified.
+
+Compilers support various extensions that are not part of standard C. Examples
+include compound statement expressions (e.g. `foo = ({ int x; Bar(&x); x }))`
+and variable-length arrays.
+
+`__attribute__` is an approved exception, as it is used in Objective-C API
+specifications.
+
+The binary form of the conditional operator, `A ?: B`, is an approved exception.
+
+## Cocoa and Objective-C Features
+
+### Identify Designated Initializer
+
+Clearly identify your designated initializer.
+
+It is important for those who might be subclassing your class that the
+designated initializer be clearly identified. That way, they only need to
+override a single initializer (of potentially several) to guarantee the
+initializer of their subclass is called. It also helps those debugging your
+class in the future understand the flow of initialization code if they need to
+step through it. Identify the designated initializer using comments or the
+`NS_DESIGNATED_INITIALIZER` macro. If you use `NS_DESIGNATED_INITIALIZER`, mark
+unsupported initializers with `NS_UNAVAILABLE`.
+
+### Override Designated Initializer
+
+When writing a subclass that requires an `init...` method, make sure you
+override the designated initializer of the superclass.
+
+If you fail to override the designated initializer of the superclass, your
+initializer may not be called in all cases, leading to subtle and very difficult
+to find bugs.
+
+### Overridden NSObject Method Placement
+
+Put overridden methods of NSObject at the top of an `@implementation`.
+
+This commonly applies to (but is not limited to) the `init...`, `copyWithZone:`,
+and `dealloc` methods. The `init...` methods should be grouped together,
+followed by other typical `NSObject` methods such as `description`, `isEqual:`,
+and `hash`.
+
+Convenience class factory methods for creating instances may precede the
+`NSObject` methods.
+
+### Initialization
+
+Don't initialize instance variables to `0` or `nil` in the `init` method; doing
+so is redundant.
+
+All instance variables for a newly allocated object are [initialized
+to](https://developer.apple.com/library/mac/documentation/General/Conceptual/CocoaEncyclopedia/ObjectAllocation/ObjectAllocation.html)
+`0` (except for isa), so don't clutter up the init method by re-initializing
+variables to `0` or `nil`.
+
+### Instance Variables In Headers Should Be @protected or @private
+
+Instance variables should typically be declared in implementation files or
+auto-synthesized by properties. When ivars are declared in a header file, they
+should be marked `@protected` or `@private`.
+
+```objectivec
+// GOOD:
+
+@interface MyClass : NSObject {
+ @protected
+ id _myInstanceVariable;
+}
+@end
+```
+
+### Avoid +new
+
+Do not invoke the `NSObject` class method `new`, nor override it in a subclass.
+Instead, use `alloc` and `init` methods to instantiate retained objects.
+
+Modern Objective-C code explicitly calls `alloc` and an `init` method to create
+and retain an object. As the `new` class method is rarely used, it makes
+reviewing code for correct memory management more difficult.
+
+### Keep the Public API Simple
+
+Keep your class simple; avoid "kitchen-sink" APIs. If a method doesn't need to
+be public, keep it out of the public interface.
+
+Unlike C++, Objective-C doesn't differentiate between public and private
+methods; any message may be sent to an object. As a result, avoid placing
+methods in the public API unless they are actually expected to be used by a
+consumer of the class. This helps reduce the likelihood they'll be called when
+you're not expecting it. This includes methods that are being overridden from
+the parent class.
+
+Since internal methods are not really private, it's easy to accidentally
+override a superclass's "private" method, thus making a very difficult bug to
+squash. In general, private methods should have a fairly unique name that will
+prevent subclasses from unintentionally overriding them.
+
+### #import and #include
+
+`#import` Objective-C and Objective-C++ headers, and `#include` C/C++ headers.
+
+Choose between `#import` and `#include` based on the language of the header that
+you are including.
+
+
+When including a header that uses Objective-C or Objective-C++, use `#import`.
+When including a standard C or C++ header, use `#include`.
+The header should provide its own `#define` guard.
+
+### Order of Includes
+
+The standard order for header inclusion is the related header, operating system
+headers, language library headers, and finally groups of headers for other
+dependencies.
+
+The related header precedes others to ensure it has no hidden dependencies.
+For implementation files the related header is the header file.
+For test files the related header is the header containing the tested interface.
+
+A blank line may separate logically distinct groups of included headers.
+
+Import headers using their path relative to the project's source directory.
+
+```objectivec
+// GOOD:
+
+#import "ProjectX/BazViewController.h"
+
+#import <Foundation/Foundation.h>
+
+#include <unistd.h>
+#include <vector>
+
+#include "base/basictypes.h"
+#include "base/integral_types.h"
+#include "util/math/mathutil.h"
+
+#import "ProjectX/BazModel.h"
+#import "Shared/Util/Foo.h"
+```
+
+### Use Umbrella Headers for System Frameworks
+
+Import umbrella headers for system frameworks and system libraries rather than
+include individual files.
+
+While it may seem tempting to include individual system headers from a framework
+such as Cocoa or Foundation, in fact it's less work on the compiler if you
+include the top-level root framework. The root framework is generally
+pre-compiled and can be loaded much more quickly. In addition, remember to use
+`@import` or `#import` rather than `#include` for Objective-C frameworks.
+
+```objectivec
+// GOOD:
+
+@import UIKit; // GOOD.
+#import <Foundation/Foundation.h> // GOOD.
+```
+
+```objectivec
+// AVOID:
+
+#import <Foundation/NSArray.h> // AVOID.
+#import <Foundation/NSString.h>
+...
+```
+
+### Avoid Messaging the Current Object Within Initializers and `-dealloc`
+
+Code in initializers and `-dealloc` should avoid invoking instance methods.
+
+Superclass initialization completes before subclass initialization. Until all
+classes have had a chance to initialize their instance state any method
+invocation on self may lead to a subclass operating on uninitialized instance
+state.
+
+A similar issue exists for `-dealloc`, where a method invocation may cause a
+class to operate on state that has been deallocated.
+
+One case where this is less obvious is property accessors. These can be
+overridden just like any other selector. Whenever practical, directly assign to
+and release ivars in initializers and `-dealloc`, rather than rely on accessors.
+
+```objectivec
+// GOOD:
+
+- (instancetype)init {
+ self = [super init];
+ if (self) {
+ _bar = 23; // GOOD.
+ }
+ return self;
+}
+```
+
+Beware of factoring common initialization code into helper methods:
+
+- Methods can be overridden in subclasses, either deliberately, or
+ accidentally due to naming collisions.
+- When editing a helper method, it may not be obvious that the code is being
+ run from an initializer.
+
+```objectivec
+// AVOID:
+
+- (instancetype)init {
+ self = [super init];
+ if (self) {
+ self.bar = 23; // AVOID.
+ [self sharedMethod]; // AVOID. Fragile to subclassing or future extension.
+ }
+ return self;
+}
+```
+
+```objectivec
+// GOOD:
+
+- (void)dealloc {
+ [_notifier removeObserver:self]; // GOOD.
+}
+```
+
+```objectivec
+// AVOID:
+
+- (void)dealloc {
+ [self removeNotifications]; // AVOID.
+}
+```
+
+### Setters copy NSStrings
+
+Setters taking an `NSString` should always copy the string it accepts. This is
+often also appropriate for collections like `NSArray` and `NSDictionary`.
+
+Never just retain the string, as it may be a `NSMutableString`. This avoids the
+caller changing it under you without your knowledge.
+
+Code receiving and holding collection objects should also consider that the
+passed collection may be mutable, and thus the collection could be more safely
+held as a copy or mutable copy of the original.
+
+```objectivec
+// GOOD:
+
+@property(nonatomic, copy) NSString *name;
+
+- (void)setZigfoos:(NSArray<Zigfoo *> *)zigfoos {
+ // Ensure that we're holding an immutable collection.
+ _zigfoos = [zigfoos copy];
+}
+```
+
+### Use Lightweight Generics to Document Contained Types
+
+All projects compiling on Xcode 7 or newer versions should make use of the
+Objective-C lightweight generics notation to type contained objects.
+
+Every `NSArray`, `NSDictionary`, or `NSSet` reference should be declared using
+lightweight generics for improved type safety and to explicitly document usage.
+
+```objectivec
+// GOOD:
+
+@property(nonatomic, copy) NSArray<Location *> *locations;
+@property(nonatomic, copy, readonly) NSSet<NSString *> *identifiers;
+
+NSMutableArray<MyLocation *> *mutableLocations = [otherObject.locations mutableCopy];
+```
+
+If the fully-annotated types become complex, consider using a typedef to
+preserve readability.
+
+```objectivec
+// GOOD:
+
+typedef NSSet<NSDictionary<NSString *, NSDate *> *> TimeZoneMappingSet;
+TimeZoneMappingSet *timeZoneMappings = [TimeZoneMappingSet setWithObjects:...];
+```
+
+Use the most descriptive common superclass or protocol available. In the most
+generic case when nothing else is known, declare the collection to be explicitly
+heterogenous using id.
+
+```objectivec
+// GOOD:
+
+@property(nonatomic, copy) NSArray<id> *unknowns;
+```
+
+### Avoid Throwing Exceptions
+
+Don't `@throw` Objective-C exceptions, but you should be prepared to catch them
+from third-party or OS calls.
+
+This follows the recommendation to use error objects for error delivery in
+[Apple's Introduction to Exception Programming Topics for
+Cocoa](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/Exceptions/Exceptions.html).
+
+We do compile with `-fobjc-exceptions` (mainly so we get `@synchronized`), but
+we don't `@throw`. Use of `@try`, `@catch`, and `@finally` are allowed when
+required to properly use 3rd party code or libraries. If you do use them, please
+document exactly which methods you expect to throw.
+
+### `nil` Checks
+
+Use `nil` checks for logic flow only.
+
+Use `nil` pointer checks for logic flow of the application, not for preventing
+crashes when sending messages. Sending a message to `nil` [reliably
+returns](http://www.sealiesoftware.com/blog/archive/2012/2/29/objc_explain_return_value_of_message_to_nil.html)
+`nil` as a pointer, zero as an integer or floating-point value, structs
+initialized to `0`, and `_Complex` values equal to `{0, 0}`.
+
+Note that this applies to `nil` as a message target, not as a parameter value.
+Individual methods may or may not safely handle `nil` parameter values.
+
+Note too that this is distinct from checking C/C++ pointers and block pointers
+against `NULL`, which the runtime does not handle and will cause your
+application to crash. You still need to make sure you do not dereference a
+`NULL` pointer.
+
+### BOOL Pitfalls
+
+Be careful when converting general integral values to `BOOL`. Avoid comparing
+directly with `YES`.
+
+`BOOL` in OS X and in 32-bit iOS builds is defined as a signed `char`, so it may
+have values other than `YES` (`1`) and `NO` (`0`). Do not cast or convert
+general integral values directly to `BOOL`.
+
+Common mistakes include casting or converting an array's size, a pointer value,
+or the result of a bitwise logic operation to a `BOOL` that could, depending on
+the value of the last byte of the integer value, still result in a `NO` value.
+When converting a general integral value to a `BOOL` use ternary operators to
+return a `YES` or `NO` value.
+
+You can safely interchange and convert `BOOL`, `_Bool` and `bool` (see C++ Std
+4.7.4, 4.12 and C99 Std 6.3.1.2). Use `BOOL` in Objective-C method signatures.
+
+Using logical operators (`&&`, `||` and `!`) with `BOOL` is also valid and will
+return values that can be safely converted to `BOOL` without the need for a
+ternary operator.
+
+```objectivec
+// AVOID:
+
+- (BOOL)isBold {
+ return [self fontTraits] & NSFontBoldTrait; // AVOID.
+}
+- (BOOL)isValid {
+ return [self stringValue]; // AVOID.
+}
+```
+
+```objectivec
+// GOOD:
+
+- (BOOL)isBold {
+ return ([self fontTraits] & NSFontBoldTrait) ? YES : NO;
+}
+- (BOOL)isValid {
+ return [self stringValue] != nil;
+}
+- (BOOL)isEnabled {
+ return [self isValid] && [self isBold];
+}
+```
+
+Also, don't directly compare `BOOL` variables directly with `YES`. Not only is
+it harder to read for those well-versed in C, but the first point above
+demonstrates that return values may not always be what you expect.
+
+```objectivec
+// AVOID:
+
+BOOL great = [foo isGreat];
+if (great == YES) { // AVOID.
+ // ...be great!
+}
+```
+
+```objectivec
+// GOOD:
+
+BOOL great = [foo isGreat];
+if (great) { // GOOD.
+ // ...be great!
+}
+```
+
+### Interfaces Without Instance Variables
+
+Omit the empty set of braces on interfaces that do not declare any instance
+variables.
+
+```objectivec
+// GOOD:
+
+@interface MyClass : NSObject
+// Does a lot of stuff.
+- (void)fooBarBam;
+@end
+```
+
+```objectivec
+// AVOID:
+
+@interface MyClass : NSObject {
+}
+// Does a lot of stuff.
+- (void)fooBarBam;
+@end
+```
+
+## Cocoa Patterns
+
+### Delegate Pattern
+
+Delegates, target objects, and block pointers should not be retained when doing
+so would create a retain cycle.
+
+To avoid causing a retain cycle, a delegate or target pointer should be released
+as soon as it is clear there will no longer be a need to message the object.
+
+If there is no clear time at which the delegate or target pointer is no longer
+needed, the pointer should only be retained weakly.
+
+Block pointers cannot be retained weakly. To avoid causing retain cycles in the
+client code, block pointers should be used for callbacks only where they can be
+explicitly released after they have been called or once they are no longer
+needed. Otherwise, callbacks should be done via weak delegate or target
+pointers.
+
+## Objective-C++
+
+### Style Matches the Language
+
+Within an Objective-C++ source file, follow the style for the language of the
+function or method you're implementing. In order to minimize clashes between the
+differing naming styles when mixing Cocoa/Objective-C and C++, follow the style
+of the method being implemented.
+
+For code in an `@implementation` block, use the Objective-C naming rules. For
+code in a method of a C++ class, use the C++ naming rules.
+
+For code in an Objective-C++ file outside of a class implementation, be
+consistent within the file.
+
+```objectivec++
+// GOOD:
+
+// file: cross_platform_header.h
+
+class CrossPlatformAPI {
+ public:
+ ...
+ int DoSomethingPlatformSpecific(); // impl on each platform
+ private:
+ int an_instance_var_;
+};
+
+// file: mac_implementation.mm
+#include "cross_platform_header.h"
+
+// A typical Objective-C class, using Objective-C naming.
+@interface MyDelegate : NSObject {
+ @private
+ int _instanceVar;
+ CrossPlatformAPI* _backEndObject;
+}
+
+- (void)respondToSomething:(id)something;
+
+@end
+
+@implementation MyDelegate
+
+- (void)respondToSomething:(id)something {
+ // bridge from Cocoa through our C++ backend
+ _instanceVar = _backEndObject->DoSomethingPlatformSpecific();
+ NSString* tempString = [NSString stringWithFormat:@"%d", _instanceVar];
+ NSLog(@"%@", tempString);
+}
+
+@end
+
+// The platform-specific implementation of the C++ class, using
+// C++ naming.
+int CrossPlatformAPI::DoSomethingPlatformSpecific() {
+ NSString* temp_string = [NSString stringWithFormat:@"%d", an_instance_var_];
+ NSLog(@"%@", temp_string);
+ return [temp_string intValue];
+}
+```
+
+Projects may opt to use an 80 column line length limit for consistency with
+Google's C++ style guide.
+
+## Objective-C Style Exceptions
+
+### Indicating style exceptions
+
+Lines of code that are not expected to adhere to these style recommendations
+require `// NOLINT` at the end of the line or `// NOLINTNEXTLINE` at the end of
+the previous line. Sometimes it is required that parts of Objective-C code must
+ignore these style recommendations (for example code may be machine generated or
+code constructs are such that its not possible to style correctly).
+
+A `// NOLINT` comment on that line or `// NOLINTNEXTLINE` on the previous line
+can be used to indicate to the reader that code is intentionally ignoring style
+guidelines. In addition these annotations can also be picked up by automated
+tools such as linters and handle code correctly. Note that there is a single
+space between `//` and `NOLINT*`.
diff --git a/objcguide.xml b/objcguide.xml
new file mode 100644
index 0000000..3beca74
--- /dev/null
+++ b/objcguide.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0"?>
+<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
+<GUIDE title="Google Objective-C Style Guide">
+ <p>
+ The style guide has moved to
+ <a href="https://github.com/google/styleguide/blob/gh-pages/objcguide.md">objcguide.md</a>
+ </p>
+</GUIDE>
diff --git a/pyguide.html b/pyguide.html
new file mode 100644
index 0000000..6987f2b
--- /dev/null
+++ b/pyguide.html
@@ -0,0 +1,2310 @@
+<HTML xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcq="http://purl.org/dc/qualifiers/1.0/" xmlns:fo="http://www.w3.org/1999/XSL/Format" xmlns:fn="http://www.w3.org/2005/xpath-functions">
+<HEAD>
+<TITLE>Google Python Style Guide</TITLE>
+<META http-equiv="Content-Type" content="text/html; charset=utf-8">
+<LINK HREF="https://www.google.com/favicon.ico" type="image/x-icon" rel="shortcut icon">
+<LINK HREF="styleguide.css" type="text/css" rel="stylesheet">
+<SCRIPT language="javascript" type="text/javascript">
+
+ function GetElementsByName(name) {
+ // Workaround a bug on old versions of opera.
+ if (document.getElementsByName) {
+ return document.getElementsByName(name);
+ } else {
+ return [document.getElementById(name)];
+ }
+ }
+
+ /**
+ * @param {string} namePrefix The prefix of the body name.
+ * @param {function(boolean): boolean} getVisibility Computes the new
+ * visibility state, given the current one.
+ */
+ function ChangeVisibility(namePrefix, getVisibility) {
+ var bodyName = namePrefix + '__body';
+ var buttonName = namePrefix + '__button';
+ var bodyElements = GetElementsByName(bodyName);
+ var linkElement = GetElementsByName('link-' + buttonName)[0];
+ if (bodyElements.length != 1) {
+ throw Error('ShowHideByName() got the wrong number of bodyElements: ' +
+ bodyElements.length);
+ } else {
+ var bodyElement = bodyElements[0];
+ var buttonElement = GetElementsByName(buttonName)[0];
+ var isVisible = bodyElement.style.display != "none";
+ if (getVisibility(isVisible)) {
+ bodyElement.style.display = "inline";
+ linkElement.style.display = "block";
+ buttonElement.innerHTML = '▽';
+ } else {
+ bodyElement.style.display = "none";
+ linkElement.style.display = "none";
+ buttonElement.innerHTML = '▶';
+ }
+ }
+ }
+
+ function ShowHideByName(namePrefix) {
+ ChangeVisibility(namePrefix, function(old) { return !old; });
+ }
+
+ function ShowByName(namePrefix) {
+ ChangeVisibility(namePrefix, function() { return true; });
+ }
+
+ function ShowHideAll() {
+ var allButton = GetElementsByName("show_hide_all_button")[0];
+ if (allButton.innerHTML == '▽') {
+ allButton.innerHTML = '▶';
+ SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '▶');
+ } else {
+ allButton.innerHTML = '▽';
+ SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "inline", '▽');
+ }
+ }
+
+ // Recursively sets state of all children
+ // of a particular node.
+ function SetHiddenState(root, newState, newButton) {
+ for (var i = 0; i != root.length; i++) {
+ SetHiddenState(root[i].childNodes, newState, newButton);
+ if (root[i].className == 'showhide_button') {
+ root[i].innerHTML = newButton;
+ }
+ if (root[i].className == 'stylepoint_body' ||
+ root[i].className == 'link_button') {
+ root[i].style.display = newState;
+ }
+ }
+ }
+
+
+ function EndsWith(str, suffix) {
+ var l = str.length - suffix.length;
+ return l >= 0 && str.indexOf(suffix, l) == l;
+ }
+
+ function RefreshVisibilityFromHashParam() {
+ var hashRegexp = new RegExp('#([^&#]*)$');
+ var hashMatch = hashRegexp.exec(window.location.href);
+ var anchor = hashMatch && GetElementsByName(hashMatch[1])[0];
+ var node = anchor;
+ var suffix = '__body';
+ while (node) {
+ var id = node.id;
+ var matched = id && EndsWith(id, suffix);
+ if (matched) {
+ var len = id.length - suffix.length;
+ ShowByName(id.substring(0, len));
+ if (anchor.scrollIntoView) {
+ anchor.scrollIntoView();
+ }
+
+ return;
+ }
+ node = node.parentNode;
+ }
+ }
+
+ window.onhashchange = RefreshVisibilityFromHashParam;
+
+ window.onload = function() {
+ // if the URL contains "?showall=y", expand the details of all children
+ var showHideAllRegex = new RegExp("[\\?&](showall)=([^&#]*)");
+ var showHideAllValue = showHideAllRegex.exec(window.location.href);
+ if (showHideAllValue != null) {
+ if (showHideAllValue[2] == "y") {
+ SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
+ "inline", '▽');
+ } else {
+ SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
+ "none", '▶');
+ }
+ }
+ var showOneRegex = new RegExp("[\\?&](showone)=([^&#]*)");
+ var showOneValue = showOneRegex.exec(window.location.href);
+ if (showOneValue) {
+ ShowHideByName(showOneValue[2]);
+ }
+
+
+ RefreshVisibilityFromHashParam();
+ }
+ </SCRIPT>
+</HEAD>
+<BODY>
+<H1>Google Python Style Guide</H1>
+ <p align="right">
+
+ Revision 2.59
+ </p>
+
+ <address>
+ Amit Patel<br>
+ Antoine Picard<br>
+ Eugene Jhong<br>
+ Jeremy Hylton<br>
+ Matt Smart<br>
+ Mike Shields<br>
+ </address>
+ <DIV style="margin-left: 50%; font-size: 75%;">
+<P>
+ Each style point has a summary for which additional information is available
+ by toggling the accompanying arrow button that looks this way:
+ <SPAN class="showhide_button" style="margin-left: 0; float: none">▶</SPAN>.
+ You may toggle all summaries with the big arrow button:
+ </P>
+<DIV style=" font-size: larger; margin-left: +2em;">
+<SPAN class="showhide_button" style="font-size: 180%; float: none" onclick="javascript:ShowHideAll()" name="show_hide_all_button" id="show_hide_all_button">▶</SPAN>
+ Toggle all summaries
+ </DIV>
+</DIV>
+<DIV class="toc">
+<DIV class="toc_title">Table of Contents</DIV>
+<TABLE>
+<TR valign="top" class="">
+<TD><DIV class="toc_category"><A href="#Python_Language_Rules">Python Language Rules</A></DIV></TD>
+<TD><DIV class="toc_stylepoint">
+<SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Lint">Lint</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Imports">Imports</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Packages">Packages</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Exceptions">Exceptions</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Global_variables">Global variables</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Nested/Local/Inner_Classes_and_Functions">Nested/Local/Inner Classes and Functions</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#List_Comprehensions">List Comprehensions</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Default_Iterators_and_Operators">Default Iterators and Operators</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Generators">Generators</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Lambda_Functions">Lambda Functions</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Conditional_Expressions">Conditional Expressions</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Default_Argument_Values">Default Argument Values</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Properties">Properties</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#True/False_evaluations">True/False evaluations</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Deprecated_Language_Features">Deprecated Language Features</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Lexical_Scoping">Lexical Scoping</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Function_and_Method_Decorators">Function and Method Decorators</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Threading">Threading</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Power_Features">Power Features</A></SPAN> </DIV></TD>
+</TR>
+<TR valign="top" class="">
+<TD><DIV class="toc_category"><A href="#Python_Style_Rules">Python Style Rules</A></DIV></TD>
+<TD><DIV class="toc_stylepoint">
+<SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Semicolons">Semicolons</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Line_length">Line length</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Parentheses">Parentheses</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Indentation">Indentation</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Blank_Lines">Blank Lines</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Whitespace">Whitespace</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Shebang_Line">Shebang Line</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Comments">Comments</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Classes">Classes</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Strings">Strings</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Files_and_Sockets">Files and Sockets</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#TODO_Comments">TODO Comments</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Imports_formatting">Imports formatting</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Statements">Statements</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Access_Control">Access Control</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Naming">Naming</A></SPAN> <SPAN style="padding-right: 1em; white-space:nowrap;" class=""><A href="#Main">Main</A></SPAN> </DIV></TD>
+</TR>
+</TABLE>
+</DIV>
+ <DIV class="">
+<H2 name="Important_Note" id="Important_Note">Important Note</H2>
+ <DIV class="">
+<H3><A name="Displaying_Hidden_Details_in_this_Guide" id="Displaying_Hidden_Details_in_this_Guide">Displaying Hidden Details in this Guide</A></H3>
+<SPAN class="link_button" id="link-Displaying_Hidden_Details_in_this_Guide__button" name="link-Displaying_Hidden_Details_in_this_Guide__button"><A href="?showone=Displaying_Hidden_Details_in_this_Guide#Displaying_Hidden_Details_in_this_Guide">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Displaying_Hidden_Details_in_this_Guide')" name="Displaying_Hidden_Details_in_this_Guide__button" id="Displaying_Hidden_Details_in_this_Guide__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ This style guide contains many details that are initially
+ hidden from view. They are marked by the triangle icon, which you
+ see here on your left. Click it now.
+ You should see "Hooray" appear below.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Displaying_Hidden_Details_in_this_Guide__body" id="Displaying_Hidden_Details_in_this_Guide__body" style="display: none">
+ <p>
+ Hooray! Now you know you can expand points to get more
+ details. Alternatively, there's a "toggle all" at the
+ top of this document.
+ </p>
+ </DIV></DIV>
+ </DIV>
+ </DIV>
+ <DIV class="">
+<H2 name="Background" id="Background">Background</H2>
+ <p>
+ Python is the main scripting language used at Google. This
+ style guide is a list of <em>do</em>s and <em>don't</em>s for Python
+ programs.
+ </p>
+
+ <p>
+ To help you format code correctly, we've created a <a href="google_python_style.vim">settings
+ file for Vim</a>. For Emacs, the default settings should be fine.
+ </p>
+
+
+ </DIV>
+
+ <DIV class="">
+<H2 name="Python_Language_Rules" id="Python_Language_Rules">Python Language Rules</H2>
+ <DIV class="">
+<H3><A name="Lint" id="Lint">Lint</A></H3>
+<SPAN class="link_button" id="link-Lint__button" name="link-Lint__button"><A href="?showone=Lint#Lint">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Lint')" name="Lint__button" id="Lint__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Run <code>pylint</code> over your code.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Lint__body" id="Lint__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN>
+ pylint
+ is a tool for finding bugs and style problems in Python source
+ code. It finds
+ problems that are typically caught by a compiler for less dynamic
+ languages like C and C++.
+
+ Because of the
+ dynamic nature of Python, some warnings may be incorrect; however,
+ spurious warnings should be fairly infrequent.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN>
+ Catches easy-to-miss errors like typos, using-vars-before-assignment, etc.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN>
+ <code>pylint</code>
+ isn't perfect. To take advantage of it, we'll need to sometimes:
+ a) Write around it b) Suppress its warnings or c) Improve it.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN>
+ Make sure you run <code>pylint</code> on your code.
+ Suppress warnings if they are inappropriate so that other issues are
+ not hidden.
+ </P>
+
+ <p>
+ To suppress warnings, you can set a line-level comment:
+ </p>
+
+ <DIV class=""><PRE>
+<span class="external"></span>dict = 'something awful' # Bad Idea... pylint: disable=redefined-builtin</PRE></DIV>
+ <p>
+ pylint
+ warnings are each identified by a alphanumeric code
+ (<code>C0112</code>) and a symbolic name
+ (<code>empty-docstring</code>). Prefer the symbolic
+ names in new code or when updating existing code.
+
+ </p>
+ <p>
+ If the reason for the suppression is not clear from the symbolic name,
+ add an explanation.
+ </p>
+ <p>
+ Suppressing in this way has the advantage that we can easily search
+ for suppressions and revisit them.
+ </p>
+ <p>
+ You can get a list of
+ pylint
+ warnings by doing
+ <code>pylint --list-msgs</code>.
+ To get more information on a particular message, use
+ <code>pylint --help-msg=C6409</code>.
+ </p>
+ <p>
+ Prefer <code>pylint: disable</code> to the deprecated older form
+ <code>pylint: disable-msg</code>.
+ </p>
+ <p>
+ Unused argument warnings can be suppressed by using `_' as the
+ identifier for the unused argument or prefixing the argument name with
+ `unused_'. In situations where changing the argument names is
+ infeasible, you can mention them at the beginning of the function.
+ For example:
+ </p>
+ <DIV class=""><PRE>
+<span class="external"></span>def foo(a, unused_b, unused_c, d=None, e=None):
+ <span class="external"> </span>_ = d, e
+ <span class="external"> </span>return a
+<span class="external"></span>
+</PRE></DIV>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Imports" id="Imports">Imports</A></H3>
+<SPAN class="link_button" id="link-Imports__button" name="link-Imports__button"><A href="?showone=Imports#Imports">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Imports')" name="Imports__button" id="Imports__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Use <code>import</code>s for packages and modules only.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Imports__body" id="Imports__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN>
+ Reusability mechanism for sharing code from one module to another.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN>
+ The namespace management convention is simple. The source of each
+ identifier is indicated in a consistent way; <code>x.Obj</code> says
+ that object <code>Obj</code> is defined in module <code>x</code>.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN> Module names can still collide. Some module names are
+ inconveniently long.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN>
+ Use <code>import x</code> for importing packages and modules.
+ <br>
+ Use <code>from x import y</code> where <code>x</code> is
+ the package prefix and <code>y</code> is the module name with no
+ prefix.
+ <br>
+ Use <code>from x import y as z</code> if two modules named
+ <code>y</code> are to be imported or if <code>y</code> is an
+ inconveniently long name.
+ </P>
+ For example the module
+ <code>sound.effects.echo</code> may be imported as follows:
+ <DIV class=""><PRE>
+<span class="external"></span>from sound.effects import echo
+<span class="external"></span>...
+<span class="external"></span>echo.EchoFilter(input, output, delay=0.7, atten=4)
+<span class="external"></span>
+</PRE></DIV>
+ <p>
+ Do not use relative names in imports. Even if the module is in the
+ same package, use the full package name. This helps prevent
+ unintentionally importing a package twice.
+ </p>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Packages" id="Packages">Packages</A></H3>
+<SPAN class="link_button" id="link-Packages__button" name="link-Packages__button"><A href="?showone=Packages#Packages">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Packages')" name="Packages__button" id="Packages__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Import each module using the full pathname location of the module.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Packages__body" id="Packages__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN>
+ Avoids conflicts in module names. Makes it easier to find modules.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN>
+ Makes it harder to deploy code because you have to replicate the
+ package hierarchy.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN>
+ All new code should import each module by its full package name.
+ </P>
+ <p>
+ Imports should be as follows:
+ </p>
+
+ <DIV class=""><PRE># Reference in code with complete name.
+import sound.effects.echo
+
+# Reference in code with just module name (preferred).
+from sound.effects import echo
+</PRE></DIV>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Exceptions" id="Exceptions">Exceptions</A></H3>
+<SPAN class="link_button" id="link-Exceptions__button" name="link-Exceptions__button"><A href="?showone=Exceptions#Exceptions">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Exceptions')" name="Exceptions__button" id="Exceptions__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Exceptions are allowed but must be used carefully.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Exceptions__body" id="Exceptions__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN>
+ Exceptions are a means of breaking out of the normal flow of control
+ of a code block to handle errors or other exceptional conditions.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN>
+ The control flow of normal operation code is not cluttered by
+ error-handling code. It also allows the control flow to skip multiple
+ frames when a certain condition occurs, e.g., returning from N
+ nested functions in one step instead of having to carry-through
+ error codes.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN>
+ May cause the control flow to be confusing. Easy to miss error
+ cases when making library calls.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN>
+
+
+ Exceptions must follow certain conditions:
+
+ <ul>
+ <li>Raise exceptions like this: <code>raise MyException('Error
+ message')</code> or <code>raise MyException</code>. Do not
+ use the two-argument form (<code>raise MyException, 'Error
+ message'</code>) or deprecated string-based exceptions
+ (<code>raise 'Error message'</code>).</li>
+ <li>Modules or packages should define their own domain-specific
+ base exception class, which should inherit from the built-in
+ Exception class. The base exception for a module should be called
+ <code>Error</code>.
+ <DIV class=""><PRE>
+<span class="external"></span>class Error(Exception):
+ <span class="external"> </span>pass</PRE></DIV>
+</li>
+ <li>Never use catch-all <code>except:</code> statements, or
+ catch <code>Exception</code> or <code>StandardError</code>,
+ unless you are re-raising the exception or in the outermost
+ block in your thread (and printing an error message). Python
+ is very tolerant in this regard and <code>except:</code> will
+ really catch everything including misspelled names, sys.exit()
+ calls, Ctrl+C interrupts, unittest failures and all kinds of
+ other exceptions that you simply don't want to catch.</li>
+ <li>Minimize the amount of code in a
+ <code>try</code>/<code>except</code> block. The larger the
+ body of the <code>try</code>, the more likely that an
+ exception will be raised by a line of code that you didn't
+ expect to raise an exception. In those cases,
+ the <code>try</code>/<code>except</code> block hides a real
+ error.</li>
+ <li>Use the <code>finally</code> clause to execute code whether
+ or not an exception is raised in the <code>try</code> block.
+ This is often useful for cleanup, i.e., closing a file.</li>
+ <li>When capturing an exception, use <code>as</code> rather than
+ a comma. For example:
+ <DIV class=""><PRE>
+<span class="external"></span>try:
+ <span class="external"> </span>raise Error
+<span class="external"></span>except Error as error:
+ <span class="external"> </span>pass</PRE></DIV>
+</li>
+ </ul>
+ </P>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Global_variables" id="Global_variables">Global variables</A></H3>
+<SPAN class="link_button" id="link-Global_variables__button" name="link-Global_variables__button"><A href="?showone=Global_variables#Global_variables">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Global_variables')" name="Global_variables__button" id="Global_variables__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Avoid global variables.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Global_variables__body" id="Global_variables__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN>
+ Variables that are declared at the module level.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN>
+ Occasionally useful.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN>
+ Has the potential to change module behavior during the import,
+ because assignments to module-level variables are done when the
+ module is imported.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN>
+ Avoid global variables in favor of class variables. Some
+ exceptions are:
+ <ul>
+ <li>Default options for scripts.</li>
+ <li>Module-level constants. For example: <code>PI = 3.14159</code>.
+ Constants should be named using all caps with underscores;
+ see <a HREF="#Naming">Naming</a> below.</li>
+ <li>It is sometimes useful for globals to cache values needed
+ or returned by functions.</li>
+ <li>If needed, globals should be made internal to the module
+ and accessed through public module level functions;
+ see <a HREF="#Naming">Naming</a> below.</li>
+ </ul>
+ </P>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Nested/Local/Inner_Classes_and_Functions" id="Nested/Local/Inner_Classes_and_Functions">Nested/Local/Inner Classes and Functions</A></H3>
+<SPAN class="link_button" id="link-Nested/Local/Inner_Classes_and_Functions__button" name="link-Nested/Local/Inner_Classes_and_Functions__button"><A href="?showone=Nested/Local/Inner_Classes_and_Functions#Nested/Local/Inner_Classes_and_Functions">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Nested/Local/Inner_Classes_and_Functions')" name="Nested/Local/Inner_Classes_and_Functions__button" id="Nested/Local/Inner_Classes_and_Functions__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Nested/local/inner classes and functions are fine.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Nested/Local/Inner_Classes_and_Functions__body" id="Nested/Local/Inner_Classes_and_Functions__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN>
+ A class can be defined inside of a method, function, or class. A
+ function can be defined inside a method or function. Nested functions
+ have read-only access to variables defined in enclosing scopes.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN>
+ Allows definition of utility classes and functions that are only
+ used inside of a very limited scope. Very <a HREF="https://en.wikipedia.org/wiki/Abstract_data_type">ADT</a>-y.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN>
+ Instances of nested or local classes cannot be pickled.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN>
+ They are fine.
+ </P>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="List_Comprehensions" id="List_Comprehensions">List Comprehensions</A></H3>
+<SPAN class="link_button" id="link-List_Comprehensions__button" name="link-List_Comprehensions__button"><A href="?showone=List_Comprehensions#List_Comprehensions">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('List_Comprehensions')" name="List_Comprehensions__button" id="List_Comprehensions__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Okay to use for simple cases.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="List_Comprehensions__body" id="List_Comprehensions__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN>
+ List comprehensions and generator expressions provide a concise
+ and efficient way to create lists and iterators without
+ resorting to the use of <code>map()</code>,
+ <code>filter()</code>, or <code>lambda</code>.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN>
+ Simple list comprehensions can be clearer and simpler than
+ other list creation techniques. Generator expressions can be
+ very efficient, since they avoid the creation of a list
+ entirely.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN>
+ Complicated list comprehensions or generator expressions can be
+ hard to read.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN>
+ Okay to use for simple cases. Each portion must fit on one line:
+ mapping expression, <code>for</code> clause, filter expression.
+ Multiple <code>for</code> clauses or filter expressions are not
+ permitted. Use loops instead when things get more complicated.
+ </P>
+
+<DIV class=""><PRE>Ye<span class="external"></span>s:
+ <span class="external"></span>result = []
+ <span class="external"></span>for x in range(10):
+ <span class="external"> </span>for y in range(5):
+ <span class="external"> </span>if x * y > 10:
+ <span class="external"> </span>result.append((x, y))
+
+ <span class="external"></span>for x in xrange(5):
+ <span class="external"> </span>for y in xrange(5):
+ <span class="external"> </span>if x != y:
+ <span class="external"> </span>for z in xrange(5):
+ <span class="external"> </span>if y != z:
+ <span class="external"> </span>yield (x, y, z)
+
+ <span class="external"></span>return ((x, complicated_transform(x))
+ <span class="external"></span> for x in long_generator_function(parameter)
+ <span class="external"></span> if x is not None)
+
+ <span class="external"></span>squares = [x * x for x in range(10)]
+
+ <span class="external"></span>eat(jelly_bean for jelly_bean in jelly_beans
+ <span class="external"></span> if jelly_bean.color == 'black')</PRE></DIV>
+<DIV class=""><PRE class="badcode">No<span class="external"></span>:
+ <span class="external"></span>result = [(x, y) for x in range(10) for y in range(5) if x * y > 10]
+
+ <span class="external"></span>return ((x, y, z)
+ <span class="external"></span> for x in xrange(5)
+ <span class="external"></span> for y in xrange(5)
+ <span class="external"></span> if x != y
+ <span class="external"></span> for z in xrange(5)
+ <span class="external"></span> if y != z)</PRE></DIV>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Default_Iterators_and_Operators" id="Default_Iterators_and_Operators">Default Iterators and Operators</A></H3>
+<SPAN class="link_button" id="link-Default_Iterators_and_Operators__button" name="link-Default_Iterators_and_Operators__button"><A href="?showone=Default_Iterators_and_Operators#Default_Iterators_and_Operators">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Default_Iterators_and_Operators')" name="Default_Iterators_and_Operators__button" id="Default_Iterators_and_Operators__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Use default iterators and operators for types that support them,
+ like lists, dictionaries, and files.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Default_Iterators_and_Operators__body" id="Default_Iterators_and_Operators__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN>
+ Container types, like dictionaries and lists, define default
+ iterators and membership test operators ("in" and "not in").
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN>
+ The default iterators and operators are simple and efficient.
+ They express the operation directly, without extra method calls.
+ A function that uses default operators is generic. It can be
+ used with any type that supports the operation.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN>
+ You can't tell the type of objects by reading the method names
+ (e.g. has_key() means a dictionary). This is also an advantage.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN> Use default iterators and operators for types
+ that support them, like lists, dictionaries, and files. The
+ built-in types define iterator methods, too. Prefer these
+ methods to methods that return lists, except that you should not
+ mutate a container while iterating over it.
+
+<DIV class=""><PRE>Yes: <span class="external"></span>for key in adict: ...
+ <span class="external"></span>if key not in adict: ...
+ <span class="external"></span>if obj in alist: ...
+ <span class="external"></span>for line in afile: ...
+ <span class="external"></span>for k, v in dict.iteritems(): ...</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>for key in adict.keys(): ...
+ <span class="external"></span>if not adict.has_key(key): ...
+ <span class="external"></span>for line in afile.readlines(): ...</PRE></DIV>
+ </P>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Generators" id="Generators">Generators</A></H3>
+<SPAN class="link_button" id="link-Generators__button" name="link-Generators__button"><A href="?showone=Generators#Generators">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Generators')" name="Generators__button" id="Generators__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Use generators as needed.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Generators__body" id="Generators__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN>
+ A generator function returns an iterator that yields a value each
+ time it executes a yield statement. After it yields a value, the
+ runtime state of the generator function is suspended until the
+ next value is needed.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN>
+ Simpler code, because the state of local variables and control flow
+ are preserved for each call. A generator uses less memory than a
+ function that creates an entire list of values at once.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN>
+ None.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN>
+ Fine. Use "Yields:" rather than "Returns:" in the
+ doc string for generator functions.
+ </P>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Lambda_Functions" id="Lambda_Functions">Lambda Functions</A></H3>
+<SPAN class="link_button" id="link-Lambda_Functions__button" name="link-Lambda_Functions__button"><A href="?showone=Lambda_Functions#Lambda_Functions">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Lambda_Functions')" name="Lambda_Functions__button" id="Lambda_Functions__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Okay for one-liners.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Lambda_Functions__body" id="Lambda_Functions__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN>
+ Lambdas define anonymous functions in an expression, as
+ opposed to a statement. They are often used to define callbacks or
+ operators for higher-order functions like <code>map()</code> and
+ <code>filter()</code>.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN>
+ Convenient.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN> Harder to read and debug than local functions. The
+ lack of names means stack traces are more difficult to
+ understand. Expressiveness is limited because the function may
+ only contain an expression.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN>
+ Okay to use them for one-liners. If the code inside the lambda
+ function is any longer than 60–80 chars, it's probably better to
+ define it as a regular (nested) function.
+ <p>
+ For common operations like multiplication, use the functions from the
+ <code>operator</code> module instead of lambda functions. For
+ example, prefer <code>operator.mul</code> to <code>lambda
+ x, y: x * y</code>.
+ </p>
+ </P>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Conditional_Expressions" id="Conditional_Expressions">Conditional Expressions</A></H3>
+<SPAN class="link_button" id="link-Conditional_Expressions__button" name="link-Conditional_Expressions__button"><A href="?showone=Conditional_Expressions#Conditional_Expressions">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Conditional_Expressions')" name="Conditional_Expressions__button" id="Conditional_Expressions__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Okay for one-liners.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Conditional_Expressions__body" id="Conditional_Expressions__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN>
+ Conditional expressions are mechanisms that provide a shorter syntax
+ for if statements. For example:
+ <code>x = 1 if cond else 2</code>.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN>
+ Shorter and more convenient than an if statement.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN>
+ May be harder to read than an if statement. The condition may be difficult
+ to locate if the expression is long.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN>
+ Okay to use for one-liners. In other cases prefer to use a complete if
+ statement.
+ </P>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Default_Argument_Values" id="Default_Argument_Values">Default Argument Values</A></H3>
+<SPAN class="link_button" id="link-Default_Argument_Values__button" name="link-Default_Argument_Values__button"><A href="?showone=Default_Argument_Values#Default_Argument_Values">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Default_Argument_Values')" name="Default_Argument_Values__button" id="Default_Argument_Values__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Okay in most cases.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Default_Argument_Values__body" id="Default_Argument_Values__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN>
+ You can specify values for variables at the end of a function's
+ parameter list, e.g., <code>def foo(a, b=0):</code>. If
+ <code>foo</code> is called with only one argument,
+ <code>b</code> is set to 0. If it is called with two arguments,
+ <code>b</code> has the value of the second argument.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN>
+ Often you have a function that uses lots of default values,
+ but—rarely—you want to override the
+ defaults. Default argument values provide an easy way to do this,
+ without having to define lots of functions for the rare
+ exceptions. Also, Python does not support overloaded
+ methods/functions and default arguments are an easy way of
+ "faking" the overloading behavior.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN>
+ Default arguments are evaluated once at module load
+ time. This may cause problems if the argument is a mutable
+ object such as a list or a dictionary. If the function modifies
+ the object (e.g., by appending an item to a list), the default
+ value is modified.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN>
+ Okay to use with the following caveat:
+ <p>
+ Do not use mutable objects as default values in the function or method
+ definition.
+ </p>
+<DIV class=""><PRE>Yes: <span class="external"></span>def foo(a, b=None):
+ <span class="external"> </span>if b is None:
+ <span class="external"> </span>b = []</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>def foo(a, b=[]):
+ <span class="external"> </span>...
+No: <span class="external"></span>def foo(a, b=time.time()): # The time the module was loaded???
+ <span class="external"> </span>...
+No: <span class="external"></span>def foo(a, b=FLAGS.my_thing): # sys.argv has not yet been parsed...
+ <span class="external"> </span>...</PRE></DIV>
+ </P>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Properties" id="Properties">Properties</A></H3>
+<SPAN class="link_button" id="link-Properties__button" name="link-Properties__button"><A href="?showone=Properties#Properties">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Properties')" name="Properties__button" id="Properties__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Use properties for accessing or setting data where you would
+ normally have used simple, lightweight accessor or setter methods.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Properties__body" id="Properties__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN> A way to wrap method calls for getting and
+ setting an attribute as a standard attribute access when the
+ computation is lightweight.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN> Readability is increased by eliminating explicit
+ get and set method calls for simple attribute access. Allows
+ calculations to be lazy. Considered the Pythonic way to
+ maintain the interface of a class. In terms of performance,
+ allowing properties bypasses needing trivial accessor methods
+ when a direct variable access is reasonable. This also allows
+ accessor methods to be added in the future without breaking the
+ interface.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN> Properties are specified after the getter and
+ setter methods are declared, requiring one to notice they are
+ used for properties farther down in the code (except for readonly
+ properties created with the <code>@property</code> decorator - see
+ below). Must inherit from
+ <code>object</code>. Can hide side-effects much like operator
+ overloading. Can be confusing for subclasses.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN> Use properties in new code to access or
+ set data where you would normally have used simple, lightweight
+ accessor or setter methods. Read-only properties should be created
+ with the <code>@property</code>
+ <a HREF="#Function_and_Method_Decorators">decorator</a>.
+
+ <p><a id="properties-template-dp">
+ Inheritance with properties can be non-obvious if the property itself is
+ not overridden. Thus one must make sure that accessor methods are
+ called indirectly to ensure methods overridden in subclasses are called
+ by the property (using the Template Method DP).
+ </a></p>
+
+ <DIV class=""><PRE>Yes: <span class="external"></span>import math
+
+ <span class="external"></span>class Square(object):
+ <span class="external"> </span>"""A square with two properties: a writable area and a read-only perimeter.
+
+ <span class="external"> </span>To use:
+ <span class="external"> </span>>>> sq = Square(3)
+ <span class="external"> </span>>>> sq.area
+ <span class="external"> </span>9
+ <span class="external"> </span>>>> sq.perimeter
+ <span class="external"> </span>12
+ <span class="external"> </span>>>> sq.area = 16
+ <span class="external"> </span>>>> sq.side
+ <span class="external"> </span>4
+ <span class="external"> </span>>>> sq.perimeter
+ <span class="external"> </span>16
+ <span class="external"> </span>"""
+
+ <span class="external"> </span>def __init__(self, side):
+ <span class="external"> </span>self.side = side
+
+ <span class="external"> </span>def __get_area(self):
+ <span class="external"> </span>"""Calculates the 'area' property."""
+ <span class="external"> </span>return self.side ** 2
+
+ <span class="external"> </span>def ___get_area(self):
+ <span class="external"> </span>"""Indirect accessor for 'area' property."""
+ <span class="external"> </span>return self.__get_area()
+
+ <span class="external"> </span>def __set_area(self, area):
+ <span class="external"> </span>"""Sets the 'area' property."""
+ <span class="external"> </span>self.side = math.sqrt(area)
+
+ <span class="external"> </span>def ___set_area(self, area):
+ <span class="external"> </span>"""Indirect setter for 'area' property."""
+ <span class="external"> </span>self.__set_area(area)
+
+ <span class="external"> </span>area = property(___get_area, ___set_area,
+ <span class="external"> </span> doc="""Gets or sets the area of the square.""")
+
+ <span class="external"> </span>@property
+ <span class="external"> </span>def perimeter(self):
+ <span class="external"> </span>return self.side * 4
+<span class="external"></span>
+</PRE></DIV>
+ </P>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="True/False_evaluations" id="True/False_evaluations">True/False evaluations</A></H3>
+<SPAN class="link_button" id="link-True/False_evaluations__button" name="link-True/False_evaluations__button"><A href="?showone=True/False_evaluations#True/False_evaluations">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('True/False_evaluations')" name="True/False_evaluations__button" id="True/False_evaluations__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Use the "implicit" false if at all possible.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="True/False_evaluations__body" id="True/False_evaluations__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN> Python evaluates certain values as <code>false</code>
+ when in a boolean context. A quick "rule of thumb" is that all
+ "empty" values are considered <code>false</code> so <code>0, None, [], {},
+ ''</code> all evaluate as <code>false</code> in a boolean context.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN> Conditions using Python booleans are easier to read
+ and less error-prone. In most cases, they're also faster.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN>
+ May look strange to C/C++ developers.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN>
+ Use the "implicit" false if at all possible, e.g., <code>if
+ foo:</code> rather than <code>if foo != []:</code>. There are a
+ few caveats that you should keep in mind though:
+ <ul>
+ <li>
+ Never use <code>==</code> or <code>!=</code> to compare
+ singletons like <code>None</code>. Use <code>is</code>
+ or <code>is not</code>.</li>
+
+ <li>Beware of writing <code>if x:</code> when you really mean
+ <code>if x is not None:</code>—e.g., when testing whether
+ a variable or argument that defaults to <code>None</code> was
+ set to some other value. The other value might be a value
+ that's false in a boolean context!</li>
+
+ <li>
+ Never compare a boolean variable to <code>False</code> using
+ <code>==</code>. Use <code>if not x:</code> instead. If
+ you need to distinguish <code>False</code> from
+ <code>None</code> then chain the expressions,
+ such as <code>if not x and x is not None:</code>.
+ </li>
+
+ <li>
+ For sequences (strings, lists, tuples), use the fact that
+ empty sequences are false, so <code>if not seq:</code> or
+ <code>if seq:</code> is preferable to <code>if
+ len(seq):</code> or <code>if not
+ len(seq):</code>.</li>
+
+ <li>
+ When handling integers, implicit false may involve more risk than
+ benefit (i.e., accidentally handling <code>None</code> as 0). You may
+ compare a value which is known to be an integer (and is not the
+ result of <code>len()</code>) against the integer 0.
+<DIV class=""><PRE>Yes: <span class="external"></span>if not users:
+ <span class="external"> </span>print 'no users'
+
+ <span class="external"></span>if foo == 0:
+ <span class="external"> </span>self.handle_zero()
+
+ <span class="external"></span>if i % 10 == 0:
+ <span class="external"> </span>self.handle_multiple_of_ten()</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>if len(users) == 0:
+ <span class="external"> </span>print 'no users'
+
+ <span class="external"></span>if foo is not None and not foo:
+ <span class="external"> </span>self.handle_zero()
+
+ <span class="external"></span>if not i % 10:
+ <span class="external"> </span>self.handle_multiple_of_ten()</PRE></DIV>
+</li>
+
+ <li>
+ Note that <code>'0'</code> (i.e., <code>0</code> as string)
+ evaluates to true.</li>
+ </ul>
+ </P>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Deprecated_Language_Features" id="Deprecated_Language_Features">Deprecated Language Features</A></H3>
+<SPAN class="link_button" id="link-Deprecated_Language_Features__button" name="link-Deprecated_Language_Features__button"><A href="?showone=Deprecated_Language_Features#Deprecated_Language_Features">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Deprecated_Language_Features')" name="Deprecated_Language_Features__button" id="Deprecated_Language_Features__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Use string methods instead of the <code>string</code> module
+ where possible. Use function call syntax instead
+ of <code>apply</code>. Use list comprehensions
+ and <code>for</code> loops instead of <code>filter</code> and
+ <code>map</code> when the function argument would have been an
+ inlined lambda anyway. Use <code>for</code> loops instead of
+ <code>reduce</code>.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Deprecated_Language_Features__body" id="Deprecated_Language_Features__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN>
+ Current versions of Python provide alternative constructs
+ that people find generally preferable.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN>
+ We do not use any Python version which does not support
+ these features, so there is no reason not to use the new
+ styles.
+<DIV class=""><PRE>Yes: <span class="external"></span>words = foo.split(':')
+
+ <span class="external"></span>[x[1] for x in my_list if x[2] == 5]
+
+ <span class="external"></span>map(math.sqrt, data) # Ok. No inlined lambda expression.
+
+ <span class="external"></span>fn(*args, **kwargs)</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>words = string.split(foo, ':')
+
+ <span class="external"></span>map(lambda x: x[1], filter(lambda x: x[2] == 5, my_list))
+
+ <span class="external"></span>apply(fn, args, kwargs)</PRE></DIV>
+ </P>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Lexical_Scoping" id="Lexical_Scoping">Lexical Scoping</A></H3>
+<SPAN class="link_button" id="link-Lexical_Scoping__button" name="link-Lexical_Scoping__button"><A href="?showone=Lexical_Scoping#Lexical_Scoping">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Lexical_Scoping')" name="Lexical_Scoping__button" id="Lexical_Scoping__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Okay to use.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Lexical_Scoping__body" id="Lexical_Scoping__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN>
+ A nested Python function can refer to variables defined in
+ enclosing functions, but can not assign to them. Variable
+ bindings are resolved using lexical scoping, that is, based on
+ the static program text. Any assignment to a name in a block
+ will cause Python to treat all references to that name as a
+ local variable, even if the use precedes the assignment. If a
+ global declaration occurs, the name is treated as a global
+ variable.
+
+ <p>
+ An example of the use of this feature is:
+ </p>
+
+ <DIV class=""><PRE>
+<span class="external"></span>def get_adder(summand1):
+ <span class="external"> </span>"""Returns a function that adds numbers to a given number."""
+ <span class="external"> </span>def adder(summand2):
+ <span class="external"> </span>return summand1 + summand2
+
+ <span class="external"> </span>return adder
+<span class="external"></span>
+</PRE></DIV>
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN>
+ Often results in clearer, more elegant code. Especially comforting
+ to experienced Lisp and Scheme (and Haskell and ML and …)
+ programmers.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN>
+ Can lead to confusing bugs. Such as this example based on
+ <a HREF="https://www.python.org/dev/peps/pep-0227/">PEP-0227</a>:
+<DIV class=""><PRE class="badcode">
+<span class="external"></span>i = 4
+<span class="external"></span>def foo(x):
+ <span class="external"> </span>def bar():
+ <span class="external"> </span>print i,
+ <span class="external"> </span># ...
+ <span class="external"> </span># A bunch of code here
+ <span class="external"> </span># ...
+ <span class="external"> </span>for i in x: # Ah, i *is* local to Foo, so this is what Bar sees
+ <span class="external"> </span>print i,
+ <span class="external"> </span>bar()</PRE></DIV>
+ <p>
+ So <code>foo([1, 2, 3])</code> will print <code>1 2 3 3</code>, not
+ <code>1 2 3 4</code>.
+ </p>
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN>
+ Okay to use.
+ </P>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Function_and_Method_Decorators" id="Function_and_Method_Decorators">Function and Method Decorators</A></H3>
+<SPAN class="link_button" id="link-Function_and_Method_Decorators__button" name="link-Function_and_Method_Decorators__button"><A href="?showone=Function_and_Method_Decorators#Function_and_Method_Decorators">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Function_and_Method_Decorators')" name="Function_and_Method_Decorators__button" id="Function_and_Method_Decorators__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Use decorators judiciously when there is a clear advantage.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Function_and_Method_Decorators__body" id="Function_and_Method_Decorators__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN>
+
+ <a HREF="https://www.python.org/dev/peps/pep-0318">Decorators
+ for Functions and Methods</a>
+ (a.k.a "the <code>@</code> notation").
+ The most common decorators are <code>@classmethod</code> and
+ <code>@staticmethod</code>, for converting ordinary methods to class or
+ static methods. However, the decorator syntax allows for
+ user-defined decorators as well. Specifically, for some function
+ <code>my_decorator</code>, this:
+ <DIV class=""><PRE>
+<span class="external"></span>class C(object):
+ <span class="external"> </span>@my_decorator
+ <span class="external"> </span>def method(self):
+ <span class="external"> </span># method body ...
+<span class="external"></span>
+</PRE></DIV>
+
+ is equivalent to:
+ <DIV class=""><PRE>
+<span class="external"></span>class C(object):
+ <span class="external"> </span>def method(self):
+ <span class="external"> </span># method body ...
+ <span class="external"> </span>method = my_decorator(method)
+<span class="external"></span>
+</PRE></DIV>
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN> Elegantly specifies some transformation on a method; the
+ transformation might eliminate some repetitive code, enforce invariants,
+ etc.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN> Decorators can perform arbitrary operations on a
+ function's arguments or return values, resulting in surprising
+ implicit behavior.
+ Additionally, decorators execute at import time. Failures in decorator
+ code are pretty much impossible to recover from.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN> Use decorators judiciously when there is a clear
+ advantage. Decorators should follow the same import and naming
+ guidelines as functions. Decorator pydoc should clearly state that the
+ function is a decorator. Write unit tests for decorators.
+
+ <p>
+ Avoid external dependencies in the decorator itself (e.g. don't rely on
+ files, sockets, database connections, etc.), since they might not be
+ available when the decorator runs (at import time, perhaps from
+ <code>pydoc</code> or other tools). A decorator that is
+ called with valid parameters should (as much as possible) be guaranteed
+ to succeed in all cases.
+ </p>
+ <p>
+ Decorators are a special case of "top level code" - see
+ <a HREF="#Main">main</a> for more discussion.
+ </p>
+ </P>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Threading" id="Threading">Threading</A></H3>
+<SPAN class="link_button" id="link-Threading__button" name="link-Threading__button"><A href="?showone=Threading#Threading">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Threading')" name="Threading__button" id="Threading__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Do not rely on the atomicity of built-in types.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Threading__body" id="Threading__body" style="display: none">
+ <p>
+ While Python's built-in data types such as dictionaries appear
+ to have atomic operations, there are corner cases where they
+ aren't atomic (e.g. if <code>__hash__</code> or
+ <code>__eq__</code> are implemented as Python methods) and their
+ atomicity should not be relied upon. Neither should you rely on
+ atomic variable assignment (since this in turn depends on
+ dictionaries).
+ </p>
+
+ <p>
+ Use the Queue module's <code>Queue</code> data type as the preferred
+ way to
+ communicate data between threads. Otherwise, use the threading
+ module and its locking primitives. Learn about the proper use
+ of condition variables so you can use
+ <code>threading.Condition</code> instead of using lower-level
+ locks.
+ </p>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Power_Features" id="Power_Features">Power Features</A></H3>
+<SPAN class="link_button" id="link-Power_Features__button" name="link-Power_Features__button"><A href="?showone=Power_Features#Power_Features">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Power_Features')" name="Power_Features__button" id="Power_Features__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Avoid these features.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Power_Features__body" id="Power_Features__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_section">Definition: </SPAN> Python is an extremely flexible language and
+ gives you many fancy features such as metaclasses, access to bytecode,
+ on-the-fly compilation, dynamic inheritance, object reparenting,
+ import hacks, reflection, modification of system internals,
+ etc.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Pros: </SPAN> These are powerful language features. They can
+ make your code more compact.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Cons: </SPAN> It's very tempting to use these "cool" features
+ when they're not absolutely necessary. It's harder to read,
+ understand, and debug code that's using unusual features
+ underneath. It doesn't seem that way at first (to the original
+ author), but when revisiting the code, it tends to be more
+ difficult than code that is longer but is straightforward.
+ </P>
+ <P class="">
+<SPAN class="stylepoint_section">Decision: </SPAN>
+ Avoid these features in
+ your code.
+ </P>
+ </DIV></DIV>
+ </DIV>
+ </DIV>
+ <DIV class="">
+<H2 name="Python_Style_Rules" id="Python_Style_Rules">Python Style Rules</H2>
+ <DIV class="">
+<H3><A name="Semicolons" id="Semicolons">Semicolons</A></H3>
+<SPAN class="link_button" id="link-Semicolons__button" name="link-Semicolons__button"><A href="?showone=Semicolons#Semicolons">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Semicolons')" name="Semicolons__button" id="Semicolons__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Do not terminate your lines with semi-colons and do not use
+ semi-colons to put two commands on the same line.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Semicolons__body" id="Semicolons__body" style="display: none">
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Line_length" id="Line_length">Line length</A></H3>
+<SPAN class="link_button" id="link-Line_length__button" name="link-Line_length__button"><A href="?showone=Line_length#Line_length">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Line_length')" name="Line_length__button" id="Line_length__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Maximum line length is <em>80 characters</em>.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Line_length__body" id="Line_length__body" style="display: none">
+ <p>
+ Exceptions:
+ <ul>
+ <li>Long import statements.</li>
+ <li>URLs in comments.</li>
+
+ </ul>
+ </p>
+
+ <p>
+ Do not use backslash line continuation.
+ </p>
+
+ <p>
+ Make use of Python's
+
+ <a HREF="https://docs.python.org/reference/lexical_analysis.html#implicit-line-joining">implicit
+ line joining inside parentheses, brackets and braces</a>.
+ If necessary, you can add an extra pair of parentheses around an
+ expression.
+ </p>
+
+
+ <DIV class=""><PRE>Yes: foo_bar(self, width, height, color='black', design=None, x='foo',
+ emphasis=None, highlight=0)
+
+ if (width == 0 and height == 0 and
+ color == 'red' and emphasis == 'strong'):</PRE></DIV>
+
+
+ <p>
+ When a literal string won't fit on a single line, use parentheses for
+ implicit line joining.
+ </p>
+
+ <DIV class=""><PRE>
+<span class="external"></span>x = ('This will build a very long long '
+<span class="external"></span> 'long long long long long long string')</PRE></DIV>
+
+ <p>
+ Within comments, put long URLs on their own line if necessary.
+ </p>
+
+ <DIV class=""><PRE>Yes: <span class="external"></span># See details at
+ <span class="external"></span># https://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html</PRE></DIV>
+
+ <DIV class=""><PRE class="badcode">No: <span class="external"></span># See details at
+ <span class="external"></span># https://www.example.com/us/developer/documentation/api/content/\
+ <span class="external"></span># v2.0/csv_file_name_extension_full_specification.html</PRE></DIV>
+
+ <p>
+ Make note of the indentation of the elements in the line
+ continuation examples above; see the
+ <a HREF="#Indentation">indentation</a>
+ section for explanation.
+ </p>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Parentheses" id="Parentheses">Parentheses</A></H3>
+<SPAN class="link_button" id="link-Parentheses__button" name="link-Parentheses__button"><A href="?showone=Parentheses#Parentheses">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Parentheses')" name="Parentheses__button" id="Parentheses__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Use parentheses sparingly.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Parentheses__body" id="Parentheses__body" style="display: none">
+ <p>
+ Do not use them in return statements or conditional statements unless
+ using parentheses for implied line continuation. (See above.)
+ It is however fine to use parentheses around tuples.
+ </p>
+
+<DIV class=""><PRE>Yes: <span class="external"></span>if foo:
+ <span class="external"> </span>bar()
+ <span class="external"></span>while x:
+ <span class="external"> </span>x = bar()
+ <span class="external"></span>if x and y:
+ <span class="external"> </span>bar()
+ <span class="external"></span>if not x:
+ <span class="external"> </span>bar()
+ <span class="external"></span>return foo
+ <span class="external"></span>for (x, y) in dict.items(): ...</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>if (x):
+ <span class="external"> </span>bar()
+ <span class="external"></span>if not(x):
+ <span class="external"> </span>bar()
+ <span class="external"></span>return (foo)</PRE></DIV>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Indentation" id="Indentation">Indentation</A></H3>
+<SPAN class="link_button" id="link-Indentation__button" name="link-Indentation__button"><A href="?showone=Indentation#Indentation">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Indentation')" name="Indentation__button" id="Indentation__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Indent your code blocks with <em>4 spaces</em>.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Indentation__body" id="Indentation__body" style="display: none">
+ <p>
+ Never use tabs or mix tabs and spaces.
+ In cases of implied line continuation, you should align wrapped elements
+ either vertically, as per the examples in the
+ <a HREF="#Line_length">line length</a> section; or using a hanging
+ indent of 4 spaces, in which case there should be no argument on
+ the first line.
+ </p>
+
+
+<DIV class=""><PRE>Yes: # Aligned with opening delimiter
+ foo = long_function_name(var_one, var_two,
+ var_three, var_four)
+
+ # Aligned with opening delimiter in a dictionary
+ foo = {
+ long_dictionary_key: value1 +
+ value2,
+ ...
+ }
+
+ # 4-space hanging indent; nothing on first line
+ foo = long_function_name(
+ var_one, var_two, var_three,
+ var_four)
+
+ # 4-space hanging indent in a dictionary
+ foo = {
+ long_dictionary_key:
+ long_dictionary_value,
+ ...
+ }</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span># Stuff on first line forbidden
+ <span class="external"></span>foo = long_function_name(var_one, var_two,
+ <span class="external"></span> var_three, var_four)
+
+ <span class="external"></span># 2-space hanging indent forbidden
+ <span class="external"></span>foo = long_function_name(
+ <span class="external"></span> var_one, var_two, var_three,
+ <span class="external"></span> var_four)
+
+ <span class="external"></span># No hanging indent in a dictionary
+ <span class="external"></span>foo = {
+ <span class="external"></span> long_dictionary_key:
+ <span class="external"> </span>long_dictionary_value,
+ <span class="external"> </span>...
+ <span class="external"></span>}</PRE></DIV>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Blank_Lines" id="Blank_Lines">Blank Lines</A></H3>
+<SPAN class="link_button" id="link-Blank_Lines__button" name="link-Blank_Lines__button"><A href="?showone=Blank_Lines#Blank_Lines">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Blank_Lines')" name="Blank_Lines__button" id="Blank_Lines__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Two blank lines between top-level definitions, one blank line
+ between method definitions.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Blank_Lines__body" id="Blank_Lines__body" style="display: none">
+ <p>
+ Two blank lines between top-level definitions, be they function
+ or class definitions. One blank line between method definitions
+ and between the <code>class</code> line and the first method.
+ Use single blank lines as you judge appropriate within functions or
+ methods.
+ </p>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Whitespace" id="Whitespace">Whitespace</A></H3>
+<SPAN class="link_button" id="link-Whitespace__button" name="link-Whitespace__button"><A href="?showone=Whitespace#Whitespace">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Whitespace')" name="Whitespace__button" id="Whitespace__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Follow standard typographic rules for the use of spaces around
+ punctuation.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Whitespace__body" id="Whitespace__body" style="display: none">
+ <p>
+ No whitespace inside parentheses, brackets or braces.
+ </p>
+<DIV class=""><PRE>Yes: <span class="external"></span>spam(ham[1], {eggs: 2}, [])</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>spam( ham[ 1 ], { eggs: 2 }, [ ] )</PRE></DIV>
+ <p>
+ No whitespace before a comma, semicolon, or colon. Do use
+ whitespace after a comma, semicolon, or colon except at the end
+ of the line.
+ </p>
+<DIV class=""><PRE>Yes: <span class="external"></span>if x == 4:
+ <span class="external"> </span>print x, y
+ <span class="external"></span>x, y = y, x</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>if x == 4 :
+ <span class="external"> </span>print x , y
+ <span class="external"></span>x , y = y , x</PRE></DIV>
+ <p>
+ No whitespace before the open paren/bracket that starts an argument list,
+ indexing or slicing.
+ </p>
+ <DIV class=""><PRE>Yes: <span class="external"></span>spam(1)</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>spam (1)</PRE></DIV>
+<DIV class=""><PRE>Yes: <span class="external"></span>dict['key'] = list[index]</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>dict ['key'] = list [index]</PRE></DIV>
+
+ <p>
+ Surround binary operators with a single space on either side for
+ assignment (<code>=</code>), comparisons (<code>==, <, >, !=,
+ <>, <=, >=, in, not in, is, is not</code>), and Booleans
+ (<code>and, or, not</code>). Use your better judgment for the
+ insertion of spaces around arithmetic operators but always be
+ consistent about whitespace on either side of a binary operator.
+ </p>
+<DIV class=""><PRE>Yes: <span class="external"></span>x == 1</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>x<1</PRE></DIV>
+ <p>
+ Don't use spaces around the '=' sign when used to indicate a
+ keyword argument or a default parameter value.
+ </p>
+<DIV class=""><PRE>Yes: <span class="external"></span>def complex(real, imag=0.0): return magic(r=real, i=imag)</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>def complex(real, imag = 0.0): return magic(r = real, i = imag)</PRE></DIV>
+
+ <p>
+ Don't use spaces to vertically align tokens on consecutive lines, since it
+ becomes a maintenance burden (applies to <code>:</code>, <code>#</code>,
+ <code>=</code>, etc.):
+ </p>
+<DIV class=""><PRE>Yes:
+ foo = 1000 # comment
+ long_name = 2 # comment that should not be aligned
+
+ dictionary = {
+ 'foo': 1,
+ 'long_name': 2,
+ }</PRE></DIV>
+<DIV class=""><PRE class="badcode">No:
+ foo = 1000 # comment
+ long_name = 2 # comment that should not be aligned
+
+ dictionary = {
+ 'foo' : 1,
+ 'long_name': 2,
+ }</PRE></DIV>
+
+
+ </DIV></DIV>
+ </DIV>
+
+ <a name="Python_Interpreter"></a>
+ <DIV class="">
+<H3><A name="Shebang_Line" id="Shebang_Line">Shebang Line</A></H3>
+<SPAN class="link_button" id="link-Shebang_Line__button" name="link-Shebang_Line__button"><A href="?showone=Shebang_Line#Shebang_Line">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Shebang_Line')" name="Shebang_Line__button" id="Shebang_Line__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Most <code>.py</code> files do not need to start with a
+ <code>#!</code> line. Start the main file of a
+ program with
+ <code>#!/usr/bin/env python</code> with an optional single digit
+ <code>2</code> or <code>3</code> suffix.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Shebang_Line__body" id="Shebang_Line__body" style="display: none">
+
+ <p>
+ This line is used by the kernel to find the Python interpreter, but is
+ ignored by Python when importing modules. It is only necessary on a
+ file that will be executed directly.
+ </p>
+ </DIV></DIV>
+ </DIV>
+
+ <DIV class="">
+<H3><A name="Comments" id="Comments">Comments</A></H3>
+<SPAN class="link_button" id="link-Comments__button" name="link-Comments__button"><A href="?showone=Comments#Comments">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Comments')" name="Comments__button" id="Comments__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Be sure to use the right style for module, function, method and in-line
+ comments.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Comments__body" id="Comments__body" style="display: none">
+
+ <P class="">
+<SPAN class="stylepoint_subsection">Doc Strings</SPAN>
+
+ <p>
+ Python has a unique commenting style using doc strings. A doc
+ string is a string that is the first statement in a package,
+ module, class or function. These strings can be extracted
+ automatically through the <code>__doc__</code> member of the
+ object and are used by <code>pydoc</code>. (Try running
+ <code>pydoc</code> on your module to see how it looks.) We
+ always use the three double-quote <code>"""</code> format for doc strings
+ (per <a href="https://www.python.org/dev/peps/pep-0257/">PEP 257</a>).
+ A doc string should be organized as a
+ summary line (one physical line) terminated by a period,
+ question mark, or exclamation point, followed by a blank line,
+ followed by the rest of the doc string starting at the same
+ cursor position as the first quote of the first line. There are
+ more formatting guidelines for doc strings below.
+ </p>
+
+ </P>
+ <P class="">
+<SPAN class="stylepoint_subsection">Modules</SPAN>
+
+
+
+ <p>
+ Every file should contain license boilerplate.
+ Choose the appropriate boilerplate for the license used by the project
+ (for example, Apache 2.0, BSD, LGPL, GPL)
+ </p>
+ </P>
+ <P class="">
+<SPAN class="stylepoint_subsection">Functions and Methods</SPAN>
+
+ <p>
+ As used in this section "function" applies to methods, function, and
+ generators.
+ </p>
+
+ <p>
+ A function must have a docstring, unless it meets all of the following
+ criteria:
+ <ul>
+ <li>not externally visible</li>
+ <li>very short</li>
+ <li>obvious</li>
+ </ul>
+ </p>
+
+ <p>
+ A docstring should give enough information to write a call to the function
+ without reading the function's code. A docstring should describe the
+ function's calling syntax and its semantics, not its implementation. For
+ tricky code, comments alongside the code are more appropriate than using
+ docstrings.
+ </p>
+
+ <p>
+ Certain aspects of a function should be documented in special sections,
+ listed below. Each section begins with a heading line, which ends with a
+ colon. Sections should be indented two spaces, except for the heading.
+ </p>
+
+ <dl>
+ <dt>Args:</dt>
+ <dd>
+ List each parameter by name. A description should follow the name, and
+ be separated by a colon and a space. If the description is too long to
+ fit on a single 80-character line, use a hanging indent of 2 or 4 spaces
+ (be consistent with the rest of the file).
+
+ <p>
+ The description should mention required type(s) and the meaning of
+ the argument.
+ </p>
+
+ <p>
+ If a function accepts *foo (variable length argument lists) and/or
+ **bar (arbitrary keyword arguments), they should be listed as *foo and
+ **bar.
+ </p>
+ </dd>
+
+ <dt>Returns: (or Yields: for generators)</dt>
+ <dd>
+ Describe the type and semantics of the return value. If the function
+ only returns None, this section is not required.
+ </dd>
+
+ <dt>Raises:</dt>
+ <dd>
+ List all exceptions that are relevant to the interface.
+ </dd>
+ </dl>
+
+ <DIV class=""><PRE>
+<span class="external"></span>def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
+ <span class="external"> </span>"""Fetches rows from a Bigtable.
+
+ <span class="external"> </span>Retrieves rows pertaining to the given keys from the Table instance
+ <span class="external"> </span>represented by big_table. Silly things may happen if
+ <span class="external"> </span>other_silly_variable is not None.
+
+ <span class="external"> </span>Args:
+ <span class="external"> </span>big_table: An open Bigtable Table instance.
+ <span class="external"> </span>keys: A sequence of strings representing the key of each table row
+ <span class="external"> </span> to fetch.
+ <span class="external"> </span>other_silly_variable: Another optional variable, that has a much
+ <span class="external"> </span> longer name than the other args, and which does nothing.
+
+ <span class="external"> </span>Returns:
+ <span class="external"> </span>A dict mapping keys to the corresponding table row data
+ <span class="external"> </span>fetched. Each row is represented as a tuple of strings. For
+ <span class="external"> </span>example:
+
+ <span class="external"> </span>{'Serak': ('Rigel VII', 'Preparer'),
+ <span class="external"> </span> 'Zim': ('Irk', 'Invader'),
+ <span class="external"> </span> 'Lrrr': ('Omicron Persei 8', 'Emperor')}
+
+ <span class="external"> </span>If a key from the keys argument is missing from the dictionary,
+ <span class="external"> </span>then that row was not found in the table.
+
+ <span class="external"> </span>Raises:
+ <span class="external"> </span>IOError: An error occurred accessing the bigtable.Table object.
+ <span class="external"> </span>"""
+ <span class="external"> </span>pass
+<span class="external"></span>
+</PRE></DIV>
+ </P>
+ <P class="">
+<SPAN class="stylepoint_subsection">Classes</SPAN>
+
+ <p>
+ Classes should have a doc string below the class definition describing
+ the class. If your class has public attributes, they should be documented
+ here in an Attributes section and follow the same formatting as a
+ function's Args section.
+ </p>
+
+ <DIV class=""><PRE>
+<span class="external"></span>class SampleClass(object):
+ <span class="external"> </span>"""Summary of class here.
+
+ <span class="external"> </span>Longer class information....
+ <span class="external"> </span>Longer class information....
+
+ <span class="external"> </span>Attributes:
+ <span class="external"> </span>likes_spam: A boolean indicating if we like SPAM or not.
+ <span class="external"> </span>eggs: An integer count of the eggs we have laid.
+ <span class="external"> </span>"""
+
+ <span class="external"> </span>def __init__(self, likes_spam=False):
+ <span class="external"> </span>"""Inits SampleClass with blah."""
+ <span class="external"> </span>self.likes_spam = likes_spam
+ <span class="external"> </span>self.eggs = 0
+
+ <span class="external"> </span>def public_method(self):
+ <span class="external"> </span>"""Performs operation blah."""
+<span class="external"></span>
+</PRE></DIV>
+
+ </P>
+ <P class="">
+<SPAN class="stylepoint_subsection">Block and Inline Comments</SPAN>
+
+ <p>
+ The final place to have comments is in tricky parts of the
+ code. If you're going to have to explain it at the next
+ <a HREF="https://en.wikipedia.org/wiki/Code_review">code review</a>,
+ you should comment it now. Complicated operations get a few lines of
+ comments before the operations
+ commence. Non-obvious ones get comments at the end of the line.
+ </p>
+
+ <DIV class=""><PRE>
+<span class="external"></span># We use a weighted dictionary search to find out where i is in
+<span class="external"></span># the array. We extrapolate position based on the largest num
+<span class="external"></span># in the array and the array size and then do binary search to
+<span class="external"></span># get the exact number.
+
+<span class="external"></span>if i & (i-1) == 0: # true iff i is a power of 2
+<span class="external"></span>
+</PRE></DIV>
+
+ <p>
+ To improve legibility, these comments should be at least 2 spaces away
+ from the code.
+ </p>
+
+ <p>
+ On the other hand, never describe the code. Assume the person
+ reading the code knows Python (though not what you're trying to
+ do) better than you do.
+ </p>
+
+ <DIV class=""><PRE class="badcode">
+<span class="external"></span># BAD COMMENT: Now go through the b array and make sure whenever i occurs
+<span class="external"></span># the next element is i+1
+<span class="external"></span>
+</PRE></DIV>
+
+ </P>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Classes" id="Classes">Classes</A></H3>
+<SPAN class="link_button" id="link-Classes__button" name="link-Classes__button"><A href="?showone=Classes#Classes">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Classes')" name="Classes__button" id="Classes__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ If a class inherits from no other base classes, explicitly inherit
+ from <code>object</code>. This also applies to nested classes.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Classes__body" id="Classes__body" style="display: none">
+ <DIV class=""><PRE>Yes: <span class="external"></span>class SampleClass(object):
+ <span class="external"> </span>pass
+
+
+ <span class="external"></span>class OuterClass(object):
+
+ <span class="external"> </span>class InnerClass(object):
+ <span class="external"> </span>pass
+
+
+ <span class="external"></span>class ChildClass(ParentClass):
+ <span class="external"> </span>"""Explicitly inherits from another class already."""
+<span class="external"></span>
+</PRE></DIV>
+ <DIV class=""><PRE class="badcode">No: <span class="external"></span>class SampleClass:
+ <span class="external"> </span>pass
+
+
+ <span class="external"></span>class OuterClass:
+
+ <span class="external"> </span>class InnerClass:
+ <span class="external"> </span>pass
+<span class="external"></span>
+</PRE></DIV>
+ <p>Inheriting from <code>object</code> is needed to make properties work
+ properly, and it will protect your code from one particular potential
+ incompatibility with Python 3000. It also defines
+ special methods that implement the default semantics of objects including
+ <code>__new__</code>, <code>__init__</code>, <code>__delattr__</code>,
+ <code>__getattribute__</code>, <code>__setattr__</code>,
+ <code>__hash__</code>, <code>__repr__</code>, and <code>__str__</code>.
+ </p>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Strings" id="Strings">Strings</A></H3>
+<SPAN class="link_button" id="link-Strings__button" name="link-Strings__button"><A href="?showone=Strings#Strings">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Strings')" name="Strings__button" id="Strings__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Use the <code>format</code> method or the <code>%</code> operator for
+ formatting strings, even when the parameters are all strings. Use your
+ best judgement to decide between <code>+</code> and <code>%</code>
+ (or <code>format</code>) though.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Strings__body" id="Strings__body" style="display: none">
+
+<DIV class=""><PRE>Yes: <span class="external"></span>x = a + b
+ <span class="external"></span>x = '%s, %s!' % (imperative, expletive)
+ <span class="external"></span>x = '{}, {}!'.format(imperative, expletive)
+ <span class="external"></span>x = 'name: %s; score: %d' % (name, n)
+ <span class="external"></span>x = 'name: {}; score: {}'.format(name, n)</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>x = '%s%s' % (a, b) # use + in this case
+ <span class="external"></span>x = '{}{}'.format(a, b) # use + in this case
+ <span class="external"></span>x = imperative + ', ' + expletive + '!'
+ <span class="external"></span>x = 'name: ' + name + '; score: ' + str(n)</PRE></DIV>
+
+ <p>
+ Avoid using the <code>+</code> and <code>+=</code> operators to
+ accumulate a string within a loop. Since strings are immutable, this
+ creates unnecessary temporary objects and results in quadratic rather
+ than linear running time. Instead, add each substring to a list
+ and <code>''.join</code> the list after the loop terminates (or, write
+ each substring to a <code>io.BytesIO</code> buffer).
+ </p>
+
+<DIV class=""><PRE>Yes: <span class="external"></span>items = ['<table>']
+ <span class="external"></span>for last_name, first_name in employee_list:
+ <span class="external"> </span>items.append('<tr><td>%s, %s</td></tr>' % (last_name, first_name))
+ <span class="external"></span>items.append('</table>')
+ <span class="external"></span>employee_table = ''.join(items)</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>employee_table = '<table>'
+ <span class="external"></span>for last_name, first_name in employee_list:
+ <span class="external"> </span>employee_table += '<tr><td>%s, %s</td></tr>' % (last_name, first_name)
+ <span class="external"></span>employee_table += '</table>'</PRE></DIV>
+
+ <p>
+ Be consistent with your choice of string quote character within a file.
+ Pick <code>'</code> or <code>"</code> and stick with it.
+ It is okay to use the other quote character on a string to avoid the
+ need to <code>\</code> escape within the string.
+ GPyLint enforces this.
+ </p>
+
+<DIV class=""><PRE>Ye<span class="external"></span>s:
+ <span class="external"></span>Python('Why are you hiding your eyes?')
+ <span class="external"></span>Gollum("I'm scared of lint errors.")
+ <span class="external"></span>Narrator('"Good!" thought a happy Python reviewer.')</PRE></DIV>
+<DIV class=""><PRE class="badcode">No<span class="external"></span>:
+ <span class="external"></span>Python("Why are you hiding your eyes?")
+ <span class="external"></span>Gollum('The lint. It burns. It burns us.')
+ <span class="external"></span>Gollum("Always the great lint. Watching. Watching.")</PRE></DIV>
+
+ <p>
+ Prefer <code>"""</code> for multi-line strings rather than
+ <code>'''</code>. Projects may choose to use <code>'''</code> for
+ all non-docstring multi-line strings if and only if they also use
+ <code>'</code> for regular strings.
+ Doc strings must use <code>"""</code> regardless.
+ Note that it is often cleaner to
+ use implicit line joining since multi-line strings do
+ not flow with the indentation of the rest of the program:
+ </p>
+
+<DIV class=""><PRE>Ye<span class="external"></span>s:
+ <span class="external"></span>print ("This is much nicer.\n"
+ <span class="external"></span> "Do it this way.\n")</PRE></DIV>
+<DIV class=""><PRE class="badcode"> No<span class="external"></span>:
+ <span class="external"></span>print """This is pretty ugly.
+Don'<span class="external"></span>t do this.
+"""<span class="external"></span>
+</PRE></DIV>
+
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Files_and_Sockets" id="Files_and_Sockets">Files and Sockets</A></H3>
+<SPAN class="link_button" id="link-Files_and_Sockets__button" name="link-Files_and_Sockets__button"><A href="?showone=Files_and_Sockets#Files_and_Sockets">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Files_and_Sockets')" name="Files_and_Sockets__button" id="Files_and_Sockets__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Explicitly close files and sockets when done with them.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Files_and_Sockets__body" id="Files_and_Sockets__body" style="display: none">
+ <p>
+ Leaving files, sockets or other file-like objects open unnecessarily
+ has many downsides, including:
+
+ <ul>
+ <li>They may consume limited system resources, such as file
+ descriptors. Code that deals with many such objects may exhaust
+ those resources unnecessarily if they're not returned to the
+ system promptly after use.</li>
+ <li>Holding files open may prevent other actions being performed on
+ them, such as moves or deletion.</li>
+ <li>Files and sockets that are shared throughout a program may
+ inadvertantly be read from or written to after logically being
+ closed. If they are actually closed, attempts to read or write
+ from them will throw exceptions, making the problem known
+ sooner.</li>
+ </ul>
+ </p>
+
+ <p>
+ Furthermore, while files and sockets are automatically closed when the
+ file object is destructed, tying the life-time of the file object to
+ the state of the file is poor practice, for several reasons:
+
+ <ul>
+ <li>There are no guarantees as to when the runtime will actually run
+ the file's destructor. Different Python implementations use
+ different memory management techniques, such as delayed Garbage
+ Collection, which may increase the object's lifetime arbitrarily
+ and indefinitely.</li>
+ <li>Unexpected references to the file may keep it around longer than
+ intended (e.g. in tracebacks of exceptions, inside globals,
+ etc).</li>
+ </ul>
+ </p>
+
+ <p>
+ The preferred way to manage files is using the <a HREF="https://docs.python.org/reference/compound_stmts.html#the-with-statement">
+ "with" statement</a>:
+ </p>
+
+<DIV class=""><PRE>
+<span class="external"></span>with open("hello.txt") as hello_file:
+ <span class="external"> </span>for line in hello_file:
+ <span class="external"> </span>print line</PRE></DIV>
+
+ <p>
+ For file-like objects that do not support the "with" statement, use
+ contextlib.closing():
+ </p>
+
+<DIV class=""><PRE>
+<span class="external"></span>import contextlib
+
+<span class="external"></span>with contextlib.closing(urllib.urlopen("https://www.python.org/")) as front_page:
+ <span class="external"> </span>for line in front_page:
+ <span class="external"> </span>print line</PRE></DIV>
+
+ <p>
+ Legacy AppEngine code using Python 2.5 may enable the "with" statement
+ using "from __future__ import with_statement".
+ </p>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="TODO_Comments" id="TODO_Comments">TODO Comments</A></H3>
+<SPAN class="link_button" id="link-TODO_Comments__button" name="link-TODO_Comments__button"><A href="?showone=TODO_Comments#TODO_Comments">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('TODO_Comments')" name="TODO_Comments__button" id="TODO_Comments__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Use <code>TODO</code> comments for code that is temporary, a
+ short-term solution, or good-enough but not perfect.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="TODO_Comments__body" id="TODO_Comments__body" style="display: none">
+ <p>
+ <code>TODO</code>s should include the string <code>TODO</code> in
+ all caps, followed by the
+
+ name, e-mail address, or other
+ identifier
+ of the person who can best provide context about the problem
+ referenced by the <code>TODO</code>,
+ in parentheses. A colon is optional. A comment explaining what there
+ is to do is required. The main purpose is to have
+ a consistent <code>TODO</code> format that can be searched to find the
+ person who can provide more details upon request. A
+ <code>TODO</code> is not a commitment that the person referenced
+ will fix the problem. Thus when you create a <code>TODO</code>, it is
+ almost always your
+
+ name
+ that is given.
+ </p>
+
+ <DIV class=""><PRE># TODO(kl@gmail.com): Use a "*" here for string repetition.
+# TODO(Zeke) Change this to use relations.</PRE></DIV>
+ <p>
+ If your <code>TODO</code> is of the form "At a future date do
+ something" make sure that you either include a very specific
+ date ("Fix by November 2009") or a very specific event
+ ("Remove this code when all clients can handle XML responses.").
+ </p>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Imports_formatting" id="Imports_formatting">Imports formatting</A></H3>
+<SPAN class="link_button" id="link-Imports_formatting__button" name="link-Imports_formatting__button"><A href="?showone=Imports_formatting#Imports_formatting">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Imports_formatting')" name="Imports_formatting__button" id="Imports_formatting__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Imports should be on separate lines.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Imports_formatting__body" id="Imports_formatting__body" style="display: none">
+ <p>
+ E.g.:
+ </p>
+
+<DIV class=""><PRE>Yes: <span class="external"></span>import os
+ <span class="external"></span>import sys</PRE></DIV>
+<DIV class=""><PRE class="badcode">No: <span class="external"></span>import os, sys</PRE></DIV>
+ <p>
+ Imports are always put at the top of the file, just after any
+ module comments and doc strings and before module globals and
+ constants. Imports should be grouped with the order being most generic
+ to least generic:
+ </p>
+ <ul>
+ <li>standard library imports</li>
+ <li>third-party imports</li>
+
+ <li>application-specific imports</li>
+ </ul>
+ <p>
+ Within each grouping, imports should be sorted lexicographically,
+ ignoring case, according to each module's full package path.
+ </p>
+ <DIV class=""><PRE>
+<span class="external"></span>import foo
+<span class="external"></span>from foo import bar
+<span class="external"></span>from foo.bar import baz
+<span class="external"></span>from foo.bar import Quux
+<span class="external"></span>from Foob import ar</PRE></DIV>
+
+
+
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Statements" id="Statements">Statements</A></H3>
+<SPAN class="link_button" id="link-Statements__button" name="link-Statements__button"><A href="?showone=Statements#Statements">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Statements')" name="Statements__button" id="Statements__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Generally only one statement per line.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Statements__body" id="Statements__body" style="display: none">
+ <p>
+ However, you may put the
+ result of a test on the same line as the test only if the entire
+ statement fits on one line. In particular, you can never do so
+ with <code>try</code>/<code>except</code> since the
+ <code>try</code> and <code>except</code> can't both fit on the
+ same line, and you can only do so with an <code>if</code> if
+ there is no <code>else</code>.
+ </p>
+
+ <DIV class=""><PRE>Ye<span class="external"></span>s:
+
+ <span class="external"></span>if foo: bar(foo)</PRE></DIV>
+<DIV class=""><PRE class="badcode">No<span class="external"></span>:
+
+ <span class="external"></span>if foo: bar(foo)
+ <span class="external"></span>else: baz(foo)
+
+ <span class="external"></span>try: bar(foo)
+ <span class="external"></span>except ValueError: baz(foo)
+
+ <span class="external"></span>try:
+ <span class="external"> </span>bar(foo)
+ <span class="external"></span>except ValueError: baz(foo)
+<span class="external"></span>
+</PRE></DIV>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Access_Control" id="Access_Control">Access Control</A></H3>
+<SPAN class="link_button" id="link-Access_Control__button" name="link-Access_Control__button"><A href="?showone=Access_Control#Access_Control">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Access_Control')" name="Access_Control__button" id="Access_Control__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ If an accessor function would be trivial you should use public variables
+ instead of accessor functions to avoid the extra cost of function
+ calls in Python. When more functionality is added you can use
+ <code>property</code> to keep the syntax consistent.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Access_Control__body" id="Access_Control__body" style="display: none">
+ <p>
+ On the other hand, if access is more complex, or the cost of accessing
+ the variable is significant, you should use function calls (following the
+ <a HREF="#naming">Naming</a> guidelines) such as <code>get_foo()</code>
+ and <code>set_foo()</code>. If the past behavior allowed access through a
+ property, do not bind the new accessor functions to the property. Any
+ code still attempting to access the variable by the old method should
+ break visibly so they are made aware of the change in complexity.
+ </p>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Naming" id="Naming">Naming</A></H3>
+<SPAN class="link_button" id="link-Naming__button" name="link-Naming__button"><A href="?showone=Naming#Naming">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Naming')" name="Naming__button" id="Naming__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ <code>module_name, package_name, ClassName,
+ method_name, ExceptionName,
+ function_name, GLOBAL_CONSTANT_NAME,
+ global_var_name, instance_var_name, function_parameter_name,
+ local_var_name.</code>
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Naming__body" id="Naming__body" style="display: none">
+ <P class="">
+<SPAN class="stylepoint_subsection">Names to Avoid</SPAN>
+
+ <ul>
+ <li>single character names except for counters or iterators</li>
+ <li>dashes (<code>-</code>) in any package/module name</li>
+ <li>
+<code>__double_leading_and_trailing_underscore__</code> names
+ (reserved by Python)</li>
+ </ul>
+
+ </P>
+ <P class="">
+<SPAN class="stylepoint_subsection">Naming Convention</SPAN>
+
+ <ul>
+ <li>
+ "Internal" means internal to a module or protected
+ or private within a class.</li>
+ <li>
+ Prepending a single underscore (<code>_</code>) has some
+ support for protecting module variables and functions (not included
+ with <code>import * from</code>). Prepending a double underscore
+ (<code>__</code>) to an instance variable or method
+ effectively serves to make the variable or method private to its class
+ (using name mangling).</li>
+ <li>
+ Place related classes and top-level functions together in a
+ module. Unlike Java,
+ there is no need to limit yourself to one class per module.</li>
+ <li>
+ Use CapWords for class names, but lower_with_under.py for module names.
+ Although there are many existing modules named CapWords.py, this is now
+ discouraged because it's confusing when the module happens to be
+ named after a class. ("wait -- did I write
+ <code>import StringIO</code> or <code>from StringIO import
+ StringIO</code>?")</li>
+ </ul>
+
+ </P>
+ <P class="">
+<SPAN class="stylepoint_subsection">Guidelines derived from Guido's Recommendations</SPAN>
+
+ <table rules="all" border="1" cellspacing="2" cellpadding="2">
+
+ <tr>
+ <th>Type</th>
+ <th>Public</th>
+ <th>Internal</th>
+ </tr>
+
+
+
+ <tr>
+ <td>Packages</td>
+ <td><code>lower_with_under</code></td>
+ <td></td>
+ </tr>
+
+ <tr>
+ <td>Modules</td>
+ <td><code>lower_with_under</code></td>
+ <td><code>_lower_with_under</code></td>
+ </tr>
+
+ <tr>
+ <td>Classes</td>
+ <td><code>CapWords</code></td>
+ <td><code>_CapWords</code></td>
+ </tr>
+
+ <tr>
+ <td>Exceptions</td>
+ <td><code>CapWords</code></td>
+ <td></td>
+ </tr>
+
+
+
+ <tr>
+ <td>Functions</td>
+ <td><code>lower_with_under()</code></td>
+ <td><code>_lower_with_under()</code></td>
+ </tr>
+
+ <tr>
+ <td>Global/Class Constants</td>
+ <td><code>CAPS_WITH_UNDER</code></td>
+ <td><code>_CAPS_WITH_UNDER</code></td>
+ </tr>
+
+ <tr>
+ <td>Global/Class Variables</td>
+ <td><code>lower_with_under</code></td>
+ <td><code>_lower_with_under</code></td>
+ </tr>
+
+ <tr>
+ <td>Instance Variables</td>
+ <td><code>lower_with_under</code></td>
+ <td><code>_lower_with_under (protected) or __lower_with_under (private)</code></td>
+ </tr>
+
+
+
+ <tr>
+ <td>Method Names</td>
+ <td><code>lower_with_under()</code></td>
+ <td><code>_lower_with_under() (protected) or __lower_with_under() (private)</code></td>
+ </tr>
+
+ <tr>
+ <td>Function/Method Parameters</td>
+ <td><code>lower_with_under</code></td>
+ <td></td>
+ </tr>
+
+ <tr>
+ <td>Local Variables</td>
+ <td><code>lower_with_under</code></td>
+ <td></td>
+ </tr>
+
+
+ </table>
+
+
+ </P>
+ </DIV></DIV>
+ </DIV>
+ <DIV class="">
+<H3><A name="Main" id="Main">Main</A></H3>
+<SPAN class="link_button" id="link-Main__button" name="link-Main__button"><A href="?showone=Main#Main">
+ link
+ </A></SPAN><SPAN class="showhide_button" onclick="javascript:ShowHideByName('Main')" name="Main__button" id="Main__button">▶</SPAN>
+ <DIV style="display:inline;" class="">
+ Even a file meant to be used as a script should be importable and a
+ mere import should not have the side effect of executing the script's
+ main functionality. The main functionality should be in a main()
+ function.
+ </DIV>
+ <DIV class=""><DIV class="stylepoint_body" name="Main__body" id="Main__body" style="display: none">
+ <p>
+ In Python,
+ <code>pydoc</code> as well as unit tests
+ require modules to be importable. Your code should always check
+ <code>if __name__ == '__main__'</code> before executing your
+ main program so that the main program is not executed when the
+ module is imported.
+
+ </p>
+
+
+
+
+
+
+
+ <DIV class=""><PRE>
+<span class="external"></span>def main():
+ <span class="external"> </span>...
+
+<span class="external"></span>if __name__ == '__main__':
+ <span class="external"> </span>main()
+<span class="external"></span>
+</PRE></DIV>
+
+ <p>
+ All code at the top level will be executed when the module is
+ imported. Be careful not to call functions, create objects, or
+ perform other operations that should not be executed when the
+ file is being <code>pydoc</code>ed.
+ </p>
+ </DIV></DIV>
+ </DIV>
+ </DIV>
+
+<H2>Parting Words</H2>
+ <p>
+ <em>BE CONSISTENT</em>.
+ </p>
+
+ <p>
+ If you're editing code, take a few minutes to look at the code
+ around you and determine its style. If they use spaces around
+ all their arithmetic operators, you should too. If their
+ comments have little boxes of hash marks around them, make your
+ comments have little boxes of hash marks around them too.
+ </p>
+
+ <p>
+ The point of having style guidelines is to have a common vocabulary
+ of coding so people can concentrate on what you're saying rather
+ than on how you're saying it. We present global style rules here so
+ people know the vocabulary, but local style is also important. If
+ code you add to a file looks drastically different from the existing
+ code around it, it throws readers out of their rhythm when they go to
+ read it. Avoid this.
+ </p>
+
+
+
+<p align="right">
+Revision 2.59
+</p>
+
+
+<address>
+ Amit Patel<br>
+ Antoine Picard<br>
+ Eugene Jhong<br>
+ Gregory P. Smith<br>
+ Jeremy Hylton<br>
+ Matt Smart<br>
+ Mike Shields<br>
+ Shane Liebling<br>
+</address>
+</BODY>
+</HTML>
diff --git a/shell.xml b/shell.xml
new file mode 100644
index 0000000..79f39f9
--- /dev/null
+++ b/shell.xml
@@ -0,0 +1,1152 @@
+<?xml version="1.0"?>
+<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
+<GUIDE title="Shell Style Guide">
+
+<p align="right">
+
+Revision 1.26
+</p>
+
+
+<address>
+ Paul Armstrong<br/>
+ Too many more to mention<br/>
+</address>
+
+<OVERVIEW>
+
+ <CATEGORY title="Background">
+
+
+
+ <STYLEPOINT title="Which Shell to Use">
+ <SUMMARY>
+ <code>Bash</code> is the only shell scripting language permitted for
+ executables.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Executables must start with <code>#!/bin/bash</code> and a minimum
+ number of flags. Use <code>set</code> to set shell options so that
+ calling your script as <code>bash <i><script_name></i></code>
+ does not break its functionality.
+ </p>
+ <p>
+ Restricting all executable shell scripts to <b>bash</b>
+ gives us a consistent shell language that's installed on all our
+ machines.
+ </p>
+ <p>
+ The only exception to this is where you're forced to by whatever
+ you're coding for. One example of this is Solaris SVR4 packages which
+ require plain Bourne shell for any scripts.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="When to use Shell">
+ <SUMMARY>
+ Shell should only be used for small utilities or simple wrapper
+ scripts.
+ </SUMMARY>
+ <BODY>
+ <p>
+ While shell scripting isn't a development language, it is used for
+ writing various utility scripts throughout Google. This
+ style guide is more a recognition of its use rather than
+ a suggestion that it be used for widespread deployment.
+ </p>
+ <p>
+ Some guidelines:
+ <ul>
+ <li>
+ If you're mostly calling other utilities and are doing relatively
+ little data manipulation, shell is an acceptable choice for the
+ task.
+ </li>
+ <li>
+ If performance matters, use something other than shell.
+ </li>
+ <li>
+ If you find you need to use arrays for anything more than
+ assignment of <code>${PIPESTATUS}</code>, you should use Python.
+ </li>
+ <li>
+ If you are writing a script that is more than 100 lines long, you
+ should probably be writing it in Python instead. Bear in mind
+ that scripts grow. Rewrite your script in another language
+ early to avoid a time-consuming rewrite at a later date.
+ </li>
+ </ul>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ </CATEGORY>
+
+</OVERVIEW>
+
+<CATEGORY title="Shell Files and Interpreter Invocation">
+
+ <STYLEPOINT title="File Extensions">
+ <SUMMARY>
+ Executables should have no extension (strongly preferred) or a
+ <code>.sh</code> extension.
+ Libraries must have a <code>.sh</code> extension and should not be
+ executable.
+ </SUMMARY>
+ <BODY>
+ <p>
+ It is not necessary to know what language a program is written in when
+ executing it and shell doesn't require an extension so we prefer not to
+ use one for executables.
+ </p>
+ <p>
+ However, for libraries it's important to know what language it is and
+ sometimes there's a need to have similar libraries in different
+ languages. This allows library files with identical purposes but
+ different languages to be identically named except for the
+ language-specific suffix.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="SUID/SGID">
+ <SUMMARY>
+ SUID and SGID are <em>forbidden</em> on shell scripts.
+ </SUMMARY>
+ <BODY>
+ <p>
+ There are too many security issues with shell that make it nearly
+ impossible to secure sufficiently to allow SUID/SGID. While bash does
+ make it difficult to run SUID, it's still possible on some platforms
+ which is why we're being explicit about banning it.
+ </p>
+ <p>
+ Use <code>sudo</code> to provide elevated access if you need it.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+</CATEGORY>
+
+<CATEGORY title="Environment">
+
+ <STYLEPOINT title="STDOUT vs STDERR">
+ <SUMMARY>
+ All error messages should go to <code>STDERR</code>.
+ </SUMMARY>
+ <BODY>
+ <p>
+ This makes it easier
+ to separate normal status from actual issues.
+ </p>
+ <p>
+ A function to print out error messages along with other status
+ information is recommended.
+ <CODE_SNIPPET>
+ err() {
+ echo "[$(date +'%Y-%m-%dT%H:%M:%S%z')]: $@" >&2
+ }
+
+ if ! do_something; then
+ err "Unable to do_something"
+ exit "${E_DID_NOTHING}"
+ fi
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+</CATEGORY>
+
+<CATEGORY title="Comments">
+
+ <STYLEPOINT title="File Header">
+ <SUMMARY>
+ Start each file with a description of its contents.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Every file must have a top-level comment including a brief overview of
+ its contents.
+ A
+ copyright notice
+ and author information are optional.
+ </p>
+ <p>
+ Example:
+ <CODE_SNIPPET>
+ #!/bin/bash
+ #
+ # Perform hot backups of Oracle databases.
+ </CODE_SNIPPET>
+ </p>
+
+
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Function Comments">
+ <SUMMARY>
+ Any function that is not both obvious and short must be commented. Any
+ function in a library must be commented regardless of length or
+ complexity.
+ </SUMMARY>
+ <BODY>
+ <p>
+ It should be possible for someone else to learn how to use your
+ program or to use a function in your library by reading the comments
+ (and self-help, if provided) without reading the code.
+ </p>
+ <p>
+ All function comments should contain:
+ <ul>
+ <li>
+ Description of the function
+ </li>
+ <li>
+ Global variables used and modified
+ </li>
+ <li>
+ Arguments taken
+ </li>
+ <li>
+ Returned values other than the default exit status of the last
+ command run
+ </li>
+ </ul>
+ </p>
+ <p>
+ Example:
+ <CODE_SNIPPET>
+ #!/bin/bash
+ #
+ # Perform hot backups of Oracle databases.
+
+ export PATH='/usr/xpg4/bin:/usr/bin:/opt/csw/bin:/opt/goog/bin'
+
+ #######################################
+ # Cleanup files from the backup dir
+ # Globals:
+ # BACKUP_DIR
+ # ORACLE_SID
+ # Arguments:
+ # None
+ # Returns:
+ # None
+ #######################################
+ cleanup() {
+ ...
+ }
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Implementation Comments">
+ <SUMMARY>
+ Comment tricky, non-obvious, interesting or important parts of your code.
+ </SUMMARY>
+ <BODY>
+ <p>
+ This follows general Google coding comment practice. Don't comment
+ everything. If there's a complex algorithm or you're doing something
+ out of the ordinary, put a short comment in.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="TODO Comments">
+ <SUMMARY>
+ Use TODO comments for code that is temporary, a short-term solution, or
+ good-enough but not perfect.
+ </SUMMARY>
+ <BODY>
+ <p>
+ This matches the convention in the <a href="cppguide.html?showone=TODO_Comments#TODO_Comments">C++
+ Guide</a>.
+ </p>
+ <p>
+ TODOs should include the string TODO in all caps, followed by your
+ username in parentheses. A colon is optional. It's preferable to put a
+ bug/ticket number next to the TODO item as well.
+ </p>
+ <p>
+ Examples:
+
+ <CODE_SNIPPET>
+ # TODO(mrmonkey): Handle the unlikely edge cases (bug ####)
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+</CATEGORY>
+
+<CATEGORY title="Formatting">
+ <p>
+ While you should follow the style that's already there for files that
+ you're modifying, the following are required for any new code.
+ </p>
+
+ <STYLEPOINT title="Indentation">
+ <SUMMARY>
+ Indent 2 spaces. No tabs.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Use blank lines between blocks to improve readability. Indentation is
+ two spaces. Whatever you do, don't use tabs. For existing files, stay
+ faithful to the existing indentation.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Line Length and Long Strings">
+ <SUMMARY>
+ Maximum line length is 80 characters.
+ </SUMMARY>
+ <BODY>
+ <p>
+ If you have to write strings that are longer than 80 characters, this
+ should be done with a here document or an embedded newline if possible.
+ Literal strings that have to be longer than 80 chars and can't sensibly
+ be split are ok, but it's strongly preferred to find a way to make it
+ shorter.
+ </p>
+ <p>
+ <CODE_SNIPPET>
+ # DO use 'here document's
+ cat <<END;
+ I am an exceptionally long
+ string.
+ END
+
+ # Embedded newlines are ok too
+ long_string="I am an exceptionally
+ long string."
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Pipelines">
+ <SUMMARY>
+ Pipelines should be split one per line if they don't all fit on one line.
+ </SUMMARY>
+ <BODY>
+ <p>
+ If a pipeline all fits on one line, it should be on one line.
+ </p>
+ <p>
+ If not, it should be split at one pipe segment per line with the pipe
+ on the newline and a 2 space indent for the next section of the pipe.
+ This applies to a chain of commands combined using '|' as well as to
+ logical compounds using '||' and '&&'.
+ <CODE_SNIPPET>
+ # All fits on one line
+ command1 | command2
+
+ # Long commands
+ command1 \
+ | command2 \
+ | command3 \
+ | command4
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Loops">
+ <SUMMARY>
+ Put <code>; do</code> and <code>; then</code> on the same line as the
+ <code>while</code>, <code>for</code> or <code>if</code>.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Loops in shell are a bit different, but we follow the same principles
+ as with braces when declaring functions. That is: <code>; then</code>
+ and <code>; do</code> should be on the same line as the if/for/while.
+ <code>else</code> should be on its own line and closing statements
+ should be on their own line vertically aligned with the opening
+ statement.
+ </p>
+ <p>
+ Example:
+ <CODE_SNIPPET>
+ for dir in ${dirs_to_cleanup}; do
+ if [[ -d "${dir}/${ORACLE_SID}" ]]; then
+ log_date "Cleaning up old files in ${dir}/${ORACLE_SID}"
+ rm "${dir}/${ORACLE_SID}/"*
+ if [[ "$?" -ne 0 ]]; then
+ error_message
+ fi
+ else
+ mkdir -p "${dir}/${ORACLE_SID}"
+ if [[ "$?" -ne 0 ]]; then
+ error_message
+ fi
+ fi
+ done
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Case statement">
+ <SUMMARY>
+ <ul>
+ <li>
+ Indent alternatives by 2 spaces.
+ </li>
+ <li>
+ A one-line alternative needs a space after the close parenthesis of
+ the pattern and before the <code>;;</code>.
+ </li>
+ <li>
+ Long or multi-command alternatives should be split over multiple
+ lines with the pattern, actions, and <code>;;</code> on separate
+ lines.
+ </li>
+ </ul>
+ </SUMMARY>
+ <BODY>
+ <p>
+ The matching expressions are indented one level from the 'case' and
+ 'esac'. Multiline actions are indented another level. In general,
+ there is no need to quote match expressions. Pattern expressions
+ should not be preceded by an open parenthesis. Avoid the
+ <code>;&</code> and <code>;;&</code> notations.
+ </p>
+ <CODE_SNIPPET>
+ case "${expression}" in
+ a)
+ variable="..."
+ some_command "${variable}" "${other_expr}" ...
+ ;;
+ absolute)
+ actions="relative"
+ another_command "${actions}" "${other_expr}" ...
+ ;;
+ *)
+ error "Unexpected expression '${expression}'"
+ ;;
+ esac
+ </CODE_SNIPPET>
+ <p>
+ Simple commands may be put on the same line as the pattern <i>and</i>
+ <code>;;</code> as long as the expression remains readable. This is
+ often appropriate for single-letter option processing. When the
+ actions don't fit on a single line, put the pattern on a line on its
+ own, then the actions, then <code>;;</code> also on a line of its own.
+ When on the same line as the actions, use a space after the close
+ parenthesis of the pattern and another before the <code>;;</code>.
+ </p>
+ <CODE_SNIPPET>
+ verbose='false'
+ aflag=''
+ bflag=''
+ files=''
+ while getopts 'abf:v' flag; do
+ case "${flag}" in
+ a) aflag='true' ;;
+ b) bflag='true' ;;
+ f) files="${OPTARG}" ;;
+ v) verbose='true' ;;
+ *) error "Unexpected option ${flag}" ;;
+ esac
+ done
+ </CODE_SNIPPET>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Variable expansion">
+ <SUMMARY>
+ In order of precedence: Stay consistent with what you find;
+ quote your variables;
+ prefer "${var}" over "$var", but see details.
+ </SUMMARY>
+ <BODY>
+ <p>
+ These are meant to be guidelines, as the topic seems too controversial for
+ a mandatory regulation.
+ <br/>
+ They are listed in order of precedence.
+ </p>
+ <ol>
+ <li>
+ Stay consistent with what you find for existing code.
+ </li>
+ <li>
+ Quote variables, see <a href="#Quoting">Quoting section below</a>.
+ </li>
+ <li>
+ <p>
+ Don't brace-quote single character shell
+ specials / positional parameters, unless strictly necessary
+ or avoiding deep confusion.
+ <br/>
+ Prefer brace-quoting all other variables.
+ <CODE_SNIPPET>
+ # Section of <em>recommended</em> cases.
+
+ # Preferred style for 'special' variables:
+ echo "Positional: $1" "$5" "$3"
+ echo "Specials: !=$!, -=$-, _=$_. ?=$?, #=$# *=$* @=$@ \$=$$ ..."
+
+ # Braces necessary:
+ echo "many parameters: ${10}"
+
+ # Braces avoiding confusion:
+ # Output is "a0b0c0"
+ set -- a b c
+ echo "${1}0${2}0${3}0"
+
+ # Preferred style for other variables:
+ echo "PATH=${PATH}, PWD=${PWD}, mine=${some_var}"
+ while read f; do
+ echo "file=${f}"
+ done < <(ls -l /tmp)
+
+ # Section of <em>discouraged</em> cases
+
+ # Unquoted vars, unbraced vars, brace-quoted single letter
+ # shell specials.
+ echo a=$avar "b=$bvar" "PID=${$}" "${1}"
+
+ # Confusing use: this is expanded as "${1}0${2}0${3}0",
+ # not "${10}${20}${30}
+ set -- a b c
+ echo "$10$20$30"
+ </CODE_SNIPPET>
+ </p>
+ </li>
+ </ol>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Quoting">
+ <SUMMARY>
+ <ul>
+ <li>
+ Always quote strings containing variables, command substitutions,
+ spaces or shell meta characters, unless careful unquoted expansion
+ is required.
+ </li>
+ <li>
+ Prefer quoting strings that are "words"
+ (as opposed to command options or path names).
+ </li>
+ <li>
+ Never quote <em>literal</em> integers.
+ </li>
+ <li>
+ Be aware of the quoting rules for
+ <a href="#Test,_%5B_and_%5B%5B">pattern matches in [[</a>.
+ </li>
+ <li>
+ Use "$@" unless you have a specific reason to use $*.
+ </li>
+ </ul>
+ </SUMMARY>
+ <BODY>
+ <p>
+ <CODE_SNIPPET>
+ # 'Single' quotes indicate that no substitution is desired.
+ # "Double" quotes indicate that substitution is required/tolerated.
+
+ # Simple examples
+ # "quote command substitutions"
+ flag="$(some_command and its args "$@" 'quoted separately')"
+
+ # "quote variables"
+ echo "${flag}"
+
+ # "never quote literal integers"
+ value=32
+ # "quote command substitutions", even when you expect integers
+ number="$(generate_number)"
+
+ # "prefer quoting words", not compulsory
+ readonly USE_INTEGER='true'
+
+ # "quote shell meta characters"
+ echo 'Hello stranger, and well met. Earn lots of $$$'
+ echo "Process $$: Done making \$\$\$."
+
+ # "command options or path names"
+ # ($1 is assumed to contain a value here)
+ grep -li Hugo /dev/null "$1"
+
+ # Less simple examples
+ # "quote variables, unless proven false": ccs might be empty
+ git send-email --to "${reviewers}" ${ccs:+"--cc" "${ccs}"}
+
+ # Positional parameter precautions: $1 might be unset
+ # Single quotes leave regex as-is.
+ grep -cP '([Ss]pecial|\|?characters*)$' ${1:+"$1"}
+
+ # For passing on arguments,
+ # "$@" is right almost everytime, and
+ # $* is wrong almost everytime:
+ #
+ # * $* and $@ will split on spaces, clobbering up arguments
+ # that contain spaces and dropping empty strings;
+ # * "$@" will retain arguments as-is, so no args
+ # provided will result in no args being passed on;
+ # This is in most cases what you want to use for passing
+ # on arguments.
+ # * "$*" expands to one argument, with all args joined
+ # by (usually) spaces,
+ # so no args provided will result in one empty string
+ # being passed on.
+ # (Consult 'man bash' for the nit-grits ;-)
+
+ set -- 1 "2 two" "3 three tres"; echo $# ; set -- "$*"; echo "$#, $@")
+ set -- 1 "2 two" "3 three tres"; echo $# ; set -- "$@"; echo "$#, $@")
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+</CATEGORY>
+
+<CATEGORY title="Features and Bugs">
+
+ <STYLEPOINT title="Command Substitution">
+ <SUMMARY>
+ Use <code>$(command)</code> instead of backticks.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Nested backticks require escaping the inner ones with <code>\</code>.
+ The <code>$(command)</code> format doesn't change when nested and is
+ easier to read.
+ </p>
+ <p>
+ Example:
+ <CODE_SNIPPET>
+ # This is preferred:
+ var="$(command "$(command1)")"
+
+ # This is not:
+ var="`command \`command1\``"
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Test, [ and [[">
+ <SUMMARY>
+ <code>[[ ... ]]</code> is preferred over <code>[</code>,
+ <code>test</code> and <code>/usr/bin/[</code>.
+ </SUMMARY>
+ <BODY>
+ <p>
+ <code>[[ ... ]]</code> reduces errors as no pathname expansion or word
+ splitting takes place between <code>[[</code> and <code>]]</code> and
+ <code>[[ ... ]]</code> allows for regular expression matching where
+ <code>[ ... ]</code> does not.
+ <CODE_SNIPPET>
+ # This ensures the string on the left is made up of characters in the
+ # alnum character class followed by the string name.
+ # Note that the RHS should not be quoted here.
+ # For the gory details, see
+ # E14 at https://tiswww.case.edu/php/chet/bash/FAQ
+ if [[ "filename" =~ ^[[:alnum:]]+name ]]; then
+ echo "Match"
+ fi
+
+ # This matches the exact pattern "f*" (Does not match in this case)
+ if [[ "filename" == "f*" ]]; then
+ echo "Match"
+ fi
+
+ # This gives a "too many arguments" error as f* is expanded to the
+ # contents of the current directory
+ if [ "filename" == f* ]; then
+ echo "Match"
+ fi
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Testing Strings">
+ <SUMMARY>
+ Use quotes rather than filler characters where possible.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Bash is smart enough to deal with an empty string in a test. So, given
+ that the code is much easier to read, use tests for empty/non-empty
+ strings or empty strings rather than filler characters.
+ <CODE_SNIPPET>
+ # Do this:
+ if [[ "${my_var}" = "some_string" ]]; then
+ do_something
+ fi
+
+ # -z (string length is zero) and -n (string length is not zero) are
+ # preferred over testing for an empty string
+ if [[ -z "${my_var}" ]]; then
+ do_something
+ fi
+
+ # This is OK (ensure quotes on the empty side), but not preferred:
+ if [[ "${my_var}" = "" ]]; then
+ do_something
+ fi
+
+ # Not this:
+ if [[ "${my_var}X" = "some_stringX" ]]; then
+ do_something
+ fi
+ </CODE_SNIPPET>
+ </p>
+ <p>
+ To avoid confusion about what you're testing for, explicitly use
+ <code>-z</code> or <code>-n</code>.
+ <CODE_SNIPPET>
+ # Use this
+ if [[ -n "${my_var}" ]]; then
+ do_something
+ fi
+
+ # Instead of this as errors can occur if ${my_var} expands to a test
+ # flag
+ if [[ "${my_var}" ]]; then
+ do_something
+ fi
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Wildcard Expansion of Filenames">
+ <SUMMARY>
+ Use an explicit path when doing wildcard expansion of filenames.
+ </SUMMARY>
+ <BODY>
+ <p>
+ As filenames can begin with a <code>-</code>, it's a lot safer to
+ expand wildcards with <code>./*</code> instead of <code>*</code>.
+ <CODE_SNIPPET>
+ # Here's the contents of the directory:
+ # -f -r somedir somefile
+
+ # This deletes almost everything in the directory by force
+ psa@bilby$ rm -v *
+ removed directory: `somedir'
+ removed `somefile'
+
+ # As opposed to:
+ psa@bilby$ rm -v ./*
+ removed `./-f'
+ removed `./-r'
+ rm: cannot remove `./somedir': Is a directory
+ removed `./somefile'
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Eval">
+ <SUMMARY>
+ <code>eval</code> should be avoided.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Eval munges the input when used for assignment to variables and can set
+ variables without making it possible to check what those variables
+ were.
+ <CODE_SNIPPET>
+ # What does this set?
+ # Did it succeed? In part or whole?
+ eval $(set_my_variables)
+
+ # What happens if one of the returned values has a space in it?
+ variable="$(eval some_function)"
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Pipes to While">
+ <SUMMARY>
+ Use process substitution or for loops in preference to piping to while.
+ Variables modified in a while loop do not propagate to the parent
+ because the loop's commands run in a subshell.
+ </SUMMARY>
+ <BODY>
+ <p>
+ The implicit subshell in a pipe to while can make it difficult to track
+ down bugs.
+ <BAD_CODE_SNIPPET>
+ last_line='NULL'
+ your_command | while read line; do
+ last_line="${line}"
+ done
+
+ # This will output 'NULL'
+ echo "${last_line}"
+ </BAD_CODE_SNIPPET>
+ </p>
+ <p>
+ Use a for loop if you are confident that the input will not contain
+ spaces or special characters (usually, this means not user input).
+ <CODE_SNIPPET>
+ total=0
+ # Only do this if there are no spaces in return values.
+ for value in $(command); do
+ total+="${value}"
+ done
+ </CODE_SNIPPET>
+ </p>
+ <p>
+ Using process substitution allows redirecting output but puts the
+ commands in an explicit subshell rather than the implicit subshell that
+ bash creates for the while loop.
+ <CODE_SNIPPET>
+ total=0
+ last_file=
+ while read count filename; do
+ total+="${count}"
+ last_file="${filename}"
+ done < <(your_command | uniq -c)
+
+ # This will output the second field of the last line of output from
+ # the command.
+ echo "Total = ${total}"
+ echo "Last one = ${last_file}"
+ </CODE_SNIPPET>
+ </p>
+ <p>
+ Use while loops where it is not necessary to pass complex results
+ to the parent shell - this is typically where some more complex
+ "parsing" is required. Beware that simple examples are probably
+ more easily done with a tool such as awk. This may also be useful
+ where you specifically don't want to change the parent scope variables.
+ <CODE_SNIPPET>
+ # Trivial implementation of awk expression:
+ # awk '$3 == "nfs" { print $2 " maps to " $1 }' /proc/mounts
+ cat /proc/mounts | while read src dest type opts rest; do
+ if [[ ${type} == "nfs" ]]; then
+ echo "NFS ${dest} maps to ${src}"
+ fi
+ done
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+</CATEGORY>
+
+<CATEGORY title="Naming Conventions">
+
+ <STYLEPOINT title="Function Names">
+ <SUMMARY>
+ Lower-case, with underscores to separate words. Separate libraries
+ with <code>::</code>. Parentheses are required after the function name.
+ The keyword <code>function</code> is optional, but must be used
+ consistently throughout a project.
+ </SUMMARY>
+ <BODY>
+ <p>
+ If you're writing single functions, use lowercase and separate words
+ with underscore. If you're writing a package, separate package names
+ with <code>::</code>. Braces must be on the same line as the function
+ name (as with other languages at Google) and no space between the
+ function name and the parenthesis.
+ <CODE_SNIPPET>
+ # Single function
+ my_func() {
+ ...
+ }
+
+ # Part of a package
+ mypackage::my_func() {
+ ...
+ }
+ </CODE_SNIPPET>
+ </p>
+ <p>
+ The <code>function</code> keyword is extraneous when "()" is present
+ after the function name, but enhances quick identification of
+ functions.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Variable Names">
+ <SUMMARY>
+ As for function names.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Variables names for loops should be similarly named for any variable
+ you're looping through.
+ <CODE_SNIPPET>
+ for zone in ${zones}; do
+ something_with "${zone}"
+ done
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Constants and Environment Variable Names">
+ <SUMMARY>
+ All caps, separated with underscores, declared at the top of the file.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Constants and anything exported to the environment should be
+ capitalized.
+ <CODE_SNIPPET>
+ # Constant
+ readonly PATH_TO_FILES='/some/path'
+
+ # Both constant and environment
+ declare -xr ORACLE_SID='PROD'
+ </CODE_SNIPPET>
+ </p>
+ <p>
+ Some things become constant at their first setting (for example, via
+ getopts). Thus, it's OK to set a constant in getopts or based on a
+ condition, but it should be made readonly immediately afterwards.
+ Note that <code>declare</code> doesn't operate on global variables
+ within functions, so <code>readonly</code> or <code>export</code> is
+ recommended instead.
+ </p>
+ <CODE_SNIPPET>
+ VERBOSE='false'
+ while getopts 'v' flag; do
+ case "${flag}" in
+ v) VERBOSE='true' ;;
+ esac
+ done
+ readonly VERBOSE
+ </CODE_SNIPPET>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Source Filenames">
+ <SUMMARY>
+ Lowercase, with underscores to separate words if desired.
+ </SUMMARY>
+ <BODY>
+ <p>
+ This is for consistency with other code styles in Google:
+ <code>maketemplate</code> or <code>make_template</code> but not
+ <code>make-template</code>.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Read-only Variables">
+ <SUMMARY>
+ Use <code>readonly</code> or <code>declare -r</code> to ensure they're
+ read only.
+ </SUMMARY>
+ <BODY>
+ <p>
+ As globals are widely used in shell, it's important to catch errors
+ when working with them. When you declare a variable that is
+ meant to be read-only, make this explicit.
+ <CODE_SNIPPET>
+ zip_version="$(dpkg --status zip | grep Version: | cut -d ' ' -f 2)"
+ if [[ -z "${zip_version}" ]]; then
+ error_message
+ else
+ readonly zip_version
+ fi
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Use Local Variables">
+ <SUMMARY>
+ Declare function-specific variables with <code>local</code>. Declaration
+ and assignment should be on different lines.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Ensure that local variables are only seen inside a function and its
+ children by using <code>local</code> when declaring them. This avoids
+ polluting the global name space and inadvertently setting variables
+ that may have significance outside the function.
+ </p>
+ <p>
+ Declaration and assignment must be separate statements when
+ the assignment value is provided by a command substitution; as
+ the 'local' builtin does not propagate the exit code from the
+ command substitution.
+ <CODE_SNIPPET>
+ my_func2() {
+ local name="$1"
+
+ # Separate lines for declaration and assignment:
+ local my_var
+ my_var="$(my_func)" || return
+
+ # DO NOT do this: $? contains the exit code of 'local', not my_func
+ local my_var="$(my_func)"
+ [[ $? -eq 0 ]] || return
+
+ ...
+ }
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Function Location">
+ <SUMMARY>
+ Put all functions together in the file just below constants. Don't hide
+ executable code between functions.
+ </SUMMARY>
+ <BODY>
+ <p>
+ If you've got functions, put them all together near the top of the
+ file. Only includes, <code>set</code> statements and setting constants
+ may be done before declaring functions.
+ </p>
+ <p>
+ Don't hide executable code between functions. Doing so makes the code
+ difficult to follow and results in nasty surprises when debugging.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="main">
+ <SUMMARY>
+ A function called <code>main</code> is required for scripts long enough
+ to contain at least one other function.
+ </SUMMARY>
+ <BODY>
+ <p>
+ In order to easily find the start of the program, put the main
+ program in a function called <code>main</code> as the bottom most
+ function. This provides consistency with the rest of the code base as
+ well as allowing you to define more variables as <code>local</code>
+ (which can't be done if the main code is not a function). The last
+ non-comment line in the file should be a call to <code>main</code>:
+ <CODE_SNIPPET>
+ main "$@"
+ </CODE_SNIPPET>
+ </p>
+ <p>
+ Obviously, for short scripts where it's just a linear flow,
+ <code>main</code> is overkill and so is not required.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+</CATEGORY>
+
+<CATEGORY title="Calling Commands">
+
+ <STYLEPOINT title="Checking Return Values">
+ <SUMMARY>
+ Always check return values and give informative return values.
+ </SUMMARY>
+ <BODY>
+ <p>
+ For unpiped commands, use <code>$?</code> or check directly via an
+ <code>if</code> statement to keep it simple.
+ </p>
+ <p>
+ Example:
+ <CODE_SNIPPET>
+ if ! mv "${file_list}" "${dest_dir}/" ; then
+ echo "Unable to move ${file_list} to ${dest_dir}" >&2
+ exit "${E_BAD_MOVE}"
+ fi
+
+ # Or
+ mv "${file_list}" "${dest_dir}/"
+ if [[ "$?" -ne 0 ]]; then
+ echo "Unable to move ${file_list} to ${dest_dir}" >&2
+ exit "${E_BAD_MOVE}"
+ fi
+
+ </CODE_SNIPPET>
+ </p>
+ <p>
+ Bash also has the <code>PIPESTATUS</code> variable that allows checking
+ of the return code from all parts of a pipe. If it's only necessary to
+ check success or failure of the whole pipe, then the following is
+ acceptable:
+ <CODE_SNIPPET>
+ tar -cf - ./* | ( cd "${dir}" && tar -xf - )
+ if [[ "${PIPESTATUS[0]}" -ne 0 || "${PIPESTATUS[1]}" -ne 0 ]]; then
+ echo "Unable to tar files to ${dir}" >&2
+ fi
+ </CODE_SNIPPET>
+ </p>
+ <p>
+ However, as <code>PIPESTATUS</code> will be overwritten as soon as you
+ do any other command, if you need to act differently on errors based on
+ where it happened in the pipe, you'll need to assign
+ <code>PIPESTATUS</code> to another variable immediately after running
+ the command (don't forget that <code>[</code> is a command and will
+ wipe out <code>PIPESTATUS</code>).
+ <CODE_SNIPPET>
+ tar -cf - ./* | ( cd "${DIR}" && tar -xf - )
+ return_codes=(${PIPESTATUS[*]})
+ if [[ "${return_codes[0]}" -ne 0 ]]; then
+ do_something
+ fi
+ if [[ "${return_codes[1]}" -ne 0 ]]; then
+ do_something_else
+ fi
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Builtin Commands vs. External Commands">
+ <SUMMARY>
+ Given the choice between invoking a shell builtin and invoking a separate
+ process, choose the builtin.
+ </SUMMARY>
+ <BODY>
+ <p>
+ We prefer the use of builtins such as the <em>Parameter Expansion</em>
+ functions in <code>bash(1)</code> as it's more robust and portable
+ (especially when compared to things like sed).
+ </p>
+ <p>
+ Example:
+ <CODE_SNIPPET>
+ # Prefer this:
+ addition=$((${X} + ${Y}))
+ substitution="${string/#foo/bar}"
+
+ # Instead of this:
+ addition="$(expr ${X} + ${Y})"
+ substitution="$(echo "${string}" | sed -e 's/^foo/bar/')"
+ </CODE_SNIPPET>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+</CATEGORY>
+
+<CATEGORY title="Conclusion">
+ <p>
+ Use common sense and <em>BE CONSISTENT</em>.
+ </p>
+ <p>
+ Please take a few minutes to read the Parting Words section at the bottom
+ of the <a href="cppguide.html">C++ Guide</a>.
+ </p>
+</CATEGORY>
+
+<p align="right">
+Revision 1.26
+</p>
+
+</GUIDE>
diff --git a/styleguide.css b/styleguide.css
new file mode 100644
index 0000000..adba8f3
--- /dev/null
+++ b/styleguide.css
@@ -0,0 +1,147 @@
+body {
+ background-color: #fff;
+ color: #333;
+ font-family: sans-serif;
+ font-size: 10pt;
+ margin-right: 100px;
+ margin-left: 100px;
+}
+
+h1, h2, h3, h4, h5, h6, .toc_title {
+ color: #06c;
+ margin-top: 2em;
+ margin-bottom: 1em;
+}
+
+h1 {
+ text-align: center;
+ font-size: 18pt;
+}
+
+h2, .toc_title {
+ font-weight: bold;
+ font-size: 12pt;
+ margin-left: -40px;
+}
+
+h3, h4, h5, h6 {
+ font-size: 10pt;
+ margin-left: -20px;
+}
+
+.toc_category, .toc_stylepoint {
+ font-size: 10pt;
+ padding-top: .3em;
+ padding-bottom: .3em;
+}
+
+table {
+ border-collapse: collapse;
+}
+
+td, th {
+ border: 1px solid #ccc;
+ padding: 2px 12px;
+ font-size: 10pt;
+}
+
+.toc td, .toc th {
+ border-width: 1px 5px;
+}
+
+code, samp, var {
+ color: #060;
+}
+
+pre {
+ font-size: 10pt;
+ display: block;
+ color: #060;
+ background-color: #f8fff8;
+ border-color: #f0fff0;
+ border-style: solid;
+ border-top-width: 1px;
+ border-bottom-width: 1px;
+ border-right-width: 1px;
+ border-left-width: 5px;
+ padding-left: 12px;
+ padding-right: 12px;
+ padding-top: 4px;
+ padding-bottom: 4px;
+}
+
+pre.badcode {
+ color: #c00;
+ background-color: #fff8f8;
+ border-color: #fff0f0;
+}
+
+.showhide_button {
+ float: left;
+ cursor: pointer;
+ border-width: 1px;
+ border-style: solid;
+ border-color: #ddd #aaa #aaa #ddd;
+ padding: 0 3px 1px;
+ margin: 0 4px 8px 0;
+ border-radius: 3px;
+ -webkit-border-radius: 3px;
+ -moz-border-radius: 3px;
+}
+
+.link_button {
+ float: left;
+ display: none;
+ background-color: #f8f8ff;
+ border-color: #f0f0ff;
+ border-style: solid;
+ border-width: 1px;
+ font-size: 75%;
+ margin-top: 0;
+ margin-left: -50px;
+ padding: 4px;
+ border-radius: 3px;
+ -webkit-border-radius: 3px;
+ -moz-border-radius: 3px;
+}
+
+address {
+ text-align: right;
+}
+
+hr {
+ margin-top: 3.5em;
+ border-width: 1px;
+ color: #fff;
+}
+
+.stylepoint_section {
+ display: block;
+ margin-bottom: 1em;
+ color: #5588ff;
+ font-family: sans-serif;
+ font-size: 90%;
+ font-weight: bold;
+ margin-left: -2%;
+}
+
+.stylepoint_subsection {
+ color: #667799;
+ font-family: sans-serif;
+ font-size: 90%;
+ font-weight: bold;
+ margin-left: -1%;
+}
+
+.stylepoint_subsubsection {
+ color: #667799;
+ font-family: sans-serif;
+ font-size: 80%;
+ font-weight: bold;
+ margin-left: 0;
+}
+
+.revision {
+ text-align: right;
+}
+
diff --git a/styleguide.xsl b/styleguide.xsl
new file mode 100644
index 0000000..dfdc598
--- /dev/null
+++ b/styleguide.xsl
@@ -0,0 +1,924 @@
+<xsl:stylesheet version="1.0"
+xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+xmlns:dc="http://purl.org/dc/elements/1.1/"
+xmlns:dcq="http://purl.org/dc/qualifiers/1.0/"
+xmlns:fo="http://www.w3.org/1999/XSL/Format"
+xmlns:fn="http://www.w3.org/2005/xpath-functions">
+ <xsl:output method="html"/>
+ <!-- Set to 1 to show explanations by default. Set to 0 to hide them -->
+ <xsl:variable name="show_explanation_default" select="0" />
+ <!-- The characters within the Webdings font that show the triangles -->
+ <xsl:variable name="show_button_text" select="'▶'" />
+ <xsl:variable name="hide_button_text" select="'▽'" />
+ <!-- The suffix for names -->
+ <xsl:variable name="button_suffix" select="'__button'"/>
+ <xsl:variable name="body_suffix" select="'__body'"/>
+ <!-- For easy reference, the name of the button -->
+ <xsl:variable name="show_hide_all_button" select="'show_hide_all_button'"/>
+
+ <!-- The top-level element -->
+ <xsl:template match="GUIDE">
+ <HTML>
+ <HEAD>
+ <TITLE><xsl:value-of select="@title"/></TITLE>
+ <META http-equiv="Content-Type" content="text/html; charset=utf-8"/>
+ <LINK HREF="https://www.google.com/favicon.ico" type="image/x-icon"
+ rel="shortcut icon"/>
+ <LINK HREF="styleguide.css"
+ type="text/css" rel="stylesheet"/>
+
+ <SCRIPT language="javascript" type="text/javascript">
+
+ function GetElementsByName(name) {
+ // Workaround a bug on old versions of opera.
+ if (document.getElementsByName) {
+ return document.getElementsByName(name);
+ } else {
+ return [document.getElementById(name)];
+ }
+ }
+
+ /**
+ * @param {string} namePrefix The prefix of the body name.
+ * @param {function(boolean): boolean} getVisibility Computes the new
+ * visibility state, given the current one.
+ */
+ function ChangeVisibility(namePrefix, getVisibility) {
+ var bodyName = namePrefix + '<xsl:value-of select="$body_suffix"/>';
+ var buttonName = namePrefix + '<xsl:value-of select="$button_suffix"/>';
+ var bodyElements = GetElementsByName(bodyName);
+ var linkElement = GetElementsByName('link-' + buttonName)[0];
+ if (bodyElements.length != 1) {
+ throw Error('ShowHideByName() got the wrong number of bodyElements: ' +
+ bodyElements.length);
+ } else {
+ var bodyElement = bodyElements[0];
+ var buttonElement = GetElementsByName(buttonName)[0];
+ var isVisible = bodyElement.style.display != "none";
+ if (getVisibility(isVisible)) {
+ bodyElement.style.display = "inline";
+ linkElement.style.display = "block";
+ buttonElement.innerHTML = '<xsl:value-of select="$hide_button_text"/>';
+ } else {
+ bodyElement.style.display = "none";
+ linkElement.style.display = "none";
+ buttonElement.innerHTML = '<xsl:value-of select="$show_button_text"/>';
+ }
+ }
+ }
+
+ function ShowHideByName(namePrefix) {
+ ChangeVisibility(namePrefix, function(old) { return !old; });
+ }
+
+ function ShowByName(namePrefix) {
+ ChangeVisibility(namePrefix, function() { return true; });
+ }
+
+ function ShowHideAll() {
+ var allButton = GetElementsByName("show_hide_all_button")[0];
+ if (allButton.innerHTML == '<xsl:value-of select="$hide_button_text"/>') {
+ allButton.innerHTML = '<xsl:value-of select="$show_button_text"/>';
+ SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '<xsl:value-of select="$show_button_text"/>');
+ } else {
+ allButton.innerHTML = '<xsl:value-of select="$hide_button_text"/>';
+ SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "inline", '<xsl:value-of select="$hide_button_text"/>');
+ }
+ }
+
+ // Recursively sets state of all children
+ // of a particular node.
+ function SetHiddenState(root, newState, newButton) {
+ for (var i = 0; i != root.length; i++) {
+ SetHiddenState(root[i].childNodes, newState, newButton);
+ if (root[i].className == 'showhide_button') {
+ root[i].innerHTML = newButton;
+ }
+ if (root[i].className == 'stylepoint_body' ||
+ root[i].className == 'link_button') {
+ root[i].style.display = newState;
+ }
+ }
+ }
+
+
+ function EndsWith(str, suffix) {
+ var l = str.length - suffix.length;
+ return l >= 0 && str.indexOf(suffix, l) == l;
+ }
+
+ function RefreshVisibilityFromHashParam() {
+ var hashRegexp = new RegExp('#([^&#]*)$');
+ var hashMatch = hashRegexp.exec(window.location.href);
+ var anchor = hashMatch && GetElementsByName(hashMatch[1])[0];
+ var node = anchor;
+ var suffix = '<xsl:value-of select="$body_suffix"/>';
+ while (node) {
+ var id = node.id;
+ var matched = id && EndsWith(id, suffix);
+ if (matched) {
+ var len = id.length - suffix.length;
+ ShowByName(id.substring(0, len));
+ if (anchor.scrollIntoView) {
+ anchor.scrollIntoView();
+ }
+
+ return;
+ }
+ node = node.parentNode;
+ }
+ }
+
+ window.onhashchange = RefreshVisibilityFromHashParam;
+
+ window.onload = function() {
+ // if the URL contains "?showall=y", expand the details of all children
+ var showHideAllRegex = new RegExp("[\\?&](showall)=([^&#]*)");
+ var showHideAllValue = showHideAllRegex.exec(window.location.href);
+ if (showHideAllValue != null) {
+ if (showHideAllValue[2] == "y") {
+ SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
+ "inline", '<xsl:value-of select="$hide_button_text"/>');
+ } else {
+ SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
+ "none", '<xsl:value-of select="$show_button_text"/>');
+ }
+ }
+ var showOneRegex = new RegExp("[\\?&](showone)=([^&#]*)");
+ var showOneValue = showOneRegex.exec(window.location.href);
+ if (showOneValue) {
+ ShowHideByName(showOneValue[2]);
+ }
+
+
+ RefreshVisibilityFromHashParam();
+ }
+ </SCRIPT>
+ </HEAD>
+ <BODY>
+ <H1><xsl:value-of select="@title"/></H1>
+ <xsl:apply-templates/>
+ </BODY>
+ </HTML>
+ </xsl:template>
+
+ <xsl:template match="OVERVIEW">
+ <xsl:variable name="button_text">
+ <xsl:choose>
+ <xsl:when test="$show_explanation_default">
+ <xsl:value-of select="$hide_button_text"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$show_button_text"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+ <DIV style="margin-left: 50%; font-size: 75%;">
+ <P>
+ Each style point has a summary for which additional information is available
+ by toggling the accompanying arrow button that looks this way:
+ <SPAN class="showhide_button" style="margin-left: 0; float: none">
+ <xsl:value-of select="$show_button_text"/></SPAN>.
+ You may toggle all summaries with the big arrow button:
+ </P>
+ <DIV style=" font-size: larger; margin-left: +2em;">
+ <SPAN class="showhide_button" style="font-size: 180%; float: none">
+ <xsl:attribute name="onclick"><xsl:value-of select="'javascript:ShowHideAll()'"/></xsl:attribute>
+ <xsl:attribute name="name"><xsl:value-of select="$show_hide_all_button"/></xsl:attribute>
+ <xsl:attribute name="id"><xsl:value-of select="$show_hide_all_button"/></xsl:attribute>
+ <xsl:value-of select="$button_text"/>
+ </SPAN>
+ Toggle all summaries
+ </DIV>
+ </DIV>
+ <xsl:call-template name="TOC">
+ <xsl:with-param name="root" select=".."/>
+ </xsl:call-template>
+ <xsl:apply-templates/>
+ </xsl:template>
+
+ <xsl:template match="PARTING_WORDS">
+ <H2>Parting Words</H2>
+ <xsl:apply-templates/>
+ </xsl:template>
+
+ <xsl:template match="CATEGORY">
+ <DIV>
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <H2>
+ <xsl:variable name="category_name">
+ <xsl:call-template name="anchorname">
+ <xsl:with-param name="sectionname" select="@title"/>
+ </xsl:call-template>
+ </xsl:variable>
+ <xsl:attribute name="name"><xsl:value-of select="$category_name"/></xsl:attribute>
+ <xsl:attribute name="id"><xsl:value-of select="$category_name"/></xsl:attribute>
+ <xsl:value-of select="@title"/>
+ </H2>
+ <xsl:apply-templates/>
+ </DIV>
+ </xsl:template>
+
+ <xsl:template match="STYLEPOINT">
+ <DIV>
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <xsl:variable name="stylepoint_name">
+ <xsl:call-template name="anchorname">
+ <xsl:with-param name="sectionname" select="@title"/>
+ </xsl:call-template>
+ </xsl:variable>
+ <xsl:variable name="button_text">
+ <xsl:choose>
+ <xsl:when test="$show_explanation_default">
+ <xsl:value-of select="$hide_button_text"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$show_button_text"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+ <H3>
+ <A>
+ <xsl:attribute name="name"><xsl:value-of select="$stylepoint_name"/></xsl:attribute>
+ <xsl:attribute name="id"><xsl:value-of select="$stylepoint_name"/></xsl:attribute>
+ <xsl:value-of select="@title"/>
+ </A>
+ </H3>
+ <xsl:variable name="buttonName">
+ <xsl:value-of select="$stylepoint_name"/><xsl:value-of select="$button_suffix"/>
+ </xsl:variable>
+ <xsl:variable name="onclick_definition">
+ <xsl:text>javascript:ShowHideByName('</xsl:text>
+ <xsl:value-of select="$stylepoint_name"/>
+ <xsl:text>')</xsl:text>
+ </xsl:variable>
+ <SPAN class="link_button" id="link-{$buttonName}" name="link-{$buttonName}">
+ <A>
+ <xsl:attribute name="href">?showone=<xsl:value-of select="$stylepoint_name"/>#<xsl:value-of select="$stylepoint_name"/></xsl:attribute>
+ link
+ </A>
+ </SPAN>
+ <SPAN class="showhide_button">
+ <xsl:attribute name="onclick"><xsl:value-of select="$onclick_definition"/></xsl:attribute>
+ <xsl:attribute name="name"><xsl:value-of select="$buttonName"/></xsl:attribute>
+ <xsl:attribute name="id"><xsl:value-of select="$buttonName"/></xsl:attribute>
+ <xsl:value-of select="$button_text"/>
+ </SPAN>
+ <xsl:apply-templates>
+ <xsl:with-param name="anchor_prefix" select="$stylepoint_name" />
+ </xsl:apply-templates>
+ </DIV>
+ </xsl:template>
+
+ <xsl:template match="SUMMARY">
+ <xsl:param name="anchor_prefix" />
+ <DIV style="display:inline;">
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <xsl:apply-templates/>
+ </DIV>
+ </xsl:template>
+
+ <xsl:template match="BODY">
+ <xsl:param name="anchor_prefix" />
+ <DIV>
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <DIV class="stylepoint_body">
+ <xsl:attribute name="name"><xsl:value-of select="$anchor_prefix"/><xsl:value-of select="$body_suffix"/></xsl:attribute>
+ <xsl:attribute name="id"><xsl:value-of select="$anchor_prefix"/><xsl:value-of select="$body_suffix"/></xsl:attribute>
+ <xsl:attribute name="style">
+ <xsl:choose>
+ <xsl:when test="$show_explanation_default">display: inline</xsl:when>
+ <xsl:otherwise>display: none</xsl:otherwise>
+ </xsl:choose>
+ </xsl:attribute>
+ <xsl:apply-templates/>
+ </DIV>
+ </DIV>
+ </xsl:template>
+
+ <xsl:template match="DEFINITION">
+ <P>
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <SPAN class="stylepoint_section">Definition: </SPAN>
+ <xsl:apply-templates/>
+ </P>
+ </xsl:template>
+
+ <xsl:template match="PROS">
+ <P>
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <SPAN class="stylepoint_section">Pros: </SPAN>
+ <xsl:apply-templates/>
+ </P>
+ </xsl:template>
+
+ <xsl:template match="CONS">
+ <P>
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <SPAN class="stylepoint_section">Cons: </SPAN>
+ <xsl:apply-templates/>
+ </P>
+ </xsl:template>
+
+ <xsl:template match="DECISION">
+ <P>
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <SPAN class="stylepoint_section">Decision: </SPAN>
+ <xsl:apply-templates/>
+ </P>
+ </xsl:template>
+
+ <xsl:template match="TODO">
+ <P>
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <DIV style="font-size: 150%;">TODO:
+ <xsl:apply-templates/>
+ </DIV>
+ </P>
+ </xsl:template>
+
+ <xsl:template match="SUBSECTION">
+ <P>
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <SPAN class="stylepoint_subsection"><xsl:value-of select="@title"/> </SPAN>
+ <xsl:apply-templates/>
+ </P>
+ </xsl:template>
+
+ <xsl:template match="SUBSUBSECTION">
+ <P>
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <SPAN class="stylepoint_subsubsection"><xsl:value-of select="@title"/> </SPAN>
+ <xsl:apply-templates/>
+ </P>
+ </xsl:template>
+
+ <xsl:template match="CODE_SNIPPET">
+ <DIV>
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <PRE><xsl:call-template name="print_without_leading_chars">
+ <xsl:with-param name="text" select="."/>
+ <xsl:with-param name="strip" select="1"/>
+ <xsl:with-param name="is_firstline" select="1"/>
+ <xsl:with-param name="trim_count">
+ <xsl:call-template name="num_leading_spaces">
+ <xsl:with-param name="text" select="."/>
+ <xsl:with-param name="max_so_far" select="1000"/>
+ </xsl:call-template>
+ </xsl:with-param>
+ </xsl:call-template></PRE>
+ </DIV>
+ </xsl:template>
+
+ <xsl:template match="BAD_CODE_SNIPPET">
+ <DIV>
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <PRE class="badcode"><xsl:call-template name="print_without_leading_chars">
+ <xsl:with-param name="text" select="."/>
+ <xsl:with-param name="strip" select="1"/>
+ <xsl:with-param name="is_firstline" select="1"/>
+ <xsl:with-param name="trim_count">
+ <xsl:call-template name="num_leading_spaces">
+ <xsl:with-param name="text" select="."/>
+ <xsl:with-param name="max_so_far" select="1000"/>
+ </xsl:call-template>
+ </xsl:with-param>
+ </xsl:call-template></PRE>
+ </DIV>
+ </xsl:template>
+
+ <xsl:template match="PY_CODE_SNIPPET">
+ <DIV>
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <PRE><xsl:call-template name="print_python_code">
+ <xsl:with-param name="text" select="."/>
+ </xsl:call-template></PRE>
+ </DIV>
+ </xsl:template>
+
+ <xsl:template match="BAD_PY_CODE_SNIPPET">
+ <DIV>
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <PRE class="badcode"><xsl:call-template name="print_python_code">
+ <xsl:with-param name="text" select="."/>
+ </xsl:call-template></PRE>
+ </DIV>
+ </xsl:template>
+
+ <xsl:template match="FUNCTION">
+ <xsl:call-template name="print_function_name">
+ <xsl:with-param name="text" select="."/>
+ </xsl:call-template>
+ </xsl:template>
+
+ <xsl:template match="SYNTAX">
+ <I>
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <xsl:apply-templates/>
+ </I>
+ </xsl:template>
+
+
+ <!-- This passes through any HTML elements that the
+ XML doc uses for minor formatting -->
+ <xsl:template match="a|address|blockquote|br|center|cite|code|dd|div|dl|dt|em|hr|i|img|li|ol|p|pre|span|table|td|th|tr|ul|var|A|ADDRESS|BLOCKQUOTE|BR|CENTER|CITE|CODE|DD|DIV|DL|DT|EM|HR|I|LI|OL|P|PRE|SPAN|TABLE|TD|TH|TR|UL|VAR">
+ <xsl:element name="{local-name()}">
+ <xsl:copy-of select="@*"/>
+ <xsl:apply-templates/>
+ </xsl:element>
+ </xsl:template>
+
+ <!-- Builds the table of contents -->
+ <xsl:template name="TOC">
+ <xsl:param name="root"/>
+ <DIV class="toc">
+ <DIV class="toc_title">Table of Contents</DIV>
+ <TABLE>
+ <xsl:for-each select="$root/CATEGORY">
+ <TR valign="top">
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <TD>
+ <DIV class="toc_category">
+ <A>
+ <xsl:attribute name="href">
+ <xsl:text>#</xsl:text>
+ <xsl:call-template name="anchorname">
+ <xsl:with-param name="sectionname" select="@title"/>
+ </xsl:call-template>
+ </xsl:attribute>
+ <xsl:value-of select="@title"/>
+ </A>
+ </DIV>
+ </TD><TD>
+ <DIV class="toc_stylepoint">
+ <xsl:for-each select="./STYLEPOINT">
+ <SPAN style="padding-right: 1em; white-space:nowrap;">
+ <xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
+ <A>
+ <xsl:attribute name="href">
+ <xsl:text>#</xsl:text>
+ <xsl:call-template name="anchorname">
+ <xsl:with-param name="sectionname" select="@title"/>
+ </xsl:call-template>
+ </xsl:attribute>
+ <xsl:value-of select="@title"/>
+ </A>
+ </SPAN>
+ <xsl:text> </xsl:text>
+ </xsl:for-each>
+ </DIV>
+ </TD>
+ </TR>
+ </xsl:for-each>
+ </TABLE>
+ </DIV>
+ </xsl:template>
+
+ <xsl:template name="TOC_one_stylepoint">
+ <xsl:param name="stylepoint"/>
+ </xsl:template>
+
+ <!-- Creates a standard anchor given any text.
+ Substitutes underscore for characters unsuitable for URLs -->
+ <xsl:template name="anchorname">
+ <xsl:param name="sectionname"/>
+ <!-- strange quoting necessary to strip apostrophes -->
+ <xsl:variable name="bad_characters" select="" ()#'""/>
+ <xsl:value-of select="translate($sectionname,$bad_characters,'_____')"/>
+ </xsl:template>
+
+ <!-- Given text, evaluates to the number of leading spaces. -->
+ <!-- TODO(csilvers): deal well with leading tabs (treat as 8 spaces?) -->
+ <xsl:template name="num_leading_spaces_one_line">
+ <xsl:param name="text"/>
+ <xsl:param name="current_count"/>
+ <xsl:choose>
+ <xsl:when test="starts-with($text, ' ')">
+ <xsl:call-template name="num_leading_spaces_one_line">
+ <xsl:with-param name="text" select="substring($text, 2)"/>
+ <xsl:with-param name="current_count" select="$current_count + 1"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$current_count"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:template>
+
+ <!-- Given a block of text, each line terminated by \n, evaluates to
+ the indentation-level of that text; that is, the largest number
+ n such that every non-blank line starts with at least n spaces. -->
+ <xsl:template name="num_leading_spaces">
+ <xsl:param name="text"/>
+ <xsl:param name="max_so_far"/>
+ <!-- TODO(csilvers): deal with case text doesn't end in a newline -->
+ <xsl:variable name="line" select="substring-before($text, '
')"/>
+ <xsl:variable name="rest" select="substring-after($text, '
')"/>
+ <xsl:variable name="num_spaces_this_line">
+ <xsl:choose>
+ <xsl:when test="$line=''">
+ <xsl:value-of select="$max_so_far"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:call-template name="num_leading_spaces_one_line">
+ <xsl:with-param name="text" select="$line"/>
+ <xsl:with-param name="current_count" select="0"/>
+ </xsl:call-template>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+ <xsl:variable name="new_max_so_far">
+ <xsl:choose>
+ <xsl:when test="$num_spaces_this_line < $max_so_far">
+ <xsl:value-of select="$num_spaces_this_line"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$max_so_far"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+ <!-- now check if we're on the last line, and if not, recurse -->
+ <xsl:if test="$rest=''">
+ <xsl:value-of select="$new_max_so_far"/>
+ </xsl:if>
+ <xsl:if test="not($rest='')">
+ <xsl:call-template name="num_leading_spaces">
+ <xsl:with-param name="text" select="$rest"/>
+ <xsl:with-param name="max_so_far" select="$new_max_so_far"/>
+ </xsl:call-template>
+ </xsl:if>
+ </xsl:template>
+
+ <!-- Given text, determine the starting position of code.
+ This similar to num_leading_spaces_one_line but treats "Yes:" and "No:"
+ as spaces. Also, if there is no code on the first line, it searches
+ subsequent lines until a non-empty line is found.
+ Used to find the start of code in snippets like:
+ Yes: if(foo):
+ No : if(foo):
+ As well as:
+ Yes:
+ if (foo):
+ -->
+ <xsl:template name="code_start_index">
+ <xsl:param name="text"/>
+ <xsl:param name="current_count"/>
+ <xsl:choose>
+ <xsl:when test="starts-with($text, ' ')">
+ <xsl:call-template name="code_start_index">
+ <xsl:with-param name="text" select="substring($text, 2)"/>
+ <xsl:with-param name="current_count" select="$current_count + 1"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:when test="starts-with($text, 'Yes:')">
+ <xsl:call-template name="code_start_index">
+ <xsl:with-param name="text" select="substring($text, 5)"/>
+ <xsl:with-param name="current_count" select="$current_count + 4"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:when test="starts-with($text, 'No:')">
+ <xsl:call-template name="code_start_index">
+ <xsl:with-param name="text" select="substring($text, 4)"/>
+ <xsl:with-param name="current_count" select="$current_count + 3"/>
+ </xsl:call-template>
+ </xsl:when>
+ <!-- This is only reached if the first line is entirely whitespace or
+ contains nothing but "Yes:" or "No:"-->
+ <xsl:when test="starts-with($text, '
')">
+ <xsl:call-template name="code_start_index">
+ <xsl:with-param name="text" select="substring($text, 2)"/>
+ <xsl:with-param name="current_count" select="0"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$current_count"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:template>
+
+ <!-- Helper for ends_with_colon. Determine whether the given line is nothing
+ but spaces and python-style comments. -->
+ <xsl:template name="is_blank_or_comment">
+ <xsl:param name="line"/>
+ <xsl:choose>
+ <xsl:when test="$line = ''">
+ <xsl:value-of select="1"/>
+ </xsl:when>
+ <xsl:when test="starts-with($line, '
')">
+ <xsl:value-of select="1"/>
+ </xsl:when>
+ <xsl:when test="starts-with($line, '#')">
+ <xsl:value-of select="1"/>
+ </xsl:when>
+ <xsl:when test="starts-with($line, ' ')">
+ <xsl:call-template name="is_blank_or_comment">
+ <xsl:with-param name="line" select="substring($line, 2)"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="0"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:template>
+
+ <!-- Determine whether the given line ends with a colon. Note that Python
+ style comments are ignored so the following lines return True:
+ - def foo():
+ - def foo(): # Bar
+ - if(foo):
+
+ But some code may confuse this function. For example the following are
+ also consider to "end_with_colon" even though they don't for Python
+ - foo(": #")
+ - foo() # No need for :
+ -->
+ <xsl:template name="ends_with_colon">
+ <xsl:param name="line"/>
+ <xsl:param name="found_colon"/>
+ <xsl:choose>
+ <xsl:when test="$line = ''">
+ <xsl:value-of select="$found_colon"/>
+ </xsl:when>
+ <xsl:when test="starts-with($line, '
')">
+ <xsl:value-of select="$found_colon"/>
+ </xsl:when>
+ <xsl:when test="starts-with($line, ' ')">
+ <xsl:call-template name="ends_with_colon">
+ <xsl:with-param name="line" select="substring($line, 2)"/>
+ <xsl:with-param name="found_colon" select="$found_colon"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:when test="starts-with($line, ':')">
+ <xsl:variable name="rest_is_comment">
+ <xsl:call-template name="is_blank_or_comment">
+ <xsl:with-param name="line" select="substring($line, 2)"/>
+ </xsl:call-template>
+ </xsl:variable>
+ <xsl:choose>
+ <xsl:when test="$rest_is_comment = '1'">
+ <xsl:value-of select="1"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:call-template name="ends_with_colon">
+ <xsl:with-param name="line" select="substring($line, 2)"/>
+ <xsl:with-param name="found_colon" select="0"/>
+ </xsl:call-template>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:call-template name="ends_with_colon">
+ <xsl:with-param name="line" select="substring($line, 2)"/>
+ <xsl:with-param name="found_colon" select="0"/>
+ </xsl:call-template>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:template>
+
+ <!-- Prints one line of python code with proper indent and calls itself
+ recursively for the rest of the text.
+ This template uses "a", "b", "c" and "d" to refer to four key column
+ numbers. They are:
+ - a: the indentation common to all lines in a code snippet. This is
+ stripped out to allow for cleaner code in the xml.
+ - b: the indentation of the most out-dented line of code. This is
+ different from "a" when code is labelled with "Yes:" or "No:"
+ - c: the indentation of the current python block, in other words, the
+ indentation of the first line of this block, which is the
+ indentation of the last line we saw that ended with a colon.
+ - d: the "total" indentation of the line, ignorng possible "Yes:" or
+ "No:" text on the line.
+
+ For example, for the last line of the following code snippet, the
+ positions of a, b, c and d are indicated below:
+ Yes: def Foo():
+ if bar():
+ a += 1
+ baz()
+ a b c d
+
+ The algorithm is:
+ 1) Split the text into first line and the rest. Note that the
+ substring-before function is supposed to handle the case where the
+ character is not present in the string but does not so we
+ automatically ignore the last line of the snippet which is always
+ empty (the closing snippet tag). This is consistent with the
+ behavior or print_without_leading_chars.
+ 2) If the current is empty (only whitespace), print newline and call
+ itself recursively on the rest of the text with the rest of the
+ parameters unchanged.
+ 3) Otherwise, measure "d"
+ 4) Measure "c" by taking:
+ - the value of "d" if the previous line ended with a colon or the
+ current line is outdented compare to the previous line
+ - the indent of the previous line otherwise
+ 5) Print line[a:c] (Note that we ignore line[0:a])
+ 6) Print line[b:c] in an external span (in order to double the block
+ indent in external code).
+ 7) Print line[c:<end>] with function names processed to produce both
+ internal and external names.
+ 8) If there are more lines, recurse.
+ -->
+ <xsl:template name="print_python_line_recursively">
+ <xsl:param name="text"/>
+ <xsl:param name="a"/>
+ <xsl:param name="b"/>
+ <xsl:param name="previous_indent"/>
+ <xsl:param name="previous_ends_with_colon"/>
+ <xsl:param name="is_first_line"/>
+ <xsl:variable name="line" select="substring-before($text, '
')"/>
+ <xsl:variable name="rest" select="substring-after($text, '
')"/>
+ <xsl:choose>
+ <xsl:when test="substring($line, $b) = '' and not($rest = '')">
+ <xsl:if test="not($is_first_line = '1')">
+ <xsl:text>
</xsl:text>
+ </xsl:if>
+ <xsl:call-template name="print_python_line_recursively">
+ <xsl:with-param name="text" select="$rest"/>
+ <xsl:with-param name="a" select="$a"/>
+ <xsl:with-param name="b" select="$b"/>
+ <xsl:with-param name="previous_indent" select="$previous_indent"/>
+ <xsl:with-param name="previous_ends_with_colon"
+ select="$previous_ends_with_colon"/>
+ <xsl:with-param name="is_first_line" select="0"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:variable name="indent_after_b">
+ <xsl:call-template name="num_leading_spaces_one_line">
+ <xsl:with-param name="text" select="substring($line, $b + 1)"/>
+ <xsl:with-param name="current_count" select="0"/>
+ </xsl:call-template>
+ </xsl:variable>
+ <xsl:variable name="d" select="$b + $indent_after_b"/>
+ <xsl:variable name="c">
+ <xsl:choose>
+ <xsl:when test="$previous_ends_with_colon = '1' or
+ $previous_indent > $d">
+ <xsl:value-of select="$d"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$previous_indent"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
+
+ <xsl:value-of select="substring($line, $a + 1, $c - $a)"/>
+ <span class="external">
+ <xsl:value-of select="substring($line, $b + 1, $c - $b)"/>
+ </span>
+ <xsl:call-template name="munge_function_names_in_text">
+ <xsl:with-param name="stripped_line"
+ select="substring($line, $c + 1)"/>
+ </xsl:call-template>
+ <xsl:if test="not(substring($rest, $a) = '')">
+ <xsl:text>
</xsl:text>
+ <xsl:call-template name="print_python_line_recursively">
+ <xsl:with-param name="text" select="$rest"/>
+ <xsl:with-param name="a" select="$a"/>
+ <xsl:with-param name="b" select="$b"/>
+ <xsl:with-param name="previous_indent" select="$c"/>
+ <xsl:with-param name="previous_ends_with_colon">
+ <xsl:call-template name="ends_with_colon">
+ <xsl:with-param name="line" select="$line"/>
+ <xsl:with-param name="found_colon" select="0"/>
+ </xsl:call-template>
+ </xsl:with-param>
+ <xsl:with-param name="is_first_line" select="0"/>
+ </xsl:call-template>
+ </xsl:if>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:template>
+
+ <!-- Print python code with internal and external styles.
+ In order to conform with PEP-8 externally, we identify 2-space indents
+ and an external-only 4-space indent.
+ Function names that are marked with $$FunctionName/$$ have an external
+ lower_with_underscore version added. -->
+ <xsl:template name="print_python_code">
+ <xsl:param name="text"/>
+
+ <xsl:variable name="a">
+ <xsl:call-template name="num_leading_spaces">
+ <xsl:with-param name="text" select="."/>
+ <xsl:with-param name="max_so_far" select="1000"/>
+ </xsl:call-template>
+ </xsl:variable>
+
+ <xsl:variable name="b">
+ <xsl:call-template name="code_start_index">
+ <xsl:with-param name="text" select="$text"/>
+ <xsl:with-param name="current_count" select="0"/>
+ </xsl:call-template>
+ </xsl:variable>
+
+ <xsl:call-template name="print_python_line_recursively">
+ <xsl:with-param name="text" select="$text"/>
+ <xsl:with-param name="a" select="$a"/>
+ <xsl:with-param name="b" select="$b"/>
+ <xsl:with-param name="previous_indent" select="$b"/>
+ <xsl:with-param name="previous_ends_with_colon" select="0"/>
+ <xsl:with-param name="is_first_line" select="1"/>
+ </xsl:call-template>
+ </xsl:template>
+
+ <!-- Given a block of text, each line terminated by \n, and a number n,
+ emits the text with the first n characters of each line
+ deleted. If strip==1, then we omit blank lines at the beginning
+ and end of the text (but not the middle!) -->
+ <!-- TODO(csilvers): deal well with leading tabs (treat as 8 spaces?) -->
+ <xsl:template name="print_without_leading_chars">
+ <xsl:param name="text"/>
+ <xsl:param name="trim_count"/>
+ <xsl:param name="strip"/>
+ <xsl:param name="is_firstline"/>
+ <!-- TODO(csilvers): deal with case text doesn't end in a newline -->
+ <xsl:variable name="line" select="substring-before($text, '
')"/>
+ <xsl:variable name="rest" select="substring-after($text, '
')"/>
+ <xsl:variable name="stripped_line" select="substring($line, $trim_count+1)"/>
+ <xsl:choose>
+ <!-- $line (or $rest) is considered empty if we'd trim the entire line -->
+ <xsl:when test="($strip = '1') and ($is_firstline = '1') and
+ (string-length($line) <= $trim_count)">
+ </xsl:when>
+ <xsl:when test="($strip = '1') and
+ (string-length($rest) <= $trim_count)">
+ <xsl:value-of select="$stripped_line"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$stripped_line"/>
+ <xsl:text>
</xsl:text>
+ </xsl:otherwise>
+ </xsl:choose>
+ <xsl:if test="not($rest='')">
+ <xsl:call-template name="print_without_leading_chars">
+ <xsl:with-param name="text" select="$rest"/>
+ <xsl:with-param name="trim_count" select="$trim_count"/>
+ <xsl:with-param name="strip" select="$strip"/>
+ <xsl:with-param name="is_firstline" select="0"/>
+ </xsl:call-template>
+ </xsl:if>
+ </xsl:template>
+
+ <!-- Given a line of code, find function names that are marked with $$ /$$ and
+ print out the line with the internal and external versions of the
+ function names.-->
+ <xsl:template name="munge_function_names_in_text">
+ <xsl:param name="stripped_line"/>
+ <xsl:choose>
+ <xsl:when test="contains($stripped_line, '$$')">
+ <xsl:value-of select="substring-before($stripped_line, '$$')"/>
+ <xsl:call-template name="print_function_name">
+ <xsl:with-param name="text" select="substring-after(substring-before($stripped_line, '/$$'), '$$')"/>
+ </xsl:call-template>
+ <xsl:call-template name="munge_function_names_in_text">
+ <xsl:with-param name="stripped_line" select="substring-after($stripped_line, '/$$')"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$stripped_line"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:template>
+
+ <!-- Given a function name, print out both the internal and external version
+ of the function name in their respective spans.-->
+ <xsl:template name="print_function_name">
+ <xsl:param name="text"/>
+ <xsl:call-template name="convert_camel_case_to_lowercase_with_under">
+ <xsl:with-param name="text" select="$text"/>
+ </xsl:call-template>
+ </xsl:template>
+
+ <!-- Given a single word of text convert it from CamelCase to
+ lower_with_under.
+ This means replacing each uppercase character with _ followed by the
+ lowercase version except for the first character which is replaced
+ without adding the _.-->
+ <xsl:template name="convert_camel_case_to_lowercase_with_under">
+ <xsl:param name="text"/>
+ <xsl:param name="is_recursive_call"/>
+ <xsl:variable name="first_char" select="substring($text, 1, 1)"/>
+ <xsl:variable name="rest" select="substring($text, 2)"/>
+ <xsl:choose>
+ <xsl:when test="contains('ABCDEFGHIJKLMNOPQRSTUVWXYZ', $first_char)">
+ <xsl:if test="$is_recursive_call='1'">
+ <xsl:text>_</xsl:text>
+ </xsl:if>
+ <xsl:value-of select="translate($first_char, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')"/>
+ </xsl:when>
+ <xsl:otherwise>
+ <xsl:value-of select="$first_char" />
+ </xsl:otherwise>
+ </xsl:choose>
+ <xsl:if test="not($rest='')">
+ <xsl:call-template name="convert_camel_case_to_lowercase_with_under">
+ <xsl:with-param name="text" select="$rest"/>
+ <xsl:with-param name="is_recursive_call" select="1"/>
+ </xsl:call-template>
+ </xsl:if>
+ </xsl:template>
+</xsl:stylesheet>
+
diff --git a/vimscriptfull.xml b/vimscriptfull.xml
new file mode 100644
index 0000000..fa7e343
--- /dev/null
+++ b/vimscriptfull.xml
@@ -0,0 +1,1534 @@
+<?xml version = '1.0'?>
+<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
+<GUIDE title="Google Vimscript Guide">
+ <p class="revision">
+
+ Revision 1.1
+ </p>
+
+
+ <address>
+ Nate Soares<br/>
+ Joshua Hoak<br/>
+ David Barnett<br/>
+ </address>
+
+ <OVERVIEW>
+ <CATEGORY title="Background">
+ <p>
+ This is the in-depth vimscript guide. If you're just a casual user
+ looking to write a plugin, the
+ <a href="vimscriptguide.html">abbreviated style guide</a> is for you.
+ </p>
+ <p>
+ This rather rotund guide dives into justifications and clarifications.
+ It provides an idealized set of rules that are rather too draconian to
+ push on casual scripters.
+ </p>
+
+ <p>
+ It's for users who want to know why certain decisions were made in the
+ abbreviated guide and who want to learn a thing or two about using
+ vimscript safely.
+ </p>
+ <p>
+ Fair warning: Vimscript is a maddening abyss. When you gaze into it, it
+ gazes also into you. Proceed with caution.
+ </p>
+ </CATEGORY>
+ </OVERVIEW>
+
+ <CATEGORY title="Portability">
+ <p>
+ Vim is highly configurable. Users can change many of the default
+ settings, including the case sensitivity, the regular expression rules,
+ the substitution rules, and more. In order for your vimscript to work
+ for all users, follow these guidelines:
+ </p>
+ <ul>
+ <li>
+ Always prefix regular expressions with one of <code>\m</code>,
+ <code>\v</code>, <code>\M</code>, or <code>\V</code> (prefer
+ tersity)
+ <ul>
+ <li>
+ Users can change the global "magic level" of regular expressions.
+ This changes how atoms are parsed in regular expressions,
+ including <code>.</code>, <code>*</code>, and <code>{</code>.
+ </li>
+ <li>
+ Even if your regular expression does not contain characters which
+ are affected by the <code>magic</code> setting you must prefix it
+ with one of the magic control atoms. This future-proofs your
+ regular expression against other devs modifying it and forgetting
+ to add the control atom.
+ </li>
+ <li>
+ If you have no opinion about what type of regular expression to
+ use, prefer the one which makes your regular expression most
+ concise.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Avoid using <code>:s[ubstitute]</code> in scripts.
+ <ul>
+ <li>
+ <code>:substitute</code> moves the cursor.
+ </li>
+ <li>
+ <code>:substitute</code> outputs an error message when the match
+ does not exist.
+ </li>
+ <li>
+ The meaning of the <code>g</code> flag depends upon the
+ <code>gdefault</code> setting. If you do use
+ <code>:substitute</code> you must save <code>gdefault</code>, set
+ it to <code>0</code> or <code>1</code>, perform the substitution,
+ and then restore it.
+ </li>
+ <li>
+ Script authors who want a safe way to replace text in the buffer
+ are encouraged to use <code>maktaba#buffer#Replace</code>.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Always use case-explicit operators for strings (<code>=~#</code> and
+ <code>=~?</code>, never <code>=~</code>).
+ <ul>
+ <li>
+ This also applies to <code>!~ == != > >= <</code> and
+ <code><=</code>
+ </li>
+ <li>
+ This only applies for strings. <code>==</code> and
+ <code>>=</code> are fine for numbers, but <code>==#</code> and
+ <code>>=#</code> must be used for strings.
+ </li>
+ <li>
+ The behavior of <code>=~</code> and friends is dependant upon the
+ <code>ignorecase</code> setting.
+ </li>
+ <li>
+ You may break this rule when you explicitly want to obey the
+ user's <code>ignorecase</code> setting. Be prepared to justify
+ your reasoning.
+ </li>
+ </ul>
+ </li>
+ <li>
+ When using regular expressions as arguments to functions, prepend them
+ with <code>\c</code> or <code>\C</code>.
+ <ul>
+ <li>
+ This forces case to be either explicitly matched or ignored.
+ </li>
+ <li>
+ This is recommended, but not required, when comparing regexes with
+ operators that specify case sensitivity (<code>=~#</code>, etc.).
+ </li>
+ <li>
+ This rule applies when your regexes are matching syntax, external
+ APIs, external messages, and most other cases.
+ </li>
+ <li>
+ It does not apply when matching text in the buffer. When matching
+ text in the buffer you should honor the <code>ignorecase</code>
+ setting.
+ </li>
+ <li>
+ You may also ignore this rule any time that you explicitly want to
+ honor the <code>ignorecase</code> setting. Be prepared to justify
+ your reasoning.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Always use <code>normal!</code> instead of <code>normal</code>.
+ <ul>
+ <li>
+ If you forgo the <code>!</code> the command will use the user's
+ key mappings and you have literally no idea what your macro will
+ do.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Always use the <code>noremap</code> family of commands.
+ <ul>
+ <li>
+ Your plugins generally shouldn't introduce mappings, but if they
+ do, the <code>map</code> command respects the users existing
+ mappings and could do anything.
+ </li>
+ </ul>
+ </li>
+ <li>
+ When using <code>catch</code>, match the error code rather than the
+ error text.
+ <ul>
+ <li>
+ The error text may be locale-dependant.
+ </li>
+ <li>
+ See <code>:help error-messages</code>.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ In general, guard all commands and functions against user settings.
+ </p>
+
+ </CATEGORY>
+ <CATEGORY title="Language Guide">
+ <ul>
+
+
+ <li>
+ Line continuations: <strong>Yes</strong>
+ <ul>
+
+ <li>
+ Plugins that support vi compatibility mode must save and restore
+ compatibility options as described in the
+ <strong>Errata section</strong> so line continuations work properly.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Exceptions: <strong>Yes, with caution</strong>
+ <ul>
+ <li>
+ Always use an error code in thrown exception messages.
+ </li>
+ <li>
+ Prefer the <code>maktaba#error</code> codes found in
+ <code>maktaba</code>.
+ </li>
+ <li>
+ Fall back to the vim error codes. See
+ <code>:help error-messages</code>.
+ </li>
+ <li>
+ Generate custom error messages using
+ <code>maktaba#error#Message</code>.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Global Variables: <strong>As configuration only</strong>
+ <ul>
+ <li>
+ See the plugin guide.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Messaging: <strong>As little as possible.</strong>
+ <ul>
+ <li>
+ Loud scripts are annoying.
+ </li>
+ <li>
+ Message the user when an error has occured.
+ </li>
+ <li>
+ Message the user when an operation which takes a long time has
+ begun work.
+ </li>
+ <li>
+ Avoid messaging otherwise.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Type checking:
+ <strong>Use strict and explicit checks where possible.</strong>
+ <ul>
+ <li>
+ Vimscript has unsafe, unintuitive behavior when dealing with some
+ types. For instance, <code>0 == 'foo'</code> evaluates to true.
+ </li>
+ <li>
+ Use strict comparison operators where possible. When comparing
+ against a string literal, use the <code>is#</code> operator.
+ Otherwise, prefer <code>maktaba#value#IsEqual</code> or check
+ <code>type()</code> explicitly.
+ </li>
+ <li>
+ Check variable types explicitly before using them. Use functions
+ from <code>maktaba#ensure</code>, or check
+ <code>maktaba#value</code> or <code>type()</code> and throw your own
+ errors.
+ </li>
+ <li>
+ Use <code>:unlet</code> for variables that may change types,
+ particularly those assigned inside loops.
+ </li>
+ </ul>
+ </li>
+ <li>
+ FuncRefs: <strong>No in most cases.</strong>
+ <ul>
+ <li>
+ FuncRefs have inconsistently enforced naming restrictions.
+ (Functions can have names that FuncRefs can not.)
+ </li>
+ <li>
+ FuncRefs have inconsistent ability to be reassigned (in Vim
+ 7.2 and before you must unlet a FuncRef before assigning it).
+ </li>
+ <li>
+ In most instances where a FuncRef is needed a string works
+ just as well: just pass the string that you would use to make
+ the FuncRef.
+ </li>
+ <li>
+ Consider using <code>maktaba#function</code> instead to create and
+ manipulate handles to functions.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Python: <strong>Sparingly</strong>
+ <ul>
+
+ <li>
+ Hurts code reuse since python code embedded in python plugins is
+ awkward to share between plugins.
+ </li>
+ <li>
+ Using python introduces python language version dependencies, which
+ are likely to get stale.
+ </li>
+ <li>
+ Exception: It's reasonable to use python for plugin functionality
+ that needs to do work in the background, as vimscript can not do
+ this.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Ruby: <strong>No</strong>
+ <ul>
+ <li>
+ We can not assume ruby interoperability.
+ </li>
+ <li>
+ You shouldn't depend upon the version of the ruby language that the
+ user has installed.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Lua: <strong>No</strong>
+ <ul>
+ <li>
+ For the same reasons an Ruby.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Dict Functions: <strong>Encouraged</strong>
+ <ul>
+ <li>
+ Vimscript can attach functions to dictionaries. Such functions
+ have access to the <code>self</code> parameter which access
+ the dict state.
+ </li>
+ <li>
+ Use these where you would use a class in python.
+ </li>
+ <li>
+ Do not over-use this feature; it is not necessary for helper
+ functions or API functions, only for encapsulated objects.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <p>
+ All other language features are fair game.
+ </p>
+ </CATEGORY>
+ <CATEGORY title="Structure">
+ <ul>
+ <li>
+ Provided functionality should be packed into modular plugins.
+ <ul>
+ <li>
+ Every function in your plugin should be specific to your
+ plugin.
+ </li>
+ <li>
+ General utility functions should be abstracted into library plugins.
+ </li>
+ <li>
+ Manage dependencies with <code>maktaba</code>.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <code>plugin-names-like-this</code>
+ <ul>
+ <li>
+ Plugin names should be descriptive and concise.
+ </li>
+
+
+ </ul>
+ </li>
+ <li>
+ Each plugin must consist of one directory (or code repository), sharing
+ a name with the plugin (with a "vim-" prefix or ".vim" suffix if
+ desired).
+ </li>
+ <li>
+ Plugin metadata should be declared in the addon-info.json format (see
+ the <a href="https://github.com/MarcWeber/vim-addon-manager/blob/master/doc/vim-addon-manager-additional-documentation.txt">VAM documentation</a> for details).
+ </li>
+ <li>
+ Functions should go in the <code>autoload/</code> subdirectory of
+ your plugin.
+ <ul>
+ <li>
+ This allows them to be late-loaded, which speeds up startup
+ time.
+ </li>
+ <li>
+ This helps vim enforce namespacing conventions.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Each file in the <code>plugin/</code> or <code>instant/</code> directory
+ should begin with the boilerplate
+ <CODE_SNIPPET>
+ let [s:plugin, s:enter] = maktaba#plugin#Enter(expand('<sfile>:p'))
+ if !s:enter
+ finish
+ endif
+ </CODE_SNIPPET>
+ (This prevents re-entry and allows users to selectively disable
+ functionality.)
+ </li>
+ <li>
+ User configuration should be via plugin flags defined in
+ <code>instant/flags.vim</code>.
+ <ul>
+ <li>
+ Define flags with
+ <code>call s:plugin.Flag('FLAGNAME', DEFAULT_VALUE)</code>.
+ </li>
+ <li>
+ Users can configure these flags using the <code>:Glaive</code>
+ command (see <a href="https://github.com/google/glaive">glaive</a>).
+ </li>
+ </ul>
+ </li>
+ <li>
+ Commands, autocommands, mappings, and settings changes should
+ occur either in the <code>plugin/</code> or the
+ <code>ftplugin/</code> subdirectories.
+ <ul>
+ <li>
+ All commands should be defined in <code>plugin/commands.vim</code>
+ or <code>ftplugin/</code> files.
+ </li>
+ <li>
+ Autocommands should be defined in <code>plugin/autocmds.vim</code>,
+ inside an augroup.
+ </li>
+ <li>
+ Mappings should be defined in <code>plugin/mappings.vim</code> and
+ will be disabled unless explicitly enabled by users.
+ </li>
+ <li>
+ If the plugin configures any standard vim settings, those should be
+ configured in <code>plugin/settings.vim</code> or
+ <code>instant/settings.vim</code>.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Avoid using the <code>after/</code> subdirectory.
+ <ul>
+ <li>
+ <code>after/</code> should be reserved for the user.
+ </li>
+ <li>
+ It is difficult for the user to add their own overrides when
+ plugins use <code>after/</code>.
+ </li>
+ </ul>
+ </li>
+ </ul>
+
+ <STYLEPOINT title="Libraries vs. Functionality">
+ <SUMMARY>
+ Separate library-providing plugins from command-providing plugins.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Many plugins provide either user functionality (commands,
+ autocommands, etc) or an API (of autoloaded functions) but not both.
+ This separation is encouraged, as it allows other plugins to pull in a
+ library without also pulling in commands, setting changes, and other
+ plugin functionality that affects the end user.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Configuration">
+ <SUMMARY>
+ Don't clobber user settings. Provide as much configurability as
+ possible: that's what Vim's all about.
+ </SUMMARY>
+ <BODY>
+ <ul>
+ <li>
+ Use maktaba flags for plugin configuration. Users can configure them
+ using the <code>:Glaive</code> command.
+
+ </li>
+ <li>
+ Check if configuration variables exist before setting them.
+ <CODE_SNIPPET>
+ if !exists('g:myplugin_option')
+ let g:myplugin_option = 1
+ endif
+ </CODE_SNIPPET>
+ </li>
+ </ul>
+ </BODY>
+ </STYLEPOINT>
+ </CATEGORY>
+ <CATEGORY title="Style Guide">
+ <p>
+ Follow google-wide style conventions. Mimic google python style when
+ in doubt.
+ </p>
+
+
+
+ <STYLEPOINT title="Documentation">
+ <SUMMARY>
+ Use <a href="https://github.com/google/vimdoc">vimdoc</a>.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Provide help files generated by
+ <a href="https://github.com/google/vimdoc">vimdoc</a>. Write
+ documentation in .vim files in conformance with the vimdoc standards
+ and include fields like "description" and "author" in the
+ addon-info.json file (see the
+ <a href="https://github.com/MarcWeber/vim-addon-manager/blob/master/doc/vim-addon-manager-additional-documentation.txt">VAM documentation</a>).
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Whitespace">
+ <SUMMARY>
+ Follow google-wide conventions.
+ </SUMMARY>
+ <BODY>
+ <ul>
+ <li>
+ Use two spaces for indents.
+ </li>
+ <li>
+ Do not use tabs.
+ </li>
+ <li>
+ Use spaces around operators except for arguments to commands.
+ <ul>
+ <li>
+ Using spaces around operators for commands is often invalid
+ syntax. This is inconsistently enforced by vimscript. To be
+ safe, always omit whitespace around arguments to commands.
+ </li>
+ <li>
+ <CODE_SNIPPET>
+ let s:variable = "concatenated " . "strings"
+ command -range=% MyCommand
+ </CODE_SNIPPET>
+ <BAD_CODE_SNIPPET>
+ let s:variable="concatenated "."strings"
+ command -range = % MyCommand
+ </BAD_CODE_SNIPPET>
+ </li>
+ </ul>
+ </li>
+ <li>
+ Do not introduce trailing whitespace.
+ <ul>
+ <li>
+ You need not go out of your way to remove it.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Restrict lines to 80 columns wide.
+ </li>
+ <li>
+ Indent continued lines by two tabs (four spaces).
+ </li>
+ <li>
+ Do not waste whitespace aligning common segments of similar
+ commands. It is both difficult and expensive to maintain.
+ <ul>
+ <li>
+ <CODE_SNIPPET>
+ command -bang MyCommand call myplugin#foo()
+ command MyCommand2 call myplugin#bar()
+ </CODE_SNIPPET>
+ <BAD_CODE_SNIPPET>
+ command -bang MyCommand call myplugin#foo()
+ command MyCommand2 call myplugin#bar()
+ </BAD_CODE_SNIPPET>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <SUBSECTION title="Line Continuations">
+ <ul start="7">
+ <li>
+ Prefer line continuations on semantic boundaries.
+ <ul>
+ <li>
+ <CODE_SNIPPET>
+ command SomeLongCommand
+ \ call some#function()
+ </CODE_SNIPPET>
+ <BAD_CODE_SNIPPET>
+ command SomeLongCommand call
+ \ some#function()
+ </BAD_CODE_SNIPPET>
+ </li>
+ <li>
+ Use your best judgement.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Place one space after the backslash denoting a line continuation.
+ <ul>
+ <li>
+ When continuing a multi-line command a pipe can be substituted
+ for this space as necessary, as follows:
+ <CODE_SNIPPET>
+ autocommand BufEnter <buffer>
+ \ if !empty(s:var)
+ \| call some#function()
+ \|else
+ \| call some#function(s:var)
+ \|endif
+ </CODE_SNIPPET>
+ </li>
+ </ul>
+ </li>
+ <li>
+ Do not continue multi-line commands when you can avoid it. Prefer
+ function calls.
+ </li>
+ </ul>
+ </SUBSECTION>
+ <SUBSECTION title="Comments">
+ <ul>
+ <li>
+ Place a space after the <code>"</code> before the comment text.
+ <ul>
+ <li>
+ <CODE_SNIPPET>
+ " I am a line comment.
+ call call(s:my_function)
+ </CODE_SNIPPET>
+ </li>
+ </ul>
+ </li>
+ <li>
+ Do not use inline comments.
+ <ul>
+ <li>
+ Some commands treat them as comments and others as unclosed
+ quotes. There are many edge cases. It's difficult to get
+ right and difficult to maintain.
+ </li>
+ <li>
+ Where you would use an inline comment, put a line comment on
+ the line above.
+ </li>
+ </ul>
+ </li>
+ <li>
+ When leaving blank lines in comments, include the quote in the
+ blank line.
+ <ul>
+ <li>
+ <CODE_SNIPPET>
+ " I am one continuous
+ "
+ " comment block
+ </CODE_SNIPPET>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </SUBSECTION>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Variables">
+ <SUMMARY>
+ <p>
+ <code>plugin-names-like-this</code>,
+ <code>FunctionNamesLikeThis</code>,
+ <code>CommandNamesLikeThis</code>,
+ <code>augroup_names_like_this</code>,
+ <code>variable_names_like_this</code>.
+ </p>
+ <p>
+ Prefix all variables with their scope.
+ </p>
+ </SUMMARY>
+ <BODY>
+ <ul>
+ <li>
+ <code>variable_names_like_this</code>
+ <ul>
+ <li>
+ FuncRef variables count as functions and should be named like
+ functions.
+ </li>
+ <li>
+ This (pathological) convention is enforced by vim itself.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Prefix global variables with <code>g:</code>
+ <ul>
+ <li>
+ Vimscript allows you to create global variables without
+ prefixing them.
+ </li>
+ <li>
+ It is very bad practice to introduce non-prefixed global
+ variables into scope.
+ </li>
+ <li>
+ Global variables should only be used for plugin configuration.
+ </li>
+ <li>
+ This does not apply to functions defined in
+ <code>autoload</code> directories.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Prefix script-local variables with <code>s:</code>
+ <ul>
+ <li>
+ This prevents namespace collisions between plugins.
+ </li>
+ <li>
+ This also applies to script-local functions.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Prefix function arguments with <code>a:</code>
+ <ul>
+ <li>
+ This is enforced by vim itself.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Prefix function-local variables with <code>l:</code>
+ <ul>
+ <li>
+ This is not enforced by vimscript but is good practice.
+ </li>
+ <li>
+ It helps you remember that all other variables must be
+ prefixed with scope.
+ </li>
+ <li>
+ <code>l:</code> disambiguates between function-local and
+ vim-predefined variables. For example, <code>count</code>
+ refers to
+ <code>v:count</code>, not <code>l:count</code>.
+ </li>
+ <li>
+ It future proofs your scripts against the introduction of new
+ vim-predefined variables.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Prefix pre-defined vim variables with <code>v:</code>
+ <ul>
+ <li>
+ This is not enforced by vimscript but is good practice.
+ </li>
+ <li>
+ It provides context as to where the (undeclared) variable is
+ coming from.
+ </li>
+ <li>
+ It reminds you that the variable can not be assigned to.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Prefix buffer-local variables with <code>b:</code>
+ <ul>
+ <li>
+ This is useful for plugins that keep per-buffer state.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Strings">
+ <SUMMARY>
+ Prefer single quotes.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Prefer single quoted strings. Specifically, in order of precedence:
+ </p>
+ <ul>
+ <li>
+ Always use single quotes for regular expressions.
+ <ul>
+ <li>
+ <code>'\s*'</code> is not the same as <code>"\s*"</code>
+ </li>
+ <li>
+ Single quotes will prevent the need for excessive backslashes.
+ </li>
+ <li>
+ Double single quotes escape to one single quote in single
+ quoted strings: <code>'example ('')'</code> represents the
+ string
+ <code>example (')</code>
+ </li>
+ </ul>
+ </li>
+ <li>
+ If your string requires escape characters (<code>\n</code>,
+ <code>\t</code>, etc.) use double quotes.
+ <ul>
+ <li>
+ Escapes can not be expressed in single quoted strings.
+ </li>
+ <li>
+ Remember that <code>'\n'</code> in a regex does not represent a
+ newline, but rather "\n". You only need to use double quotes
+ when you want to embed the represented character itself (e.g. a
+ newline) in the string.
+ </li>
+ </ul>
+ </li>
+ <li>
+ If your string contains no escapes nor single quotes, use single
+ quoted strings.
+ <ul>
+ <li>
+ Most strings in vimscript are regexes, so this provides maximum
+ consistency.
+ </li>
+ </ul>
+ </li>
+ <li>
+ If your non-regex string contains single quotes but no double
+ quotes, use double quotes.
+ <ul>
+ <li>
+ Don't bother escaping strings if you don't have to.
+ </li>
+ <li>
+ This is similar to the python string rules.
+ </li>
+ </ul>
+ </li>
+ <li>
+ If your string contains both single and double quotes, use whichever
+ quoting style requires less escaping.
+ <ul>
+ <li>
+ Break ties in favor of single quotes.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Settings">
+ <SUMMARY>
+ Prefer long names. Set settings locally.
+ </SUMMARY>
+ <BODY>
+ <ul start="6">
+ <li>
+ Prefer long names of built in settings (i.e. <code>tabstop</code>
+ over
+ <code>ts</code>).
+ </li>
+ <li>
+ Set local settings unless you explicitly want to set global
+ settings.
+ <ul>
+ <li>
+ Use <code>setlocal</code> and <code>&l:</code> instead of
+ <code>set</code> and <code>&</code>.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </BODY>
+ </STYLEPOINT>
+ </CATEGORY>
+ <CATEGORY title="Usage Guide">
+ <p>
+ Vim plugins should provide any or all of the following:
+ <strong>Commands,</strong> <strong>Autocommands,</strong>
+ <strong>Functions,</strong> <strong>Statusline Flags, and</strong>
+ <strong>Mappings.</strong>
+ </p>
+
+ <STYLEPOINT title="Commands">
+ <SUMMARY>
+ <ul>
+ <li>Define in <code>plugin/commands.vim</code>.</li>
+ <li>CommandNamesLikeThis.</li>
+ <li>Prefer semantic names to a unified prefix.</li>
+ <li>Do not use <code>[!]</code></li>
+ <li>Extract logic into functions.</li>
+ </ul>
+ </SUMMARY>
+ <BODY>
+ <ul>
+ <li>
+ <code>CommandNamesLikeThis</code>
+ </li>
+ <li>
+ Commands should be defined in one block with no whitespace between
+ them.
+ <ul>
+ <li>
+ Name commands semantically at the expense of a common prefix.
+ </li>
+ <li>
+ <BAD_CODE_SNIPPET>
+ command WhitespaceFixTrailing
+ command WhitespaceFixIndentation
+ </BAD_CODE_SNIPPET>
+ <CODE_SNIPPET>
+ command FixTrailingWhitespace
+ command FixIndentation
+ </CODE_SNIPPET>
+ </li>
+ </ul>
+ </li>
+ <li>
+ Use <code>command</code> without a bang.
+ <ul>
+ <li>
+ This notifies users to command name conflicts immediately at
+ startup.
+ </li>
+ <li>
+ Command name collisions are an error and should not fail
+ silently.
+ </li>
+ <li>
+ Plugins are guarded against re-entry, so a single vim session
+ should never attempt to re-define defined commands.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Do not put logic in commands.
+ <ul>
+ <li>
+ Delegate to functions instead.
+ </li>
+ <li>
+ Pass non-argument command parameters (<code><bang></code>,
+ <code><register></code>, etc.) before argument parameters
+ (<code><f-args></code>, etc.).
+ </li>
+ <li>
+ Otherwise variable-length argument functions are difficult to
+ implement.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Do not autoload commands.
+ <ul>
+ <li>
+ Autoloaded commands will not be available until after a function
+ in the same file is called.
+ </li>
+ <li>
+ Commands intended to be used in the .vimrc should be defined in
+ a <code>instant/commands.vim</code> file in plugins using
+ maktaba, or explicitly installed via an autoload function in
+ non-maktaba plugins.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <SUBSECTION title="Conventions">
+ <ul>
+ <li>
+ Pass <code><bang></code> to functions with
+ <code>'<bang>' == '!'</code>.
+ <ul>
+ <li>
+ The function should receive a boolean parameter, not a string.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </SUBSECTION>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Autocommands">
+ <SUMMARY>
+ <ul>
+ <li>Define in <code>plugin/autocmds.vim</code>.</li>
+ <li>Use augroups.</li>
+ <li>augroup_names_like_this.</li>
+ <li>Clear the augroup first.</li>
+ <li>Extract logic into functions.</li>
+ </ul>
+ </SUMMARY>
+ <BODY>
+ <ul>
+ <li>
+ All autocommands should be defined in the
+ <code>plugin/autocmds.vim</code> file.
+ <ul>
+ <li>
+ This allows users to disable your autocommands with
+ <code>Glaive myplugin !plugin[autocmds]</code>.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Declare all autocommands in an <code>augroup</code> block.
+ <ul>
+ <li>
+ This allows your autocommands to be cleared with
+ <code>autocmd!</code>.
+ </li>
+ <li>
+ If your plugin only has one <code>augroup</code>, the
+ <code>augroup</code> name should be the same as your plugin
+ name, with underscores in place of any hyphens.
+ </li>
+ <li>
+ Otherwise <code>augroup</code> names should start with your
+ plugin name followed by an underscore.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Do not put logic in autocommands.
+ <ul>
+ <li>
+ Delegate to functions instead.
+ </li>
+ </ul>
+ </li>
+ <li>
+ When creating a new <code>augroup</code>, clear it with
+ <code>autocmd!</code>
+ <ul>
+ <li>
+ This allows your plugins to be re-enterable.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Functions">
+ <SUMMARY>
+ <ul>
+ <li>FunctionNamesLikeThis.</li>
+ <li>Autoload all functions.</li>
+ <li>Prefix script-local functions with <code>s:</code></li>
+ <li>Use <code>[!]</code>.</li>
+ <li>Use <code>[abort]</code>.</li>
+ </ul>
+ </SUMMARY>
+ <BODY>
+ <ul>
+ <li>
+ <code>FunctionNamesLikeThis</code>
+ </li>
+ <li>
+ Prefix all script-local functions with <code>s:</code>
+ </li>
+ <li>
+ Do not provide global functions. Use autoloaded functions instead.
+ </li>
+ <li>
+ Place two blank lines between top-level functions.
+ </li>
+ <li>
+ Declare all functions with <code>abort</code>.
+ <ul>
+ <li>
+ If you do not do this, the function's behavior depends upon
+ whether it is called within a <code>try..endtry</code> block
+ somewhere on the stack.
+ </li>
+ <li>
+ The <code>abort</code> keyword forces the function to act
+ consistently.
+ </li>
+ <li>
+ Without it, the function may (or may not) attempt to continue
+ execution after an error occurs.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Use <code>function!</code> with a bang.
+ <ul>
+ <li>
+ This allows developers to re-source their scripts and have the
+ functions reloaded without complaint.
+ </li>
+ <li>
+ Function names should never collide because functions should
+ always be either script-local or defined in an
+ <code>autoload</code> directory.
+ </li>
+ <li>
+ Failing to use a bang in any function in an autoload file will
+ lead to cryptic errors if vim tries to re-source the file
+ (e.g., if you refer to an nonexistent autoload function).
+ </li>
+ </ul>
+ </li>
+ <li>
+ Use <code>...</code> for optional arguments, not for lists of
+ arguments.
+ <ul>
+ <li>
+ Vimscript functions take at most 20 arguments.
+ </li>
+ <li>
+ Lists have no such length restriction.
+ </li>
+ <li>
+ Your function is likely to break when given too many arguments
+ if you use <code>...</code> for a list of arguments.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Throw exceptions rather than printing errors.
+ <ul>
+ <li>
+ Printed errors can not be caught.
+ </li>
+ <li>
+ Top-level functions expecting errors may catch them and print
+ error messages, but even those should throw their own errors
+ when they choke.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Mappings">
+ <SUMMARY>
+ <ul>
+ <li>
+ Provide opt-in key mappings in <code>plugin/mappings.vim</code>.
+ </li>
+ <li>
+ <code><Plug></code> mappings can be defined in
+ <code>plugin/plugs.vim</code> (unlike mappings.vim, plugs.vim is
+ opt-out).
+ </li>
+ </ul>
+ </SUMMARY>
+ <BODY>
+ <ul>
+ <li>
+ Define key mappings in <code>plugin/mappings.vim</code>, using
+ <code>maktaba#plugin#MapPrefix</code> to get a prefix.
+ <ul>
+ <li>
+ Mappings defined in the special <code>plugin/mappings.vim</code>
+ file will be disabled by default (by the standard
+ <code>maktaba#plugin#Enter()</code> boilerplate).
+ </li>
+ <li>
+ Users can enable key mappings with
+ <code>Glaive myplugin plugin[mappings]</code>.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Make all mappings with <code><unique></code>.
+ <ul>
+ <li>
+ This will inform the user when they have a mapping conflict
+ instead of silently clobbering their existing mappings.
+ </li>
+ </ul>
+ </li>
+ <li>
+ You may provide pseudo-mappings using <code><Plug></code> and
+ your plugin's name in <code>plugin/plugs.vim</code> (separate from
+ standard key mappings).
+ <ul>
+ <li>
+ <code><Plug></code> is a sequence which can not be typed.
+ </li>
+ <li>
+ You can do something like
+ <code>noremap <Plug>namespace#MappingName
+ some_key_sequence</code>
+ and then users can do
+ <code>noremap <leader>x
+ <Plug>namespace#MappingName</code>
+ to take advantage of your pseudo-mapping.
+ </li>
+ <li>
+ Pseudo-mappings should <strong>not</strong> be in
+ <code>plugin/mappings.vim</code> or they will be disabled by
+ default.
+ </li>
+ <li>
+ Such pseudo-mappings should be named <code><Plug></code>
+ followed by your plugin name, a pound sign, and a unique mapping
+ name (CamelCased like a function).
+ </li>
+ </ul>
+ </li>
+ <li>
+ Always use the <code>noremap</code> family of commands. Never use
+ the <code>map</code> family.
+ <ul>
+ <li>
+ <code>map</code> depends upon the user's existing mappings, and
+ could do anything.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Only use <code>noremap</code> for commands that both make a motion
+ and take a range.
+ <ul>
+ <li>
+ <code>noremap</code> makes mappings in normal, visual, and
+ operator-pending modes.
+ </li>
+ <li>
+ If you don't want all these use <code>nnoremap</code>
+ <code>onoremap</code> or <code>vnoremap</code> explicitly.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Always use <code><SID></code> in place of <code>s:</code> when
+ accessing script locals in mappings.
+ <ul>
+ <li>
+ Using <code>s:</code> will often fail as the mapping attempts to
+ type a literal s and colon.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </BODY>
+ </STYLEPOINT>
+ </CATEGORY>
+ <CATEGORY title="Conventions">
+ <STYLEPOINT title="Dependency Checking">
+ <SUMMARY>
+ Declare dependencies in addon-info.json and use <code>maktaba</code>.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Declaring dependencies in addon-info.json allows conformant plugin
+ managers (like VAM) to ensure dependencies are installed. See the
+ <a href="https://github.com/MarcWeber/vim-addon-manager/blob/master/doc/vim-addon-manager-additional-documentation.txt">VAM documentation</a> for details.
+ </p>
+ <p>
+ Calling <code>maktaba#library#Require</code> from dependent code at
+ runtime ensures that dependencies have been installed and that they
+ don't include unsafe non-library files.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Statusline Flags">
+ <SUMMARY>
+ Use <code><plugin-name>#status#Status()</code> or its
+ finer-grained variants to provide statusline flags.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Following is a convention for exposing statusline flags to the user. A
+ plugin should never modify the user's statusline except for when that
+ is the only purpose of the plugin (powerline, etc.).
+ </p>
+ <ul>
+ <li>
+ Provide the
+ <code class="green">Info</code>,
+ <code class="yellow">Alert</code>,
+ <code class="orange">Warning</code>, and
+ <code class="red">Error</code> functions under the
+ <code><plugin-name>#status</code> namespace.
+ </li>
+ <li>
+ <code class="green">Info</code> should provide information about the
+ state of the buffer.
+ <ul>
+ <li>
+ Example: The current git branch.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <code class="yellow">Alert</code> should provide a quiet reminder
+ that the buffer is non-standard.
+ <ul>
+ <li>
+ Example: The readonly setting is on.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <code class="orange">Warning</code> should provide a warning about
+ the current state of the buffer.
+ <ul>
+ <li>
+ Example: The file has been edited elsewhere.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <code class="red">Error</code> should bring to attention a loud
+ issue with the buffer.
+ <ul>
+ <li>
+ Example: The file does not pass the syntax checker.
+ </li>
+ </ul>
+ </li>
+ <li>
+ By following these conventions, users can easily build up their own
+ statusline customizing the verbosity and colors to their tastes.
+ </li>
+ <li>
+ All functions should take no arguments and should return either
+ empty strings or strings enclosed by square brackets, e.g.
+ <code>[Google]</code>. For example:
+ <ul>
+ <li>
+ A trailing whitespace plugin might return <code>[$]</code> if
+ the file contains trailing whitespace
+ </li>
+ <li>
+ A prose writing plugin might return <code>[write]</code> if vim
+ is in writing mode.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Consider providing the
+ <code><plugin-name>#status#Status</code> function.
+ <ul>
+ <li>
+ It should return the first non-empty of <code>Error</code>,
+ <code>Warning</code>, <code>Alert</code>, or <code>Info</code>.
+ </li>
+ <li>
+ This is useful for users who want only the most relevant flag
+ and do not have a colored statusline.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </BODY>
+ </STYLEPOINT>
+ </CATEGORY>
+ <CATEGORY title="Forbidden Commands">
+ <p>
+ These are commands which can only be used by a limited number of
+ plugins, and should not in general be used by yours.
+ </p>
+ <ul>
+ <li>
+ Do not use <code>:match :2match</code> or <code>:3match</code>
+ <ul>
+ <li>
+ These are reserved for the user and for vim itself.
+ </li>
+ <li>
+ Use <code>matchadd()</code> to create a matchlevel unique to your
+ plugin.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Do not use <code>echoerr</code>.
+ <ul>
+ <li>
+ <code>echoerr</code> does not print the red error message that you
+ might think it does.
+ </li>
+ <li>
+ <code>echoerr</code> prints an error message as well as context
+ about the code where <code>echoerr</code> was called.
+ </li>
+ <li>
+ <code>echoerr</code> is best suited for debugging.
+ </li>
+ <li>
+ Use <code>echohl</code> in tandem with <code>echomsg</code> if
+ you want the red error bar.
+ </li>
+ </ul>
+ </li>
+ <li>
+ Use <code>echomsg</code> instead of <code>echo</code>.
+ <ul>
+ <li>
+ <code>echomsg</code> messages can be reviewed with the
+ <code>:messages</code> command.
+ </li>
+ <li>
+ <code>echo</code> messages disappear permanently on redraw, which
+ can be very annoying to users who failed to read the message in
+ time.
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </CATEGORY>
+ <CATEGORY title="Layout">
+ <p>
+ Lay out <code>plugin/</code> files in the following sections, if
+ applicable, separated by two blank lines:
+ </p>
+ <ul>
+ <li>
+ Declaration of script constants
+ </li>
+ <li>
+ Declaration of configuration variables
+ </li>
+ <li>
+ Other declarations (commands in <code>commands.vim</code> file,
+ autocommands in <code>autocmds.vim</code> file, etc.)
+ </li>
+ </ul>
+ <p>
+ Lay out <code>autoload/</code> files in the following sections, if
+ applicable, separated by two blank lines:
+ </p>
+ <ul>
+ <li>
+ <code>maktaba#library#Require</code> calls
+ </li>
+ <li>
+ Script-local variables
+ </li>
+ <li>
+ Script-local functions
+ </li>
+ <li>
+ Private autoloaded functions
+ </li>
+ <li>
+ Public autoloaded functions
+ </li>
+ </ul>
+ <p>
+ This is recommended convention and is not enforced.
+ </p>
+
+ </CATEGORY>
+ <CATEGORY title="Recommended Shortcuts">
+
+ <p>
+ Use the following shortcuts:
+ </p>
+ <ul>
+ <li>
+ <code>catch</code> over <code>catch /.*/</code>
+ </li>
+ <li>
+ <code>return</code> over <code>return 0</code> when the return value
+ has no semantic purpose.
+ </li>
+ </ul>
+
+ </CATEGORY>
+ <CATEGORY title="Errata">
+ <p>
+ This section plumbs some of the darker corners of vimscript, explaining
+ the language pathologies that you wish you didn't have to know.
+
+ </p>
+
+ <STYLEPOINT title="Compatibility Mode">
+ <SUMMARY>
+ If you don't support vi-compatibility mode, fail gracefully.
+ </SUMMARY>
+ <BODY>
+ <p>
+ When <code>compatible</code> is set, many vim features are not
+ available. The vim feature which most commonly affects vimscript
+ authors is line continuations.
+ </p>
+ <p>
+ If you want your plugin to work in vim with vi compatibility on, you
+ will need to save the compatibility options at the beginning of each
+ plugin file, clear them, and restore them at the end of each plugin
+ file. See <code>:help use-cpo-save</code> for details.
+ </p>
+ <p>
+ Plugins that depend on maktaba generally don't need to worry about
+ compatible mode since maktaba currently just disables it, printing a
+ warning.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ </CATEGORY>
+
+ <p align="right">
+ Revision 1.1
+ </p>
+
+
+ <address>
+ Nate Soares<br/>
+ Joshua Hoak<br/>
+ David Barnett<br/>
+ </address>
+</GUIDE>
diff --git a/vimscriptguide.xml b/vimscriptguide.xml
new file mode 100644
index 0000000..2baf3fd
--- /dev/null
+++ b/vimscriptguide.xml
@@ -0,0 +1,412 @@
+<?xml version = '1.0'?>
+<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
+<GUIDE title="Google Vimscript Style Guide">
+ <p class="revision">
+
+ Revision 1.1
+ </p>
+
+
+ <address>
+ Nate Soares<br/>
+ Joshua Hoak<br/>
+ David Barnett<br/>
+ </address>
+
+ <OVERVIEW>
+ <CATEGORY title="Background">
+ <p>
+ This is a casual version of the vimscript style guide, because
+ vimscript is a casual language. When submitting vim plugin code, you
+ must adhere to these rules. For clarifications, justifications, and
+ explanations about the finer points of vimscript, please refer to the
+ <a href="vimscriptfull.xml">heavy guide</a>.
+ </p>
+ </CATEGORY>
+ </OVERVIEW>
+
+ <CATEGORY title="Portability">
+ <p>
+ It's hard to get vimscript right. Many commands depend upon the user's
+ settings. By following these guidelines, you can hope to make your
+ scripts portable.
+ </p>
+ <STYLEPOINT title="Strings">
+ <SUMMARY>Prefer single quoted strings</SUMMARY>
+ <BODY>
+ <p>
+ Double quoted strings are semantically different in vimscript, and
+ you probably don't want them (they break regexes).
+ </p>
+ <p>
+ Use double quoted strings when you need an escape sequence (such as
+ <code>"\n"</code>) or if you know it doesn't matter and you need to
+ embed single quotes.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Matching Strings">
+ <SUMMARY>
+ Use the <code>=~#</code> or <code>=~?</code> operator families over the
+ <code>=~</code> family.
+ </SUMMARY>
+ <BODY>
+ <p>
+ The matching behavior depends upon the user's ignorecase and smartcase
+ settings and on whether you compare them with the <code>=~</code>,
+ <code>=~#</code>, or <code>=~?</code> family of operators. Use the
+ <code>=~#</code> and <code>=~?</code> operator families explicitly
+ when comparing strings unless you explicitly need to honor the user's
+ case sensitivity settings.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Regular Expressions">
+ <SUMMARY>Prefix all regexes with <code>\m\C</code>.</SUMMARY>
+ <BODY>
+ <p>
+ In addition to the case sensitivity settings, regex behavior depends
+ upon the user's nomagic setting. To make regexes act like nomagic and
+ noignorecase are set, prepend all regexes with <code>\m\C</code>.
+ </p>
+ <p>
+ You are welcome to use other magic levels (<code>\v</code>) and case
+ sensitivities (<code>\c</code>) so long as they are intentional and
+ explicit.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Dangerous commands">
+ <SUMMARY>Avoid commands with unintended side effects.</SUMMARY>
+ <BODY>
+ <p>
+ Avoid using <code>:s[ubstitute]</code> as it moves the cursor and
+ prints error messages. Prefer functions (such as
+ <code>search()</code>) better suited to scripts.
+ </p>
+ <p>
+ For many vim commands, functions exist that do the same thing with
+ fewer side effects. See <code>:help functions()</code> for a list of
+ built-in functions.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Fragile commands">
+ <SUMMARY>Avoid commands that rely on user settings.</SUMMARY>
+ <BODY>
+ <p>
+ Always use <code>normal!</code> instead of <code>normal</code>. The
+ latter depends upon the user's key mappings and could do anything.
+ </p>
+ <p>
+ Avoid <code>:s[ubstitute]</code>, as its behavior depends upon a
+ number of local settings.
+ </p>
+ <p>
+ The same applies to other commands not listed here.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Catching Exceptions">
+ <SUMMARY>Match error codes, not error text.</SUMMARY>
+ <BODY>
+ <p>Error text may be locale dependant.</p>
+ </BODY>
+ </STYLEPOINT>
+ </CATEGORY>
+
+ <CATEGORY title="General Guidelines">
+
+
+ <STYLEPOINT title="Messaging">
+ <SUMMARY>Message the user infrequently.</SUMMARY>
+ <BODY>
+ <p>
+ Loud scripts are annoying. Message the user only when:
+ <ul>
+ <li>A long-running process has kicked off.</li>
+ <li>An error has occurred.</li>
+ </ul>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Type checking">
+ <SUMMARY>Use strict and explicit checks where possible.</SUMMARY>
+ <BODY>
+ <p>
+ Vimscript has unsafe, unintuitive behavior when dealing with some
+ types. For instance, <code>0 == 'foo'</code> evaluates to true.
+ </p>
+ <p>
+ Use strict comparison operators where possible. When comparing against
+ a string literal, use the <code>is#</code> operator. Otherwise, prefer
+ <code>maktaba#value#IsEqual</code> or check <code>type()</code>
+ explicitly.
+ </p>
+ <p>
+ Check variable types explicitly before using them. Use functions from
+ <code>maktaba#ensure</code>, or check <code>maktaba#value</code> or
+ <code>type()</code> and throw your own errors.
+ </p>
+ <p>
+ Use <code>:unlet</code> for variables that may change types,
+ particularly those assigned inside loops.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Python">
+ <SUMMARY>Use sparingly.</SUMMARY>
+ <BODY>
+ <p>
+ Use python only when it provides critical functionality, for example
+ when writing threaded code.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Other Languages">
+ <SUMMARY>Use vimscript instead.</SUMMARY>
+ <BODY>
+ <p>
+ Avoid using other scripting languages such as ruby and lua. We can
+ not guarantee that the end user's vim has been compiled with support
+ for non-vimscript languages.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Boilerplate">
+ <SUMMARY>
+ Use <a href="https://github.com/google/maktaba">maktaba</a>.
+ </SUMMARY>
+ <BODY>
+ <p>
+ maktaba removes boilerplate, including:
+ <ul>
+ <li>Plugin creation</li>
+ <li>Error handling</li>
+ <li>Dependency checking</li>
+ </ul>
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Plugin layout">
+ <SUMMARY>Organize functionality into modular plugins</SUMMARY>
+ <BODY>
+ <p>
+ Group your functionality as a plugin, unified in one directory (or
+ code repository) which shares your plugin's name (with a "vim-" prefix
+ or ".vim" suffix if desired). It should be split into plugin/,
+ autoload/, etc. subdirectories as necessary, and it should declare
+ metadata in the addon-info.json format (see the
+ <a href="https://github.com/MarcWeber/vim-addon-manager/blob/master/doc/vim-addon-manager-additional-documentation.txt">VAM documentation</a> for details).
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Functions">
+ <SUMMARY>
+ In the autoload/ directory, defined with <code>[!]</code> and
+ <code>[abort]</code>.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Autoloading allows functions to be loaded on demand, which makes
+ startuptime faster and enforces function namespacing.
+ </p>
+ <p>
+ Script-local functions are welcome, but should also live in autoload/
+ and be called by autoloaded functions.
+ </p>
+ <p>
+ Non-library plugins should expose commands instead of functions.
+ Command logic should be extracted into functions and autoloaded.
+ </p>
+ <p>
+ <code>[!]</code> allows developers to reload their functions
+ without complaint.
+ </p>
+ <p>
+ <code>[abort]</code> forces the function to halt when it encounters
+ an error.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Commands">
+ <SUMMARY>
+ In the plugin/commands.vim or under the ftplugin/ directory, defined
+ without <code>[!]</code>.
+ </SUMMARY>
+ <BODY>
+ <p>
+ General commands go in <code>plugin/commands.vim</code>.
+ Filetype-specific commands go in <code>ftplugin/</code>.
+ </p>
+ <p>
+ Excluding <code>[!]</code> prevents your plugin from silently
+ clobbering existing commands. Command conflicts should be resolved by
+ the user.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Autocommands">
+ <SUMMARY>
+ Place them in plugin/autocmds.vim, within augroups.
+ </SUMMARY>
+ <BODY>
+ <p>
+ Place all autocommands in augroups.
+ </p>
+ <p>
+ The augroup name should be unique. It should either be, or be prefixed
+ with, the plugin name.
+ </p>
+ <p>
+ Clear the augroup with <code>autocmd!</code> before defining new
+ autocommands in the augroup. This makes your plugin re-entrable.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Mappings">
+ <SUMMARY>
+ Place them in <code>plugin/mappings.vim</code>, using
+ <code>maktaba#plugin#MapPrefix</code> to get a prefix.
+ </SUMMARY>
+ <BODY>
+ <p>
+ All key mappings should be defined in
+ <code>plugin/mappings.vim</code>.
+ </p>
+ <p>
+ Partial mappings (see :help using-<Plug>.) should be defined in
+ <code>plugin/plugs.vim</code>.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ <STYLEPOINT title="Settings">
+ <SUMMARY>Change settings locally</SUMMARY>
+ <BODY>
+ <p>
+ Use <code>:setlocal</code> and <code>&l:</code> instead of
+ <code>:set</code> and <code>&</code> unless you have explicit
+ reason to do otherwise.
+ </p>
+ </BODY>
+ </STYLEPOINT>
+ </CATEGORY>
+
+ <CATEGORY title="Style">
+ <p>
+ Follow google style conventions. When in doubt, treat vimscript style
+ like python style.
+ </p>
+
+ <STYLEPOINT title="Whitespace">
+ <SUMMARY>
+ Similar to python.
+
+ <br/>
+ <br/>
+ </SUMMARY>
+ <BODY>
+ <ul>
+ <li>Use two spaces for indents</li>
+ <li>Do not use tabs</li>
+ <li>Use spaces around operators
+ <p>This does not apply to arguments to commands.</p>
+ <CODE_SNIPPET>
+ let s:variable = "concatenated " . "strings"
+ command -range=% MyCommand
+ </CODE_SNIPPET>
+ </li>
+ <li>Do not introduce trailing whitespace
+ <p>You need not go out of your way to remove it.</p>
+ <p>
+ Trailing whitespace is allowed in mappings which prep commands
+ for user input, such as
+ "<code>noremap <leader>gf :grep -f </code>".
+ </p>
+ </li>
+ <li>Restrict lines to 80 columns wide</li>
+ <li>Indent continued lines by four spaces</li>
+ <li>Do not align arguments of commands
+ <BAD_CODE_SNIPPET>
+ command -bang MyCommand call myplugin#foo()
+ command MyCommand2 call myplugin#bar()
+ </BAD_CODE_SNIPPET>
+ <CODE_SNIPPET>
+ command -bang MyCommand call myplugin#foo()
+ command MyCommand2 call myplugin#bar()
+ </CODE_SNIPPET>
+ </li>
+ </ul>
+ </BODY>
+ </STYLEPOINT>
+
+ <STYLEPOINT title="Naming">
+ <SUMMARY>
+ <p>
+ In general, use
+ <code>plugin-names-like-this</code>,
+ <code>FunctionNamesLikeThis</code>,
+ <code>CommandNamesLikeThis</code>,
+ <code>augroup_names_like_this</code>,
+ <code>variable_names_like_this</code>.
+ </p>
+ <p>Always prefix variables with their scope.</p>
+ </SUMMARY>
+ <BODY>
+ <SUBSECTION title="plugin-names-like-this">
+ <p>Keep them short and sweet.</p>
+
+ </SUBSECTION>
+ <SUBSECTION title="FunctionNamesLikeThis">
+ <p>Prefix script-local functions with <code>s:</code></p>
+ <p>Autoloaded functions may not have a scope prefix.</p>
+ <p>
+ Do not create global functions. Use autoloaded functions
+ instead.
+ </p>
+ </SUBSECTION>
+ <SUBSECTION title="CommandNamesLikeThis">
+ <p>Prefer succinct command names over common command prefixes.</p>
+ </SUBSECTION>
+ <SUBSECTION title="variable_names_like_this">
+ <p>Augroup names count as variables for naming purposes.</p>
+ </SUBSECTION>
+ <SUBSECTION title="Prefix all variables with their scope.">
+ <ul>
+ <li>Global variables with <code>g:</code></li>
+ <li>Script-local variables with <code>s:</code></li>
+ <li>Function arguments with <code>a:</code></li>
+ <li>Function-local variables with <code>l:</code></li>
+ <li>Vim-predefined variables with <code>v:</code></li>
+ <li>Buffer-local variables with <code>b:</code></li>
+ </ul>
+ <p>
+ <code>g:</code>, <code>s:</code>, and <code>a:</code> must always
+ be used.
+ </p>
+ <p>
+ <code>b:</code> changes the variable semantics; use it when you
+ want buffer-local semantics.
+ </p>
+ <p>
+ <code>l:</code> and <code>v:</code> should be used for consistency,
+ future proofing, and to avoid subtle bugs. They are not strictly
+ required. Add them in new code but don’t go out of your way to add
+ them elsewhere.
+ </p>
+ </SUBSECTION>
+ </BODY>
+ </STYLEPOINT>
+ </CATEGORY>
+
+ <p align="right">
+ Revision 1.1
+ </p>
+
+
+ <address>
+ Nate Soares<br/>
+ Joshua Hoak<br/>
+ David Barnett<br/>
+ </address>
+</GUIDE>
diff --git a/xmlstyle.html b/xmlstyle.html
new file mode 100644
index 0000000..7566f7e
--- /dev/null
+++ b/xmlstyle.html
@@ -0,0 +1,681 @@
+<style type="text/css">
+/* default css */
+table {
+font-size: 1em;
+line-height: inherit;
+}
+tr {
+text-align: left;
+}
+div, address, ol, ul, li, option, select {
+margin-top: 0px;
+margin-bottom: 0px;
+}
+p {
+margin: 0px;
+}
+body {
+margin: 6px;
+padding: 0px;
+font-family: Verdana, sans-serif;
+font-size: 10pt;
+background-color: #ffffff;
+}
+img {
+-moz-force-broken-image-icon: 1;
+}
+@media screen {
+html.pageview {
+background-color: #f3f3f3 !important;
+}
+body {
+min-height: 1100px;
+counter-reset: __goog_page__;
+}
+* html body {
+height: 1100px;
+}
+.pageview body {
+border-top: 1px solid #ccc;
+border-left: 1px solid #ccc;
+border-right: 2px solid #bbb;
+border-bottom: 2px solid #bbb;
+width: 648px !important;
+margin: 15px auto 25px;
+padding: 40px 50px;
+}
+/* IE6 */
+* html {
+overflow-y: scroll;
+}
+* html.pageview body {
+overflow-x: auto;
+}
+/* Prevent repaint errors when scrolling in Safari. This "Star-7" css hack
+targets Safari 3.1, but not WebKit nightlies and presumably Safari 4.
+That's OK because this bug is fixed in WebKit nightlies/Safari 4 :-). */
+html*#wys_frame::before {
+content: '\A0';
+position: fixed;
+overflow: hidden;
+width: 0;
+height: 0;
+top: 0;
+left: 0;
+}
+.writely-callout-data {
+display: none;
+*display: inline-block;
+*width: 0;
+*height: 0;
+*overflow: hidden;
+}
+.writely-footnote-marker {
+background-image: url('images/footnote_doc_icon.gif');
+background-color: transparent;
+background-repeat: no-repeat;
+width: 7px;
+overflow: hidden;
+height: 16px;
+vertical-align: top;
+-moz-user-select: none;
+}
+.editor .writely-footnote-marker {
+cursor: move;
+}
+.writely-footnote-marker-highlight {
+background-position: -15px 0;
+-moz-user-select: text;
+}
+.writely-footnote-hide-selection ::-moz-selection, .writely-footnote-hide-selection::-moz-selection {
+background: transparent;
+}
+.writely-footnote-hide-selection ::selection, .writely-footnote-hide-selection::selection {
+background: transparent;
+}
+.writely-footnote-hide-selection {
+cursor: move;
+}
+.editor .writely-comment-yellow {
+background-color: #FF9;
+background-position: -240px 0;
+}
+.editor .writely-comment-yellow-hover {
+background-color: #FF0;
+background-position: -224px 0;
+}
+.editor .writely-comment-blue {
+background-color: #C0D3FF;
+background-position: -16px 0;
+}
+.editor .writely-comment-blue-hover {
+background-color: #6292FE;
+background-position: 0 0;
+}
+.editor .writely-comment-orange {
+background-color: #FFDEAD;
+background-position: -80px 0;
+}
+.editor .writely-comment-orange-hover {
+background-color: #F90;
+background-position: -64px 0;
+}
+.editor .writely-comment-green {
+background-color: #99FBB3;
+background-position: -48px 0;
+}
+.editor .writely-comment-green-hover {
+background-color: #00F442;
+background-position: -32px 0;
+}
+.editor .writely-comment-cyan {
+background-color: #CFF;
+background-position: -208px 0;
+}
+.editor .writely-comment-cyan-hover {
+background-color: #0FF;
+background-position: -192px 0;
+}
+.editor .writely-comment-purple {
+background-color: #EBCCFF;
+background-position: -144px 0;
+}
+.editor .writely-comment-purple-hover {
+background-color: #90F;
+background-position: -128px 0;
+}
+.editor .writely-comment-magenta {
+background-color: #FCF;
+background-position: -112px 0;
+}
+.editor .writely-comment-magenta-hover {
+background-color: #F0F;
+background-position: -96px 0;
+}
+.editor .writely-comment-red {
+background-color: #FFCACA;
+background-position: -176px 0;
+}
+.editor .writely-comment-red-hover {
+background-color: #FF7A7A;
+background-position: -160px 0;
+}
+.editor .writely-comment-marker {
+background-image: url('images/markericons_horiz.gif');
+background-color: transparent;
+padding-right: 11px;
+background-repeat: no-repeat;
+width: 16px;
+height: 16px;
+-moz-user-select: none;
+}
+.editor .writely-comment-hidden {
+padding: 0;
+background: none;
+}
+.editor .writely-comment-marker-hidden {
+background: none;
+padding: 0;
+width: 0;
+}
+.editor .writely-comment-none {
+opacity: .2;
+filter:progid:DXImageTransform.Microsoft.Alpha(opacity=20);
+-moz-opacity: .2;
+}
+.editor .writely-comment-none-hover {
+opacity: .2;
+filter:progid:DXImageTransform.Microsoft.Alpha(opacity=20);
+-moz-opacity: .2;
+}
+.br_fix br:not(:-moz-last-node):not(:-moz-first-node) {
+position:relative;
+left: -1ex
+}
+.br_fix br+br {
+position: static !important
+}
+}
+h6 { font-size: 8pt }
+h5 { font-size: 8pt }
+h4 { font-size: 10pt }
+h3 { font-size: 12pt }
+h2 { font-size: 14pt }
+h1 { font-size: 18pt }
+blockquote {padding: 10px; border: 1px #DDD dashed }
+a img {border: 0}
+.pb {
+border-width: 0;
+page-break-after: always;
+/* We don't want this to be resizeable, so enforce a width and height
+using !important */
+height: 1px !important;
+width: 100% !important;
+}
+.editor .pb {
+border-top: 1px dashed #C0C0C0;
+border-bottom: 1px dashed #C0C0C0;
+}
+div.google_header, div.google_footer {
+position: relative;
+margin-top: 1em;
+margin-bottom: 1em;
+}
+/* Table of contents */
+.editor div.writely-toc {
+background-color: #f3f3f3;
+border: 1px solid #ccc;
+}
+.writely-toc > ol {
+padding-left: 3em;
+font-weight: bold;
+}
+ol.writely-toc-subheading {
+padding-left: 1em;
+font-weight: normal;
+}
+/* IE6 only */
+* html writely-toc ol {
+list-style-position: inside;
+}
+.writely-toc-none {
+list-style-type: none;
+}
+.writely-toc-decimal {
+list-style-type: decimal;
+}
+.writely-toc-upper-alpha {
+list-style-type: upper-alpha;
+}
+.writely-toc-lower-alpha {
+list-style-type: lower-alpha;
+}
+.writely-toc-upper-roman {
+list-style-type: upper-roman;
+}
+.writely-toc-lower-roman {
+list-style-type: lower-roman;
+}
+.writely-toc-disc {
+list-style-type: disc;
+}
+/* Ordered lists converted to numbered lists can preserve ordered types, and
+vice versa. This is confusing, so disallow it */
+ul[type="i"], ul[type="I"], ul[type="1"], ul[type="a"], ul[type="A"] {
+list-style-type: disc;
+}
+ol[type="disc"], ol[type="circle"], ol[type="square"] {
+list-style-type: decimal;
+}
+/* end default css */
+/* custom css */
+/* end custom css */
+/* ui edited css */
+body {
+font-family: Verdana;
+font-size: 10.0pt;
+line-height: normal;
+background-color: #ffffff;
+}
+/* end ui edited css */
+/* editor CSS */
+.editor a:visited {color: #551A8B}
+.editor table.zeroBorder {border: 1px dotted gray}
+.editor table.zeroBorder td {border: 1px dotted gray}
+.editor table.zeroBorder th {border: 1px dotted gray}
+.editor div.google_header, .editor div.google_footer {
+border: 2px #DDDDDD dashed;
+position: static;
+width: 100%;
+min-height: 2em;
+}
+.editor .misspell {background-color: yellow}
+.editor .writely-comment {
+font-size: 9pt;
+line-height: 1.4;
+padding: 1px;
+border: 1px dashed #C0C0C0
+}
+/* end editor CSS */
+</style>
+<style>
+body {
+margin: 0px;
+}
+#doc-contents {
+margin: 6px;
+}
+#google-view-footer {
+clear: both;
+border-top: thin solid;
+padding-top: 0.3em;
+padding-bottom: 0.3em;
+}
+a.google-small-link:link, a.google-small-link:visited {
+color:#112ABB;
+font-family:Arial,Sans-serif;
+font-size:11px !important;
+}
+body, p, div, td {
+direction: inherit;
+}
+@media print {
+#google-view-footer {
+display: none;
+}
+}
+</style>
+<script>
+function viewOnLoad() {
+if (document.location.href.indexOf('spi=1') != -1) {
+if (navigator.userAgent.toLowerCase().indexOf('msie') != -1) {
+window.print();
+} else {
+window.setTimeout(window.print, 10);
+}
+}
+if (document.location.href.indexOf('hgd=1') != -1) {
+var footer = document.getElementById("google-view-footer");
+if (footer) {
+footer.style.display = 'none';
+}
+}
+}
+</script>
+</head>
+<body>
+<div id="doc-contents">
+<div>
+
+<h1 style="text-align: center;">
+Google XML Document Format Style Guide</h1><div style="text-align: center;">Version 1.0<br>Copyright Google 2008<br><br></div><h2>Introduction</h2>This document provides a set of guidelines for general use when designing new XML document formats (and to some extent XML documents as well; see Section 11). Document formats usually include both formal parts (DTDs, schemas) and parts expressed in normative English prose.<br><br>These guidelines apply to new designs, and are not intended to force retroactive changes in existing designs. When participating in the creation of public or private document format designs, the guidelines may be helpful but should not control the group consensus.<br><br>This guide is meant for the design of XML that is to be generated and consumed by machines rather than human beings. Its rules are <i>not applicable</i> to formats such as XHTML (which should be formatted as much like HTML as possible) or ODF which are meant to express rich text. A document that includes embedded content in XHTML or some other rich-text format, but also contains purely machine-interpretable portions, SHOULD follow this style guide for the machine-interpretable portions. It also does not affect XML document formats that are created by translations from proto buffers or through some other type of format.<br><br>Brief rationales have been added to most of the guidelines. They are maintained in the same document in hopes that they won't get out of date, but they are not considered normative.<br><br>The terms MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are used in this document in the sense of <a title="RFC 2119" href="https://www.ietf.org/rfc/rfc2119.txt" id="iecm">RFC 2119.</a><br> <br><h2>1. To design or not to design, that is the question<br></h2><ol><li>Attempt to reuse existing XML formats whenever possible, especially those which allow extensions. Creating an entirely new format should be done only with care and consideration; read <a title="Tim Bray's warnings" href="https://www.tbray.org/ongoing/When/200x/2006/01/08/No-New-XML-Languages" id="d3cy">Tim Bray's warnings</a> first. Try to get wide review of your format, from outside your organization as well, if possible. [<i>Rationale:</i> New document formats have a cost: they must be reviewed, documented, and learned by users.]<br><br></li><li>If you are reusing or extending an existing format, make <i>sensible</i>
+
+use of the prescribed elements and attributes, especially any that are
+required. Don't completely repurpose them, but do try to see how they
+might be used in creative ways if the vanilla semantics aren't
+suitable. As a last resort when an element or attribute is required by the format but is not appropriate for your use case, use some
+fixed string as its value. [<i>Rationale:</i> Markup reuse is good, markup abuse is bad.]<br><br></li><li>When extending formats, use the implicit style of the existing format, even if it contradicts this guide. [<i>Rationale: </i>Consistency.]<br></li></ol><br><h2>2. Schemas</h2><ol><li>Document formats SHOULD be expressed using a schema language. [<i>Rationale: </i>Clarity and machine-checkability.]<br><br></li><li>The schema language SHOULD be <a title="RELAX NG" href="http://www.relaxng.org/" id="p1s7">RELAX NG</a> <a title="compact syntax" href="http://www.relaxng.org/compact-tutorial-20030326.html" id="ulci">compact syntax</a>. Embedded <a title="Schematron" href="http://www.schematron.com/" id="ymh-">Schematron</a> rules MAY be added to the schema for additional fine control. [<i>Rationale:</i>
+
+RELAX NG is the most flexible schema language, with very few arbitrary
+restrictions on designs. The compact syntax is quite easy to read and
+learn, and can be converted one-to-one to and from the XML syntax when
+necessary. Schematron handles arbitrary cross-element and
+cross-attribute constraints nicely.]<br><br></li><li>Schemas SHOULD use the <a title=""Salami Slice" style" href="http://www.xfront.com/GlobalVersusLocal.html#SecondDesign" id="r:fj">"Salami Slice" style</a> (one rule per element). Schemas MAY use the <a title=""Russian Doll" style" href="http://www.xfront.com/GlobalVersusLocal.html#FirstDesign" id="h14y">"Russian Doll" style</a> (schema resembles document) if they are short and simple. The <a title=""Venetian Blind" style" href="http://www.xfront.com/GlobalVersusLocal.html#ThirdDesign" id="dr_g">"Venetian Blind" style</a> (one rule per element type) is unsuited to RELAX NG and SHOULD NOT be used.<br><br></li><li>Regular expressions SHOULD be provided to assist in validating complex values.<br><br></li><li>DTDs and/or W3C XML Schemas MAY be provided for compatibility with existing products, tools, or users. [<i>Rationale:</i> We can't change the world all at once.]<br></li></ol></div><div><br><h2>3. Namespaces</h2><ol><li>Element names MUST be in a namespace, except
+when extending pre-existing document types that do not use namespaces.
+
+A default namespace SHOULD be used. [<i>Rationale:</i> Namespace-free
+documents are obsolete; every set of names should be in some
+namespace. Using a default namespace improves readability.]<br><br></li><li>Attribute
+names SHOULD NOT be in a namespace unless they are drawn from a foreign
+document type or are meant to be used in foreign document types. [<i>Rationale:</i> Attribute names in a namespace must always have a prefix, which is annoying to type and hard to read.]<br><br>
+</li><li>Namespace names are HTTP URIs. Namespace names SHOULD take the form <span style="font-family: Courier New;">https://example.com/</span><i style="font-family: Courier New;">whatever</i><span style="font-family: Courier New;">/</span><i><span style="font-family: Courier New;">year</span>, </i>where <i>whatever</i> is a unique value based on the name of the document type, and <i>year</i>
+
+is the year the namespace was created. There may be additional URI-path parts
+before the <i>year.</i> [<i>Rationale:</i> Existing convention. Providing the year allows for the possible recycling of code names.]<br><br></li><li>Namespaces MUST NOT be changed unless the semantics of particular elements or attributes has changed in drastically incompatible ways. [<i>Rationale:</i> Changing the namespace requires changing all client code.]<br><br></li><li>Namespace prefixes SHOULD be short (but not so short that they are likely to be conflict with another project). Single-letter prefixes MUST NOT be used. Prefixes SHOULD contain only lower-case ASCII letters. [<i>Rationale:</i> Ease of typing and absence of encoding compatibility problems.]</li></ol><br>
+
+<h2>4. Names and enumerated values</h2><b>Note: </b>"Names" refers to the names of elements, attributes, and enumerated values.<br><br><ol><li>All names MUST use lowerCamelCase. That is, they start with an initial lower-case letter, then each new word within the name starts with an initial capital letter. [<i>Rationale:</i> Adopting a single style provides consistency, which helps when referring to names since the capitalization is known and so does not have to be remembered. It matches Java style, and other languages can be dealt with using automated name conversion.]<br><br></li><li>Names MUST contain only ASCII letters and digits.
+[<i>Rationale:</i> Ease of typing and absence of encoding compatibility problems.]<br> <br></li><li>Names SHOULD NOT exceed 25 characters. Longer names SHOULD be
+avoided by devising concise and informative names. If a name can only remain within this limit by becoming obscure, the limit SHOULD be ignored. [<i>Rationale: </i>Longer names are awkward to use and require additional bandwidth.]<br><br></li><li>Published standard abbreviations, if sufficiently well-known, MAY be employed in constructing names. Ad hoc abbreviations MUST NOT be used. Acronyms MUST be treated as words for camel-casing purposes: informationUri, not informationURI. [<i>Rationale:</i> An abbreviation that is well known
+to one community is often incomprehensible to others who need to use
+the same document format (and who do understand the full name); treating an acronym as a word makes it easier to see where the word boundaries are.] <br></li></ol><p><br></p><p>
+
+</p><h2>
+5. Elements</h2><ol><li>All elements MUST contain either nothing, character content, or child elements. Mixed content MUST NOT be used. [<i>Rationale:</i> Many XML data models don't handle mixed content properly, and its use makes the element order-dependent. As always, textual formats are not covered by this rule.]<br><br></li><li>XML elements that merely wrap repeating child elements SHOULD NOT be used. [<i>Rationale:</i> They are not used in Atom and add nothing.]</li></ol>
+
+<p><br></p><h2>6. Attributes</h2><ol><li>Document formats MUST NOT depend on the order of attributes in a start-tag. [<i>Rationale:</i> Few XML parsers report the order, and it is not part of the XML Infoset.]<br><br></li><li>Elements SHOULD NOT be overloaded with too many attributes (no more
+than 10 as a rule of thumb). Instead, use child elements to
+encapsulate closely related attributes. [<i>Rationale:</i> This
+approach maintains the built-in extensibility that XML provides with
+elements, and is useful for providing forward compatibility as a
+specification evolves.]<br><br></li><li>Attributes MUST NOT be used to hold values in which line breaks are significant. [<i>Rationale:</i> Such line breaks are converted to spaces by conformant XML parsers.]<br><br></li><li>Document formats MUST allow either single or double quotation marks around attribute values. [<i>Rationale:</i> XML parsers don't report the difference.]<br></li></ol>
+
+<p><br></p>
+<p>
+</p><h2>
+7. Values</h2><ol><li>Numeric values SHOULD be 32-bit signed integers, 64-bit signed integers, or 64-bit IEEE doubles, all expressed in base 10. These correspond to the XML Schema types <span style="font-family: Courier New;">xsd:int</span>, <span style="font-family: Courier New;">xsd:long</span>, and <span style="font-family: Courier New;">xsd:double</span> respectively. If required in particular cases, <span style="font-family: Courier New;">xsd:integer</span> (unlimited-precision integer) values MAY also be used. [<i>Rationale:</i> There are far too many numeric types in XML Schema: these provide a reasonable subset.] <br><br></li><li>
+
+Boolean values SHOULD NOT be used (use enumerations instead). If they must be used, they MUST be expressed as <span style="font-family: Courier New;">true</span> or <span style="font-family: Courier New;">false</span>, corresponding to a subset of the XML Schema type <span style="font-family: Courier New;">xsd:boolean</span>. The alternative <span style="font-family: Courier New;">xsd:boolean</span> values <span style="font-family: Courier New;">1</span> and <span style="font-family: Courier New;">0</span> MUST NOT be used. [<i>Rationale:</i> Boolean arguments are not extensible. The additional flexibility of allowing numeric values is not abstracted away by any parser.]<br><br></li><li>Dates should be represented using <a title="RFC 3339" href="https://www.ietf.org/rfc/rfc3339.txt" id="sk98">RFC 3339</a> format, a subset of both
+ISO 8601 format and XML Schema <span style="font-family: Courier New;">xsd:dateTime</span> format. UTC times SHOULD be used rather than local times.
+
+[<i>Rationale:</i> There are far too many date formats and time zones, although it is recognized that sometimes local time preserves important information.]<br><br></li><li>Embedded syntax in character content and attribute values SHOULD NOT be
+used. Syntax in values means XML tools are largely useless. Syntaxes such as dates, URIs, and
+XPath expressions are exceptions. [<i>Rationale:</i>
+Users should be able to process XML documents using only an XML parser
+without requiring additional special-purpose parsers, which are easy to
+get wrong.]<br><br></li><li>Be careful with whitespace in values. XML parsers don't strip whitespace in elements, but do convert newlines to spaces in attributes. However, application frameworks may do more aggressive whitespace stripping. Your document format SHOULD give rules for whitespace stripping.<br></li></ol>
+
+<p><br>
+</p>
+<p>
+</p><h2>8. Key-value pairs<br></h2><ol><li>
+Simple key-value pairs SHOULD be represented with an empty element whose name represents the key, with the <span style="font-family: Courier New;">value</span> attribute containing the value. Elements that have a <span style="font-family: Courier New;">value</span> attribute MAY also have a <span style="font-family: Courier New;">unit</span> attribute to specify the unit of a measured value. For physical measurements, the <a title="SI system" href="https://en.wikipedia.org/wiki/International_System_of_Units" id="rhxg">SI system</a> SHOULD be used. [<i>Rationale:</i>
+
+Simplicity and design consistency. Keeping the value in an attribute
+hides it from the user, since displaying just the value without the key is not useful.]<br><br></li><li>If the number of possible keys is very large or unbounded, key-value pairs MAY be represented by a single generic element with <span style="font-family: Courier New;">key</span>, <span style="font-family: Courier New;">value</span>, and optional <span style="font-family: Courier New;">unit</span> and <span style="font-family: Courier New;">scheme</span>
+attributes (which serve to discriminate keys from different domains).
+In that case, also provide (not necessarily in the same document) a
+list of keys with human-readable explanations.</li></ol><br><h2>9. Binary data</h2><p><b>Note: </b>There are no hard and fast rules about whether binary data should be included as part of an XML document or not. If it's too large, it's probably better to link to it.</p><p><br></p><ol><li>Binary data MUST NOT be included directly as-is in XML documents, but MUST be encoded using Base64 encoding. [<i>Rationale:</i> XML does not allow arbitrary binary bytes.]<br><br></li><li>
+
+The line breaks required by Base64 MAY be omitted. [<i>Rationale:</i> The line breaks are meant to keep plain text lines short, but XML is not really plain text.]<br><br></li><li>An attribute named <span style="font-family: Courier New;">xsi:type</span> with value <span style="font-family: Courier New;">xs:base64Binary</span> MAY be attached to this element to signal that the Base64 format is in use. [Rationale: Opaque blobs should have decoding instructions attached.]<br><br></li></ol>
+<h2>10. Processing instructions</h2><ol><li>New processing instructions MUST NOT be created except in order to specify purely local processing conventions, and SHOULD be avoided altogether. Existing standardized processing instructions MAY be used. [<i>Rationale:</i> Processing instructions fit awkwardly into XML data models and can always be replaced by elements; they exist primarily to avoid breaking backward compatibility.]</li></ol><p> </p>
+
+<p>
+</p><p> </p><h2>11. Representation of XML document instances<br></h2><p><b>Note:</b> These points are only guidelines, as the format of program-created instances will often be outside the programmer's control (for example, when an XML serialization library is being used). <i>In no case</i> should XML parsers rely on these guidelines being followed. Use standard XML parsers, not hand-rolled hacks.<br></p><p><br></p><ol><li>The character encoding used SHOULD be UTF-8. Exceptions should require extremely compelling circumstances. [<i>Rationale:</i> UTF-8 is universal and in common use.]<br><br></li><li>Namespaces SHOULD be declared in the root element of a document wherever possible. [<i>Rationale: </i>Clarity and consistency.]<br><br></li><li>The mapping of namespace URIs to prefixes SHOULD remain constant throughout the document, and SHOULD also be used in documentation of the design. [<i>Rationale: </i>Clarity and consistency.]<br><br></li><li>Well-known prefixes such as html: (for XHTML), dc: (for Dublin Core metadata), and xs: (for XML Schema) should be used for standard namespaces. [<i>Rationale:</i> Human readability.]<br><br></li><li>Redundant whitespace in a tag SHOULD NOT be
+used. Use one space before each attribute in a start-tag; if the start
+tag is too long, the space MAY be replaced by a newline. [<i>Rationale:</i> Consistency and conciseness.]<br><br></li><li>Empty elements MAY be expressed as empty tags or a start-tag
+immediately followed by an end-tag. No distinction should be made
+between these two formats by any application. [<i>Rationale:</i> They are not distinguished by XML parsers.]<br><br></li><li>Documents MAY be pretty-printed using 2-space indentation for child
+elements. Elements that contain character content SHOULD NOT be
+wrapped. Long start-tags MAY be broken using newlines (possibly with extra indentation) after any attribute value except the last. [<i>Rationale:</i> General compatibility with our style. Wrapping character content affects its value.]<br><br></li><li>Attribute values MAY be surrounded with either quotation marks or apostrophes.
+Specifications MUST NOT require or forbid the use of either form. <span style="font-family: Courier New;">&apos;</span> and <span style="font-family: Courier New;">&quot;</span> may be freely used to escape each type of quote. [<i>Rationale:</i> No XML parsers report the distinction.]<br><br>
+
+</li><li>Comments MUST NOT be used to carry real data. Comments MAY be used to contain TODOs in hand-written XML. Comments SHOULD NOT be used at all in publicly transmitted documents. [<i>Rationale: </i>Comments are often discarded by parsers.]<br><br></li><li>If comments are nevertheless used, they SHOULD appear only in the document prolog or in elements that
+contain child elements. If pretty-printing is required, pretty-print
+comments like elements, but with line wrapping. Comments SHOULD NOT
+appear in elements that contain character content. [<i>Rationale: </i>Whitespace in and around comments improves readability, but embedding a
+comment in character content can lead to confusion about what
+whitespace is or is not in the content.]<br><br></li><li>Comments SHOULD have whitespace following <span style="font-family: Courier New;"><!--</span> and preceding <span style="font-family: Courier New;">--></span>. [<i>Rationale:</i> Readability.]<br><br></li><li>CDATA sections MAY be used; they are equivalent to the use of <span style="font-family: Courier New;">&amp;</span> and <span style="font-family: Courier New;">&lt;</span>. Specifications MUST NOT require or forbid the use of CDATA sections. [<i>Rationale:</i> Few XML parsers report the distinction, and combinations of CDATA and text are often reported as single objects anyway.]<br><br></li><li>Entity references other than the XML standard entity references <span style="font-family: Courier New;">&amp;</span>, <span style="font-family: Courier New;">&lt;</span>, <span style="font-family: Courier New;">&gt;</span>, <span style="font-family: Courier New;">&quot;</span>, and <span style="font-family: Courier New;">&apos;</span> MUST NOT be used. Character references MAY be used, but actual characters are preferred, unless the character encoding is not UTF-8. As usual, textual formats are exempt from this rule.<br></li></ol>
+
+<br><p> </p><p>
+</p>
+<p>
+</p><br><br><h2>
+12. Elements vs. Attributes
+</h2>
+<p>
+<b>Note:</b> There are no hard and fast rules for deciding when to use attributes and when to use elements. Here are some of the considerations that designers should take into account; no rationales are given.
+</p>
+<h3>
+12.1. General points:<br>
+</h3>
+
+<ol>
+<li>
+<p>
+Attributes are more restrictive than elements, and all designs have some elements, so an all-element design is simplest -- which is not the same as best.
+</p>
+<p>
+<br>
+</p>
+</li>
+<li>
+<p>
+In a tree-style data model, elements are typically represented internally as nodes, which use more memory than the strings used to represent attributes. Sometimes the nodes are of different application-specific classes, which in many languages also takes up memory to represent the classes.
+</p>
+<p>
+<br>
+
+</p>
+</li>
+<li>
+<p>
+When streaming, elements are processed one at a time (possibly even piece by piece, depending on the XML parser you are using), whereas all the attributes of an element and their values are reported at once, which costs memory, particularly if some attribute values are very long.
+</p>
+<p>
+<br>
+</p>
+</li>
+<li>
+<p>
+Both element content and attribute values need to be escaped appropriately, so escaping should not be a consideration in the design.
+</p>
+<p>
+<br>
+</p>
+
+</li>
+<li>
+<p>
+In some programming languages and libraries, processing elements is easier; in others, processing attributes is easier. Beware of using ease of processing as a criterion. In particular, XSLT can handle either with equal facility.
+</p>
+<p>
+<br>
+</p>
+</li>
+<li>
+<p>
+If a piece of data should usually be shown to the user, consider using an element; if not, consider using an attribute. (This rule is often violated for one reason or another.)
+
+</p>
+<p>
+<br>
+</p>
+</li>
+<li>
+<p>
+If you are extending an existing schema, do things by analogy to how things are done in that schema.
+</p>
+<p>
+<br>
+</p>
+</li>
+<li>
+<p>
+Sensible schema languages, meaning RELAX NG and Schematron, treat elements and attributes symmetrically. Older and cruder<a href="https://www.w3.org/TR/2004/REC-xmlschema-0-20041028/" id="h2c3" title="XML Schema"> </a>schema languages such as DTDs and XML Schema, tend to have better support for elements.
+
+</p>
+</li>
+</ol>
+<p>
+</p>
+<h3>
+12.2 Using elements<br>
+</h3>
+<ol>
+<li>
+<p>
+If something might appear more than once in a data model, use an element rather than introducing attributes with names like <span style="font-family: Courier New;">foo1, foo2, foo3</span> ....
+</p>
+
+<p>
+<br>
+</p>
+</li>
+<li>
+<p>
+Use elements to represent a piece of information that can be considered an independent object and when the information is related via a parent/child relationship to another piece of information.
+</p>
+<p>
+<br>
+</p>
+</li>
+<li>
+<p>
+Use elements when data incorporates strict typing or relationship rules.
+</p>
+<p>
+
+<br>
+</p>
+</li>
+<li>
+<p>
+If order matters between two pieces of data, use elements for them: attributes are inherently unordered.
+</p>
+<p>
+<br>
+</p>
+</li>
+<li>
+<p>
+If a piece of data has, or might have, its own substructure, use it in an element: getting substructure into an attribute is always messy. Similarly, if the data is a constituent part of some larger piece of data, put it in an element.
+</p>
+
+<p>
+<br>
+</p>
+</li>
+<li>
+<p>
+An exception to the previous rule: multiple whitespace-separated tokens can safely be put in an attribute. In principle, the separator can be anything, but schema-language validators are currently only able to handle whitespace, so it's best to stick with that.
+</p>
+<p>
+<br>
+</p>
+</li>
+<li>
+<p>
+If a piece of data extends across multiple lines, use an element: XML parsers will change newlines in attribute values into spaces.
+
+<br><br></p></li><li>If a piece of data is very large, use an element so that its content can be streamed.<br><br></li>
+<li>
+<p>
+If a piece of data is in a natural language, put it in an element so you can use the <span style="font-family: Courier New;">xml:lang</span> attribute to label the language being used. Some kinds of natural-language text, like Japanese, often make use <a href="https://www.w3.org/TR/2001/REC-ruby-20010531" id="pa2f" title="annotations">annotations</a> that are conventionally represented using child elements; right-to-left languages like Hebrew and Arabic may similarly require child elements to manage <a href="https://www.w3.org/TR/2001/REC-ruby-20010531" id="ehyv" title="bidirectionality">bidirectionality</a> properly.
+</p>
+
+<p>
+</p>
+</li>
+</ol>
+<h3>
+12.3 Using attributes<br>
+</h3>
+<ol>
+<li>
+<p>
+If the data is a code from an enumeration, code list, or controlled vocabulary, put it in an attribute if possible. For example, language tags, currency codes, medical diagnostic codes, etc. are best handled as attributes.
+</p>
+<p>
+<br>
+
+</p>
+</li>
+<li>
+<p>
+If a piece of data is really metadata on some other piece of data (for example, representing a class or role that the main data serves, or specifying a method of processing it), put it in an attribute if possible.
+</p>
+<p>
+<br>
+</p>
+</li>
+<li>
+<p>
+In particular, if a piece of data is an ID for some other piece of data, or a reference to such an ID, put the identifying piece in an attribute. When it's an ID, use the name <span style="font-family: Courier New;">xml:id</span> for the attribute.
+
+</p>
+<p>
+<br>
+</p>
+</li>
+<li>
+<p>
+Hypertext references are conventionally put in <span style="font-family: Courier New;">href</span> attributes.
+</p>
+<p>
+<br>
+</p>
+</li>
+<li>
+
+<p>
+If a piece of data is applicable to an element and any descendant elements unless it is overridden in some of them, it is conventional to put it in an attribute. Well-known examples are <span style="font-family: Courier New;">xml:lang</span>, <span style="font-family: Courier New;">xml:space</span>, <span style="font-family: Courier New;">xml:base</span>, and namespace declarations.
+</p>
+<p>
+<br>
+</p>
+</li>
+<li>
+<p>
+
+If terseness is really the <i>most</i> important thing, use attributes, but consider <span style="font-family: Courier New;">gzip</span> compression instead -- it works very well on documents with highly repetitive structures.</p></li>
+</ol></div><br><div><div><div><div><div>
+<br><h2>13. Parting words
+</h2>
+<p>
+</p><p>
+Use common sense and <i>BE CONSISTENT</i>. Design for extensibility. You <i>are</i> gonna need it. [<i>Rationale:</i> Long and painful experience.]<br></p><p><br> </p>
+
+<p>
+When designing XML formats, take a few minutes to look at other formats and determine their style. The point of having style guidelines is so that people can concentrate on what you are
+saying, rather than on how you are saying it. <br></p><p>
+<br>
+Break <i>ANY OR ALL</i> of these rules (yes, even the ones that say MUST) rather than create a crude, arbitrary, disgusting mess of a design if that's what following them slavishly would give you. In particular, random mixtures of attributes and child elements are hard to follow and hard to use, though it often makes good sense to use both when the data clearly fall into two different groups such as simple/complex or metadata/data.
+</p>
+<div><p>
+<br>
+Newbies always ask:
+</p>
+
+<p>
+ "Elements or attributes?
+</p>
+<p>
+Which will serve me best?"
+</p>
+<p>
+ Those who know roar like lions;
+</p>
+<p>
+ Wise hackers smile like tigers.
+</p>
+<p>
+ --a <a href="https://en.wikipedia.org/wiki/Waka_%28poetry%29#Forms_of_waka" id="s3k3" title="tanka">tanka</a>, or extended haiku
+
+</p>
+</div>
+<p>
+<br>
+</p>
+<br>[TODO: if a registry of schemas is set up, add a link to it]<br><br></div><br></div><br></div></div></div><br>
+<br clear="all"/>
+</div>
