From 505ba68c74eb97e6966f60907ce893001bedc706 Mon Sep 17 00:00:00 2001 From: Ted Osborne Date: Tue, 30 Jan 2018 12:36:50 -0500 Subject: [PATCH] Revert "Project import generated by Copybara." This reverts commit 54cca78d64e44b1c4290f4d0fed6a5e494116808. --- README.md | 54 + Rguide.xml | 447 ++ angularjs-google-style.html | 393 ++ cppguide.html | 6170 +++++++++++++++++++++++++ cppguide.xml | 18 + cpplint/README | 45 + cpplint/cpplint.py | 6228 ++++++++++++++++++++++++++ cpplint/cpplint_test_header.h | 1 + cpplint/cpplint_unittest.py | 5805 ++++++++++++++++++++++++ cpplint/nested/cpplint_test_header.h | 1 + docguide/README.md | 10 + docguide/READMEs.md | 69 + docguide/VERSION | 1 + docguide/best_practices.md | 115 + docguide/philosophy.md | 71 + docguide/style.md | 420 ++ eclipse-cpp-google-style.xml | 167 + eclipse-java-google-style.xml | 337 ++ google-c-style.el | 151 + google-r-style.html | 18 + htmlcssguide.html | 877 ++++ htmlcssguide.xml | 8 + include/jsguide.js | 56 + include/link.png | Bin 0 -> 189 bytes include/styleguide.css | 261 ++ include/styleguide.js | 289 ++ intellij-java-google-style.xml | 598 +++ javaguide.css | 572 +++ javaguide.html | 1187 +++++ javaguidelink.png | Bin 0 -> 189 bytes javascriptguide.xml | 3629 +++++++++++++++ jsguide.html | 2816 ++++++++++++ jsoncstyleguide.html | 18 + jsoncstyleguide.xml | 1187 +++++ jsoncstyleguide_example_01.png | Bin 0 -> 319109 bytes jsoncstyleguide_example_02.png | Bin 0 -> 258701 bytes lispguide.xml | 3887 ++++++++++++++++ objcguide.md | 1661 +++++++ objcguide.xml | 8 + pyguide.html | 2310 ++++++++++ pyguide.md | 2568 ----------- shell.xml | 1152 +++++ styleguide.css | 147 + styleguide.xsl | 924 ++++ vimscriptfull.xml | 1534 +++++++ vimscriptguide.xml | 412 ++ xmlstyle.html | 681 +++ 47 files changed, 44735 insertions(+), 2568 deletions(-) create mode 100644 README.md create mode 100644 Rguide.xml create mode 100644 angularjs-google-style.html create mode 100644 cppguide.html create mode 100644 cppguide.xml create mode 100644 cpplint/README create mode 100755 cpplint/cpplint.py create mode 100644 cpplint/cpplint_test_header.h create mode 100755 cpplint/cpplint_unittest.py create mode 100644 cpplint/nested/cpplint_test_header.h create mode 100644 docguide/README.md create mode 100644 docguide/READMEs.md create mode 100644 docguide/VERSION create mode 100644 docguide/best_practices.md create mode 100644 docguide/philosophy.md create mode 100644 docguide/style.md create mode 100644 eclipse-cpp-google-style.xml create mode 100644 eclipse-java-google-style.xml create mode 100644 google-c-style.el create mode 100644 google-r-style.html create mode 100644 htmlcssguide.html create mode 100644 htmlcssguide.xml create mode 100644 include/jsguide.js create mode 100644 include/link.png create mode 100644 include/styleguide.css create mode 100644 include/styleguide.js create mode 100644 intellij-java-google-style.xml create mode 100644 javaguide.css create mode 100644 javaguide.html create mode 100644 javaguidelink.png create mode 100644 javascriptguide.xml create mode 100644 jsguide.html create mode 100644 jsoncstyleguide.html create mode 100644 jsoncstyleguide.xml create mode 100644 jsoncstyleguide_example_01.png create mode 100644 jsoncstyleguide_example_02.png create mode 100644 lispguide.xml create mode 100644 objcguide.md create mode 100644 objcguide.xml create mode 100644 pyguide.html delete mode 100644 pyguide.md create mode 100644 shell.xml create mode 100644 styleguide.css create mode 100644 styleguide.xsl create mode 100644 vimscriptfull.xml create mode 100644 vimscriptguide.xml create mode 100644 xmlstyle.html 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]. + +Creative Commons License + +[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 @@ + + + + + + Google's R Style Guide + + + + +

Google's R Style Guide

+ +

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

+ + + + + + +

Summary: R Style Rules

+ +
    +
  1. File Names: end in .R
    2. +
  2. Identifiers: variable.name + (or variableName), + FunctionName, kConstantName
    3. +
  3. Line Length: maximum 80 characters
    4. +
  4. Indentation: two spaces, no tabs
    5. +
  5. Spacing
    6. +
  6. Curly Braces: first on same line, last on + own line
    7. +
  7. else: Surround else with braces
    8. +
  8. Assignment: use <-, not + =
    9. +
  9. Semicolons: don't use them
    10. +
  10. General Layout and Ordering
    11. +
  11. Commenting Guidelines: all comments begin + with # followed by a space; inline comments need two + spaces before the #
    12. +
  12. Function Definitions and Calls
    13. +
  13. Function Documentation
    14. +
  14. Example Function
    15. +
  15. TODO Style: TODO(username)
    16. +
+ +

Summary: R Language Rules

+
    +
  1. attach: avoid using it
    2. +
  2. Functions: + errors should be raised using stop()
    3. +
  3. Objects and Methods: avoid S4 objects and + methods when possible; never mix S3 and S4
    4. +
+ +

Notation and Naming

+ +

File Names

+

+ File names should end in .R and, of course, be + meaningful. +
GOOD: predict_ad_revenue.R +
BAD: foo.R +

+ +

Identifiers

+

+ Don't use underscores ( _ ) or hyphens + ( - ) 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 + (variable.name), but variableName + is also accepted; + function names have initial capital letters and no dots + (FunctionName); + constants are named like functions but with an initial + k. +

+ + + +

Syntax

+ +

Line Length

+

+ The maximum line length is 80 characters. +

+ +

Indentation

+

+ When indenting your code, use two spaces. Never use tabs or mix + tabs and spaces. +
Exception: When a line break occurs inside parentheses, + align the wrapped line with the first character inside the + parenthesis. +

+ +

Spacing

+

+ Place spaces around all binary operators (=, + +, -, <-, etc.). +
Exception: Spaces around ='s are + optional when passing parameters in a function call. +

+

+ Do not place a space before a comma, but always place one after a + comma. +

GOOD: +

+
tab.prior <- table(df[df$days.from.opt < 0, "campaign.id"])
+total <- sum(x[, 1])
+total <- sum(x[1, ])
+

+ BAD: +

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

+ Place a space before left parenthesis, except in a function call. +

+

+ GOOD: +
if (debug) +

+

+ BAD: +
if(debug) +

+

+ Extra spacing (i.e., more than one space in a row) is okay if it + improves alignment of equals signs or arrows (<-). +

+
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 = "")))
+
+

+ Do not place spaces around code in parentheses or square brackets. +
Exception: Always place a space after a comma. +

+

+ GOOD:

if (debug)
+x[1, ]
+

+ BAD:

if ( debug )  # No spaces around debug
+x[1,]  # Needs a space after the comma
+ +

Curly Braces

+

+ 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 consistently either use or not use curly braces for + single statement blocks. +

+ 
+if (is.null(ylim)) {
+  ylim <- c(0, 0.06)
+}
+

+ xor (but not both) +

+ 
+if (is.null(ylim))
+  ylim <- c(0, 0.06)
+

+ Always begin the body of a block on a new line. +

+

+ BAD: +
if (is.null(ylim)) + ylim <- c(0, 0.06) +
if (is.null(ylim)) + {ylim <- c(0, 0.06)} +

+ +

Surround else with braces

+

+ An else statement should always be surrounded on the + same line by curly braces.

+ 
+if (condition) {
+  one or more lines
+} else {
+  one or more lines
+}
+
+

+ BAD:
+

+ 
+if (condition) {
+  one or more lines
+}
+else {
+  one or more lines
+}
+
+

+ BAD:
+

+ 
+if (condition)
+  one line
+else
+  one line
+
+ +

Assignment

+

+ Use <-, not =, for assignment. +

+

+ GOOD: +
x <- 5 +

+

+ BAD: +
x = 5 +

+

Semicolons

+

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

+ + +

Organization

+

General Layout and Ordering

+

+ If everyone uses the same general ordering, we'll be able to + read and understand each other's scripts faster and more easily. +

+
    +
  1. Copyright statement comment
    2. +
  2. Author comment
    3. +
  3. File description comment, including purpose of + program, inputs, and outputs
    4. +
  4. source() and library() statements
    5. +
  5. Function definitions
    6. +
  6. Executed statements, if applicable (e.g., + print, plot)
    7. +
+

+ Unit tests should go in a separate file named + originalfilename_test.R. +

+

Commenting Guidelines

+

+ Comment your code. Entire commented lines should begin with + # and one space. +

+

+ Short comments can be placed after code preceded by two spaces, + #, and then one space. +

+
# 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)")
+
+

Function Definitions and + Calls

+

+ Function definitions should first list arguments without default + values, followed by those with default values. +

+

+ In both function definitions and function calls, multiple + arguments per line are allowed; line breaks are only allowed + between assignments. +
GOOD: +

+
PredictCTR <- function(query, property, num.days,
+                       show.plot = TRUE)
+
+ BAD: +
PredictCTR <- function(query, property, num.days, show.plot =
+                       TRUE)
+
+

Ideally, unit tests should serve as sample function calls (for + shared library routines). +

+

Function Documentation

+

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 Args:, with a description of + each (including the data type); and a description of the return + value, denoted by Returns:. The comments should be + descriptive enough that a caller can use the function without + reading any of the function's code. +

+ +

Example Function

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

TODO Style

+ +

+ Use a consistent style for TODOs throughout your code. +
TODO(username): Explicit description of action to + be taken +

+ + +

Language

+ +

Attach

+

The possibilities for creating errors when using + attach are numerous. Avoid it.

+

Functions

+

Errors should be raised using stop().

+

Objects and Methods

+

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: + + https://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf.) +

+

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

+

Avoid mixing S3 and S4: S4 methods ignore S3 inheritance and + vice-versa. +

+ + +

Exceptions

+ +

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

+ + +

Parting Words

+ +

+ Use common sense and BE CONSISTENT. +

+

+ 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 + if + 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. +

+

+ 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 will throw readers out of their rhythm when they go to + read it. Try to avoid this. +

+ +

+ OK, enough writing about writing code; the code itself is much more + interesting. Have fun! +

+ + +

References

+ +

+ + http://www.maths.lth.se/help/R/RCC/ - R Coding Conventions +

+

+ http://ess.r-project.org/ - For + emacs users. This runs R in your emacs and has an emacs mode. +

+ + + + 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 @@ + + + + + + + + + + Google's AngularJS Style Guide + + + +

An AngularJS Style Guide for Closure Users at Google

+ +

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.

+ +

This document describes style for AngularJS apps in google3. This guide + supplements and extends the + Google JavaScript Style Guide. +

+ +

Style Note: 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 + + JavaScript types. 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: + Martin Fowler on closures, + much longer description, appendix A of the + + closure book has a good description of inheritance patterns and why it prefers + pseudoclassical, + + Javascript, the Good Parts as a counter.)

+ +
1 Angular Language Rules
+ +
2 Angular Style Rules
+ +
3 Angular Tips, Tricks, and Best Practices
+ + +
4 Best practices links and docs
+ +

1 Angular Language Rules

+ +

Manage dependencies with Closure's goog.require and goog.provide

+

Choose a namespace for your project, and use goog.provide and goog.require.

+
+goog.provide('hello.about.AboutCtrl');
+goog.provide('hello.versions.Versions');
+
+ +

Why? + Google BUILD rules integrate nicely with closure provide/require.

+ +

Modules

+ +

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.

+ +

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.

+ +

Why? + 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. +

+ +

+ Modules should reference other modules using the Angular Module's "name" property +

+ +

For example:

+ +
+// 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]);
+  
+      No: my.application.module = angular.module('hello', ['my.submoduleA']);
+
+ +

Why? + 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.

+ +

Use a common externs file

+ +

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.

+ +

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 + here.

+ +

JSCompiler Flags

+

Reminder: According to the JS style guide, customer facing code must be compiled.

+ +

Recommended: 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. +

+ +

Note - if you are using @export for methods, you will need to add the compiler flag

+
+"--generate_exports",
+
+ +

If you are using @export for properties, you will need to add the flags:

+
+"--generate_exports",
+"--remove_unused_prototype_props_in_externs=false",
+"--export_local_property_definitions",
+
+ +

Controllers and Scopes

+

Controllers are classes. Methods should be defined on MyCtrl.prototype.

+ +

Google Angular applications should use the 'controller as' 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. +

+ +

Pre Angular 1.2, this looks like:

+
+/**
+ * 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;
+};
+
+ +

And the template:

+ +
+<div ng-controller="hello.mainpage.HomeCtrl"/>
+  <span ng-class="homeCtrl.myColor">I'm in a color!</span>
+  <span>{{homeCtrl.add(5, 6)}}</span>
+</div>
+
+ +

After Angular 1.2, this looks like:

+ +
+/**
+ * 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;
+};
+
+ +

If you are compiling with property renaming, expose properties and methods using the @export + annotation. Remember to @export the constructor as well.

+ +

And in the template:

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

Why? + 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.

+ +

Directives

+ +

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.

+ +
+goog.provide('hello.pane.paneDirective');
+
+/**
+ * Description and usage
+ * @return {angular.Directive} Directive definition object.
+ */
+hello.pane.paneDirective = function() {
+  // ...
+};
+
+ +

Exception: DOM manipulation may occur in services for DOM elements disconnected from the + rest of the view, e.g. dialogs or keyboard shortcuts.

+ +

Services

+ +

Services registered on the module with module.service are classes. + Use module.service instead of module.provider or + module.factory unless you need to do initialization beyond just creating a + new instance of the class.

+ +
+/**
+ * @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() {/*...*/};
+
+ +

In the module:

+ +
+module.service('request', hello.request.Request);
+
+ + +

2 Angular Style Rules

+ +

Reserve $ for Angular properties and services

+

Do not use $ to prepend your own object properties and service identifiers. Consider this style + of naming reserved by AngularJS and jQuery.

+ +

Yes:

+
+  $scope.myModel = { value: 'foo' }
+  myModule.service('myService', function() { /*...*/ });
+  var MyCtrl = function($http) {this.http_ = $http;};
+
+ +

No:

+
+  $scope.$myModel = { value: 'foo' } // BAD
+  $scope.myModel = { $value: 'foo' } // BAD
+  myModule.service('$myService', function() { ... }); // BAD
+  var MyCtrl = function($http) {this.$http_ = $http;}; // BAD
+
+ +

Why? + 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. +

+ +

Custom elements

+ +

For custom elements (e.g. <ng-include src="template"></ng-include>), IE8 + requires special support (html5shiv-like hacks) to enable css styling. Be aware of this + restriction in apps targeting old versions of IE.

+ +

3 Angular Tips, Tricks, and Best Practices

+ +

These are not strict style guide rules, but are placed here as reference for folks getting + started with Angular at Google.

+ +

Testing

+ +

Angular is designed for test-driven development.

+ +

The recommended unit testing setup is Jasmine + Karma (though you could use closure tests + or js_test)

+ +

Angular provides easy adapters to load modules and use the injector in Jasmine tests. +

+

+ + +

Consider using the Best Practices for App Structure

+

+ This directory structure doc describes how to structure your application with controllers in + nested subdirectories and all components (e.g. services and directives) in a 'components' dir. +

+ + +

Be aware of how scope inheritance works

+ +

See + The Nuances of Scope Prototypal Inheritance

+ +

Use @ngInject for easy dependency injection compilation

+

This removes the need to add myCtrl['$inject'] = ... to prevent minification from + messing up Angular's dependency injection.

+ +

Usage:

+
+/**
+ * My controller.
+ * @param {!angular.$http} $http
+ * @param {!my.app.myService} myService
+ * @constructor
+ * @export
+ * @ngInject
+ */
+my.app.MyCtrl = function($http, myService) {
+  //...
+};
+
+ +

4 Best practices links and docs

+ + +
+ Last modified Feb 07 2013 +
+ + diff --git a/cppguide.html b/cppguide.html new file mode 100644 index 0000000..590cc9f --- /dev/null +++ b/cppguide.html @@ -0,0 +1,6170 @@ + + + + +Google C++ Style Guide + + + + + +
+

Google C++ Style Guide

+
+ +
+ + + +

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.

+ +

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.

+ +

Style, 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.

+ +

+Most open-source projects developed by +Google conform to the requirements in this guide. +

+ + + + + +

Note that this guide is not a C++ tutorial: we assume that +the reader is familiar with the language.

+ +

Goals of the Style Guide

+
+

Why do we have this document?

+ +

There are a few core goals that we believe this guide should +serve. These are the fundamental whys 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.

+ +

The goals of the style guide as we currently see them are as follows:

+
+
Style rules should pull their weight
+
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, goto contravenes many +of the following principles, but is already vanishingly rare, so the Style +Guide doesn’t discuss it.
+ +
Optimize for the reader, not the writer
+
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 (std::unique_ptr +demonstrates the ownership transfer unambiguously at the call +site).
+ +
Be consistent with existing code
+
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 #includes 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.
+ +
Be consistent with the broader C++ community when appropriate
+
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.
+ +
Avoid surprising or dangerous constructs
+
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. +
+ +
Avoid constructs that our average C++ programmer would find tricky +or hard to maintain
+
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.
+ +
Be mindful of our scale
+
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.
+ +
Concede to optimization when necessary
+
Performance optimizations can sometimes be necessary and +appropriate, even when they conflict with the other principles of this +document.
+
+ +

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.

+ +
+ + + +

Header Files

+ +

In general, every .cc file should have an +associated .h file. There are some common +exceptions, such as unittests and +small .cc files containing just a +main() function.

+ +

Correct use of header files can make a huge difference to +the readability, size and performance of your code.

+ +

The following rules will guide you through the various +pitfalls of using header files.

+ + +

Self-contained Headers

+ +
+

Header files should be self-contained (compile on their own) and +end in .h. Non-header files that are meant for inclusion +should end in .inc and be used sparingly.

+
+ +
+

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 header guards and include all +other headers it needs.

+ +

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 .cc 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 (-inl.h); +this practice was common in the past, but is no longer allowed.

+ +

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 .cc file that instantiates the template.

+ +

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 header guards, and might not include +their prerequisites. Name such files with the .inc +extension. Use sparingly, and prefer self-contained headers when +possible.

+ +
+ +

The #define Guard

+ +
+

All header files should have #define guards to +prevent multiple inclusion. The format of the symbol name +should be +<PROJECT>_<PATH>_<FILE>_H_.

+
+ +
+ + + +

To guarantee uniqueness, they should +be based on the full path in a project's source tree. For +example, the file foo/src/bar/baz.h in +project foo should have the following +guard:

+ +
#ifndef FOO_BAR_BAZ_H_
+#define FOO_BAR_BAZ_H_
+
+...
+
+#endif  // FOO_BAR_BAZ_H_
+
+ + + + +
+ +

Forward Declarations

+ +
+

Avoid using forward declarations where possible. + Just #include the headers you need.

+
+ +
+ +
+

A "forward declaration" is a declaration of a class, +function, or template without an associated definition.

+
+ +
+
    +
  • Forward declarations can save compile time, as + #includes force the compiler to open + more files and process more input.
    • + +
  • Forward declarations can save on unnecessary + recompilation. #includes can force + your code to be recompiled more often, due to unrelated + changes in the header.
    • +
+
+ +
+
    +
  • Forward declarations can hide a dependency, allowing + user code to skip necessary recompilation when headers + change.
    • + +
  • 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.
    • + +
  • Forward declaring symbols from namespace + std:: yields undefined behavior.
    • + +
  • It can be difficult to determine whether a forward + declaration or a full #include is needed. + Replacing an #include with a forward + declaration can silently change the meaning of + code: + 
          // 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*)
+
    + If the #include was replaced with forward + decls for B and D, + test() would call f(void*). +
    • + +
  • Forward declaring multiple symbols from a header + can be more verbose than simply + #includeing the header.
    • + +
  • Structuring code to enable forward declarations + (e.g. using pointer members instead of object members) + can make the code slower and more complex.
    • + + +
+
+ +
+
    +
  • Try to avoid forward declarations of entities + defined in another project.
    • + +
  • When using a function declared in a header file, + always #include that header.
    • + +
  • When using a class template, prefer to + #include its header file.
    • +
+ +

Please see Names and Order +of Includes for rules about when to #include a header.

+
+ +
+ +

Inline Functions

+ +
+

Define functions inline only when they are small, say, 10 +lines or fewer.

+
+ +
+ +
+

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.

+
+ +
+

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.

+
+ +
+

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.

+
+ +
+

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!

+ +

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

+ +

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.

+
+ +
+ +

Names and Order of Includes

+ +
+

Use standard order for readability and to avoid hidden +dependencies: Related header, C library, C++ library, other libraries' +.h, your project's .h.

+
+ +
+

+All of a project's header files should be +listed as descendants of the project's source +directory without use of UNIX directory shortcuts +. (the current directory) or .. +(the parent directory). For example, + +google-awesome-project/src/base/logging.h +should be included as:

+ +
#include "base/logging.h"
+
+ +

In dir/foo.cc or +dir/foo_test.cc, whose main +purpose is to implement or test the stuff in +dir2/foo2.h, order your includes +as follows:

+ +
    +
  1. dir2/foo2.h.
    2. + +
  2. C system files.
    3. + +
  3. C++ system files.
    4. + +
  4. Other libraries' .h + files.
    5. + +
  5. + Your project's .h + files.
    6. +
+ +

With the preferred ordering, if +dir2/foo2.h omits any necessary +includes, the build of dir/foo.cc +or dir/foo_test.cc 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.

+ +

dir/foo.cc and +dir2/foo2.h are usually in the same +directory (e.g. base/basictypes_test.cc and +base/basictypes.h), but may sometimes be in different +directories too.

+ + + +

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.

+ +

You should include all the headers that define the symbols you rely +upon, except in the unusual case of forward +declaration. If you rely on symbols from bar.h, +don't count on the fact that you included foo.h which +(currently) includes bar.h: include bar.h +yourself, unless foo.h explicitly demonstrates its intent +to provide you the symbols of bar.h. However, any +includes present in the related header do not need to be included +again in the related cc (i.e., foo.cc can +rely on foo.h's includes).

+ +

For example, the includes in + +google-awesome-project/src/foo/internal/fooserver.cc +might look like this:

+ + +
#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"
+
+ +

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:

+ +
#include "foo/public/fooserver.h"
+
+#include "base/port.h"  // For LANG_CXX11.
+
+#ifdef LANG_CXX11
+#include <initializer_list>
+#endif  // LANG_CXX11
+
+ +
+ +

Scoping

+ +

Namespaces

+ +
+

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 using-directives (e.g. +using namespace foo). Do not use +inline namespaces. For unnamed namespaces, see +Unnamed Namespaces and +Static Variables. +

+ +
+ +
+

Namespaces subdivide the global scope +into distinct, named scopes, and so are useful for preventing +name collisions in the global scope.

+
+ +
+ +

Namespaces provide a method for preventing name conflicts +in large programs while allowing most code to use reasonably +short names.

+ +

For example, if two different projects have a class +Foo in the global scope, these symbols may +collide at compile time or at runtime. If each project +places their code in a namespace, project1::Foo +and project2::Foo are now distinct symbols that +do not collide, and code within each project's namespace +can continue to refer to Foo without the prefix.

+ +

Inline namespaces automatically place their names in +the enclosing scope. Consider the following snippet, for +example:

+ +
namespace X {
+inline namespace Y {
+  void foo();
+}  // namespace Y
+}  // namespace X
+
+ +

The expressions X::Y::foo() and +X::foo() are interchangeable. Inline +namespaces are primarily intended for ABI compatibility +across versions.

+
+ +
+ +

Namespaces can be confusing, because they complicate +the mechanics of figuring out what definition a name refers +to.

+ +

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.

+ +

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.

+
+ +
+ +

Namespaces should be used as follows:

+ +
    +
  • Follow the rules on Namespace Names. +
  • Terminate namespaces with comments as shown in the given examples. +
  • + +

    Namespaces wrap the entire source file after + includes, + + gflags definitions/declarations + and forward declarations of classes from other namespaces.

    + +
    // 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
+
    + +
    // In the .cc file
+namespace mynamespace {
+
+// Definition of functions is within scope of the namespace.
+void MyClass::Foo() {
+  ...
+}
+
+}  // namespace mynamespace
+
    + +

    More complex .cc files might have additional details, + like flags or using-declarations.

    + +
    #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
+
    +
    • + + + +
  • Do not declare anything in namespace + std, including forward declarations of + standard library classes. Declaring entities in + namespace std is undefined behavior, i.e., + not portable. To declare entities from the standard + library, include the appropriate header file.
    • + +

  • You may not use a using-directive + to make all names from a namespace available.

    + +
    // Forbidden -- This pollutes the namespace.
+using namespace foo;
+
    +
    • + +

  • Do not use Namespace aliases 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.

    + +
    // Shorten access to some commonly used names in .cc files.
+namespace baz = ::foo::bar::baz;
+
    + +
    // 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
+
    + +
  • Do not use inline namespaces.
    • +
+
+
+ +

Unnamed Namespaces and Static +Variables

+ +
+

When definitions in a .cc file do not need to be +referenced outside that file, place them in an unnamed +namespace or declare them static. Do not use either +of these constructs in .h files. +

+ +
+ +
+

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

+
+ +
+ +

Use of internal linkage in .cc files is encouraged +for all code that does not need to be referenced elsewhere. +Do not use internal linkage in .h files.

+ +

Format unnamed namespaces like named namespaces. In the + terminating comment, leave the namespace name empty:

+ +
namespace {
+...
+}  // namespace
+
+
+
+ +

Nonmember, Static Member, and Global Functions

+ +
+

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.

+
+ +
+ +
+

Nonmember and static member functions can be useful in + some situations. Putting nonmember functions in a + namespace avoids polluting the global namespace.

+
+ +
+

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.

+
+ +
+

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 +namespaces instead. For a header +myproject/foo_bar.h, for example, write

+
namespace myproject {
+namespace foo_bar {
+void Function1();
+void Function2();
+}  // namespace foo_bar
+}  // namespace myproject
+
+

instead of

+
namespace myproject {
+class FooBar {
+ public:
+  static void Function1();
+  static void Function2();
+};
+}  // namespace myproject
+
+ +

If you define a nonmember function and it is only +needed in its .cc file, use +internal linkage to limit +its scope.

+
+ +
+ +

Local Variables

+ +
+

Place a function's variables in the narrowest scope +possible, and initialize variables in the declaration.

+
+ +
+ +

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

+ +
int i;
+i = f();      // Bad -- initialization separate from declaration.
+
+ +
int j = g();  // Good -- declaration has initialization.
+
+ +
std::vector<int> v;
+v.push_back(1);  // Prefer initializing using brace initialization.
+v.push_back(2);
+
+ +
std::vector<int> v = {1, 2};  // Good -- v starts initialized.
+
+ +

Variables needed for if, while +and for statements should normally be declared +within those statements, so that such variables are confined +to those scopes. E.g.:

+ +
while (const char* p = strchr(str, '/')) str = p + 1;
+
+ +

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.

+ +
// Inefficient implementation:
+for (int i = 0; i < 1000000; ++i) {
+  Foo f;  // My ctor and dtor get called 1000000 times each.
+  f.DoSomething(i);
+}
+
+ +

It may be more efficient to declare such a variable +used in a loop outside that loop:

+ +
Foo f;  // My ctor and dtor get called once each.
+for (int i = 0; i < 1000000; ++i) {
+  f.DoSomething(i);
+}
+
+ +
+ +

Static and Global Variables

+ +
+

Variables of class type with + static storage duration are forbidden: they cause hard-to-find bugs due + to indeterminate order of construction and destruction. However, such + variables are allowed if they are constexpr: they have no + dynamic initialization or destruction.

+
+ +
+ +

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.

+ +

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.

+ +

Likewise, global and static variables are destroyed +when the program terminates, regardless of whether the +termination is by returning from main() or +by calling exit(). 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 string variable +might be run prior to the destructor for another variable +that contains a reference to that string.

+ +

One way to alleviate the destructor problem is to +terminate the program by calling +quick_exit() instead of exit(). +The difference is that quick_exit() does not +invoke destructors and does not invoke any handlers that +were registered by calling atexit(). If you +have a handler that needs to run when a program +terminates via quick_exit() (flushing logs, +for example), you can register it using +at_quick_exit(). (If you have a handler that +needs to run at both exit() and +quick_exit(), you need to register it in +both places.)

+ +

As a result we only allow static variables to contain +POD data. This rule completely disallows +std::vector (use C arrays instead), or +string (use const char []).

+ + + +

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.

+ + + + + +
+ +

Classes

+ +

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.

+ +

Doing Work in Constructors

+ +
+

Avoid virtual method calls in constructors, and avoid +initialization that can fail if you can't signal an error.

+
+ +
+ +
+

It is possible to perform arbitrary initialization in the body +of the constructor.

+
+ +
+
    +
  • No need to worry about whether the class has been initialized or + not.
    • + +
  • Objects that are fully initialized by constructor call can + be const and may also be easier to use with standard containers + or algorithms.
    • +
+ +
+ +
+
    +
  • 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.
    • + +
  • There is no easy way for constructors to signal errors, short of + crashing the program (not always appropriate) or using exceptions + (which are forbidden).
    • + +
  • If the work fails, we now have an object whose initialization + code failed, so it may be an unusual state requiring a bool + IsValid() state checking mechanism (or similar) which is easy + to forget to call.
    • + +
  • 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.
    • +
+
+ + +
+

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 Init() method. Avoid Init() 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).

+
+ +
+ + +

Implicit Conversions

+ +
+

Do not define implicit conversions. Use the explicit +keyword for conversion operators and single-argument +constructors.

+
+ +
+ +
+

Implicit conversions allow an +object of one type (called the source type) to +be used where a different type (called the destination +type) is expected, such as when passing an +int argument to a function that takes a +double parameter.

+ +

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. operator +bool()). 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).

+ +

The explicit 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:

+
class Foo {
+  explicit Foo(int x, double y);
+  ...
+};
+
+void Func(Foo f);
+
+
Func({42, 3.14});  // Error
+
+This kind of code isn't technically an implicit conversion, but the +language treats it as one as far as explicit is concerned. +
+ +
+
    +
  • Implicit conversions can make a type more usable and + expressive by eliminating the need to explicitly name a type + when it's obvious.
    • +
  • Implicit conversions can be a simpler alternative to + overloading.
    • +
  • List initialization syntax is a concise and expressive + way of initializing objects.
    • +
+
+ +
+
    +
  • 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.
    • + +
  • 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.
    • + +
  • Constructors that take a single argument may accidentally + be usable as implicit type conversions, even if they are not + intended to do so.
    • + +
  • When a single-argument constructor is not marked + explicit, there's no reliable way to tell whether + it's intended to define an implicit conversion, or the author + simply forgot to mark it.
    • + +
  • It's not always clear which type should provide the conversion, + and if they both do, the code becomes ambiguous.
    • + +
  • List initialization can suffer from the same problems if + the destination type is implicit, particularly if the + list has only a single element.
    • +
+
+ +
+

Type conversion operators, and constructors that are +callable with a single argument, must be marked +explicit in the class definition. As an +exception, copy and move constructors should not be +explicit, 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.

+ +

Constructors that cannot be called with a single argument +should usually omit explicit. Constructors that +take a single std::initializer_list parameter should +also omit explicit, in order to support copy-initialization +(e.g. MyType m = {1, 2};).

+
+ +
+ +

Copyable and Movable Types

+ +
+

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

+ +
+ +
+

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. +string is an example of a copyable type.

+ +

A movable type is one that can be initialized and assigned +from temporaries (all copyable types are therefore movable). +std::unique_ptr<int> 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.

+ +

The copy/move constructors can be implicitly invoked by the compiler +in some situations, e.g. when passing objects by value.

+
+ +
+

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.

+ +

Copy/move constructors and assignment operators are usually +easier to define correctly than alternatives +like Clone(), CopyFrom() or Swap(), +because they can be generated by the compiler, either implicitly or +with = default. 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 + + +copy elision.

+ +

Move operations allow the implicit and efficient transfer of +resources out of rvalue objects. This allows a plainer coding style +in some cases.

+
+ +
+

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 (Registerer), +objects tied to a specific scope (Cleanup), or closely coupled to +object identity (Mutex) 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 +object slicing. +Defaulted or carelessly-implemented copy operations can be incorrect, and the +resulting bugs can be confusing and difficult to diagnose.

+ +

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.

+
+ +
+ +

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

+ +

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.

+ +
class Foo {
+ public:
+  Foo(Foo&& other) : field_(other.field) {}
+  // Bad, defines only move constructor, but not operator=.
+
+ private:
+  Field field_;
+};
+
+ +

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 Clone() +method, and a protected copy constructor that derived classes +can use to implement it.

+ +

If you do not want to support copy/move operations on your type, +explicitly disable them using = delete in +the public: section:

+ +
// MyClass is neither copyable nor movable.
+MyClass(const MyClass&) = delete;
+MyClass& operator=(const MyClass&) = delete;
+
+ +

+ +
+
+ +

Structs vs. Classes

+ +
+

Use a struct only for passive objects that + carry data; everything else is a class.

+
+ +
+ +

The struct and class +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.

+ +

structs 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, +Initialize(), Reset(), +Validate().

+ +

If more functionality is required, a +class is more appropriate. If in doubt, make +it a class.

+ +

For consistency with STL, you can use +struct instead of class for +functors and traits.

+ +

Note that member variables in structs and classes have +different naming rules.

+ +
+ +

Inheritance

+ +
+

Composition is often more appropriate than inheritance. +When using inheritance, make it public.

+
+ +
+ +
+

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 +interface inheritance, in which +only method names are inherited.

+
+ +
+

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.

+
+ +
+

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.

+
+ +
+ +

All inheritance should be public. If you +want to do private inheritance, you should be including +an instance of the base class as a member instead.

+ +

Do not overuse implementation inheritance. Composition +is often more appropriate. Try to restrict use of +inheritance to the "is-a" case: Bar +subclasses Foo if it can reasonably be said +that Bar "is a kind of" +Foo.

+ +

Make your destructor virtual if +necessary. If your class has virtual methods, its +destructor should be virtual.

+ +

Limit the use of protected to those +member functions that might need to be accessed from +subclasses. Note that data +members should be private.

+ +

Explicitly annotate overrides of virtual functions +or virtual destructors with an override +or (less frequently) final specifier. +Older (pre-C++11) code will use the +virtual keyword as an inferior +alternative annotation. For clarity, use exactly one of +override, final, or +virtual when declaring an override. +Rationale: A function or destructor marked +override or final 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.

+
+ +
+ +

Multiple Inheritance

+ +
+

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 pure +interface classes tagged with the +Interface suffix.

+
+ +
+ +
+

Multiple inheritance allows a sub-class to have more than +one base class. We distinguish between base classes that are +pure interfaces and those that have an +implementation.

+
+ +
+

Multiple implementation inheritance may let you re-use +even more code than single inheritance (see Inheritance).

+
+ +
+

Only very rarely is multiple implementation +inheritance actually useful. When multiple implementation +inheritance seems like the solution, you can usually find +a different, more explicit, and cleaner solution.

+
+ +
+

Multiple inheritance is allowed only when all +superclasses, with the possible exception of the first one, +are pure interfaces. In order to +ensure that they remain pure interfaces, they must end with +the Interface suffix.

+
+ +
+

There is an exception to +this rule on Windows.

+
+ +
+ +

Interfaces

+ +
+

Classes that satisfy certain conditions are allowed, but +not required, to end with an Interface suffix.

+
+ +
+ +
+

A class is a pure interface if it meets the following +requirements:

+ +
    +
  • It has only public pure virtual ("= + 0") methods and static methods (but see below + for destructor).
    • + +
  • It may not have non-static data members.
    • + +
  • It need not have any constructors defined. If a + constructor is provided, it must take no arguments and + it must be protected.
    • + +
  • If it is a subclass, it may only be derived from + classes that satisfy these conditions and are tagged + with the Interface suffix.
    • +
+ +

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, The C++ +Programming Language, 3rd edition, section 12.4 +for details.

+
+ +
+

Tagging a class with the Interface suffix +lets others know that they must not add implemented +methods or non static data members. This is particularly +important in the case of multiple inheritance. +Additionally, the interface concept is already +well-understood by Java programmers.

+
+ +
+

The Interface 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.

+
+ +
+

A class may end +with Interface 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 Interface.

+
+ +
+ +

Operator Overloading

+ +
+

Overload operators judiciously. Do not create user-defined literals.

+
+ +
+ +
+

C++ permits user code to +declare +overloaded versions of the built-in operators using the +operator keyword, so long as one of the parameters +is a user-defined type. The operator keyword also +permits user code to define new kinds of literals using +operator"", and to define type-conversion functions +such as operator bool().

+
+ +
+

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. ==, <, +=, and <<), and adhering to +those conventions can make user-defined types more readable +and enable them to interoperate with libraries that expect +those names.

+ +

User-defined literals are a very concise notation for +creating objects of user-defined types.

+
+ +
+
    +
  • Providing a correct, consistent, and unsurprising + set of operator overloads requires some care, and failure + to do so can lead to confusion and bugs.
    • + +
  • Overuse of operators can lead to obfuscated code, + particularly if the overloaded operator's semantics + don't follow convention.
    • + +
  • The hazards of function overloading apply just as + much to operator overloading, if not more so.
    • + +
  • Operator overloads can fool our intuition into + thinking that expensive operations are cheap, built-in + operations.
    • + +
  • Finding the call sites for overloaded operators may + require a search tool that's aware of C++ syntax, rather + than e.g. grep.
    • + +
  • If you get the argument type of an overloaded operator + wrong, you may get a different overload rather than a + compiler error. For example, foo < bar + may do one thing, while &foo < &bar + does something totally different.
    • + +
  • Certain operator overloads are inherently hazardous. + Overloading unary & can cause the same + code to have different meanings depending on whether + the overload declaration is visible. Overloads of + &&, ||, and , + (comma) cannot match the evaluation-order semantics of the + built-in operators.
    • + +
  • 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.
    • + +
  • User-defined literals allow the creation of new + syntactic forms that are unfamiliar even to experienced C++ + programmers.
    • +
+
+ +
+

Define overloaded operators only if their meaning is +obvious, unsurprising, and consistent with the corresponding +built-in operators. For example, use | as a +bitwise- or logical-or, not as a shell-style pipe.

+ +

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 +<, overload all the comparison operators, +and make sure < and > never +return true for the same arguments.

+ +

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 a < b compiles but +b < a doesn't.

+ +

Don't go out of your way to avoid defining operator +overloads. For example, prefer to define ==, +=, and <<, rather than +Equals(), CopyFrom(), and +PrintTo(). 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 std::set, +use a custom comparator rather than overloading +<.

+ +

Do not overload &&, ||, +, (comma), or unary &. Do not overload +operator"", i.e. do not introduce user-defined +literals.

+ +

Type conversion operators are covered in the section on +implicit conversions. +The = operator is covered in the section on +copy constructors. Overloading +<< for use with streams is covered in the +section on streams. See also the rules on +function overloading, which +apply to operator overloading as well.

+
+ +
+ +

Access Control

+ +
+

Make data members private, unless they are +static const (and follow the +naming convention for constants). For technical +reasons, we allow data members of a test fixture class to +be protected when using + + +Google +Test).

+
+ +

Declaration Order

+ +
+

Group similar declarations together, placing public parts +earlier.

+
+ +
+ +

A class definition should usually start with a +public: section, followed by +protected:, then private:. Omit +sections that would be empty.

+ +

Within each section, generally prefer grouping similar +kinds of declarations together, and generally prefer the +following order: types (including typedef, +using, and nested structs and classes), +constants, factory functions, constructors, assignment +operators, destructor, all other methods, data members.

+ +

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 Inline +Functions for more details.

+ +
+ +

Functions

+ +

Parameter Ordering

+ +
+

When defining a function, parameter order is: inputs, then +outputs.

+
+ +
+

Parameters to C/C++ functions are either input to the +function, output from the function, or both. Input +parameters are usually values or const +references, while output and input/output parameters will +be pointers to non-const. 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.

+ +

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.

+ +
+ +

Write Short Functions

+ +
+

Prefer small and focused functions.

+
+ +
+

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.

+ +

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.

+ +

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.

+ +
+ +

Reference Arguments

+ +
+

All parameters passed by reference must be labeled +const.

+
+ +
+ +
+

In C, if a +function needs to modify a variable, the parameter must +use a pointer, eg int foo(int *pval). In +C++, the function can alternatively declare a reference +parameter: int foo(int &val).

+
+ +
+

Defining a parameter as reference avoids ugly code like +(*pval)++. Necessary for some applications +like copy constructors. Makes it clear, unlike with +pointers, that a null pointer is not a possible +value.

+
+ +
+

References can be confusing, as they have value syntax +but pointer semantics.

+
+ +
+

Within function parameter lists all references must be +const:

+ +
void Foo(const string &in, string *out);
+
+ +

In fact it is a very strong convention in Google code +that input arguments are values or const +references while output arguments are pointers. Input +parameters may be const pointers, but we +never allow non-const reference parameters +except when required by convention, e.g., +swap().

+ +

However, there are some instances where using +const T* is preferable to const +T& for input parameters. For example:

+ +
    +
  • You want to pass in a null pointer.
    • + +
  • The function saves a pointer or reference to the + input.
    • +
+ +

Remember that most of the time input +parameters are going to be specified as const +T&. Using const T* instead +communicates to the reader that the input is somehow +treated differently. So if you choose const +T* rather than const T&, do so +for a concrete reason; otherwise it will likely confuse +readers by making them look for an explanation that +doesn't exist.

+
+ +
+ +

Function Overloading

+ +
+

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.

+
+ +
+ +
+

You may write a function that takes a const +string& and overload it with another that +takes const char*.

+ +
class MyClass {
+ public:
+  void Analyze(const string &text);
+  void Analyze(const char *text, size_t textlen);
+};
+
+
+ +
+

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.

+
+ +
+

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.

+
+ +
+

If you want to overload a function, consider qualifying +the name with some information about the arguments, e.g., +AppendString(), AppendInt() +rather than just Append(). If you are +overloading a function to support variable number of +arguments of the same type, consider making it take a +std::vector so that the user can use an +initializer list + to specify the arguments.

+
+ +
+ +

Default Arguments

+ +
+

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 function overloading, and +prefer overloaded functions if the readability gained with +default arguments doesn't outweigh the downsides below.

+
+ +
+ +
+

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.

+
+ +
+

Defaulted arguments are another way to achieve the +semantics of overloaded functions, so all the reasons not to overload +functions apply.

+ +

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.

+ +

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.

+ +

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.

+
+ +
+

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 void +f(int n = counter++);.)

+ +

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.

+
+ +
+ +

Trailing Return Type Syntax

+
+

Use trailing return types only where using the ordinary syntax (leading + return types) is impractical or much less readable.

+
+ +
+

C++ allows two different forms of function declarations. In the older + form, the return type appears before the function name. For example:

+
int foo(int x);
+
+

The new form, introduced in C++11, uses the auto + keyword before the function name and a trailing return type after + the argument list. For example, the declaration above could + equivalently be written:

+
auto foo(int x) -> int;
+
+

The trailing return type is in the function's scope. This doesn't + make a difference for a simple case like int but it matters + for more complicated cases, like types declared in class scope or + types written in terms of the function parameters.

+
+ +
+
+

Trailing return types are the only way to explicitly specify the + return type of a lambda expression. + 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. +

+

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:

+ 
template <class T, class U> auto add(T t, U u) -> decltype(t + u);
+ versus + 
template <class T, class U> decltype(declval<T&>() + declval<U&>()) add(T t, U u);
+
+ +
+

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.

+

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.

+
+ +
+

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 + discouraged in most cases.

+ +
+
+ +

Google-Specific Magic

+ + + +

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.

+ + + +

Ownership and Smart Pointers

+ +
+

Prefer to have single, fixed owners for dynamically +allocated objects. Prefer to transfer ownership with smart +pointers.

+
+ +
+ +
+

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

+ +

"Smart" pointers are classes that act like pointers, +e.g. by overloading the * and +-> operators. Some smart pointer types +can be used to automate ownership bookkeeping, to ensure +these responsibilities are met. + +std::unique_ptr is a smart pointer type +introduced in C++11, which expresses exclusive ownership +of a dynamically allocated object; the object is deleted +when the std::unique_ptr goes out of scope. +It cannot be copied, but can be moved to +represent ownership transfer. + +std::shared_ptr is a smart pointer type +that expresses shared ownership of +a dynamically allocated object. std::shared_ptrs +can be copied; ownership of the object is shared among +all copies, and the object is deleted when the last +std::shared_ptr is destroyed.

+
+ +
+
    +
  • It's virtually impossible to manage dynamically + allocated memory without some sort of ownership + logic.
    • + +
  • Transferring ownership of an object can be cheaper + than copying it (if copying it is even possible).
    • + +
  • 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.
    • + +
  • Smart pointers can improve readability by making + ownership logic explicit, self-documenting, and + unambiguous.
    • + +
  • Smart pointers can eliminate manual ownership + bookkeeping, simplifying the code and ruling out large + classes of errors.
    • + +
  • For const objects, shared ownership can be a simple + and efficient alternative to deep copying.
    • +
+
+ +
+
    +
  • 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.
    • + +
  • The performance costs of value semantics are often + overestimated, so the performance benefits of ownership + transfer might not justify the readability and + complexity costs.
    • + +
  • APIs that transfer ownership force their clients + into a single memory management model.
    • + +
  • Code using smart pointers is less explicit about + where the resource releases take place.
    • + +
  • std::unique_ptr expresses ownership + transfer using C++11's move semantics, which are + relatively new and may confuse some programmers.
    • + +
  • Shared ownership can be a tempting alternative to + careful ownership design, obfuscating the design of a + system.
    • + +
  • Shared ownership requires explicit bookkeeping at + run-time, which can be costly.
    • + +
  • In some cases (e.g. cyclic references), objects + with shared ownership may never be deleted.
    • + +
  • Smart pointers are not perfect substitutes for + plain pointers.
    • +
+
+ +
+

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 std::unique_ptr to +make ownership transfer explicit. For example:

+ +
std::unique_ptr<Foo> FooFactory();
+void FooConsumer(std::unique_ptr<Foo> ptr);
+
+ + + +

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. +std::shared_ptr<const Foo>). If you +do use shared ownership, prefer to use +std::shared_ptr.

+ +

Never use std::auto_ptr. Instead, use +std::unique_ptr.

+
+ +
+ +

cpplint

+ +
+

Use cpplint.py +to detect style errors.

+
+ +
+ +

cpplint.py +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 // +NOLINT at the end of the line or +// NOLINTNEXTLINE in the previous line.

+ + + +

Some projects have instructions on +how to run cpplint.py from their project +tools. If the project you are contributing to does not, +you can download + +cpplint.py separately.

+ +
+ + + +

Other C++ Features

+ +

Rvalue References

+ +
+

Use rvalue references only to define move constructors and move assignment +operators, or for perfect forwarding. +

+
+ +
+ +
+

Rvalue references +are a type of reference that can only bind to temporary +objects. The syntax is similar to traditional reference +syntax. For example, void f(string&& +s); declares a function whose argument is an +rvalue reference to a string.

+
+ +
+
    +
  • 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 + v1 is a std::vector<string>, + for example, then auto v2(std::move(v1)) + 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.
    • + +
  • 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".)
    • + +
  • 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.
    • + +
  • std::move is necessary to make + effective use of some standard-library types, such as + std::unique_ptr.
    • +
+
+ +
+
    +
  • 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.
    • +
+
+ +
+

Use rvalue references only to define move constructors and move assignment + operators (as described in Copyable and + Movable Types) and, in conjunction with std::forward, +to support perfect forwarding. You may use std::move to express +moving a value from one object to another rather than copying it.

+
+ +
+ +

Friends

+ +
+

We allow use of friend classes and functions, +within reason.

+
+ +
+ +

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 friend is to have a +FooBuilder class be a friend of +Foo so that it can construct the inner state +of Foo 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.

+ +

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.

+ +
+ +

Exceptions

+ +
+

We do not use C++ exceptions.

+
+ +
+ +
+
    +
  • 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.
    • + + + +
  • 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.
    • + +
  • Some third-party C++ libraries use exceptions, and + turning them off internally makes it harder to + integrate with those libraries.
    • + +
  • Exceptions are the only way for a constructor to + fail. We can simulate this with a factory function or + an Init() method, but these require heap + allocation or a new "invalid" state, respectively.
    • + +
  • Exceptions are really handy in testing + frameworks.
    • +
+
+ +
+
    +
  • When you add a throw 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 + f() calls g() calls + h(), and h throws an + exception that f catches, g + has to be careful or it may not clean up properly.
    • + +
  • 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.
    • + +
  • 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.
    • + +
  • Turning on exceptions adds data to each binary + produced, increasing compile time (probably slightly) + and possibly increasing address space pressure. +
    • + +
  • 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!
    • +
+
+ +
+

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.

+ +

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.

+ +

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.

+ +

This prohibition also applies to the exception-related +features added in C++11, such as noexcept, +std::exception_ptr, and +std::nested_exception.

+ +

There is an exception to +this rule (no pun intended) for Windows code.

+
+ +
+ +

Run-Time Type +Information (RTTI)

+ +
+

Avoid using Run Time Type Information (RTTI).

+
+ +
+ +
+

RTTI allows a +programmer to query the C++ class of an object at run +time. This is done by use of typeid or +dynamic_cast.

+
+ +
+

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.

+ +

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.

+
+ +
+

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.

+ +

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.

+ +

RTTI is useful when considering multiple abstract +objects. Consider

+ +
bool Base::Equal(Base* other) = 0;
+bool Derived::Equal(Base* other) {
+  Derived* that = dynamic_cast<Derived*>(other);
+  if (that == NULL)
+    return false;
+  ...
+}
+
+
+ +
+

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:

+ +
    +
  • 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.
    • + +
  • 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.
    • +
+ +

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 +dynamic_cast may be used freely on the +object. Usually one +can use a static_cast as an alternative in +such situations.

+ +

Decision trees based on type are a strong indication +that your code is on the wrong track.

+ +
if (typeid(*data) == typeid(D1)) {
+  ...
+} else if (typeid(*data) == typeid(D2)) {
+  ...
+} else if (typeid(*data) == typeid(D3)) {
+...
+
+ +

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.

+ +

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.

+
+ +
+ +

Casting

+ +
+

Use C++-style casts +like static_cast<float>(double_value), or brace +initialization for conversion of arithmetic types like +int64 y = int64{1} << 42. Do not use +cast formats like +int y = (int)x or int y = int(x) (but the latter +is okay when invoking a constructor of a class type).

+
+ +
+ +
+

C++ introduced a +different cast system from C that distinguishes the types +of cast operations.

+
+ +
+

The problem with C casts is the ambiguity of the operation; +sometimes you are doing a conversion +(e.g., (int)3.5) and sometimes you are doing +a cast (e.g., (int)"hello"). Brace +initialization and C++ casts can often help avoid this +ambiguity. Additionally, C++ casts are more visible when searching for +them.

+
+ +
+

The C++-style cast syntax is verbose and cumbersome.

+
+ +
+

Do not use C-style casts. Instead, use these C++-style casts when +explicit type conversion is necessary.

+ +
    +
  • Use brace initialization to convert arithmetic types + (e.g. int64{x}). This is the safest approach because code + will not compile if conversion can result in information loss. The + syntax is also concise.
    • + + + +
  • Use static_cast 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.
    • + + + +
  • Use const_cast to remove the + const qualifier (see const).
    • + +
  • Use reinterpret_cast 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. +
    • + + +
+ +

See the +RTTI section for guidance on the use of +dynamic_cast.

+
+ +
+ +

Streams

+ +
+

Use streams where appropriate, and stick to "simple" +usages.

+
+ +
+ +
+

Streams are the standard I/O abstraction in C++, as +exemplified by the standard header <iostream>. +They are widely used in Google code, but only for debug logging +and test diagnostics.

+
+ +
+

The << and >> +stream operators provide an API for formatted I/O that +is easily learned, portable, reusable, and extensible. +printf, by contrast, doesn't even support +string, to say nothing of user-defined types, +and is very difficult to use portably. +printf also obliges you to choose among the +numerous slightly different versions of that function, +and navigate the dozens of conversion specifiers.

+ +

Streams provide first-class support for console I/O +via std::cin, std::cout, +std::cerr, and std::clog. +The C APIs do as well, but are hampered by the need to +manually buffer the input.

+
+ +
+
    +
  • 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.
    • + +
  • 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).
    • + +
  • The practice of building up output through chains +of << operators interferes with +internationalization, because it bakes word order into the +code, and streams' support for localization is +flawed.
    • + + + + + +
  • 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.
    • + +
  • Resolving the many overloads of << 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.
    • +
+
+ +
+

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.

+ +

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.

+ +

If you do use streams, avoid the stateful parts of the +streams API (other than error state), such as imbue(), +xalloc(), and register_callback(). +Use explicit formatting functions rather than +stream manipulators or formatting flags to control formatting +details such as number base, precision, or padding.

+ +

Overload << as a streaming operator +for your type only if your type represents a value, and +<< writes out a human-readable string +representation of that value. Avoid exposing implementation +details in the output of <<; if you need to print +object internals for debugging, use named functions instead +(a method named DebugString() is the most common +convention).

+
+ +
+ +

Preincrement and Predecrement

+ +
+

Use prefix form (++i) of the increment and +decrement operators with iterators and other template +objects.

+
+ +
+ +
+

When a variable +is incremented (++i or i++) or +decremented (--i or i--) and +the value of the expression is not used, one must decide +whether to preincrement (decrement) or postincrement +(decrement).

+
+ +
+

When the return value is ignored, the "pre" form +(++i) is never less efficient than the +"post" form (i++), and is often more +efficient. This is because post-increment (or decrement) +requires a copy of i to be made, which is +the value of the expression. If i is an +iterator or other non-scalar type, copying i +could be expensive. Since the two types of increment +behave the same when the value is ignored, why not just +always pre-increment?

+
+ +
+

The tradition developed, in C, of using post-increment +when the expression value is not used, especially in +for loops. Some find post-increment easier +to read, since the "subject" (i) precedes +the "verb" (++), just like in English.

+
+ +
+

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.

+
+ +
+ +

Use of const

+ +
+

Use const whenever it makes sense. With C++11, +constexpr is a better choice for some uses of +const.

+
+ +
+ +
+

Declared variables and parameters can be preceded +by the keyword const to indicate the variables +are not changed (e.g., const int foo). Class +functions can have the const qualifier to +indicate the function does not change the state of the +class member variables (e.g., class Foo { int +Bar(char c) const; };).

+
+ +
+

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.

+
+ +
+

const is viral: if you pass a +const variable to a function, that function +must have const in its prototype (or the +variable will need a const_cast). This can +be a particular problem when calling library +functions.

+
+ +
+

const 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 +const whenever it makes sense to do so:

+ +
    +
  • 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 (const T&) or + pointer-to-const (const T*), respectively.
    • + +
  • Declare methods to be const whenever + possible. Accessors should almost always be + const. Other methods should be const if + they do not modify any data members, do not call any + non-const methods, and do not return a + non-const pointer or + non-const reference to a data member.
    • + +
  • Consider making data members const + whenever they do not need to be modified after + construction.
    • +
+ +

The mutable keyword is allowed but is +unsafe when used with threads, so thread safety should be +carefully considered first.

+
+ +
+

Where to put the const

+ +

Some people favor the form int const *foo +to const int* foo. They argue that this is +more readable because it's more consistent: it keeps the +rule that const always follows the object +it's describing. However, this consistency argument +doesn't apply in codebases with few deeply-nested pointer +expressions since most const expressions +have only one const, and it applies to the +underlying value. In such cases, there's no consistency +to maintain. Putting the const first is +arguably more readable, since it follows English in +putting the "adjective" (const) before the +"noun" (int).

+ +

That said, while we encourage putting +const first, we do not require it. But be +consistent with the code around you!

+
+ +
+ +

Use of constexpr

+ +
+

In C++11, use constexpr to define true +constants or to ensure constant initialization.

+
+ +
+ +
+

Some variables can be declared constexpr +to indicate the variables are true constants, i.e. fixed at +compilation/link time. Some functions and constructors +can be declared constexpr which enables them +to be used in defining a constexpr +variable.

+
+ +
+

Use of constexpr 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.

+
+ +
+

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.

+
+ +
+

constexpr definitions enable a more +robust specification of the constant parts of an +interface. Use constexpr to specify true +constants and the functions that support their +definitions. Avoid complexifying function definitions to +enable their use with constexpr. Do not use +constexpr to force inlining.

+
+ +
+ +

Integer Types

+ +
+

Of the built-in C++ integer types, the only one used + is +int. If a program needs a variable of a +different size, use +a precise-width integer type from +<stdint.h>, such as +int16_t. 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 +int64_t. +Keep in mind that even if your value won't ever be too large +for an int, it may be used in intermediate +calculations which may require a larger type. When in doubt, +choose a larger type.

+
+ +
+ +
+

C++ does not specify the sizes of its integer types. +Typically people assume that short is 16 bits, +int is 32 bits, long is 32 bits +and long long is 64 bits.

+
+ +
+

Uniformity of declaration.

+
+ +
+

The sizes of integral types in C++ can vary based on +compiler and architecture.

+
+ +
+ +

+<stdint.h> defines types +like int16_t, uint32_t, +int64_t, etc. You should always use +those in preference to short, unsigned +long long and the like, when you need a guarantee +on the size of an integer. Of the C integer types, only +int should be used. When appropriate, you +are welcome to use standard types like +size_t and ptrdiff_t.

+ +

We use int very often, for integers we +know are not going to be too big, e.g., loop counters. +Use plain old int for such things. You +should assume that an int 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 +int64_t +or +uint64_t.

+ +

For integers we know can be "big", + use +int64_t. +

+ +

You should not use the unsigned integer types such as +uint32_t, 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.

+ + + +

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.

+ +

Use care when converting integer types. Integer +conversions and promotions can cause non-intuitive +behavior.

+
+ +
+ +

On Unsigned Integers

+ +

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:

+ +
for (unsigned int i = foo.Length()-1; i >= 0; --i) ...
+
+ +

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.

+ +

So, document that a variable is non-negative using +assertions. Don't use an unsigned +type.

+
+ +
+ +

64-bit Portability

+ +
+

Code should be 64-bit and 32-bit friendly. Bear in mind +problems of printing, comparisons, and structure alignment.

+
+ +
+ +
    +
  • +

    printf() 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 + inttypes.h):

    + +
    + 
    // 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"
+
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    TypeDO NOT useDO useNotes
    void * (or any pointer)%lx%p
    int64_t%qd, %lld%" PRId64 "
    uint64_t%qu, %llu, + %llx%" PRIu64 ", + %" PRIx64 "
    size_t%u%" PRIuS ", %" PRIxS " + C99 specifies %zu
    ptrdiff_t%d%" PRIdS " + C99 specifies %td
    + +

    Note that the PRI* 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 % when using + the PRI* macros. So, e.g. + printf("x = %30" PRIuS "\n", x) would + expand on 32-bit Linux to printf("x = %30" "u" + "\n", x), which the compiler will treat as + printf("x = %30u\n", x).

    + + +
    • + +
  • Remember that sizeof(void *) != + sizeof(int). Use intptr_t if + you want a pointer-sized integer.
    • + +
  • You may need to be careful with structure + alignments, particularly for structures being stored on + disk. Any class/structure with a + int64_t/uint64_t + 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 + __attribute__((packed)). MSVC offers + #pragma pack() and + __declspec(align()).
    • + +
  • +

    Use the LL or ULL + suffixes as needed to create 64-bit constants. For + example:

    + + +
    int64_t my_value = 0x123456789LL;
+uint64_t my_mask = 3ULL << 48;
+
    +
    • +
+ +
+ +

Preprocessor Macros

+ +
+

Avoid defining macros, especially in headers; prefer +inline functions, enums, and const variables. +Name macros with a project-specific prefix. Do not use +macros to define pieces of a C++ API.

+
+ +
+ +

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.

+ +

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:

+ +
class WOMBAT_TYPE(Foo) {
+  // ...
+
+ public:
+  EXPAND_PUBLIC_WOMBAT_API(Foo)
+
+  EXPAND_WOMBAT_COMPARISONS(Foo, ==, <)
+};
+
+ +

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 +const 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 #define guards to prevent double +inclusion of header files). It makes testing much more +difficult.

+ +

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.

+ +

The following usage pattern will avoid many problems +with macros; if you use macros, follow it whenever +possible:

+ +
    +
  • Don't define macros in a .h file.
    • + +
  • #define macros right before you use + them, and #undef them right after.
    • + +
  • Do not just #undef an existing macro + before replacing it with your own; instead, pick a name + that's likely to be unique.
    • + +
  • Try not to use macros that expand to unbalanced C++ + constructs, or at least document that behavior + well.
    • + +
  • Prefer not using ## to generate + function/class/variable names.
    • +
+ +

Exporting macros from headers (i.e. defining them in a header +without #undefing 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).

+ +
+ +

0 and nullptr/NULL

+ +
+

Use 0 for integers, 0.0 for +reals, nullptr (or NULL) for +pointers, and '\0' for chars.

+
+ +
+ +

Use 0 for integers and 0.0 +for reals. This is not controversial.

+ +

For +pointers (address values), there is a choice between +0, NULL, and +nullptr. For projects that allow C++11 +features, use nullptr. For C++03 projects, +we prefer NULL because it looks like a +pointer. In fact, some C++ compilers provide special +definitions of NULL which enable them to +give useful warnings, particularly in situations where +sizeof(NULL) is not equal to +sizeof(0).

+ +

Use '\0' for chars. This is the correct +type and also makes code more readable.

+ +
+ +

sizeof

+ +
+

Prefer sizeof(varname) to +sizeof(type).

+
+ +
+ +

Use sizeof(varname) when you +take the size of a particular variable. +sizeof(varname) will update +appropriately if someone changes the variable type either +now or later. You may use +sizeof(type) 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.

+ +
Struct data;
+memset(&data, 0, sizeof(data));
+
+ +
memset(&data, 0, sizeof(Struct));
+
+ +
if (raw_size < sizeof(int)) {
+  LOG(ERROR) << "compressed record not big enough for count: " << raw_size;
+  return false;
+}
+
+ +
+ +

auto

+ +
+

Use auto 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.

+
+ +
+ +
+

+

    +
  • C++ type names can be long and cumbersome, especially when they +involve templates or namespaces.
    • +
  • When a C++ type name is repeated within a single declaration or a +small code region, the repetition may not be aiding readability.
    • +
  • 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.
    • +
+
+
+ +

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:

+ +
auto foo = x.add_foo();
+auto i = y.Find(key);
+
+ +

it may not be obvious what the resulting types are if the type +of y isn't very well known, or if y was +declared many lines earlier.

+ +

Programmers have to understand the difference between +auto and const auto& or +they'll get copies when they didn't mean to.

+ +

If an auto 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.

+
+ +
+ +

auto is permitted when it increases readability, +particularly as described below. Never initialize an auto-typed +variable with a braced initializer list.

+ +

Specific cases where auto is allowed or encouraged: +

    +
  • (Encouraged) For iterators and other long/cluttery type names, particularly +when the type is clear from context (calls +to find, begin, or end for +instance).
    • +
  • (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 new +commonly falls into this category, as does use of auto in +a range-based loop over a container whose type is spelled out +nearby.
    • +
  • (Allowed) When the type doesn't matter because it isn't being used for +anything other than equality comparison.
    • +
  • (Encouraged) When iterating over a map with a range-based loop +(because it is often assumed that the correct type +is std::pair<KeyType, ValueType> whereas it is actually +std::pair<const KeyType, ValueType>). This is +particularly well paired with local key +and value aliases for .first +and .second (often const-ref). +
    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.
+}
+
    +
    • +
+ +
+ +
+ +

Braced Initializer List

+ +
+

You may use braced initializer lists.

+
+ +
+ +

In C++03, aggregate types (arrays and structs with no +constructor) could be initialized with braced initializer lists.

+ +
struct Point { int x; int y; };
+Point p = {1, 2};
+
+ +

In C++11, this syntax was generalized, and any object type can now +be created with a braced initializer list, known as a +braced-init-list in the C++ grammar. Here are a few examples +of its use.

+ +
// 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});
+
+ +

A user-defined type can also define a constructor and/or assignment operator +that take std::initializer_list<T>, which is automatically +created from braced-init-list:

+ +
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};
+
+ +

Finally, brace initialization can also call ordinary +constructors of data types, even if they do not have +std::initializer_list<T> constructors.

+ +
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"};
+
+ +

Never assign a braced-init-list to an auto +local variable. In the single element case, what this +means can be confusing.

+ +
auto d = {1.23};        // d is a std::initializer_list<double>
+
+ +
auto d = double{1.23};  // Good -- d is a double, not a std::initializer_list.
+
+ +

See Braced_Initializer_List_Format for formatting.

+ +
+ +

Lambda expressions

+ +
+

Use lambda expressions where appropriate. Prefer explicit captures +when the lambda will escape the current scope.

+
+ +
+ +
+ +

Lambda expressions are a concise way of creating anonymous +function objects. They're often useful when passing +functions as arguments. For example:

+ +
std::sort(v.begin(), v.end(), [](int x, int y) {
+  return Weight(x) < Weight(y);
+});
+
+ +

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:

+ +
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;
+});
+
+ + +Default captures implicitly capture any variable referenced in the +lambda body, including this if any members are used: + +
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];
+});
+
+ +

Lambdas were introduced in C++11 along with a set of utilities +for working with function objects, such as the polymorphic +wrapper std::function. +

+
+ +
+
    +
  • Lambdas are much more concise than other ways of + defining function objects to be passed to STL + algorithms, which can be a readability + improvement.
    • + +
  • Appropriate use of default captures can remove + redundancy and highlight important exceptions from + the default.
    • + +
  • Lambdas, std::function, and + std::bind can be used in combination as a + general purpose callback mechanism; they make it easy + to write functions that take bound functions as + arguments.
    • +
+
+ +
+
    +
  • Variable capture in lambdas can be a source of dangling-pointer + bugs, particularly if a lambda escapes the current scope.
    • + +
  • 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.
    • + +
  • It's possible for use of lambdas to get out of + hand; very long nested anonymous functions can make + code harder to understand.
    • + +
+
+ +
+
    +
  • Use lambda expressions where appropriate, with formatting as +described below.
    • +
  • Prefer explicit captures if the lambda may escape the current scope. +For example, instead of: +
    {
+  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.
+
    +prefer to write: +
    {
+  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.
+
    +
    • +
  • Use default capture by reference ([&]) only when the +lifetime of the lambda is obviously shorter than any potential +captures. +
    • +
  • 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. +
    • +
  • 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.
    • +
  • Specify the return type of the lambda explicitly if that will +make it more obvious to readers, as with +auto.
    • + +
+
+ +
+ +

Template metaprogramming

+
+

Avoid complicated template programming.

+
+ +
+ +
+

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.

+
+ +
+

Template metaprogramming allows extremely flexible interfaces that +are type safe and high performance. Facilities like + +Google Test, +std::tuple, std::function, and +Boost.Spirit would be impossible without it.

+
+ +
+

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.

+ +

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.

+ +

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.

+
+ +
+

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.

+ +

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 sizeof trick for detecting function +overload resolution, then there's a good chance you've gone too +far.

+ +

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.

+ +
+
+ + +

Boost

+ +
+

Use only approved libraries from the Boost library +collection.

+
+ +
+ +
+

The + +Boost library collection is a popular collection of +peer-reviewed, free, open-source C++ libraries.

+
+ +
+

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.

+
+ +
+

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.

+
+ +
+ + + +
+

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:

+ + + +

We are actively considering adding other Boost +features to the list, so this list may be expanded in +the future.

+
+ +

The following libraries are permitted, but their use +is discouraged because they've been superseded by +standard libraries in C++11:

+ + +
+ +
+ + + +

std::hash

+ +
+

Do not define specializations of std::hash.

+
+ +
+ +
+

std::hash<T> is the function object that the +C++11 hash containers use to hash keys of type T, +unless the user explicitly specifies a different hash function. For +example, std::unordered_map<int, string> is a hash +map that uses std::hash<int> to hash its keys, +whereas std::unordered_map<int, string, MyIntHash> +uses MyIntHash.

+ +

std::hash is defined for all integral, floating-point, +pointer, and enum types, as well as some standard library +types such as string and unique_ptr. Users +can enable it to work for their own types by defining specializations +of it for those types.

+
+ +
+

std::hash is easy to use, and simplifies the code +since you don't have to name it explicitly. Specializing +std::hash 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.

+
+ +
+

std::hash 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 + +hash flooding attacks.

+ +

Even for experts, std::hash specializations are +inordinately difficult to implement correctly for compound types, +because the implementation cannot recursively call std::hash +on data members. High-quality hash algorithms maintain large +amounts of internal state, and reducing that state to the +size_t bytes that std::hash +returns is usually the slowest part of the computation, so it +should not be done more than once.

+ +

Due to exactly that issue, std::hash does not work +with std::pair or std::tuple, and the +language does not allow us to extend it to support them.

+
+ +
+

You can use std::hash 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 std::hash +does not support, consider using legacy hash containers (e.g. +hash_map) for now; they use a different default hasher, +which is unaffected by this prohibition.

+ +

If you want to use the standard hash containers anyway, you will +need to specify a custom hasher for the key type, e.g.

+
std::unordered_map<MyKeyType, Value, MyKeyTypeHasher> my_map;
+

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

+ +

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 +std::hash.

+
+ +
+ +

C++11

+ +
+

Use libraries and language extensions from C++11 when appropriate. +Consider portability to other environments +before using C++11 features in your +project.

+ +
+ +
+ +
+

C++11 contains +significant changes both to the language and +libraries.

+
+ +
+

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.

+
+ +
+

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.

+ +

As with Boost, 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.

+ + +
+ +
+ +

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:

+ +
    + + + + + + + + +
  • Compile-time rational numbers + (<ratio>), because of concerns that + it's tied to a more template-heavy interface + style.
    • + +
  • The <cfenv> and + <fenv.h> headers, because many + compilers do not support those features reliably.
    • + +
  • Ref-qualifiers on member functions, such as void X::Foo() + & or void X::Foo() &&, because of concerns + that they're an overly obscure feature.
    • + + + + +
+
+ +
+ +

Nonstandard Extensions

+ +
+

Nonstandard extensions to C++ may not be used unless otherwise specified.

+
+
+
+

Compilers support various extensions that are not part of standard C++. Such + extensions include GCC's __attribute__, intrinsic functions such + as __builtin_prefetch, designated initializers (e.g. + Foo f = {.field = 3}), inline assembly, __COUNTER__, + __PRETTY_FUNCTION__, compound statement expressions (e.g. + foo = ({ int x; Bar(&x); x }), variable-length arrays and + alloca(), and the a?:b syntax.

+
+ +
+
    +
  • 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.
    • +
  • Important performance guidance to the compiler can only be specified + using extensions.
    • +
+
+ +
+
    +
  • Nonstandard extensions do not work in all compilers. Use of nonstandard + extensions reduces portability of code.
    • +
  • 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.
    • +
  • Nonstandard extensions add to the language features that a reader must + know to understand the code.
    • +
+
+ +
+

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.

+
+
+ +

Aliases

+ +
+

Public aliases are for the benefit of an API's user, and should be clearly documented.

+
+
+
+

There are several ways to create names that are aliases of other entities:

+
typedef Foo Bar;
+using Bar = Foo;
+using other_namespace::Foo;
+
+ +

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.

+
+ +
+
    +
  • Aliases can improve readability by simplifying a long or complicated name.
    • +
  • Aliases can reduce duplication by naming in one place a type used repeatedly in an API, + which might make it easier to change the type later. +
    • +
+
+ +
+
    +
  • 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.
    • +
  • Clients can easily rely on unintended details of public aliases, making + changes difficult.
    • +
  • 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.
    • +
  • Aliases can create risk of name collisions
    • +
  • Aliases can reduce readability by giving a familiar construct an unfamiliar name
    • +
  • 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
    • +
+
+ +
+

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.

+

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.

+

Don't put namespace aliases in your public API. (See also Namespaces). +

+ +

For example, these aliases document how they are intended to be used in client code:

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

These aliases don't document intended use, and half of them aren't meant for client use:

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

However, local convenience aliases are fine in function definitions, private sections of + classes, explicitly marked internal namespaces, and in .cc files:

+ +
// In a .cc file
+using std::unordered_set;
+
+ +
+
+ +

Naming

+ +

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

+ +

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.

+ +

General Naming Rules

+ +
+

Names should be descriptive; avoid abbreviation.

+
+ +
+

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.

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

Note that certain universally-known abbreviations are OK, such as +i for an iteration variable and T for a +template parameter.

+ +

Template parameters should follow the naming style for their +category: type template parameters should follow the rules for +type names, and non-type template +parameters should follow the rules for +variable names. + +

+ +

File Names

+ +
+

Filenames should be all lowercase and can include +underscores (_) or dashes (-). +Follow the convention that your + +project uses. If there is no consistent +local pattern to follow, prefer "_".

+
+ +
+ +

Examples of acceptable file names:

+ +
    +
  • my_useful_class.cc
    • +
  • my-useful-class.cc
    • +
  • myusefulclass.cc
    • +
  • myusefulclass_test.cc // _unittest and _regtest are deprecated.
    • +
+ +

C++ files should end in .cc and header files should end in +.h. Files that rely on being textually included at specific points +should end in .inc (see also the section on +self-contained headers).

+ +

Do not use filenames that already exist in +/usr/include, such as db.h.

+ +

In general, make your filenames very specific. For +example, use http_server_logs.h rather than +logs.h. A very common case is to have a pair +of files called, e.g., foo_bar.h and +foo_bar.cc, defining a class called +FooBar.

+ +

Inline functions must be in a .h file. If +your inline functions are very short, they should go +directly into your .h file.

+ +
+ +

Type Names

+ +
+

Type names start with a capital letter and have a capital +letter for each new word, with no underscores: +MyExcitingClass, MyExcitingEnum.

+
+ +
+ +

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:

+ +
// 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 { ...
+
+ +
+ +

Variable Names

+ +
+

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: +a_local_variable, a_struct_data_member, +a_class_data_member_.

+
+ +
+ +

Common Variable names

+ +

For example:

+ +
string table_name;  // OK - uses underscore.
+string tablename;   // OK - all lowercase.
+
+ +
string tableName;   // Bad - mixed case.
+
+ +

Class Data Members

+ +

Data members of classes, both static and non-static, are +named like ordinary nonmember variables, but with a +trailing underscore.

+ +
class TableInfo {
+  ...
+ private:
+  string table_name_;  // OK - underscore at end.
+  string tablename_;   // OK.
+  static Pool<TableInfo>* pool_;  // OK.
+};
+
+ +

Struct Data Members

+ +

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.

+ +
struct UrlTableProperties {
+  string name;
+  int num_entries;
+  static Pool<UrlTableProperties>* pool;
+};
+
+ + +

See Structs vs. +Classes for a discussion of when to use a struct +versus a class.

+ +
+ +

Constant Names

+ +
+

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:

+
+ +
const int kDaysInAWeek = 7;
+
+ +
+ +

All such variables with static storage duration (i.e. statics and globals, + see + Storage Duration 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.

+ +

+ +

Function Names

+ +
+

Regular functions have mixed case; accessors and mutators may be named +like variables.

+
+ +
+ +

Ordinarily, functions should start with a capital letter and have a +capital letter for each new word +(a.k.a. "Camel +Case" or "Pascal case"). Such names should not have +underscores. Prefer to capitalize acronyms as single words +(i.e. StartRpc(), not StartRPC()).

+ +
AddTableEntry()
+DeleteUrl()
+OpenFileOrDie()
+
+ +

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

+ +

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, int count() and void +set_count(int count).

+ +
+ +

Namespace Names

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

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

+ + + + + +

Keep in mind that the rule +against abbreviated names 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.

+ +

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 std namespaces. Prefer unique project +identifiers +(websearch::index, websearch::index_util) +over collision-prone names like websearch::util.

+ +

For internal namespaces, be wary of other code being +added to the same internal 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 +(websearch::index::frobber_internal for use +in frobber.h)

+ +
+ +

Enumerator Names

+ +
+

Enumerators (for both scoped and unscoped enums) should be named either like +constants or like +macros: either kEnumName or +ENUM_NAME.

+
+ +
+ +

Preferably, the individual enumerators should be named +like constants. However, it +is also acceptable to name them like +macros. The enumeration name, +UrlTableErrors (and +AlternateUrlTableErrors), is a type, and +therefore mixed case.

+ +
enum UrlTableErrors {
+  kOK = 0,
+  kErrorOutOfMemory,
+  kErrorMalformedInput,
+};
+enum AlternateUrlTableErrors {
+  OK = 0,
+  OUT_OF_MEMORY = 1,
+  MALFORMED_INPUT = 2,
+};
+
+ +

Until January 2009, the style was to name enum values +like macros. 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.

+ + + +
+ +

Macro Names

+ +
+

You're not really going to +define a macro, are you? If you do, they're like this: +MY_MACRO_THAT_SCARES_SMALL_CHILDREN.

+
+ +
+ +

Please see the description +of macros; in general macros should not be used. +However, if they are absolutely needed, then they should be +named with all capitals and underscores.

+ +
#define ROUND(x) ...
+#define PI_ROUNDED 3.0
+
+ +
+ +

Exceptions to Naming Rules

+ +
+

If you are naming something that is analogous to an +existing C or C++ entity then you can follow the existing +naming convention scheme.

+
+ +
+ +
+
bigopen()
+
function name, follows form of open()
+ +
uint
+
typedef
+ +
bigpos
+
struct or class, follows + form of pos
+ +
sparse_hash_map
+
STL-like entity; follows STL naming conventions
+ +
LONGLONG_MAX
+
a constant, as in INT_MAX
+
+ +
+ +

Comments

+ +

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.

+ +

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!

+ +

Comment Style

+ +
+

Use either the // or /* */ +syntax, as long as you are consistent.

+
+ +
+ +

You can use either the // or the /* +*/ syntax; however, // is +much more common. Be consistent with how you +comment and what style you use where.

+ +
+ +

File Comments

+ +
+

Start each file with license boilerplate.

+ +

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.

+ +
+ +
+ +

Legal Notice and Author +Line

+ + + +

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

+ +

If you make significant changes to a file with an +author line, consider deleting the author line.

+ +

File Contents

+ +

If a .h 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.

+ +

Do not duplicate comments in both the .h and the +.cc. Duplicated comments diverge.

+ +
+ +

Class Comments

+ +
+

Every non-obvious class declaration should have an accompanying +comment that describes what it is for and how it should be used.

+
+ +
+ +
// 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 {
+  ...
+};
+
+ +

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.

+ +

The class comment is often a good place for a small example code snippet +demonstrating a simple and focused usage of the class.

+ +

When sufficiently separated (e.g. .h and .cc +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.

+ +
+ +

Function Comments

+ +
+

Declaration comments describe use of the function (when it is +non-obvious); comments at the definition of a function describe +operation.

+
+ +
+ +

Function Declarations

+ +

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.

+ +

Types of things to mention in comments at the function +declaration:

+ +
    +
  • What the inputs and outputs are.
    • + +
  • 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.
    • + +
  • If the function allocates memory that the caller + must free.
    • + +
  • Whether any of the arguments can be a null + pointer.
    • + +
  • If there are any performance implications of how a + function is used.
    • + +
  • If the function is re-entrant. What are its + synchronization assumptions?
    • +
+ +

Here is an example:

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

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.

+ +
// Returns true if the table cannot hold any more entries.
+bool IsTableFull();
+
+ +

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.

+ +

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.

+ +

Function Definitions

+ +

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.

+ +

Note you should not just repeat the comments +given with the function declaration, in the +.h 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.

+ +
+ +

Variable Comments

+ +
+

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.

+
+ +
+ +

Class Data Members

+ +

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 (int +num_events_;), no comment is needed.

+ +

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:

+ +
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_;
+
+ +

Global Variables

+ +

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:

+ +
// The total number of tests cases that we run through in this regression test.
+const int kNumTestCases = 6;
+
+ +
+ +

Implementation Comments

+ +
+

In your implementation you should have comments in tricky, +non-obvious, interesting, or important parts of your code.

+
+ +
+ +

Explanatory Comments

+ +

Tricky or complicated code blocks should have comments +before them. Example:

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

Line Comments

+ +

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:

+ +
// 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.
+
+ +

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.

+ +

If you have several comments on subsequent lines, it +can often be more readable to line them up:

+ +
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. */
+
+ +

Function Argument Comments

+ +

When the meaning of a function argument is nonobvious, consider +one of the following remedies:

+ +
    +
  • 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.
    • + +
  • Consider changing the function signature to replace a bool + argument with an enum argument. This will make the argument + values self-describing.
    • + +
  • 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. +
    • + +
  • Replace large or complex nested expressions with named variables.
    • + +
  • As a last resort, use comments to clarify argument meanings at the + call site.
    • +
+ +Consider the following example: + +
// What are these arguments?
+const DecimalNumber product = CalculateProduct(values, 7, false, nullptr);
+
+ +

versus:

+ +
ProductOptions options;
+options.set_precision_decimals(7);
+options.set_use_cache(ProductOptions::kDontUseCache);
+const DecimalNumber product =
+    CalculateProduct(values, options, /*completion_callback=*/nullptr);
+
+ +

Don'ts

+ +

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 why +the code does what it does, or make the code self describing.

+ +Compare this: + +
// Find the element in the vector.  <-- Bad: obvious!
+auto iter = std::find(v.begin(), v.end(), element);
+if (iter != v.end()) {
+  Process(element);
+}
+
+ +To this: + +
// Process "element" unless it was already processed.
+auto iter = std::find(v.begin(), v.end(), element);
+if (iter != v.end()) {
+  Process(element);
+}
+
+ +Self-describing code doesn't need a comment. The comment from +the example above would be obvious: + +
if (!IsAlreadyProcessed(element)) {
+  Process(element);
+}
+
+ +
+ +

Punctuation, Spelling and Grammar

+ +
+

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 you +should be consistent with your style.

+ +

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.

+ +
+ +

TODO Comments

+ +
+

Use TODO comments for code that is temporary, +a short-term solution, or good-enough but not perfect.

+
+ +
+ +

TODOs should include the string +TODO 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 TODO. The +main purpose is to have a consistent TODO that +can be searched to find out how to get more details upon +request. A TODO is not a commitment that the +person referenced will fix the problem. Thus when you create +a TODO with a name, it is almost always your +name that is given.

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

If your TODO 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.").

+ +
+ +

Deprecation Comments

+ +
+

Mark deprecated interface points with DEPRECATED +comments.

+
+ +
+ +

You can mark an interface as deprecated by writing a +comment containing the word DEPRECATED in +all caps. The comment goes either before the declaration +of the interface or on the same line as the +declaration.

+ + + +

After the word +DEPRECATED, write your name, e-mail address, +or other identifier in parentheses.

+ +

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.

+ +

Marking an interface point DEPRECATED +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.

+ +

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.

+ + + +
+ +

Formatting

+ +

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.

+ + + +

To help you format code correctly, we've +created a + +settings file for emacs.

+ +

Line Length

+ +
+

Each line of text in your code should be at most 80 +characters long.

+
+ +
+ + + +

We recognize that this rule is +controversial, but so much existing code already adheres +to it, and we feel that consistency is important.

+ +
+

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?

+
+ +
+

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.

+
+ +
+

80 characters is the maximum.

+ +

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.

+ +

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.

+ +

An #include statement with a +long path may exceed 80 columns.

+ +

You needn't be concerned about +header guards that exceed +the maximum length.

+
+ +
+ +

Non-ASCII Characters

+ +
+

Non-ASCII characters should be rare, and must use UTF-8 +formatting.

+
+ +
+ +

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.

+ +

Hex encoding is also OK, and encouraged where it +enhances readability — for example, +"\xEF\xBB\xBF", or, even more simply, +u8"\uFEFF", is the Unicode zero-width +no-break space character, which would be invisible if +included in the source as straight UTF-8.

+ +

Use the u8 prefix +to guarantee that a string literal containing +\uXXXX 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.

+ +

You shouldn't use the C++11 char16_t and +char32_t character types, since they're for +non-UTF-8 text. For similar reasons you also shouldn't +use wchar_t (unless you're writing code that +interacts with the Windows API, which uses +wchar_t extensively).

+ +
+ +

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.

+ +
+ +

Function Declarations and Definitions

+ +
+

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 +function call.

+
+ +
+ +

Functions look like this:

+ + +
ReturnType ClassName::FunctionName(Type par_name1, Type par_name2) {
+  DoSomething();
+  ...
+}
+
+ +

If you have too much text to fit on one line:

+ +
ReturnType ClassName::ReallyLongFunctionName(Type par_name1, Type par_name2,
+                                             Type par_name3) {
+  DoSomething();
+  ...
+}
+
+ +

or if you cannot fit even the first parameter:

+ +
ReturnType LongClassName::ReallyReallyReallyLongFunctionName(
+    Type par_name1,  // 4 space indent
+    Type par_name2,
+    Type par_name3) {
+  DoSomething();  // 2 space indent
+  ...
+}
+
+ +

Some points to note:

+ +
    +
  • Choose good parameter names.
    • + +
  • Parameter names may be omitted only if the parameter is unused and its + purpose is obvious.
    • + +
  • If you cannot fit the return type and the function + name on a single line, break between them.
    • + +
  • If you break after the return type of a function + declaration or definition, do not indent.
    • + +
  • The open parenthesis is always on the same line as + the function name.
    • + +
  • There is never a space between the function name + and the open parenthesis.
    • + +
  • There is never a space between the parentheses and + the parameters.
    • + +
  • The open curly brace is always on the end of the last line of the function + declaration, not the start of the next line.
    • + +
  • The close curly brace is either on the last line by + itself or on the same line as the open curly brace.
    • + +
  • There should be a space between the close + parenthesis and the open curly brace.
    • + +
  • All parameters should be aligned if possible.
    • + +
  • Default indentation is 2 spaces.
    • + +
  • Wrapped parameters have a 4 space indent.
    • +
+ +

Unused parameters that are obvious from context may be omitted:

+ +
class Foo {
+ public:
+  Foo(Foo&&);
+  Foo(const Foo&);
+  Foo& operator=(Foo&&);
+  Foo& operator=(const Foo&);
+};
+
+ +

Unused parameters that might not be obvious should comment out the variable +name in the function definition:

+ +
class Shape {
+ public:
+  virtual void Rotate(double radians) = 0;
+};
+
+class Circle : public Shape {
+ public:
+  void Rotate(double radians) override;
+};
+
+void Circle::Rotate(double /*radians*/) {}
+
+ +
// Bad - if someone wants to implement later, it's not clear what the
+// variable means.
+void Circle::Rotate(double) {}
+
+ +

Attributes, and macros that expand to attributes, appear at the very +beginning of the function declaration or definition, before the +return type:

+
MUST_USE_RESULT bool IsOK();
+
+ +
+ +

Lambda Expressions

+ +
+

Format parameters and bodies as for any other function, and capture +lists like other comma-separated lists.

+
+ +
+

For by-reference captures, do not leave a space between the +ampersand (&) and the variable name.

+
int x = 0;
+auto x_plus_n = [&x](int n) -> int { return x + n; }
+
+

Short lambdas may be written inline as function arguments.

+
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());
+
+ +
+ +

Function Calls

+ +
+

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.

+
+ +
+ +

Function calls have the following format:

+
bool result = DoSomething(argument1, argument2, argument3);
+
+ +

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:

+
bool result = DoSomething(averyveryveryverylongargument1,
+                          argument2, argument3);
+
+ +

Arguments may optionally all be placed on subsequent +lines with a four space indent:

+
if (...) {
+  ...
+  ...
+  if (...) {
+    bool result = DoSomething(
+        argument1, argument2,  // 4 space indent
+        argument3, argument4);
+    ...
+  }
+
+ +

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.

+ +

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:

+
int my_heuristic = scores[x] * y + bases[x];
+bool result = DoSomething(my_heuristic, x, y, z);
+
+ +

Or put the confusing argument on its own line with +an explanatory comment:

+
bool result = DoSomething(scores[x] * y + bases[x],  // Score heuristic.
+                          x, y, z);
+
+ +

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.

+ +

Sometimes arguments form a structure that is important +for readability. In those cases, feel free to format the +arguments according to that structure:

+
// Transform the widget by a 3x3 matrix.
+my_widget.Transform(x1, x2, x3,
+                    y1, y2, y3,
+                    z1, z2, z3);
+
+ +
+ +

Braced Initializer List Format

+ +
+

Format a braced initializer list +exactly like you would format a function call in its place.

+
+ +
+ +

If the braced list follows a name (e.g. a type or +variable name), format as if the {} were the +parentheses of a function call with that name. If there +is no name, assume a zero-length name.

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

Conditionals

+ +
+

Prefer no spaces inside parentheses. The if +and else keywords belong on separate lines.

+
+ +
+ +

There are two acceptable formats for a basic +conditional statement. One includes spaces between the +parentheses and the condition, and one does not.

+ +

The most common form is without spaces. Either is +fine, but be consistent. 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.

+ +
if (condition) {  // no spaces inside parentheses
+  ...  // 2 space indent.
+} else if (...) {  // The else goes on the same line as the closing brace.
+  ...
+} else {
+  ...
+}
+
+ +

If you prefer you may add spaces inside the +parentheses:

+ +
if ( condition ) {  // spaces inside parentheses - rare
+  ...  // 2 space indent.
+} else {  // The else goes on the same line as the closing brace.
+  ...
+}
+
+ +

Note that in all cases you must have a space between +the if and the open parenthesis. You must +also have a space between the close parenthesis and the +curly brace, if you're using one.

+ +
if(condition) {   // Bad - space missing after IF.
+if (condition){   // Bad - space missing before {.
+if(condition){    // Doubly bad.
+
+ +
if (condition) {  // Good - proper space after IF and before {.
+
+ +

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 +else clause.

+ +
if (x == kFoo) return new Foo();
+if (x == kBar) return new Bar();
+
+ +

This is not allowed when the if statement has an +else:

+ +
// Not allowed - IF statement on one line when there is an ELSE clause
+if (x) DoThis();
+else DoThat();
+
+ +

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 +if must always always have an accompanying +brace.

+ +
if (condition)
+  DoSomething();  // 2 space indent.
+
+if (condition) {
+  DoSomething();  // 2 space indent.
+}
+
+ +

However, if one part of an +if-else statement uses curly +braces, the other part must too:

+ +
// 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;
+}
+
+ +
// Curly braces around both IF and ELSE required because
+// one of the clauses used braces.
+if (condition) {
+  foo;
+} else {
+  bar;
+}
+
+ +
+ +

Loops and Switch Statements

+ +
+

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

+
+ +
+ +

case blocks in switch +statements can have curly braces or not, depending on +your preference. If you do include curly braces they +should be placed as shown below.

+ +

If not conditional on an enumerated value, switch +statements should always have a default 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 +assert:

+ + + +
+
switch (var) {
+  case 0: {  // 2 space indent
+    ...      // 4 space indent
+    break;
+  }
+  case 1: {
+    ...
+    break;
+  }
+  default: {
+    assert(false);
+  }
+}
+
+
+ + + + + +

Braces are optional for single-statement loops.

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

Empty loop bodies should use an empty pair of braces or continue, +but not a single semicolon.

+ +
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.
+
+ +
while (condition);  // Bad - looks like part of do/while loop.
+
+ +
+ +

Pointer and Reference Expressions

+ +
+

No spaces around period or arrow. Pointer operators do not +have trailing spaces.

+
+ +
+ +

The following are examples of correctly-formatted +pointer and reference expressions:

+ +
x = *p;
+p = &x;
+x = r.y;
+x = r->y;
+
+ +

Note that:

+ +
    +
  • There are no spaces around the period or arrow when + accessing a member.
    • + +
  • Pointer operators have no space after the + * or &.
    • +
+ +

When declaring a pointer variable or argument, you may +place the asterisk adjacent to either the type or to the +variable name:

+ +
// These are fine, space preceding.
+char *c;
+const string &str;
+
+// These are fine, space following.
+char* c;
+const string& str;
+
+ +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. +
// Fine if helpful for readability.
+int x, y;
+
+
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 &
+
+ +

You should do this consistently within a single +file, +so, when modifying an existing file, use the style in +that file.

+ +
+ +

Boolean Expressions

+ +
+

When you have a boolean expression that is longer than the +standard line length, be +consistent in how you break up the lines.

+
+ +
+ +

In this example, the logical AND operator is always at +the end of the lines:

+ +
if (this_one_thing > this_other_thing &&
+    a_third_thing == a_fourth_thing &&
+    yet_another && last_one) {
+  ...
+}
+
+ +

Note that when the code wraps in this example, both of +the && 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 +&& and ~, rather than +the word operators, such as and and +compl.

+ +
+ +

Return Values

+ +
+

Do not needlessly surround the return +expression with parentheses.

+
+ +
+ +

Use parentheses in return expr; only +where you would use them in x = expr;.

+ +
return result;                  // No parentheses in the simple case.
+// Parentheses OK to make a complex expression more readable.
+return (some_long_condition &&
+        another_condition);
+
+ +
return (value);                // You wouldn't write var = (value);
+return(result);                // return is not a function!
+
+ +
+ + + +

Variable and Array Initialization

+ +
+

Your choice of =, (), or +{}.

+
+ +
+ +

You may choose between =, +(), and {}; the following are +all correct:

+ +
int x = 3;
+int x(3);
+int x{3};
+string name = "Some Name";
+string name("Some Name");
+string name{"Some Name"};
+
+ +

Be careful when using a braced initialization list {...} +on a type with an std::initializer_list constructor. +A nonempty braced-init-list prefers the +std::initializer_list constructor whenever +possible. Note that empty braces {} are special, and +will call a default constructor if available. To force the +non-std::initializer_list constructor, use parentheses +instead of braces.

+ +
std::vector<int> v(100, 1);  // A vector of 100 1s.
+std::vector<int> v{100, 1};  // A vector of 100, 1.
+
+ +

Also, the brace form prevents narrowing of integral +types. This can prevent some types of programming +errors.

+ +
int pi(3.14);  // OK -- pi == 3.
+int pi{3.14};  // Compile error: narrowing conversion.
+
+ +
+ +

Preprocessor Directives

+ +
+

The hash mark that starts a preprocessor directive should +always be at the beginning of the line.

+
+ +
+ +

Even when preprocessor directives are within the body +of indented code, the directives should start at the +beginning of the line.

+ +
// 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();
+  }
+
+ +
// 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();
+  }
+
+ +
+ +

Class Format

+ +
+

Sections in public, protected and +private order, each indented one space.

+
+ +
+ +

The basic format for a class definition (lacking the +comments, see Class +Comments for a discussion of what comments are +needed) is:

+ +
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_;
+};
+
+ +

Things to note:

+ +
    +
  • Any base class name should be on the same line as + the subclass name, subject to the 80-column limit.
    • + +
  • The public:, protected:, + and private: keywords should be indented + one space.
    • + +
  • Except for the first instance, these keywords + should be preceded by a blank line. This rule is + optional in small classes.
    • + +
  • Do not leave a blank line after these + keywords.
    • + +
  • The public section should be first, + followed by the protected and finally the + private section.
    • + +
  • See Declaration + Order for rules on ordering declarations within + each of these sections.
    • +
+ +
+ +

Constructor Initializer Lists

+ +
+

Constructor initializer lists can be all on one line or +with subsequent lines indented four spaces.

+
+ +
+ +

The acceptable formats for initializer lists are:

+ +
// 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) {}
+
+ +
+ +

Namespace Formatting

+ +
+

The contents of namespaces are not indented.

+
+ +
+ +

Namespaces do not add an +extra level of indentation. For example, use:

+ +
namespace {
+
+void foo() {  // Correct.  No extra indentation within namespace.
+  ...
+}
+
+}  // namespace
+
+ +

Do not indent within a namespace:

+ +
namespace {
+
+  // Wrong.  Indented when it should not be.
+  void foo() {
+    ...
+  }
+
+}  // namespace
+
+ +

When declaring nested namespaces, put each namespace +on its own line.

+ +
namespace foo {
+namespace bar {
+
+ +
+ +

Horizontal Whitespace

+ +
+

Use of horizontal whitespace depends on location. Never put +trailing whitespace at the end of a line.

+
+ +
+ +

General

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

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

+ +

Loops and Conditionals

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

Operators

+ +
// 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)
+  ...
+
+ +

Templates and Casts

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

Vertical Whitespace

+ +
+

Minimize use of vertical whitespace.

+
+ +
+ +

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.

+ +

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.

+ +

Some rules of thumb to help when blank lines may be +useful:

+ +
    +
  • Blank lines at the beginning or end of a function + very rarely help readability.
    • + +
  • Blank lines inside a chain of if-else blocks may + well help readability.
    • +
+ +
+ +

Exceptions to the Rules

+ +

The coding conventions described above are mandatory. +However, like all good rules, these sometimes have exceptions, +which we discuss here.

+ + + +
+

Existing Non-conformant Code

+ +
+

You may diverge from the rules when dealing with code that +does not conform to this style guide.

+
+ +
+ +

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 consistency includes +local consistency, too.

+ +
+
+ + + +

Windows Code

+ +
+

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.

+
+ +
+

It is worth reiterating a few of the guidelines that +you might forget if you are used to the prevalent Windows +style:

+ +
    +
  • Do not use Hungarian notation (for example, naming + an integer iNum). Use the Google naming + conventions, including the .cc extension + for source files.
    • + +
  • Windows defines many of its own synonyms for + primitive types, such as DWORD, + HANDLE, 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 + const TCHAR * instead of + LPCTSTR.
    • + +
  • When compiling with Microsoft Visual C++, set the + compiler to warning level 3 or higher, and treat all + warnings as errors.
    • + +
  • Do not use #pragma once; instead use + the standard Google include guards. The path in the + include guards should be relative to the top of your + project tree.
    • + +
  • In fact, do not use any nonstandard extensions, + like #pragma and __declspec, + unless you absolutely must. Using + __declspec(dllimport) and + __declspec(dllexport) is allowed; however, + you must use them through macros such as + DLLIMPORT and DLLEXPORT, so + that someone can easily disable the extensions if they + share the code.
    • +
+ +

However, there are just a few rules that we +occasionally need to break on Windows:

+ +
    +
  • Normally we forbid + the use of multiple implementation inheritance; + 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.
    • + +
  • 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 + _ATL_NO_EXCEPTIONS 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.)
    • + +
  • 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 StdAfx.h + or precompile.h. To make your code easier + to share with other projects, avoid including this file + explicitly (except in precompile.cc), and + use the /FI compiler option to include the + file automatically.
    • + +
  • Resource headers, which are usually named + resource.h and contain only macros, do not + need to conform to these style guidelines.
    • +
+ +
+ +

Parting Words

+ +

Use common sense and BE CONSISTENT.

+ +

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

+ +

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.

+ + + +

OK, enough writing about writing code; the code itself is much +more interesting. Have fun!

+ +
+ +
+
+ + diff --git a/cppguide.xml b/cppguide.xml new file mode 100644 index 0000000..8efc102 --- /dev/null +++ b/cppguide.xml @@ -0,0 +1,18 @@ + + + + + + + Redirecting + + + + Redirecting you to cppguide.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] ... + + 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 , 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] "') + + +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 ." 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 + # template + # template + # template + 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 , + # template 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 ?= and )\?=?\s*(\w+|[+-]?\d+)(\.\d*)?', + line): + error(filename, linenum, 'build/deprecated', 3, + '>? and ))?' + # 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> 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 + # 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{}> + # + # 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(... + # string Class::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 // 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(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',)), + ('', ('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', + )), + ('', ('numeric_limits',)), + ('', ('list',)), + ('', ('map', 'multimap',)), + ('', ('allocator', 'make_shared', 'make_unique', 'shared_ptr', + 'unique_ptr', 'weak_ptr')), + ('', ('queue', 'priority_queue',)), + ('', ('set', 'multiset',)), + ('', ('stack',)), + ('', ('char_traits', 'basic_string',)), + ('', ('tuple',)), + ('', ('unordered_map', 'unordered_multimap')), + ('', ('unordered_set', 'unordered_multiset')), + ('', ('pair',)), + ('', ('vector',)), + + # gcc extensions. + # Note: std::hash is their hash, ::hash is our hash + ('', ('hash_map', 'hash_multimap',)), + ('', ('hash_set', 'hash_multiset',)), + ('', ('slist',)), + ) + +_HEADERS_MAYBE_TEMPLATES = ( + ('', ('copy', 'max', 'min', 'min_element', 'sort', + 'transform', + )), + ('', ('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(..., ...), 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 . + + 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: { '': (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[''] = (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..50d1d82 --- /dev/null +++ b/cpplint/cpplint_unittest.py @@ -0,0 +1,5805 @@ +#!/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(...) 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(...) 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(...) instead' + ' [readability/casting] [4]') + self.TestLint( + 'int a = (int)-1.0;', + 'Using C-style cast. Use static_cast(...) instead' + ' [readability/casting] [4]') + self.TestLint( + 'int *a = (int *)NULL;', + 'Using C-style cast. Use reinterpret_cast(...) instead' + ' [readability/casting] [4]') + + self.TestLint( + 'uint16 a = (uint16)1.0;', + 'Using C-style cast. Use static_cast(...) instead' + ' [readability/casting] [4]') + self.TestLint( + 'int32 a = (int32)1.0;', + 'Using C-style cast. Use static_cast(...) instead' + ' [readability/casting] [4]') + self.TestLint( + 'uint64 a = (uint64)1.0;', + 'Using C-style cast. Use static_cast(...) 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 CallbackType;', '') + self.TestLint('scoped_ptr< MockCallback > callback_value;', '') + self.TestLint('std::function', '') + 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 + void Function(int arg1, + int arg2) { + variable &= ~Type1{0} - 1; + }""", + '') + self.TestMultiLineLint( + """ + template + class Class { + void Function() { + variable &= ~Type{0} - 1; + } + };""", + '') + self.TestMultiLineLint( + """ + template + class Class { + void Function() { + variable &= ~Type{0} - 1; + } + };""", + '') + self.TestMultiLineLint( + """ + namespace { + template + 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(foo);', error_msg) + self.TestLint('int* x = &reinterpret_cast(foo);', error_msg) + self.TestLint('int* x = &(int*)foo;', + ['Using C-style cast. Use reinterpret_cast(...) ' + '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)->member_;', alt_error_msg) + self.TestLint('int* x = &down_cast(obj)[index];', alt_error_msg) + self.TestLint('int* x = &(down_cast(obj)->member_);', '') + self.TestLint('int* x = &(down_cast(obj)[index]);', '') + self.TestLint('int* x = &down_cast(obj)\n->member_;', alt_error_msg) + self.TestLint('int* x = &(down_cast(obj)\n->member_);', '') + + # It's OK to cast an address. + self.TestLint('int* x = reinterpret_cast(&foo);', '') + + # Function pointers returning references should not be confused + # with taking address of old-style casts. + self.TestLint('auto x = implicit_cast(&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();', '') + 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(...) instead' + ' [readability/casting] [4]') + + self.TestLint( + '(char *) "foo"', + 'Using C-style cast. ' + 'Use const_cast(...) instead' + ' [readability/casting] [4]') + + self.TestLint( + '(int*)foo', + 'Using C-style cast. ' + 'Use reinterpret_cast(...) 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(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', '') + self.TestLint('std::function', '') + self.TestLint('std::function< int(bool) >', '') + self.TestLint('mfunction', '') + + 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 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(...) instead ' + '[readability/casting] [4]'))) + self.assertEquals( + 1, + error_collector.Results().count( + ('Using deprecated casting style. ' + 'Use static_cast(...) instead ' + '[readability/casting] [4]'))) + + # Like gMock method definitions, MockCallback instantiations look very similar + # to bad casts. + def testMockCallback(self): + self.TestLint( + 'MockCallback', + '') + self.TestLint( + 'MockCallback', + '') + + # 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 foo;' + self.assertEquals('Add #include 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 + std::vector foo; + """, + '') + self.TestIncludeWhatYouUse( + """#include + std::pair foo; + """, + 'Add #include for pair<>' + ' [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include + std::pair foo; + """, + 'Add #include for pair<>' + ' [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include + std::pair foo; + """, + 'Add #include for pair<>' + ' [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include + auto foo = std::make_pair(1, 2); + """, + 'Add #include for make_pair' + ' [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include + std::pair foo; + """, + '') + self.TestIncludeWhatYouUse( + """#include + DECLARE_string(foobar); + """, + '') + self.TestIncludeWhatYouUse( + """#include + DEFINE_string(foobar, "", ""); + """, + '') + self.TestIncludeWhatYouUse( + """#include + std::pair foo; + """, + 'Add #include for pair<>' + ' [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include "base/foobar.h" + std::vector foo; + """, + 'Add #include for vector<>' + ' [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include + std::set foo; + """, + 'Add #include for set<>' + ' [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include "base/foobar.h" + hash_map foobar; + """, + 'Add #include for hash_map<>' + ' [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include "base/containers/hash_tables.h" + base::hash_map foobar; + """, + '') + self.TestIncludeWhatYouUse( + """#include "base/foobar.h" + bool foobar = std::less(0,1); + """, + 'Add #include for less<>' + ' [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include "base/foobar.h" + bool foobar = min(0,1); + """, + 'Add #include for min [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + 'void a(const string &foobar);', + 'Add #include for string [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + 'void a(const std::string &foobar);', + 'Add #include 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 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 for transform ' + '[build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include "base/foobar.h" + bool foobar = min_element(a.begin(), a.end()); + """, + 'Add #include for min_element ' + '[build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """foo->swap(0,1); + foo.swap(0,1); + """, + '') + self.TestIncludeWhatYouUse( + """#include + void a(const std::multimap &foobar); + """, + 'Add #include for multimap<>' + ' [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include + void a(const std::unordered_map &foobar); + """, + 'Add #include for unordered_map<>' + ' [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include + void a(const std::unordered_set &foobar); + """, + 'Add #include for unordered_set<>' + ' [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include + void a(const std::priority_queue &foobar); + """, + '') + self.TestIncludeWhatYouUse( + """#include + #include + #include + #include "base/basictypes.h" + #include "base/port.h" + vector hajoa;""", '') + self.TestIncludeWhatYouUse( + """#include + int i = numeric_limits::max() + """, + 'Add #include for numeric_limits<>' + ' [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include + int i = numeric_limits::max() + """, + '') + self.TestIncludeWhatYouUse( + """#include + std::unique_ptr x; + """, + 'Add #include for unique_ptr<>' + ' [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include + auto x = std::make_unique(0); + """, + 'Add #include for make_unique<>' + ' [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include + vector foo(vector x) { return std::move(x); } + """, + 'Add #include for move' + ' [build/include_what_you_use] [4]') + self.TestIncludeWhatYouUse( + """#include + int a, b; + std::swap(a, b); + """, + 'Add #include 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 '] + message = self.PerformIncludeWhatYouUse( + """#include "blah/a.h" + std::set 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 foo;""", + filename='blah/a_flymake.cc', + io=MockIo(mock_header_contents)) + self.assertEquals(message, 'Add #include 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 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 foo;""" % os.path.basename(os.getcwd()), + filename='a.cc', + io=MockIo(mock_header_contents)) + self.assertEquals(message, 'Add #include 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 class Foo { + Foo(int f); + };""", + 'Single-parameter constructors should be marked explicit.' + ' [runtime/explicit] [5]') + # inline case for templatized classes. + self.TestMultiLineLint( + """ + template 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 + class Foo { + Foo(Bar b); + };""", + 'Single-parameter constructors should be marked explicit.' + ' [runtime/explicit] [5]') + # but copy constructors that take multiple template parameters are OK + self.TestMultiLineLint( + """ + template + class Foo { + Foo(Foo& 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 class Foo { + Foo(const Foo&); + };""", + '') + # Special case for std::initializer_list + self.TestMultiLineLint( + """ + class Foo { + Foo(std::initializer_list &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 ', '') + self.TestLanguageRulesCheck('foo_unittest.cc', '#include ', '') + + 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& 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& 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& p);', + operand_error_message % 'std::vector& 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 &const_x, ' + 'vector &nonconst_x) {', + operand_error_message % 'vector &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 &x,', + ' sparsegroup &y) {', + '}', + 'ostream& operator<<(', + ' ostream& out', + ' const dense_hash_set& 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::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::ReadPtr::ReadPtr(const RCULocked* rcu) {', + ' DCHECK(!(data & kFlagMask)) << "Error";', + '}', + '', + 'RCULocked::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{}', '') + 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 p = {1, 2};', '') + self.TestLint('vector p{1, 2};', '') + self.TestLint('x = vector{1, 2};', '') + self.TestLint('x = (struct in_addr){ 0 };', '') + self.TestLint('Func(vector{1, 2})', '') + self.TestLint('Func((struct in_addr){ 0 })', '') + self.TestLint('Func(vector{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{new Foo{}};', '') + self.TestLint('auto foo = std::unique_ptr{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 {}> = 0>', '') + + self.TestMultiLineLint('std::unique_ptr foo{\n' + ' new Foo{}\n' + '};\n', '') + self.TestMultiLineLint('std::unique_ptr 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 kCL' + + ('o' * 41) + 'gStr[] = {\n', + 'Lines should be <= 80 characters long' + ' [whitespace/line_length] [2]') + self.TestMultiLineLint('const pair kCL' + + ('o' * 40) + 'ngStr[] =\n' + ' {\n' + ' {"gooooo", "oooogle"},\n' + '};\n', '') + self.TestMultiLineLint('const pair 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 (foobar) {', 'Missing spaces around >' + ' [whitespace/operators] [3]') + self.TestLint('if (foobaz) {', 'Missing spaces around <' + ' [whitespace/operators] [3]') + self.TestLint('if (foobar) {', 'Missing spaces around <' + ' [whitespace/operators] [3]') + self.TestLint('template', '') + self.TestLint('std::unique_ptr>', '') + self.TestLint('typedef hash_map', '') + self.TestLint('10<<20', '') + self.TestLint('10<>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>::ToString()', '') + self.TestLint('map, map>::iterator', '') + self.TestLint('func>>()', '') + self.TestLint('MACRO1(list>)', '') + self.TestLint('MACRO2(list>, 42)', '') + self.TestLint('void DoFoo(const set>& arg1);', '') + self.TestLint('void SetFoo(set>* arg1);', '') + self.TestLint('foo = new set>;', '') + self.TestLint('reinterpret_cast>*>(a);', '') + self.TestLint('MACRO(<<)', '') + self.TestLint('MACRO(<<, arg)', '') + self.TestLint('MACRO(<<=)', '') + self.TestLint('MACRO(<<=, arg)', '') + + self.TestLint('using Vector3::operator==;', '') + self.TestLint('using Vector3::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(\n' + ' int x) { return ""; }', '') + self.TestLint('template<>\n' + 'string FunctionTemplateSpecialization* >(\n' + ' int x) { return ""; }', '') + + # should not catch methods of template classes. + self.TestLint('string Class::Method() const {\n' + ' return "";\n' + '}\n', '') + self.TestLint('string Class::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::', + '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 my_elements = {// first\n' + ' 1,', '') + self.TestMultiLineLint('vector 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('//!, ', + ' class B = piyo, ', + ' class C = fuga >', + '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('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>'''), + '') + 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 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 + 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, styleguide_dir_name) = os.path.split(styleguide_path) + # parent dir of styleguide + cpplint._root = styleguide_parent_path + self.assertIsNotNone(styleguide_parent_path) + # do not hardcode the 'styleguide' repository name, it could be anything. + expected_prefix = re.sub(r'[^a-zA-Z0-9]', '_', styleguide_dir_name).upper() + '_' + # do not have 'styleguide' repo in '/' + self.assertEquals('%sCPPLINT_CPPLINT_TEST_HEADER_H_' %(expected_prefix), + 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('%sCPPLINT_CPPLINT_TEST_HEADER_H_' %(expected_prefix), + 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] "' + ' [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 ', + 'C++ TR1 headers such as are ' + 'unapproved. [build/c++tr1] [5]') + self.TestCxx11Feature('#include ', + ' is an unapproved C++11 header.' + ' [build/c++11] [5]') + + def testBlockedClasses(self): + self.TestCxx11Feature('std::alignment_of', + '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', + '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(my_shared_ptr)', '') + self.TestCxx11Feature('std::declval()', '') + + 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', '') + +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 ', + ' is an unapproved C++14 header.' + ' [build/c++14] [5]') + self.TestCxx14Feature('#include ', + ' 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(['']), '') + self.TestLanguageRulesCheck('foo/foo.cc', Format(['']), '') + 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"', + '', + '', + '', + '"bar/bar-inl.h"', + '"bar/bar.h"']), + '') + + # Test bad orders. + self.TestLanguageRulesCheck( + 'foo/foo.cc', + Format(['', '']), + '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"', '']), + '') + 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"', '']), + '') + # 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"', + '']), + '') + self.TestLanguageRulesCheck('foo/foo.cc', + Format(['"foo/foo.h"', + '', + '"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"', + '', + '"base/google.h"', + '', + '"b/c.h"', + '', + 'MACRO', + '"a/b.h"']), + '') + self.TestLanguageRulesCheck('a/a.cc', + Format(['"a/a.h"', + '', + '"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 \n', + '#include "base/port.h"\n', + '#include \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 \n', + '#include "base/port.h"\n', + '#ifdef LANG_CXX11\n', + '#include \n', + '#endif // LANG_CXX11\n']), + '') + self.TestLanguageRulesCheck( + 'a/a.cc', + ''.join(['#include \n', + '#ifdef LANG_CXX11\n', + '#include "base/port.h"\n', + '#include \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(['', '"Python.h"', '']), + '') + + +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::ReadPtr::ReadPtr(const RCULocked* rcu) {', + ' DCHECK(!(data & kFlagMask)) << "Error";', + '}', + '// Line 4', + 'RCULocked::WritePtr::WritePtr(RCULocked* rcu)', + ' : lock_(&rcu_->mutex_) {', + '}', + '// Line 8', + 'template ', + 'typename std::enable_if<', + ' std::is_array::value && (std::extent::value > 0)>::type', + 'MakeUnique(A&&... a) = delete;', + '// Line 13', + 'auto x = []() {};', + '// Line 15', + 'template ', + 'friend bool operator==(const reffed_ptr& a,', + ' const reffed_ptr& 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']) + 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 >']) + 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 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']) + 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 ', + '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 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 C >', + ' : 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 ``. + +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 + + + + Redirecting you to Rguide.xml. + + diff --git a/htmlcssguide.html b/htmlcssguide.html new file mode 100644 index 0000000..79ebafe --- /dev/null +++ b/htmlcssguide.html @@ -0,0 +1,877 @@ + + + + +Google HTML/CSS Style Guide + + + + + + +
+

Google HTML/CSS Style Guide

+

1 Background

+ +

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.

+ +

2 General

+ +

2.1 General Style Rules

+ +

2.1.1 Protocol

+ +

Use the HTTPS protocol for embedded resources where possible.

+ +

Always use the HTTPS protocol (https:) for images and other media +files, style sheets, and scripts, unless the respective files are not available +over HTTPS.

+ +
<!-- 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>
+
+ +
<!-- Recommended -->
+<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
+
+ +
/* 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';
+
+ +
/* Recommended */
+@import 'https://fonts.googleapis.com/css?family=Open+Sans';
+
+ +

2.2 General Formatting Rules

+ +

2.2.1 Indentation

+ +

Indent by 2 spaces at a time.

+ +

Don’t use tabs or mix tabs and spaces for indentation.

+ +
<ul>
+  <li>Fantastic
+  <li>Great
+</ul>
+
+ +
.example {
+  color: blue;
+}
+
+ +

2.2.2 Capitalization

+ +

Use only lowercase.

+ +

All code has to be lowercase: This applies to HTML element names, attributes, +attribute values (unless text/CDATA), CSS selectors, properties, and property +values (with the exception of strings).

+ +
<!-- Not recommended -->
+<A HREF="/">Home</A>
+
+ +
<!-- Recommended -->
+<img src="google.png" alt="Google">
+
+ +
/* Not recommended */
+color: #E5E5E5;
+
+ +
/* Recommended */
+color: #e5e5e5;
+
+ +

2.2.3 Trailing Whitespace

+ +

Remove trailing white spaces.

+ +

Trailing white spaces are unnecessary and can complicate diffs.

+ +
<!-- Not recommended -->
+<p>What?_
+
+ +
<!-- Recommended -->
+<p>Yes please.
+
+ +

2.3 General Meta Rules

+ +

2.3.1 Encoding

+ +

Use UTF-8 (no BOM).

+ +

Make sure your editor uses UTF-8 as character encoding, without a byte order +mark.

+ +

Specify the encoding in HTML templates and documents via <meta +charset="utf-8">. Do not specify the encoding of style sheets as these assume +UTF-8.

+ +

(More on encodings and when and how to specify them can be found in Handling +character encodings in HTML and CSS.)

+ +

2.3.2 Comments

+ +

Explain code as needed, where possible.

+ +

Use comments to explain code: What does it cover, what purpose does it serve, +why is respective solution used or preferred?

+ +

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

+ +

2.3.3 Action Items

+ +

Mark todos and action items with TODO.

+ +

Highlight todos by using the keyword TODO only, not other common formats like +@@.

+ +

Append a contact (username or mailing list) in parentheses as with the format +TODO(contact).

+ +

Append action items after a colon as in TODO: action item.

+ +
{# TODO(john.doe): revisit centering #}
+<center>Test</center>
+
+ +
<!-- TODO: remove optional tags -->
+<ul>
+  <li>Apples</li>
+  <li>Oranges</li>
+</ul>
+
+ +

3 HTML

+ +

3.1 HTML Style Rules

+ +

3.1.1 Document Type

+ +

Use HTML5.

+ +

HTML5 (HTML syntax) is preferred for all HTML documents: <!DOCTYPE html>.

+ +

(It’s recommended to use HTML, as text/html. Do not use XHTML. XHTML, as +application/xhtml+xml, lacks both browser +and infrastructure support and offers less room for optimization than HTML.)

+ +

Although fine with HTML, do not close void elements, i.e. write <br>, not +<br />.

+ +

3.1.2 HTML Validity

+ +

Use valid HTML where possible.

+ +

Use valid HTML code unless that is not possible due to otherwise unattainable +performance goals regarding file size.

+ +

+ +Use tools such as the W3C HTML validator +to test. +

+ +

Using valid HTML is a measurable baseline quality attribute that contributes to +learning about technical requirements and constraints, and that ensures proper +HTML usage.

+ +
<!-- Not recommended -->
+<title>Test</title>
+<article>This is only a test.
+
+ +
<!-- Recommended -->
+<!DOCTYPE html>
+<meta charset="utf-8">
+<title>Test</title>
+<article>This is only a test.</article>
+
+ +

3.1.3 Semantics

+ +

Use HTML according to its purpose.

+ +

Use elements (sometimes incorrectly called “tags”) for what they have been +created for. For example, use heading elements for headings, p elements for +paragraphs, a elements for anchors, etc.

+ +

Using HTML according to its purpose is important for accessibility, reuse, and +code efficiency reasons.

+ +
<!-- Not recommended -->
+<div onclick="goToRecommendations();">All recommendations</div>
+
+ +
<!-- Recommended -->
+<a href="recommendations/">All recommendations</a>
+
+ +

3.1.4 Multimedia Fallback

+ +

Provide alternative contents for multimedia.

+ +

For multimedia, such as images, videos, animated objects via canvas, make sure +to offer alternative access. For images that means use of meaningful alternative +text (alt) and for video and audio transcripts and captions, if available.

+ +

Providing alternative contents is important for accessibility reasons: A blind +user has few cues to tell what an image is about without @alt, and other users +may have no way of understanding what video or audio contents are about either.

+ +

(For images whose alt 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 alt="".)

+ +
<!-- Not recommended -->
+<img src="spreadsheet.png">
+
+ +
<!-- Recommended -->
+<img src="spreadsheet.png" alt="Spreadsheet screenshot.">
+
+ +

3.1.5 Separation of Concerns

+ +

Separate structure from presentation from behavior.

+ +

Strictly keep structure (markup), presentation (styling), and behavior +(scripting) apart, and try to keep the interaction between the three to an +absolute minimum.

+ +

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.

+ +

In addition, keep the contact area as small as possible by linking as few style +sheets and scripts as possible from documents and templates.

+ +

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.

+ +
<!-- 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>
+
+ +
<!-- 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!
+
+ +

3.1.6 Entity References

+ +

Do not use entity references.

+ +

There is no need to use entity references like &mdash;, &rdquo;, or +&#x263a;, assuming the same encoding (UTF-8) is used for files and editors +as well as among teams.

+ +

The only exceptions apply to characters with special meaning in HTML (like < +and &) as well as control or “invisible” characters (like no-break spaces).

+ +
<!-- Not recommended -->
+The currency symbol for the Euro is &ldquo;&eur;&rdquo;.
+
+ +
<!-- Recommended -->
+The currency symbol for the Euro is “€”.
+
+ +

3.1.7 Optional Tags

+ +

Omit optional tags (optional).

+ +

For file size optimization and scannability purposes, consider omitting optional +tags. The HTML5 specification +defines what tags can be omitted.

+ +

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

+ +
<!-- Not recommended -->
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Spending money, spending bytes</title>
+  </head>
+  <body>
+    <p>Sic.</p>
+  </body>
+</html>
+
+ +
<!-- Recommended -->
+<!DOCTYPE html>
+<title>Saving money, saving bytes</title>
+<p>Qed.
+
+ +

3.1.8 type Attributes

+ +

Omit type attributes for style sheets and scripts.

+ +

Do not use type attributes for style sheets (unless not using CSS) and scripts +(unless not using JavaScript).

+ +

Specifying type attributes in these contexts is not necessary as HTML5 implies +text/css +and text/javascript +as defaults. This can be safely done even for older browsers.

+ +
<!-- Not recommended -->
+<link rel="stylesheet" href="https://www.google.com/css/maia.css"
+  type="text/css">
+
+ +
<!-- Recommended -->
+<link rel="stylesheet" href="https://www.google.com/css/maia.css">
+
+ +
<!-- Not recommended -->
+<script src="https://www.google.com/js/gweb/analytics/autotrack.js"
+  type="text/javascript"></script>
+
+ +
<!-- Recommended -->
+<script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>
+
+ +

3.2 HTML Formatting Rules

+ +

3.2.1 General Formatting

+ +

Use a new line for every block, list, or table element, and indent every such +child element.

+ +

Independent of the styling of an element (as CSS allows elements to assume a +different role per display property), put every block, list, or table element +on a new line.

+ +

Also, indent them if they are child elements of a block, list, or table element.

+ +

(If you run into issues around whitespace between list items it’s acceptable to +put all li elements in one line. A linter is encouraged to throw a warning +instead of an error.)

+ +
<blockquote>
+  <p><em>Space</em>, the final frontier.</p>
+</blockquote>
+
+ +
<ul>
+  <li>Moe
+  <li>Larry
+  <li>Curly
+</ul>
+
+ +
<table>
+  <thead>
+    <tr>
+      <th scope="col">Income
+      <th scope="col">Taxes
+  <tbody>
+    <tr>
+      <td>$ 5.00
+      <td>$ 4.50
+</table>
+
+ +

3.2.2 HTML Line-Wrapping

+ +

Break long lines (optional).

+ +

While there is no column limit recommendation for HTML, you may consider +wrapping long lines if it significantly improves readability.

+ +

When line-wrapping, each continuation line should be indented at least 4 +additional spaces from the original line.

+ +
<md-progress-circular md-mode="indeterminate" class="md-accent"
+    ng-show="ctrl.loading" md-diameter="35">
+</md-progress-circular>
+
+ +
<md-progress-circular
+    md-mode="indeterminate"
+    class="md-accent"
+    ng-show="ctrl.loading"
+    md-diameter="35">
+</md-progress-circular>
+
+ +
<md-progress-circular md-mode="indeterminate"
+                      class="md-accent"
+                      ng-show="ctrl.loading"
+                      md-diameter="35">
+</md-progress-circular>
+
+ +

3.2.3 HTML Quotation Marks

+ +

When quoting attributes values, use double quotation marks.

+ +

Use double ("") rather than single quotation marks ('') around attribute +values.

+ +
<!-- Not recommended -->
+<a class='maia-button maia-button-secondary'>Sign in</a>
+
+ +
<!-- Recommended -->
+<a class="maia-button maia-button-secondary">Sign in</a>
+
+ +

4 CSS

+ +

4.1 CSS Style Rules

+ +

4.1.1 CSS Validity

+ +

Use valid CSS where possible.

+ +

Unless dealing with CSS validator bugs or requiring proprietary syntax, use +valid CSS code.

+ +

+ +Use tools such as the W3C CSS validator +to test. +

+ +

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.

+ +

4.1.2 ID and Class Naming

+ +

Use meaningful or generic ID and class names.

+ +

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.

+ +

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.

+ +

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

+ +

Using functional or generic names reduces the probability of unnecessary +document or template changes.

+ +
/* Not recommended: meaningless */
+#yee-1901 {}
+
+/* Not recommended: presentational */
+.button-green {}
+.clear {}
+
+ +
/* Recommended: specific */
+#gallery {}
+#login {}
+.video {}
+
+/* Recommended: generic */
+.aux {}
+.alt {}
+
+ +

4.1.3 ID and Class Name Style

+ +

Use ID and class names that are as short as possible but as long as necessary.

+ +

Try to convey what an ID or class is about while being as brief as possible.

+ +

Using ID and class names this way contributes to acceptable levels of +understandability and code efficiency.

+ +
/* Not recommended */
+#navigation {}
+.atr {}
+
+ +
/* Recommended */
+#nav {}
+.author {}
+
+ +

4.1.4 Type Selectors

+ +

Avoid qualifying ID and class names with type selectors.

+ +

Unless necessary (for example with helper classes), do not use element names in +conjunction with IDs or classes.

+ +

Avoiding unnecessary ancestor selectors is useful for performance reasons.

+ +
/* Not recommended */
+ul#example {}
+div.error {}
+
+ +
/* Recommended */
+#example {}
+.error {}
+
+ +

4.1.5 Shorthand Properties

+ +

Use shorthand properties where possible.

+ +

CSS offers a variety of shorthand +properties (like font) that should be used whenever possible, even in cases +where only one value is explicitly set.

+ +

Using shorthand properties is useful for code efficiency and understandability.

+ +
/* 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;
+
+ +
/* Recommended */
+border-top: 0;
+font: 100%/1.6 palatino, georgia, serif;
+padding: 0 1em 2em;
+
+ +

4.1.6 0 and Units

+ +

Omit unit specification after “0” values, unless required.

+ +

Do not use units after 0 values unless they are required.

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

4.1.7 Leading 0s

+ +

Omit leading “0”s in values.

+ +

Do not put 0s in front of values or lengths between -1 and 1.

+ +
font-size: .8em;
+
+ +

4.1.8 Hexadecimal Notation

+ +

Use 3 character hexadecimal notation where possible.

+ +

For color values that permit it, 3 character hexadecimal notation is shorter and +more succinct.

+ +
/* Not recommended */
+color: #eebbcc;
+
+ +
/* Recommended */
+color: #ebc;
+
+ +

4.1.9 Prefixes

+ +

Prefix selectors with an application-specific prefix (optional).

+ +

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.

+ +

Using namespaces helps preventing naming conflicts and can make maintenance +easier, for example in search and replace operations.

+ +
.adw-help {} /* AdWords */
+#maia-note {} /* Maia */
+
+ +

4.1.10 ID and Class Name Delimiters

+ +

Separate words in ID and class names by a hyphen.

+ +

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.

+ +
/* Not recommended: does not separate the words “demo” and “image” */
+.demoimage {}
+
+/* Not recommended: uses underscore instead of hyphen */
+.error_status {}
+
+ +
/* Recommended */
+#video-id {}
+.ads-sample {}
+
+ +

4.1.11 Hacks

+ +

Avoid user agent detection as well as CSS “hacks”—try a different approach +first.

+ +

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.

+ +

4.2 CSS Formatting Rules

+ +

4.2.1 Declaration Order

+ +

Alphabetize declarations.

+ +

Put declarations in alphabetical order in order to achieve consistent code in a +way that is easy to remember and maintain.

+ +

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

+ +
background: fuchsia;
+border: 1px solid;
+-moz-border-radius: 4px;
+-webkit-border-radius: 4px;
+border-radius: 4px;
+color: black;
+text-align: center;
+text-indent: 2em;
+
+ +

4.2.2 Block Content Indentation

+ +

Indent all block content.

+ +

Indent all block content, +that is rules within rules as well as declarations, so to reflect hierarchy and +improve understanding.

+ +
@media screen, projection {
+
+  html {
+    background: #fff;
+    color: #444;
+  }
+
+}
+
+ +

4.2.3 Declaration Stops

+ +

Use a semicolon after every declaration.

+ +

End every declaration with a semicolon for consistency and extensibility +reasons.

+ +
/* Not recommended */
+.test {
+  display: block;
+  height: 100px
+}
+
+ +
/* Recommended */
+.test {
+  display: block;
+  height: 100px;
+}
+
+ +

4.2.4 Property Name Stops

+ +

Use a space after a property name’s colon.

+ +

Always use a single space between property and value (but no space between +property and colon) for consistency reasons.

+ +
/* Not recommended */
+h3 {
+  font-weight:bold;
+}
+
+ +
/* Recommended */
+h3 {
+  font-weight: bold;
+}
+
+ +

4.2.5 Declaration Block Separation

+ +

Use a space between the last selector and the declaration block.

+ +

Always use a single space between the last selector and the opening brace that +begins the declaration block.

+ +

The opening brace should be on the same line as the last selector in a given +rule.

+ +
/* Not recommended: missing space */
+#video{
+  margin-top: 1em;
+}
+
+/* Not recommended: unnecessary line break */
+#video
+{
+  margin-top: 1em;
+}
+
+ +
/* Recommended */
+#video {
+  margin-top: 1em;
+}
+
+ +

4.2.6 Selector and Declaration Separation

+ +

Separate selectors and declarations by new lines.

+ +

Always start a new line for each selector and declaration.

+ +
/* Not recommended */
+a:focus, a:active {
+  position: relative; top: 1px;
+}
+
+ +
/* Recommended */
+h1,
+h2,
+h3 {
+  font-weight: normal;
+  line-height: 1.2;
+}
+
+ +

4.2.7 Rule Separation

+ +

Separate rules by new lines.

+ +

Always put a blank line (two line breaks) between rules.

+ +
html {
+  background: #fff;
+}
+
+body {
+  margin: auto;
+  width: 50%;
+}
+
+ +

4.2.8 CSS Quotation Marks

+ +

Use single ('') rather than double ("") quotation marks for attribute +selectors and property values.

+ +

Do not use quotation marks in URI values (url()).

+ +

Exception: If you do need to use the @charset rule, use double quotation +marks—single quotation marks are not permitted.

+ +
/* Not recommended */
+@import url("https://www.google.com/css/maia.css");
+
+html {
+  font-family: "open sans", arial, sans-serif;
+}
+
+ +
/* Recommended */
+@import url(https://www.google.com/css/maia.css);
+
+html {
+  font-family: 'open sans', arial, sans-serif;
+}
+
+ +

4.3 CSS Meta Rules

+ +

4.3.1 Section Comments

+ +

Group sections by a section comment (optional).

+ +

If possible, group style sheet sections together by using comments. Separate +sections with new lines.

+ +
/* Header */
+
+#adw-header {}
+
+/* Footer */
+
+#adw-footer {}
+
+/* Gallery */
+
+.adw-gallery {}
+
+ +

Parting Words

+ +

Be consistent.

+ +

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.

+ +

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.

+
+ + diff --git a/htmlcssguide.xml b/htmlcssguide.xml new file mode 100644 index 0000000..0ab9f80 --- /dev/null +++ b/htmlcssguide.xml @@ -0,0 +1,8 @@ + + + +

+ The style guide has moved to + htmlcssguide.html +

+ 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 0000000000000000000000000000000000000000..75d5c7ba8dcc22b100b18b8c800da9ed99afbf7b GIT binary patch literal 189 zcmeAS@N?(olHy`uVBq!ia0vp^q9Dw{1|(OCFP#RYT0C7GLo80eoovW;K!L}#nDP3f zLaS;${>#Z0UFCva2M?aC%WS)H?QB_5g+S7$o~{tDg%>YO@zZ2dVrDwAKuzez0i`Ul zbE@l3-bt1V61%3rbUmT<%Dy%3?@ZTjdAE&Ol|^ce?3NY5cci0UGX8nXab09-b9Pp3 o=^vw)Kdk>g`TD$n)}_KZpTAr6giAPD0^P&l>FVdQ&MBb@0Ar|2 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 = + ''; + 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 @@ + + + + + + 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 @@ + + + + +Google Java Style Guide + + + + + + +
+

Google Java Style Guide

+
+ +
+ +

1 Introduction

+ +

This document serves as the complete definition of Google's coding standards for +source code in the Java™ Programming Language. A Java source file is described as being in +Google Style if and only if it adheres to the rules herein.

+ +

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

+ + + +

1.1 Terminology notes

+ +

In this document, unless otherwise clarified:

+ +
    +
  1. The term class is used inclusively to mean an "ordinary" class, enum class, + interface or annotation type (@interface).
    2. + +
  2. The term member (of a class) is used inclusively to mean a nested class, field, + method, or constructor; that is, all top-level contents of a class except initializers + and comments. + +
  3. The term comment always refers to implementation comments. We do not + use the phrase "documentation comments", instead using the common term "Javadoc."
    4. +
+ +

Other "terminology notes" will appear occasionally throughout the document.

+ +

1.2 Guide notes

+ +

Example code in this document is non-normative. That is, while the examples +are in Google Style, they may not illustrate the only stylish way to represent the +code. Optional formatting choices made in examples should not be enforced as rules.

+ + +

2 Source file basics

+ +

2.1 File name

+ +

The source file name consists of the case-sensitive name of the top-level class it contains +(of which there is exactly one), plus the +.java extension.

+ +

2.2 File encoding: UTF-8

+ +

Source files are encoded in UTF-8.

+ +

2.3 Special characters

+ +

2.3.1 Whitespace characters

+ +

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:

+ +
    +
  1. All other whitespace characters in string and character literals are escaped.
    2. + +
  2. Tab characters are not used for indentation.
    3. +
+ +

2.3.2 Special escape sequences

+ +

For any character that has a + + special escape sequence +(\b, +\t, +\n, +\f, +\r, +\", +\' and +\\), that sequence +is used rather than the corresponding octal +(e.g. \012) or Unicode +(e.g. \u000a) escape.

+ +

2.3.3 Non-ASCII characters

+ +

For the remaining non-ASCII characters, either the actual Unicode character +(e.g. ∞) or the equivalent Unicode escape +(e.g. \u221e) is used. The choice depends only on +which makes the code easier to read and understand, although Unicode escapes +outside string literals and comments are strongly discouraged.

+ +

Tip: In the Unicode escape case, and occasionally even when actual +Unicode characters are used, an explanatory comment can be very helpful.

+ +

Examples:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ExampleDiscussion
String unitAbbrev = "μs";Best: perfectly clear even without a comment.
String unitAbbrev = "\u03bcs"; // "μs"Allowed, but there's no reason to do this.
String unitAbbrev = "\u03bcs"; + // Greek letter mu, "s"Allowed, but awkward and prone to mistakes.
String unitAbbrev = "\u03bcs";Poor: the reader has no idea what this is.
return '\ufeff' + content; + // byte order markGood: use escapes for non-printable characters, and comment if necessary.
+ +

Tip: 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 broken and they must be fixed.

+ + + +

3 Source file structure

+ +
+

A source file consists of, in order:

+ +
    +
  1. License or copyright information, if present
    2. +
  2. Package statement
    3. +
  3. Import statements
    4. +
  4. Exactly one top-level class
    5. +
+
+ +

Exactly one blank line separates each section that is present.

+ + + +

If license or copyright information belongs in a file, it belongs here.

+ + + +

3.2 Package statement

+ +

The package statement is not line-wrapped. The column limit (Section 4.4, +Column limit: 100) does not apply to package statements.

+ + +

3.3 Import statements

+ +

3.3.1 No wildcard imports

+ +

Wildcard imports, static or otherwise, are not used.

+ +

3.3.2 No line-wrapping

+ +

Import statements are not line-wrapped. The column limit (Section 4.4, +Column limit: 100) does not apply to import +statements.

+ +

3.3.3 Ordering and spacing

+ +

Imports are ordered as follows:

+ +
    +
  1. All static imports in a single block.
    2. +
  2. All non-static imports in a single block.
    3. +
+ +

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.

+ +

Within each block the imported names appear in ASCII sort order. (Note: +this is not the same as the import statements being in ASCII sort order, since '.' +sorts before ';'.)

+ + + +

3.3.4 No static import for classes

+ +

Static import is not used for static nested classes. They are imported with +normal imports.

+ +

3.4 Class declaration

+ + +

3.4.1 Exactly one top-level class declaration

+ +

Each top-level class resides in a source file of its own.

+ + +

3.4.2 Ordering of class contents

+ +

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.

+ +

What is important is that each class uses some logical order, 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.

+ + + + +
3.4.2.1 Overloads: never split
+ +

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

+ +

4 Formatting

+ +

Terminology Note: block-like construct refers to +the body of a class, method or constructor. Note that, by Section 4.8.3.1 on +array initializers, any array initializer +may optionally be treated as if it were a block-like construct.

+ + +

4.1 Braces

+ +

4.1.1 Braces are used where optional

+ +

Braces are used with +if, +else, +for, +do and +while statements, even when the +body is empty or contains only a single statement.

+ +

4.1.2 Nonempty blocks: K & R style

+ +

Braces follow the Kernighan and Ritchie style +("Egyptian brackets") +for nonempty blocks and block-like constructs:

+ +
    +
  • No line break before the opening brace.
    • + +
  • Line break after the opening brace.
    • + +
  • Line break before the closing brace.
    • + +
  • Line break after the closing brace, only if that brace terminates a statement or + terminates the body of a method, constructor, or named class. + For example, there is no line break after the brace if it is followed by + else or a comma.
    • +
+ +

Examples:

+ +
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();
+    }
+  }
+};
+
+ +

A few exceptions for enum classes are given in Section 4.8.1, +Enum classes.

+ + +

4.1.3 Empty blocks: may be concise

+ +

An empty block or block-like construct may be in K & R style (as described in +Section 4.1.2). Alternatively, it may be closed immediately +after it is opened, with no characters or line break in between +({}), unless it is part of a +multi-block statement (one that directly contains multiple blocks: +if/else or +try/catch/finally).

+ +

Examples:

+ +
  // This is acceptable
+  void doNothing() {}
+
+  // This is equally acceptable
+  void doNothingElse() {
+  }
+
+
  // This is not acceptable: No concise empty blocks in a multi-block statement
+  try {
+    doSomething();
+  } catch (Exception e) {}
+
+ +

4.2 Block indentation: +2 spaces

+ +

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, +Nonempty blocks: K & R Style.)

+ +

4.3 One statement per line

+ +

Each statement is followed by a line break.

+ + +

4.4 Column limit: 100

+ +

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, Line-wrapping. +

+ +

Each Unicode code point counts as one character, even if its display width is +greater or less. For example, if using +fullwidth characters, +you may choose to wrap the line earlier than where this rule strictly requires.

+ +

Exceptions:

+ +
    +
  1. Lines where obeying the column limit is not possible (for example, a long URL in Javadoc, + or a long JSNI method reference).
    2. + +
  2. package and + import statements (see Sections + 3.2 Package statement and + 3.3 Import statements).
    3. + +
  3. Command lines in a comment that may be cut-and-pasted into a shell.
    4. +
+ +

4.5 Line-wrapping

+ +

Terminology Note: When code that might otherwise legally +occupy a single line is divided into multiple lines, this activity is called +line-wrapping.

+ +

There is no comprehensive, deterministic formula showing exactly how to line-wrap in +every situation. Very often there are several valid ways to line-wrap the same piece of code.

+ +

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.

+ +

Tip: Extracting a method or local variable may solve the problem +without the need to line-wrap.

+ +

4.5.1 Where to break

+ +

The prime directive of line-wrapping is: prefer to break at a +higher syntactic level. Also:

+ +
    +
  1. When a line is broken at a non-assignment operator the break comes before + the symbol. (Note that this is not the same practice used in Google style for other languages, + such as C++ and JavaScript.) +
      +
    • This also applies to the following "operator-like" symbols: +
        +
      • the dot separator (.)
        • +
      • the two colons of a method reference + (::)
        • +
      • an ampersand in a type bound + (<T extends Foo & Bar>)
        • +
      • a pipe in a catch block + (catch (FooException | BarException e)).
        • +
      +
      • +
    +
    2. + +
  2. When a line is broken at an assignment operator the break typically comes + after the symbol, but either way is acceptable. +
      +
    • This also applies to the "assignment-operator-like" colon in an enhanced + for ("foreach") statement.
      • +
    +
    3. + +
  3. A method or constructor name stays attached to the open parenthesis + (() that follows it.
    4. + +
  4. A comma (,) stays attached to the token that + precedes it.
    5. + +
  5. 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: +
    MyLambda<String, Long, Object> lambda =
+    (String label, Long value, Object obj) -> {
+        ...
+    };
+
+Predicate<String> predicate = str ->
+    longExpressionInvolving(str);
+
    +
    6. +
+ +

Note: The primary goal for line wrapping is to have clear +code, not necessarily code that fits in the smallest number of lines.

+ + +

4.5.2 Indent continuation lines at least +4 spaces

+ +

When line-wrapping, each line after the first (each continuation line) is indented +at least +4 from the original line.

+ +

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.

+ +

Section 4.6.3 on Horizontal alignment addresses +the discouraged practice of using a variable number of spaces to align certain tokens with +previous lines.

+ +

4.6 Whitespace

+ +

4.6.1 Vertical Whitespace

+ +

A single blank line appears:

+ +
    +
  1. Between consecutive members or initializers of a class: fields, constructors, + methods, nested classes, static initializers, and instance initializers. +
      +
    • Exception: A blank line between two consecutive + fields (having no other code between them) is optional. Such blank lines are used as needed to + create logical groupings of fields.
      • +
    • Exception: Blank lines between enum constants are + covered in Section 4.8.1.
      • +
    +
    2. + +
  2. Between statements, as needed to organize the code into logical subsections. + +
  3. Optionally before the first member or initializer, or after the last member or + initializer of the class (neither encouraged nor discouraged).
    4. + +
  4. As required by other sections of this document (such as Section 3, + Source file structure, and Section 3.3, + Import statements).
    5. +
+ +

Multiple consecutive blank lines are permitted, but never required (or encouraged).

+ +

4.6.2 Horizontal whitespace

+ +

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

+ +
    +
  1. Separating any reserved word, such as + if, + for or + catch, from an open parenthesis + (() + that follows it on that line
    2. + +
  2. Separating any reserved word, such as + else or + catch, from a closing curly brace + (}) that precedes it on that line
    3. + +
  3. Before any open curly brace + ({), with two exceptions: +
      +
    • @SomeAnnotation({a, b}) (no space is used)
      • + +
    • String[][] x = {{"foo"}}; (no space is required + between {{, by item 8 below)
      • +
    +
    4. + +
  4. On both sides of any binary or ternary operator. This also applies to the following + "operator-like" symbols: +
      +
    • the ampersand in a conjunctive type bound: + <T extends Foo & Bar>
      • + +
    • the pipe for a catch block that handles multiple exceptions: + catch (FooException | BarException e)
      • + +
    • the colon (:) in an enhanced + for ("foreach") statement
      • + +
    • the arrow in a lambda expression: + (String str) -> str.length()
      • +
    + but not + +
      +
    • the two colons (::) of a method reference, which + is written like Object::toString
      • +
    • the dot separator (.), which is written like + object.toString()
      • +
    +
    5. + +
  5. After ,:; or the closing parenthesis + ()) of a cast
    6. + +
  6. On both sides of the double slash (//) that + begins an end-of-line comment. Here, multiple spaces are allowed, but not required.
    7. + +
  7. Between the type and variable of a declaration: + List<String> list
    8. + +
  8. Optional just inside both braces of an array initializer +
      +
    • new int[] {5, 6} and + new int[] { 5, 6 } are both valid
      • +
    +
    9. +
+ +This rule is never interpreted as requiring or forbidding additional space at the start or +end of a line; it addresses only interior space. + +

4.6.3 Horizontal alignment: never required

+ +

Terminology Note: Horizontal alignment 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.

+ +

This practice is permitted, but is never required by Google Style. It is not +even required to maintain horizontal alignment in places where it was already used.

+ +

Here is an example without alignment, then using alignment:

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

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

+ + +

4.7 Grouping parentheses: recommended

+ +

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 not reasonable to assume that every reader has the entire Java +operator precedence table memorized.

+ +

4.8 Specific constructs

+ +

4.8.1 Enum classes

+ +

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: + +

private enum Answer {
+  YES {
+    @Override public String toString() {
+      return "yes";
+    }
+  },
+
+  NO,
+  MAYBE
+}
+
+ +

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 +array initializers).

+ +
private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }
+
+ +

Since enum classes are classes, all other rules for formatting classes apply.

+ + +

4.8.2 Variable declarations

+ +
4.8.2.1 One variable per declaration
+ +

Every variable declaration (field or local) declares only one variable: declarations such as +int a, b; are not used.

+ +

Exception: Multiple variable declarations are acceptable in the header of a +for loop.

+ +
4.8.2.2 Declared when needed
+ +

Local variables are not 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.

+ +

4.8.3 Arrays

+ +
4.8.3.1 Array initializers: can be "block-like"
+ +

Any array initializer may optionally be formatted as if it were a "block-like +construct." For example, the following are all valid (not an exhaustive +list):

+ +
new int[] {           new int[] {
+  0, 1, 2, 3            0,
+}                       1,
+                        2,
+new int[] {             3,
+  0, 1,               }
+  2, 3
+}                     new int[]
+                          {0, 1, 2, 3}
+
+ +
4.8.3.2 No C-style array declarations
+ +

The square brackets form a part of the type, not the variable: +String[] args, not +String args[].

+ +

4.8.4 Switch statements

+ + + +

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 case FOO: or +default:), followed by one or more statements (or, for +the last statement group, zero or more statements).

+ +
4.8.4.1 Indentation
+ +

As with any other block, the contents of a switch block are indented +2.

+ +

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.

+ + +
4.8.4.2 Fall-through: commented
+ +

Within a switch block, each statement group either terminates abruptly (with a +break, +continue, +return or thrown 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 +// fall through). This special comment is not required in +the last statement group of the switch block. Example:

+ +
switch (input) {
+  case 1:
+  case 2:
+    prepareOneOrTwo();
+    // fall through
+  case 3:
+    handleOneTwoOrThree();
+    break;
+  default:
+    handleLargeNumber(input);
+}
+
+ +

Notice that no comment is needed after case 1:, only +at the end of the statement group.

+ +
4.8.4.3 The default case is present
+ +

Each switch statement includes a default statement +group, even if it contains no code.

+ +

Exception: A switch statement for an enum type may omit +the default statement group, if it includes +explicit cases covering all possible values of that type. This enables IDEs or other static +analysis tools to issue a warning if any cases were missed. + +

+ + +

4.8.5 Annotations

+ +

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, Line-wrapping), so the indentation level is not +increased. Example:

+ +
@Override
+@Nullable
+public String getNameIfPresent() { ... }
+
+ +

Exception: A single parameterless annotation +may instead appear together with the first line of the signature, for example:

+ +
@Override public int hashCode() { ... }
+
+ +

Annotations applying to a field also appear immediately after the documentation block, but in +this case, multiple annotations (possibly parameterized) may be listed on the same line; +for example:

+ +
@Partial @Mock DataLoader loader;
+
+ +

There are no specific rules for formatting annotations on parameters, local variables, or types. +

+ + +

4.8.6 Comments

+ +

This section addresses implementation comments. Javadoc is addressed separately in +Section 7, Javadoc.

+ +

Any line break may be preceded by arbitrary whitespace followed by an implementation comment. +Such a comment renders the line non-blank.

+ +
4.8.6.1 Block comment style
+ +

Block comments are indented at the same level as the surrounding code. They may be in +/* ... */ style or +// ... style. For multi-line +/* ... */ comments, subsequent lines must start with +* aligned with the * on the previous line.

+ +
/*
+ * This is          // And so           /* Or you can
+ * okay.            // is this.          * even do this. */
+ */
+
+ + +

Comments are not enclosed in boxes drawn with asterisks or other characters.

+ +

Tip: When writing multi-line comments, use the +/* ... */ style if you want automatic code formatters to +re-wrap the lines when necessary (paragraph-style). Most formatters don't re-wrap lines in +// ... style comment blocks.

+ + + + +

4.8.7 Modifiers

+ +

Class and member modifiers, when present, appear in the order +recommended by the Java Language Specification: +

+ +
public protected private abstract default static final transient volatile synchronized native strictfp
+
+ +

4.8.8 Numeric Literals

+ +

long-valued integer literals use an uppercase L suffix, never +lowercase (to avoid confusion with the digit 1). For example, 3000000000L +rather than 3000000000l.

+ + +

5 Naming

+ +

5.1 Rules common to all identifiers

+ +

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 +\w+ .

+ +

In Google Style special prefixes or +suffixes, like those seen in the examples name_, +mName, s_name and +kName, are not used.

+ +

5.2 Rules by identifier type

+ +

5.2.1 Package names

+ +

Package names are all lowercase, with consecutive words simply concatenated together (no +underscores). For example, com.example.deepspace, not +com.example.deepSpace or +com.example.deep_space.

+ +

5.2.2 Class names

+ +

Class names are written in UpperCamelCase.

+ +

Class names are typically nouns or noun phrases. For example, +Character or +ImmutableList. Interface names may also be nouns or +noun phrases (for example, List), but may sometimes be +adjectives or adjective phrases instead (for example, +Readable).

+ +

There are no specific rules or even well-established conventions for naming annotation types.

+ +

Test classes are named starting with the name of the class they are testing, and ending +with Test. For example, +HashTest or +HashIntegrationTest.

+ +

5.2.3 Method names

+ +

Method names are written in lowerCamelCase.

+ +

Method names are typically verbs or verb phrases. For example, +sendMessage or +stop.

+ +

Underscores may appear in JUnit test method names to separate logical components of the +name, with each component written in lowerCamelCase. +One typical pattern is <methodUnderTest>_<state>, +for example pop_emptyStack. There is no One Correct +Way to name test methods.

+ + +

5.2.4 Constant names

+ +

Constant names use CONSTANT_CASE: all uppercase +letters, with each word separated from the next by a single underscore. But what is a +constant, exactly?

+ +

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 intending to never mutate the object is not enough. Examples:

+ +
// 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"};
+
+ +

These names are typically nouns or noun phrases.

+ +

5.2.5 Non-constant field names

+ +

Non-constant field names (static or otherwise) are written +in lowerCamelCase.

+ +

These names are typically nouns or noun phrases. For example, +computedValues or +index.

+ +

5.2.6 Parameter names

+ +

Parameter names are written in lowerCamelCase.

+ +

One-character parameter names in public methods should be avoided.

+ +

5.2.7 Local variable names

+ +

Local variable names are written in lowerCamelCase.

+ +

Even when final and immutable, local variables are not considered to be constants, and should not +be styled as constants.

+ +

5.2.8 Type variable names

+ +

Each type variable is named in one of two styles:

+ +
    +
  • A single capital letter, optionally followed by a single numeral (such as + E, T, + X, T2) +
    • + +
  • A name in the form used for classes (see Section 5.2.2, + Class names), followed by the capital letter + T (examples: + RequestT, + FooBarT).
    • +
+ + + +

5.3 Camel case: defined

+ +

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.

+ +

Beginning with the prose form of the name:

+ +
    +
  1. Convert the phrase to plain ASCII and remove any apostrophes. For example, "Müller's + algorithm" might become "Muellers algorithm".
    2. + +
  2. Divide this result into words, splitting on spaces and any remaining punctuation (typically + hyphens). + +
      +
    • Recommended: 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 per se; it defies any + convention, so this recommendation does not apply.
      • +
    +
    3. + +
  3. Now lowercase everything (including acronyms), then uppercase only the first + character of: +
      +
    • ... each word, to yield upper camel case, or
      • +
    • ... each word except the first, to yield lower camel case
      • +
    +
    4. + +
  4. Finally, join all the words into a single identifier.
    5. +
+ +

Note that the casing of the original words is almost entirely disregarded. Examples:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Prose formCorrectIncorrect
"XML HTTP request"XmlHttpRequestXMLHTTPRequest
"new customer ID"newCustomerIdnewCustomerID
"inner stopwatch"innerStopwatchinnerStopWatch
"supports IPv6 on iOS?"supportsIpv6OnIossupportsIPv6OnIOS
"YouTube importer"YouTubeImporter
+ YoutubeImporter*
+ +

*Acceptable, but not recommended.

+ +

Note: Some words are ambiguously hyphenated in the English +language: for example "nonempty" and "non-empty" are both correct, so the method names +checkNonempty and +checkNonEmpty are likewise both correct.

+ + +

6 Programming Practices

+ +

6.1 @Override: always used

+ +

A method is marked with the @Override 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.

+ +

Exception: +@Override may be omitted when the parent method is +@Deprecated.

+ + +

6.2 Caught exceptions: not ignored

+ +

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 +AssertionError.)

+ +

When it truly is appropriate to take no action whatsoever in a catch block, the reason this is +justified is explained in a comment.

+ +
try {
+  int i = Integer.parseInt(response);
+  return handleNumericResponse(i);
+} catch (NumberFormatException ok) {
+  // it's not numeric; that's fine, just continue
+}
+return handleTextResponse(response);
+
+ +

Exception: In tests, a caught exception may be ignored +without comment if its name is or begins with expected. The +following is a very common idiom for ensuring that the code under test does throw an +exception of the expected type, so a comment is unnecessary here.

+ +
try {
+  emptyStack.pop();
+  fail();
+} catch (NoSuchElementException expected) {
+}
+
+ +

6.3 Static members: qualified using class

+ +

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.

+ +
Foo aFoo = ...;
+Foo.aStaticMethod(); // good
+aFoo.aStaticMethod(); // bad
+somethingThatYieldsAFoo().aStaticMethod(); // very bad
+
+ + +

6.4 Finalizers: not used

+ +

It is extremely rare to override Object.finalize.

+ +

Tip: Don't do it. If you absolutely must, first read and understand + + + Effective Java Item 7, + +"Avoid Finalizers," very carefully, and then don't do it.

+ + + +

7 Javadoc

+ + + +

7.1 Formatting

+ +

7.1.1 General form

+ +

The basic formatting of Javadoc blocks is as seen in this example:

+ +
/**
+ * Multiple lines of Javadoc text are written here,
+ * wrapped normally...
+ */
+public int method(String p1) { ... }
+
+ +

... or in this single-line example:

+ +
/** An especially short bit of Javadoc. */
+
+ +

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 @return. + +

7.1.2 Paragraphs

+ +

One blank line—that is, a line containing only the aligned leading asterisk +(*)—appears between paragraphs, and before the group of block tags if +present. Each paragraph but the first has <p> immediately before the first word, +with no space after.

+ + + +

7.1.3 Block tags

+ +

Any of the standard "block tags" that are used appear in the order @param, +@return, @throws, @deprecated, 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 @. +

+ +

7.2 The summary fragment

+ +

Each Javadoc block begins with a brief summary fragment. This +fragment is very important: it is the only part of the text that appears in certain contexts such as +class and method indexes.

+ +

This is a fragment—a noun phrase or verb phrase, not a complete sentence. It does +not begin with A {@code Foo} is a..., or +This method returns..., nor does it form a complete imperative sentence +like Save the record.. However, the fragment is capitalized and +punctuated as if it were a complete sentence.

+ +

Tip: A common mistake is to write simple Javadoc in the form +/** @return the customer ID */. This is incorrect, and should be +changed to /** Returns the customer ID. */.

+ + +

7.3 Where Javadoc is used

+ +

At the minimum, Javadoc is present for every +public class, and every +public or +protected member of such a class, with a few exceptions +noted below.

+ +

Additional Javadoc content may also be present, as explained in Section 7.3.4, +Non-required Javadoc.

+ +

7.3.1 Exception: self-explanatory methods

+ +

Javadoc is optional for "simple, obvious" methods like +getFoo, in cases where there really and truly is +nothing else worthwhile to say but "Returns the foo".

+ +

Important: 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 getCanonicalName, don't omit its documentation +(with the rationale that it would say only +/** Returns the canonical name. */) if a typical reader may have no idea +what the term "canonical name" means!

+ +

7.3.2 Exception: overrides

+ +

Javadoc is not always present on a method that overrides a supertype method. + +

+ + + +

7.3.4 Non-required Javadoc

+ +

Other classes and members have Javadoc as needed or desired. + +

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 /**).

+ +

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.

+ + + +
+
+ + diff --git a/javaguidelink.png b/javaguidelink.png new file mode 100644 index 0000000000000000000000000000000000000000..75d5c7ba8dcc22b100b18b8c800da9ed99afbf7b GIT binary patch literal 189 zcmeAS@N?(olHy`uVBq!ia0vp^q9Dw{1|(OCFP#RYT0C7GLo80eoovW;K!L}#nDP3f zLaS;${>#Z0UFCva2M?aC%WS)H?QB_5g+S7$o~{tDg%>YO@zZ2dVrDwAKuzez0i`Ul zbE@l3-bt1V61%3rbUmT<%Dy%3?@ZTjdAE&Ol|^ce?3NY5cci0UGX8nXab09-b9Pp3 o=^vw)Kdk>g`TD$n)}_KZpTAr6giAPD0^P&l>FVdQ&MBb@0Ar|2 + + +

+ Please note: there's a newer version of this guide that includes + ECMAScript 6th Edition features. It lives here. + You should probably be using that for new code. + + Revision 2.93 +

+ +
+ Aaron Whyte
+ Bob Jervis
+ Dan Pupius
+ Erik Arvidsson
+ Fritz Schneider
+ Robby Walker
+
+ + + + + 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. + + +

+ Hooray! Now you know you can expand points to get more + details. Alternatively, there's a "toggle all" at the + top of this document. +

+ + + + +

+ JavaScript is the main client-side scripting language used + + by many of Google's open-source + projects. + This style guide is a list of dos and don'ts for + JavaScript programs. +

+ + + + + + + + + + + + + + + Declarations with var: Always + + + + When you fail to specify var, + 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 + var. + + + + + + +
    +
  • Use NAMES_LIKE_THIS for constant values.
    • +
  • Use @const to indicate a constant (non-overwritable) + pointer (a variable or property).
    • +
  • Never use the + + const keyword + as it's not supported in Internet Explorer.
    • +
+ + + + + +

If a value is intended to be constant + and immutable, it should be given a name + in CONSTANT_VALUE_CASE. + ALL_CAPS additionally implies @const + (that the value is not overwritable). +

+ +

Primitive types (number, string, + boolean) are constant values.

+ +

Objects' + 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.

+ + + + + +

The @const 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 + + const keyword (which we do not use due to the + lack of support in Internet Explorer).

+ +

A @const annotation on a method additionally + implies that the method cannot not be overridden in subclasses. +

+ +

A @const annotation on a constructor implies the + class cannot be subclassed (akin to final in Java). +

+ + + + + +

Note that @const does not necessarily imply + CONSTANT_VALUES_CASE. + + However, CONSTANT_VALUES_CASE + does imply @const. +

+ + + /** + * Request timeout in milliseconds. + * @type {number} + */ + goog.example.TIMEOUT_IN_MILLISECONDS = 60; + + +

The number of seconds in a minute never changes. It is a + constant value. ALL_CAPS + also implies @const, so the constant cannot be + overwritten. +

+ +

The open source compiler will allow the symbol to be + overwritten because the constant is + not marked as @const.

+ + + /** + * Map of URL to response string. + * @const + */ + MyClass.fetchedUrlCache_ = new goog.structs.Map(); + + + + /** + * Class that cannot be subclassed. + * @const + * @constructor + */ + sloth.MyFinalClass = function() {}; + + +

In this case, the pointer can never be overwritten, but + value is highly mutable and not constant (and thus in + camelCase, not ALL_CAPS).

+ + + + + + + + + Always use semicolons. + + +

Relying on implicit insertion can cause subtle, hard to debug + problems. Don't do it. You're better than that.

+

There are a couple places where missing semicolons are particularly + dangerous:

+ + // 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(); + + +
    +
  1. 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.
    2. +
  2. You will most likely get a 'no such property in undefined' + error at runtime as it tries to call + x[ffVersion, ieVersion][isIE]().
    3. +
  3. die is always called since the array minus 1 is + NaN which is never equal to anything (not even if + resultOfOperation() returns NaN) and + THINGS_TO_EAT gets assigned the result of + die().
    4. +
+ + +

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.

+

This has really surprised people, so make sure your assignments end + with semicolons.

+ + +

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:

+ + var foo = function() { + return true; + }; // semicolon here. + + function foo() { + return true; + } // no semicolon here. + + + + + + + Yes + +

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.

+ + + + + No + +

Do not do this:

+ + if (x) { + function foo() {} + } + + +

While most script engines support Function Declarations within blocks + it is not part of ECMAScript (see + ECMA-262, + 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:

+ + if (x) { + var foo = function() {}; + } + + + + + + Yes + +

You basically can't avoid exceptions if you're doing something + non-trivial (using an application development framework, etc.). + Go for it.

+ + + + + Yes + +

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.

+ + + + + Always preferred over non-standards features + +

For maximum portability and compatibility, always prefer standards + features over non-standards features (e.g., + string.charAt(3) over string[3] and element + access with DOM functions instead of using an application-specific + shorthand).

+ + + + + No + +

There's no reason to use wrapper objects for primitive types, plus + they're dangerous:

+ + var x = new Boolean(false); + if (x) { + alert('hi'); // Shows 'hi'. + } + +

Don't do it!

+

However type casting is fine.

+ + var x = Boolean(0); + if (x) { + alert('hi'); // This will never be alerted. + } + typeof Boolean(0) == 'boolean'; + typeof new Boolean(0) == 'object'; + +

This is very useful for casting things to + number, string and boolean.

+ + + + + Not preferred + +

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!

+ +

For that reason, it is best to use goog.inherits() from + + the Closure Library + + or a similar library function. +

+ + function D() { + goog.base(this) + } + goog.inherits(D, B); + + D.prototype.method = function() { + ... + }; + + + + + + /** @constructor */ + function SomeConstructor() { + this.someProperty = 1; + } + Foo.prototype.someMethod = function() { ... }; + +

While there are several ways to attach methods and properties to an + object created via "new", the preferred style for methods + is:

+ + Foo.prototype.bar = function() { + /* ... */ + }; + +

The preferred style for other properties is to initialize the field + in the constructor:

+ + /** @constructor */ + function Foo() { + this.bar = value; + } + + +

Current JavaScript engines optimize based on the "shape" + of an object, + adding a property to an object (including overriding + a value set on the prototype) changes the shape and can degrade + performance.

+ + + + + + Prefer this.foo = null. + + + Foo.prototype.dispose = function() { + this.property_ = null; + }; + +

Instead of:

+ + Foo.prototype.dispose = function() { + delete this.property_; + }; + +

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 + if (key in obj).

+ + + + + Yes, but be careful. + +

The ability to create closures is perhaps the most useful and often + overlooked feature of JS. Here is + + a good description of how closures work.

+

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:

+ + function foo(element, a, b) { + element.onclick = function() { /* uses a and b */ }; + } + +

the function closure keeps a reference to element, + a, and b even if it never uses + element. Since element 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:

+ + function foo(element, a, b) { + element.onclick = bar(a, b); + } + + function bar(a, b) { + return function() { /* uses a and b */ }; + } + + + + + + + Only for code loaders and REPL (Read–eval–print loop) + + +

eval() makes for confusing semantics and is dangerous + to use if the string being eval()'d contains user input. + There's usually a better, clearer, and safer way to write your code, + so its use is generally not permitted.

+ +

For RPC you can always use JSON and read the result using + JSON.parse() instead of eval().

+ +

Let's assume we have a server that returns something like this:

+ + + { + "name": "Alice", + "id": 31502, + "email": "looking_glass@example.com" + } + + + + var userInfo = eval(feed); + var email = userInfo['email']; + + +

If the feed was modified to include malicious JavaScript code, then + if we use eval then that code will be executed.

+ + + var userInfo = JSON.parse(feed); + var email = userInfo['email']; + + +

With JSON.parse, invalid JSON (including all executable + JavaScript) will cause an exception to be thrown.

+ + + + + + No + +

Using with clouds the semantics of your program. + Because the object of the with can have properties that + collide with local variables, it can drastically change the meaning + of your program. For example, what does this do?

+ + with (foo) { + var x = 3; + return x; + } + +

Answer: anything. The local variable x could be + clobbered by a property of foo and perhaps it even has + a setter, in which case assigning 3 could cause lots of + other code to execute. Don't use with.

+ + + + + + Only in object constructors, methods, and in setting up closures + + +

The semantics of this can be tricky. At times it refers + to the global object (in most places), the scope of the caller (in + eval), 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 + call()ed or apply()ed).

+

Because this is so easy to get wrong, limit its use to those places + where it is required:

+
    +
  • in constructors
    • +
  • in methods of objects (including in the creation of closures)
    • +
+ + + + + + Only for iterating over keys in an object/map/hash + + +

for-in loops are often incorrectly used to loop over + the elements in an Array. This is however very error + prone because it does not loop from 0 to + length - 1 but over all the present keys in the object + and its prototype chain. Here are a few cases where it fails:

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

Always use normal for loops when using arrays.

+ + function printArray(arr) { + var l = arr.length; + for (var i = 0; i < l; i++) { + print(arr[i]); + } + } + + + + + + + Never use Array as a map/hash/associative array + + +

Associative Arrays are not allowed... or more precisely + you are not allowed to use non number indexes for arrays. If you need + a map/hash use Object instead of Array in + these cases because the features that you want are actually features + of Object and not of Array. + Array just happens to extend Object (like + any other object in JS and therefore you might as well have used + Date, RegExp or String).

+ + + + + No + +

Do not do this:

+ + 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.'; + +

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.

+

Use string concatenation instead:

+ + 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.'; + + + + + + Yes + +

Use Array and Object literals instead of + Array and Object constructors.

+

Array constructors are error-prone due to their arguments.

+ + // 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(); + +

Because of this, if someone changes the code to pass 1 argument + instead of 2 arguments, the array might not have the expected + length.

+

To avoid these kinds of weird cases, always use the more readable + array literal.

+ + var a = [x1, x2, x3]; + var a2 = [x1, x2]; + var a3 = [x1]; + var a4 = []; + +

Object constructors don't have the same problems, but for readability + and consistency object literals should be used.

+ + var o = new Object(); + + var o2 = new Object(); + o2.a = 0; + o2.b = 1; + o2.c = 2; + o2['strange key'] = 3; + +

Should be written as:

+ + var o = {}; + + var o2 = { + a: 0, + b: 1, + c: 2, + 'strange key': 3 + }; + + + + + + No + +

Modifying builtins like Object.prototype and + Array.prototype are strictly forbidden. Modifying other + builtins like Function.prototype is less dangerous but + still leads to hard to debug issues in production and should be + avoided.

+ + + + + No + +

Don't do this:

+ + var f = function () { + /*@cc_on if (@_jscript) { return 2* @*/ 3; /*@ } @*/ + }; + +

Conditional Comments hinder automated tools as they can vary the + JavaScript syntax tree at runtime.

+ + + + + + + +

In general, use + functionNamesLikeThis, + variableNamesLikeThis, + ClassNamesLikeThis, + EnumNamesLikeThis, + methodNamesLikeThis, + CONSTANT_VALUES_LIKE_THIS, + foo.namespaceNamesLikeThis.bar, and + filenameslikethis.js. +

+ + + +
    +
  • Private properties and methods should be named with a + trailing underscore. +
    • +
  • Protected properties and methods should be + named without a trailing underscore (like public ones).
    • +
+

For more information on private and protected, + read the section on + + visibility. +

+ + + + + + + +

Optional function arguments start with opt_.

+

Functions that take a variable number of arguments should have the + last argument named var_args. You may not refer to + var_args in the code; use the arguments + array.

+

Optional and variable arguments can also be specified in + @param annotations. Although either convention is + acceptable to the compiler, using both together is preferred.

+ + + + +

EcmaScript 5 getters and setters for properties are discouraged. + However, if they are used, then getters must not change observable + state.

+ + /** + * WRONG -- Do NOT do this. + */ + var foo = { get next() { return this.nextId++; } }; + + + + +

Getters and setters methods for properties are not required. + However, if they are used, then getters must be named + getFoo() and setters must be named + setFoo(value). (For boolean getters, + isFoo() is also acceptable, and often sounds more + natural.)

+ + + +

JavaScript has no inherent packaging or namespacing support.

+

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.

+ +

ALWAYS 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 sloth.*.

+ + var sloth = {}; + + sloth.sleep = function() { + ... + }; + + + +

Many JavaScript libraries, including + + the Closure Library + + and + + Dojo toolkit + + give you high-level functions for declaring your namespaces. + Be consistent about how you declare your namespaces.

+ + goog.provide('sloth'); + + sloth.sleep = function() { + ... + }; + + + +

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 sloth.hats.

+ + + +

"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 foo.hats.*, your + internal code should not define all its symbols in + foo.hats.*, because it will break if the other + team defines new symbols.

+ + foo.require('foo.hats'); + + /** + * WRONG -- Do NOT do this. + * @constructor + * @extends {foo.hats.RoundHat} + */ + foo.hats.BowlerHat = function() { + }; + +

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.

+ + foo.provide('googleyhats.BowlerHat'); + + foo.require('foo.hats'); + + /** + * @constructor + * @extends {foo.hats.RoundHat} + */ + googleyhats.BowlerHat = function() { + ... + }; + + goog.exportSymbol('foo.hats.BowlerHat', googleyhats.BowlerHat); + + + + + +

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.

+ + /** + * @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()); + }; + +

Do not create local aliases of namespaces. Namespaces should only + be aliased using goog.scope.

+ + myapp.main = function() { + var namespace = some.long.namespace; + namespace.MyClass.staticHelper(new namespace.MyClass()); + }; + +

Avoid accessing properties of an aliased type, unless it is an + enum.

+ + /** @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: + ... + } + }; + + + myapp.main = function() { + var MyClass = some.long.namespace.MyClass; + MyClass.staticHelper(null); + }; + +

Never create aliases in the global scope. Use them only in + function blocks.

+ + + +

Filenames should be all lowercase in order to avoid confusion on + case-sensitive platforms. Filenames should end in .js, + and should contain no punctuation except for - or + _ (prefer - to _).

+ + + + + + + + Must always succeed without side effects. + + +

You can control how your objects string-ify themselves by defining a + custom toString() 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 + toString() calls a method that does an + assert, assert might try to output the name + of the object in which it failed, which of course requires calling + toString().

+ + + + + OK + +

It isn't always possible to initialize variables at the point of + declaration, so deferred initialization is fine.

+ + + + + Always + +

Always use explicit scope - doing so increases portability and + clarity. For example, don't rely on window being in the + scope chain. You might want to use your function in another + application for which window is not the content + window.

+ + + + + Expand for more information. + +

We follow the C++ formatting + rules in spirit, with the following additional clarifications.

+ +

Because of implicit semicolon insertion, always start your curly + braces on the same line as whatever they're opening. For + example:

+ + if (something) { + // ... + } else { + // ... + } + + + +

Single-line array and object initializers are allowed when they + fit on a line:

+ + var arr = [1, 2, 3]; // No space after [ or before ]. + var obj = {a: 1, b: 2, c: 3}; // No space after { or before }. + +

Multiline array initializers and object initializers are indented + 2 spaces, with the braces on their own line, just like blocks.

+ + // 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!'); + +

Long identifiers or values present problems for aligned + initialization lists, so always prefer non-aligned initialization. + For example:

+ + CORRECT_Object.prototype = { + a: 0, + b: 1, + lengthyName: 2 + }; + +

Not like this:

+ + WRONG_Object.prototype = { + a : 0, + b : 1, + lengthyName: 2 + }; + + + +

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:

+ + // 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) { + // ... + } + +

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.

+ + if (veryLongFunctionNameA( + veryLongArgumentName) || + veryLongFunctionNameB( + veryLongArgumentName)) { + veryLongFunctionNameC(veryLongFunctionNameD( + veryLongFunctioNameE( + veryLongFunctionNameF))); + } + + + +

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

+ + 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; + }); + + + + +

+ goog.scope + may be used to shorten references to + namespaced symbols in programs using + the Closure + Library.

+

Only one goog.scope invocation may be added per + file. Always place it in the global scope.

+

The opening goog.scope(function() { invocation + must be preceded by exactly one blank line and follow any + goog.provide statements, goog.require + statements, or top-level comments. The invocation must be closed on + the last line in the file. Append // goog.scope to the + closing statement of the scope. Separate the comment from the + semicolon by two spaces.

+

Similar to C++ namespaces, do not indent under goog.scope + declarations. Instead, continue from the 0 column.

+

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

+ + + goog.scope(function() { + var Button = goog.ui.Button; + + Button = function() { ... }; + ... + + +

Names must be the same as the last property of the global that they + are aliasing.

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

Except for array literals, + object literals, 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). +

+ + + someWonderfulHtml = '
' + + getEvenMoreHtml(someReallyInterestingValues, moreValues, + evenMoreParams, 'a duck', true, 72, + slightlyMoreMonkeys(0xfff)) + + '
'; + + 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(); + } + + + +

Use newlines to group logically related pieces of code. + For example:

+ + doSomethingTo(x); + doSomethingElseTo(x); + andThen(x); + + nowDoSomethingWith(y); + + andNowWith(z); + + + +

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.

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

This includes the dot operator.

+ + var x = foo.bar(). + doSomething(). + doSomethingElse(); + + + + + + + Only where required + +

Use sparingly and in general only where required by the syntax + and semantics.

+

Never use parentheses for unary operators such as + delete, typeof and void or + after keywords such as return, throw as + well as others (case, in or + new).

+ + + + + Prefer ' over " + +

For consistency single-quotes (') are preferred to double-quotes ("). + This is helpful when creating strings that include HTML:

+ + var msg = 'This is some HTML'; + + + + + + Encouraged, use JSDoc annotations @private and + @protected + +

We recommend the use of the JSDoc annotations @private and + @protected to indicate visibility levels for classes, + functions, and properties.

+

The --jscomp_warning=visibility compiler flag turns on compiler + warnings for visibility violations. See + + Closure Compiler + Warnings. +

+

@private global variables and functions are only + accessible to code in the same file.

+

Constructors marked @private may only be instantiated by + code in the same file and by their static and instance members. + @private constructors may also be accessed anywhere in the + same file for their public static properties and by the + instanceof operator.

+

Global variables, functions, and constructors should never be + annotated @protected.

+ + // 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_(); + +

@private 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.

+

@protected 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.

+

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

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

Notice that in JavaScript, there is no distinction between a type + (like AA_PrivateClass_) 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).

+ + + + + Encouraged and enforced by the compiler. + + +

When documenting a type in JSDoc, be as specific and accurate as + possible. The types we support are based on the + + EcmaScript 4 spec.

+ +

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.

+ +

As the ES4 proposal has evolved, this language has changed. The + compiler still supports old syntaxes for types, but those syntaxes + are deprecated.

+ +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Syntax NameSyntaxDescriptionDeprecated Syntaxes
Primitive Type + There are 5 primitive types in JavaScript: + {null}, + {undefined}, + {boolean}, + {number}, and + {string}. + Simply the name of a type. +
Instance Type + {Object}
+ An instance of Object or null.

+ {Function}
+ An instance of Function or null.

+ {EventTarget}
+ An instance of a constructor that implements the EventTarget + interface, or null. +

An instance of a constructor or interface function.

+ + Constructor functions are functions defined with the + @constructor JSDoc tag. + Interface functions are functions defined with the + @interface JSDoc tag.

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

+
Enum Type + {goog.events.EventType}
+ One of the properties of the object literal initializer + of goog.events.EventType. + 		An enum must be initialized as an object literal, or as + an alias of another enum, annotated with the @enum + JSDoc tag. The properties of this literal are the instances + of the enum. The syntax of the enum is defined + below.

+ + Note that this is one of the few things in our type system + that were not in the ES4 spec. +

+
Type Application + {Array.<string>}
An array of strings.

+ {Object.<string, number>} +
An object in which the keys are strings and the values + are numbers. +

Parameterizes a type, by applying a set of type arguments + to that type. The idea is analogous to generics in Java. + +
Type Union + {(number|boolean)}
A number or a boolean. + 		Indicates that a value might have type A OR type B.

+ + The parentheses may be omitted at the top-level + expression, but the parentheses should be included in + sub-expressions to avoid ambiguity.
+ {number|boolean}
+ {function(): (number|boolean)} +

+ {(number,boolean)},
+ {(number||boolean)} +
Nullable type + {?number}
A number or null. + 		Shorthand for the union of the null type with any + other type. This is just syntactic sugar. + + {number?} +
Non-nullable type + {!Object}
An Object, but never the + null value. + 		Filters null out of nullable types. Most often used + with instance types, which are nullable by default. + + {Object!} +
Record Type + {{myNum: number, myObject}} +
An anonymous type with the given type members. + 		+

Indicates that the value has the specified members with the + specified types. In this case, myNum with a + type number and myObject with any + type.

+

Notice that the braces are part of the type syntax. For + example, to denote an Array of objects that + have a length property, you might write + Array.<{length}>.

+ 		+
Function Type + {function(string, boolean)}
+ A function that takes two arguments (a string and a boolean), + and has an unknown return value.
+ 		Specifies a function. +
Function Return Type + {function(): number}
+ A function that takes no arguments and returns a number.
+ 		Specifies a function return type. +
Function this Type + {function(this:goog.ui.Menu, string)}
+ A function that takes one argument (a string), and executes + in the context of a goog.ui.Menu. + 		Specifies the context type of a function type. +
Function new Type + {function(new:goog.ui.Menu, string)}
+ A constructor that takes one argument (a string), and + creates a new instance of goog.ui.Menu when called + with the 'new' keyword. + 		Specifies the constructed type of a constructor. +
Variable arguments + {function(string, ...[number]): number}
+ A function that takes one argument (a string), and then a + variable number of arguments that must be numbers. + 		Specifies variable arguments to a function. +
+ + Variable arguments (in @param annotations) + + @param {...number} var_args
+ A variable number of arguments to an annotated function. + 		+ Specifies that the annotated function accepts a variable + number of arguments. + +
Function optional arguments + {function(?string=, number=)}
+ A function that takes one optional, nullable string and one + optional number as arguments. The = syntax is + only for function type declarations. + 		Specifies optional arguments to a function. +
+ + Function optional arguments + (in @param annotations) + + @param {number=} opt_argument
+ An optional parameter of type number. + 		Specifies that the annotated function accepts an optional + argument. +
The ALL type{*}Indicates that the variable can take on any type. +
The UNKNOWN type{?}Indicates that the variable can take on any type, + and the compiler should not type-check any uses of it. +
+ + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Type ExampleValue ExamplesDescription
number + + 1 + 1.0 + -5 + 1e5 + Math.PI + + +
Number + + new Number(true) + + + + Number object + +
string + + 'Hello' + "World" + String(42) + + + String value +
String + + new String('Hello') + new String(42) + + + + String object + +
boolean + + true + false + Boolean(0) + + + Boolean value +
Boolean + + new Boolean(true) + + + + Boolean object + +
RegExp + + new RegExp('hello') + /world/g + +
Date + + new Date + new Date() + +
+ + null + + + + null + + +
+ + undefined + + + + undefined + + +
void + + function f() { + return; + } + + No return value
Array + + ['foo', 0.3, null] + [] + + Untyped Array
Array.<number> + + [11, 22, 33] + + + An Array of numbers +
Array.<Array.<string>> + + [['one', 'two', 'three'], ['foo', 'bar']] + + Array of Arrays of strings
Object + + {} + {foo: 'abc', bar: 123, baz: null} + + +
Object.<string> + + {'foo': 'bar'} + + + An Object in which the values are strings. +
Object.<number, string> + + var obj = {}; + obj[1] = 'bar'; + + + An Object in which the keys are numbers and the values are + strings.

Note that in JavaScript, the keys are always + implicitly converted to strings, so + obj['1'] == obj[1]. + 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. +

Function + + function(x, y) { + return x * y; + } + + + + Function object + +
function(number, number): number + + function(x, y) { + return x * y; + } + + function value
SomeClass + + /** @constructor */ + function SomeClass() {} + + new SomeClass(); + + +
SomeInterface + + /** @interface */ + function SomeInterface() {} + + SomeInterface.prototype.draw = function() {}; + + +
project.MyClass + + /** @constructor */ + project.MyClass = function () {} + + new project.MyClass() + + +
project.MyEnum + + /** @enum {string} */ + project.MyEnum = { + /** The color blue. */ + BLUE: '#0000dd', + /** The color red. */ + RED: '#dd0000' + }; + + Enumeration

+ JSDoc comments on enum values are optional. +

Element + + document.createElement('div') + + Elements in the DOM.
Node + + document.body.firstChild + + Nodes in the DOM.
HTMLInputElement + + htmlDocument.getElementsByTagName('input')[0] + + A specific type of DOM element.
+ + + +

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.

+ + + /** @type {number} */ (x) + + + + + +

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.

+ +

Instances of classes and interfaces are nullable by default. + For example, the following declaration

+ + + /** + * Some class, initialized with a value. + * @param {Object} value Some value. + * @constructor + */ + function MyClass(value) { + /** + * Some value. + * @type {Object} + * @private + */ + this.myValue_ = value; + } + + +

tells the compiler that the myValue_ property holds + either an Object or null. If myValue_ must never be + null, it should be declared like this:

+ + + /** + * 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; + } + + +

This way, if the compiler can determine that somewhere in the code + MyClass is initialized with a null value, it will issue + a warning.

+ + + +

Optional parameters to functions may be undefined at runtime, so if + they are assigned to class properties, those properties must be + declared accordingly:

+ + + /** + * 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; + } + + +

This tells the compiler that myValue_ may hold an + Object, null, or remain undefined.

+ +

Note that the optional parameter opt_value is declared + to be of type {Object=}, not + {Object|undefined}. 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.

+ +

Finally, note that being nullable and being optional are orthogonal + properties. The following four declarations are all different:

+ + + /** + * 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) { + // ... + }; + + + + + +

Sometimes types can get complicated. A function that accepts + content for an Element might look like:

+ + + /** + * @param {string} tagName + * @param {(string|Element|Text|Array.<Element>|Array.<Text>)} contents + * @return {!Element} + */ + goog.createElement = function(tagName, contents) { + ... + }; + + +

You can define commonly used type expressions with a + @typedef tag. For example,

+ + + /** @typedef {(string|Element|Text|Array.<Element>|Array.<Text>)} */ + goog.ElementContent; + + /** + * @param {string} tagName + * @param {goog.ElementContent} contents + * @return {!Element} + */ + goog.createElement = function(tagName, contents) { + ... + }; + + + + + +

The compiler has limited support for template types. It can only + infer the type of this inside an anonymous function + literal from the type of the this argument and whether the + this argument is missing.

+ + + /** + * @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; }); + + + + + + + Use JSDoc + +

+ We follow the + + C++ style for comments in spirit. +

+ +

All files, classes, methods and properties should be documented with + JSDoc + comments with the appropriate tags + and types. Textual descriptions for properties, + methods, method parameters and method return values should be included + unless obvious from the property, method, or parameter name. +

+ +

Inline comments should be of the // variety.

+ +

Complete sentences are recommended but not required. + Complete sentences should use appropriate capitalization + and punctuation.

+ + +

The JSDoc syntax is based on + + JavaDoc. Many tools extract metadata from JSDoc comments to + perform code validation and optimizations. These comments must be + well-formed.

+ + + /** + * 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. + */ + + + + +

If you have to line break a block tag, you should treat this as + breaking a code statement and indent it four spaces.

+ + + /** + * 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; + }; + + +

You should not indent the @fileoverview command. You do not have to + indent the @desc command.

+ +

Even though it is not preferred, it is also acceptable to line up + the description.

+ + + /** + * 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; + }; + + + + +

Like JavaDoc, JSDoc supports many HTML tags, like <code>, + <pre>, <tt>, <strong>, <ul>, <ol>, + <li>, <a>, and others.

+ +

This means that plaintext formatting is not respected. So, don't + rely on whitespace to format JSDoc:

+ + + /** + * Computes weight based on three factors: + * items sent + * items received + * last timestamp + */ + + +

It'll come out like this:

+ + + Computes weight based on three factors: items sent items received last timestamp + + +

Instead, do this:

+ + + /** + * Computes weight based on three factors: + * <ul> + * <li>items sent + * <li>items received + * <li>last timestamp + * </ul> + */ + + + The + JavaDoc style guide is a useful resource on how to write + well-formed doc comments. + + + +

+ + A copyright notice 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: +

+ + + /** + * @fileoverview Description of file, its uses and information + * about its dependencies. + */ + + + + + + +

Classes must be documented with a description and a + type tag that + identifies the constructor. +

+ + + /** + * 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); + + + + +

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.

+ + /** + * 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) { + // ... + } + + + + + + /** @constructor */ + project.MyClass = function() { + /** + * Maximum number of things per pane. + * @type {number} + */ + this.someProperty = 4; + } + + + + + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TagTemplate & ExamplesDescription
+ @author + + + @author username@google.com (first last) +

For example:

+ + /** + * @fileoverview Utilities for handling textareas. + * @author kuth@google.com (Uthur Pendragon) + */ + + 		+ Document the author of a file or the owner of a test, + generally only used in the @fileoverview comment. + +
@code + {@code ...} +

For example:

+ + /** + * 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() { + // ... + }; + + 		+ Indicates that a term in a JSDoc description is code so it may + be correctly formatted in generated documentation. +
@const + @const
+ @const {type} +

For example:

+ + /** @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. + }; + + 		+

Marks a variable (or property) as read-only and suitable + for inlining.

+ +

A @const variable is an immutable pointer to + a value. If a variable or property marked as + @const is overwritten, JSCompiler will give + warnings.

+ +

The type declaration of a constant value can be omitted + if it can be clearly inferred. An additional comment about + the variable is optional.

+ +

When @const is applied to a method, it + implies the method is not only not overwritable, but also + that the method is finalized — + not overridable in subclasses.

+ +

For more on @const, see the + Constants section.

+ +
@constructor + @constructor +

For example:

+ + /** + * A rectangle. + * @constructor + */ + function GM_Rect() { + ... + } + + 		+ Used in a class's documentation to indicate the constructor. +
@define + @define {Type} description +

For example:

+ + /** @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; + + 		+ Indicates a constant that can be overridden by the compiler at + compile-time. In the example, the compiler flag + --define='goog.userAgent.ASSUME_IE=true' + could be specified in the BUILD file to indicate that the + constant goog.userAgent.ASSUME_IE should be replaced + with true. +
@deprecated + @deprecated Description +

For example:

+ + /** + * 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) { + // ... + }; + + 		+ Used to tell that a function, method or property should not be + used any more. Always provide instructions on what callers + should use instead. +
@dict + @dict Description +

For example:

+ + /** + * @constructor + * @dict + */ + function Foo(x) { + this['x'] = x; + } + var obj = new Foo(123); + var num = obj.x; // warning + + (/** @dict */ { x: 1 }).x = 123; // warning + + 		+ When a constructor (Foo in the example) is + annotated with @dict, you can only use the + bracket notation to access the properties of Foo + objects. + The annotation can also be used directly on object literals. +
@enum + @enum {Type} +

For example:

+ + /** + * Enum for tri-state values. + * @enum {number} + */ + project.TriState = { + TRUE: 1, + FALSE: -1, + MAYBE: 0 + }; + +
@export + @export +

For example:

+ + /** @export */ + foo.MyPublicClass.prototype.myPublicMethod = function() { + // ... + }; + + 		+

Given the code on the left, when the compiler is run with + the --generate_exports flag, it will generate the + code:

+ + goog.exportSymbol('foo.MyPublicClass.prototype.myPublicMethod', + foo.MyPublicClass.prototype.myPublicMethod); + +

which will export the symbols to uncompiled code. + Code that uses the @export annotation must either

+
    +
  1. include //javascript/closure/base.js, or
    2. +
  2. define both goog.exportSymbol and + goog.exportProperty with the same method + signature in their own codebase.
    3. +
+
@expose + @expose +

For example:

+ + /** @expose */ + MyClass.prototype.exposedProperty = 3; + + 		+

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

+ +

+ @expose should never be used in library code, + because it will prevent that property from ever getting + removed. +

+
@extends + + @extends Type
+ @extends {Type} + +

For example:

+ + /** + * Immutable empty node list. + * @constructor + * @extends goog.ds.BasicNodeList + */ + goog.ds.EmptyNodeList = function() { + ... + }; + + 		+ Used with @constructor to indicate that a class + inherits from another class. Curly braces around the type are + optional. +
@externs + @externs +

For example:

+ + /** + * @fileoverview This is an externs file. + * @externs + */ + + var document; + + 		+

+ Declares an + + externs file. +

+ + +
@fileoverview + @fileoverview Description +

For example:

+ + /** + * @fileoverview Utilities for doing things that require this very long + * but not indented comment. + * @author kuth@google.com (Uthur Pendragon) + */ + + 		Makes the comment block provide file level information.
@implements + + @implements Type
+ @implements {Type} + +

For example:

+ + /** + * A shape. + * @interface + */ + function Shape() {}; + Shape.prototype.draw = function() {}; + + /** + * @constructor + * @implements {Shape} + */ + function Square() {}; + Square.prototype.draw = function() { + ... + }; + + 		+ Used with @constructor to indicate that a class + implements an interface. Curly braces around the type are + optional. +
@inheritDoc + @inheritDoc +

For example:

+ + /** @inheritDoc */ + project.SubClass.prototype.toString() { + // ... + }; + + 		+

Deprecated. Use + @override instead.

+ + 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 + @inheritDoc implies @override +
@interface + @interface +

For example:

+ + /** + * A shape. + * @interface + */ + function Shape() {}; + Shape.prototype.draw = function() {}; + + /** + * A polygon. + * @interface + * @extends {Shape} + */ + function Polygon() {}; + Polygon.prototype.getSides = function() {}; + + 		+ Used to indicate that the function defines an interface. +
@lends + @lends objectName
+ @lends {objectName} +

For example:

+ + goog.object.extend( + Button.prototype, + /** @lends {Button.prototype} */ { + isButton: function() { return true; } + }); + + 		+ 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.

+ + 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, @type {Foo} means "an instance of Foo", + but @lends {Foo} means "the constructor Foo".

+ + The + JSDoc Toolkit docs have more information on this + annotation. +

@license or + @preserve + @license Description +

For example:

+ + /** + * @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: + */ + + 		+ Anything marked by @license or + @preserve 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. +
@noalias + @noalias +

For example:

+ + /** @noalias */ + function Range() {} + + 		+ 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. +
@nocompile + @nocompile +

For example:

+ + /** @nocompile */ + + // JavaScript code + + 		+ 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. +
@nosideeffects + @nosideeffects +

For example:

+ + /** @nosideeffects */ + function noSideEffectsFn1() { + // ... + } + + /** @nosideeffects */ + var noSideEffectsFn2 = function() { + // ... + }; + + /** @nosideeffects */ + a.prototype.noSideEffectsFn3 = function() { + // ... + }; + + 		+ 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. +
@override + @override +

For example:

+ + /** + * @return {string} Human-readable representation of project.SubClass. + * @override + */ + project.SubClass.prototype.toString = function() { + // ... + }; + + 		+ 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. +
@param + @param {Type} varname Description +

For example:

+ + /** + * 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) { + // ... + }; + + 		+ Used with method, function and constructor calls to document + the arguments of a function.

+ + Type + names must be enclosed in curly braces. If the type + is omitted, the compiler will not type-check the parameter. +

@private + @private
+ @private {type} +

For example:

+ + /** + * Handlers that are listening to this logger. + * @private {!Array.<Function>} + */ + this.handlers_ = []; + + 		+ Used in conjunction with a trailing underscore on the method + or property name to indicate that the member is + private and final. +
@protected + @protected
+ @protected {type} +

For example:

+ + /** + * 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) { + // ... + }; + + 		+ Used to indicate that the member or property is + protected. + Should be used in conjunction with names with no trailing + underscore. +
@public + @public
+ @public {type} +

For example:

+ + /** + * 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; + + 		+ 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. +
@return + @return {Type} Description +

For example:

+ + /** + * @return {string} The hex ID of the last item. + */ + goog.Baz.prototype.getLastId = function() { + // ... + return id; + }; + + 		+ 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 @return tag.

+ + Type + names must be enclosed in curly braces. If the type + is omitted, the compiler will not type-check the return value. +

@see + @see Link +

For example:

+ + /** + * Adds a single item, recklessly. + * @see #addSafely + * @see goog.Collect + * @see goog.RecklessAdder#add + ... + + 		Reference a lookup to another class function or method.
@struct + @struct Description +

For example:

+ + /** + * @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 + + 		+ When a constructor (Foo in the example) is + annotated with @struct, you can only use the dot + notation to access the properties of Foo objects. + Also, you cannot add new properties to Foo + objects after they have been created. + The annotation can also be used directly on object literals. +
@supported + @supported Description +

For example:

+ + /** + * @fileoverview Event Manager + * Provides an abstracted interface to the + * browsers' event systems. + * @supported So far tested in IE6 and FF1.5 + */ + + 		+ Used in a fileoverview to indicate what browsers are supported + by the file. +
@suppress + + @suppress {warning1|warning2} + + + @suppress {warning1,warning2} + +

For example:

+ + /** + * @suppress {deprecated} + */ + function f() { + deprecatedVersionOfF(); + } + + 		+ Suppresses warnings from tools. Warning categories are + separated by | or ,. + +
@template + @template +

For example:

+ + /** + * @param {function(this:T, ...)} fn + * @param {T} thisObj + * @param {...*} var_args + * @template T + */ + goog.bind = function(fn, thisObj, var_args) { + ... + }; + + 		+ This annotation can be used to declare a + template typename. +
@this + + @this Type
+ @this {Type} + +

For example:

+ + pinto.chat.RosterWidget.extern('getRosterElement', + /** + * Returns the roster widget element. + * @this pinto.chat.RosterWidget + * @return {Element} + */ + function() { + return this.getWrappedComponent_().getElement(); + }); + + 		+ The type of the object in whose context a particular method is + called. Required when the this keyword is referenced + from a function that is not a prototype method. +
@type + + @type Type
+ @type {Type} + +

For example:

+ + /** + * The message hex ID. + * @type {string} + */ + var hexId = hexId; + + 		+ Identifies the type of a variable, + property, or expression. Curly braces are not required around + most types, but some projects mandate them for all types, for + consistency. +
@typedef + @typedef +

For example:

+ + /** @typedef {(string|number)} */ + goog.NumberLike; + + /** @param {goog.NumberLike} x A number or a string. */ + goog.readNumber = function(x) { + ... + } + + 		+ This annotation can be used to declare an alias of a more + complex type. +
+ + + +

+ You may also see other types of JSDoc annotations in third-party + code. These annotations appear in the + + JSDoc Toolkit Tag Reference + + but are currently discouraged in Google code. You should consider + them "reserved" names for future use. These include: +

    +
  • @augments
    • +
  • @argument
    • +
  • @borrows
    • +
  • @class
    • +
  • @constant
    • +
  • @constructs
    • +
  • @default
    • +
  • @event
    • +
  • @example
    • +
  • @field
    • +
  • @function
    • +
  • @ignore
    • +
  • @inner
    • +
  • @link
    • +
  • @memberOf
    • +
  • @name
    • +
  • @namespace
    • +
  • @property
    • +
  • @public
    • +
  • @requires
    • +
  • @returns
    • +
  • @since
    • +
  • @static
    • +
  • @version
    • +
+

+ + + + + + + Only provide top-level symbols. + + +

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

+

Do this:

+ + goog.provide('namespace.MyClass'); + +

Not this:

+ + 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'); + +

+ Members on namespaces may also be provided: +

+ + goog.provide('foo.bar'); + goog.provide('foo.bar.method'); + goog.provide('foo.bar.CONSTANT'); + + + + + + Required + + + +

Use of JS compilers such as the + Closure Compiler + is required for all customer-facing code.

+ + + + + + + + + JavaScript tidbits + + +

The following are all false in boolean expressions:

+
    +
  • null
    • +
  • undefined
    • +
  • '' the empty string
    • +
  • 0 the number
    • +
+

But be careful, because these are all true:

+
    +
  • '0' the string
    • +
  • [] the empty array
    • +
  • {} the empty object
    • +
+ +

This means that instead of this:

+ + while (x != null) { + +

you can write this shorter code (as long as you don't expect x to + be 0, or the empty string, or false):

+ + while (x) { + + +

And if you want to check a string to see if it is null or empty, + you could do this:

+ + if (y != null && y != '') { + +

But this is shorter and nicer:

+ + if (y) { + + +

Caution: There are many unintuitive things about + boolean expressions. Here are some of them:

+
    +
  • + Boolean('0') == true
    + '0' != true
    • +
  • + 0 != null
    + 0 == []
    + 0 == false
    • +
  • + Boolean(null) == false
    + null != true
    + null != false
    • +
  • + Boolean(undefined) == false
    + undefined != true
    + undefined != false
    • +
  • + Boolean([]) == true
    + [] != true
    + [] == false
    • +
  • + Boolean({}) == true
    + {} != true
    + {} != false
    • +
+ + + +

Instead of this:

+ + if (val) { + return foo(); + } else { + return bar(); + } + +

you can write this:

+ + return val ? foo() : bar(); + + +

The ternary conditional is also useful when generating HTML:

+ + var html = '<input type="checkbox"' + + (isChecked ? ' checked' : '') + + (isEnabled ? '' : ' disabled') + + ' name="foo">'; + + + + +

These binary boolean operators are short-circuited, and evaluate + to the last evaluated term.

+ +

"||" has been called the 'default' operator, because instead of + writing this:

+ + /** @param {*=} opt_win */ + function foo(opt_win) { + var win; + if (opt_win) { + win = opt_win; + } else { + win = window; + } + // ... + } + +

you can write this:

+ + /** @param {*=} opt_win */ + function foo(opt_win) { + var win = opt_win || window; + // ... + } + + +

"&&" is also useful for shortening code. For instance, + instead of this:

+ + if (node) { + if (node.kids) { + if (node.kids[index]) { + foo(node.kids[index]); + } + } + } + + +

you could do this:

+ + if (node && node.kids && node.kids[index]) { + foo(node.kids[index]); + } + + +

or this:

+ + var kid = node && node.kids && node.kids[index]; + if (kid) { + foo(kid); + } + + +

However, this is going a little too far:

+ + node && node.kids && node.kids[index] && foo(node.kids[index]); + + + + +

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

+ + var paragraphs = document.getElementsByTagName('p'); + for (var i = 0; i < paragraphs.length; i++) { + doSomething(paragraphs[i]); + } + + +

It is better to do this instead:

+ + var paragraphs = document.getElementsByTagName('p'); + for (var i = 0, paragraph; paragraph = paragraphs[i]; i++) { + doSomething(paragraph); + } + + +

This works well for all collections and arrays as long as the array + does not contain things that are treated as boolean false.

+ +

In cases where you are iterating over the childNodes you can also + use the firstChild and nextSibling properties.

+ + var parentNode = document.getElementById('foo'); + for (var child = parentNode.firstChild; child; child = child.nextSibling) { + doSomething(child); + } + + + + + + + + + +

+ BE CONSISTENT. +

+ +

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

+ +

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

+ + + +

+ Revision 2.93 +

+ + +
+ Aaron Whyte
+ Bob Jervis
+ Dan Pupius
+ Erik Arvidsson
+ Fritz Schneider
+ Robby Walker
+
+ diff --git a/jsguide.html b/jsguide.html new file mode 100644 index 0000000..c931a69 --- /dev/null +++ b/jsguide.html @@ -0,0 +1,2816 @@ + + + + +Google JavaScript Style Guide + + + + + + +
+

Google JavaScript Style Guide

+

1 Introduction

+ +

This document serves as the complete definition of Google’s coding standards +for source code in the JavaScript programming language. A JavaScript source file +is described as being in Google Style if and only if it adheres to the rules +herein.

+ +

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

+ +

1.1 Terminology notes

+ +

In this document, unless otherwise clarified:

+ +
    +

  1. The term comment always refers to implementation comments. We do not use +the phrase documentation comments, instead using the common term “JSDoc” +for both human-readable text and machine-readable annotations within +/** … */.

    2. +

  2. This Style Guide uses RFC 2119 terminology when using the phrases must, +must not, should, should not, and may. The terms prefer and +avoid correspond to should and should not, respectively. Imperative +and declarative statements are prescriptive and correspond to must.

    3. +
+ +

Other terminology notes will appear occasionally throughout the document.

+ +

1.2 Guide notes

+ +

Example code in this document is non-normative. That is, while the examples +are in Google Style, they may not illustrate the only stylish way to represent +the code. Optional formatting choices made in examples must not be enforced as +rules.

+ +

2 Source file basics

+ +

2.1 File name

+ +

File names must be all lowercase and may include underscores (_) or dashes +(-), but no additional punctuation. Follow the convention that your project +uses. Filenames’ extension must be .js.

+ +

2.2 File encoding: UTF-8

+ +

Source files are encoded in UTF-8.

+ +

2.3 Special characters

+ +

2.3.1 Whitespace characters

+ +

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

+ +
    +

  1. All other whitespace characters in string literals are escaped, and

    2. +

  2. Tab characters are not used for indentation.

    3. +
+ +

2.3.2 Special escape sequences

+ +

For any character that has a special escape sequence (\', \", \\, \b, +\f, \n, \r, \t, \v), that sequence is used rather than the +corresponding numeric escape (e.g \x0a, \u000a, or \u{a}). Legacy octal +escapes are never used.

+ +

2.3.3 Non-ASCII characters

+ +

For the remaining non-ASCII characters, either the actual Unicode character +(e.g. ∞) or the equivalent hex or Unicode escape (e.g. \u221e) is used, +depending only on which makes the code easier to read and understand.

+ +

Tip: In the Unicode escape case, and occasionally even when actual Unicode +characters are used, an explanatory comment can be very helpful.

+ + + + + + + + + + +
Example + Discussion +
const units = 'μs'; + Best: perfectly clear even without a comment. +
+ const units = '\u03bcs'; // 'μs' + + Allowed, but there’s no reason to do this. +
+ const units = '\u03bcs'; // Greek letter mu, 's' + + Allowed, but awkward and prone to mistakes. +
const units = '\u03bcs'; + Poor: the reader has no idea what this is. +
+ return '\ufeff' + content; // byte order mark + + + Good: use escapes for non-printable characters, and comment if + necessary. +
+ +

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 broken and they must be fixed.

+ +

3 Source file structure

+ +

A source file consists of, in order:

+ +
    +
  1. License or copyright information, if present
    2. +
  2. @fileoverview JSDoc, if present
    3. +
  3. goog.module statement
    4. +
  4. goog.require statements
    5. +
  5. The file’s implementation
    6. +
+ +

Exactly one blank line separates each section that is present, except the +file's implementation, which may be preceded by 1 or 2 blank lines.

+ + + +

If license or copyright information belongs in a file, it belongs here.

+ +

3.2 @fileoverview JSDoc, if present

+ +

See ?? for formatting rules.

+ +

3.3 goog.module statement

+ +

All files must declare exactly one goog.module name on a single line: lines +containing a goog.module declaration must not be wrapped, and are therefore an +exception to the 80-column limit.

+ +

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.

+ +

Example

+ +
goog.module('search.urlHistory.UrlHistoryService');
+
+ +

3.3.1 Hierarchy

+ +

Module namespaces may never be named as a direct child of another module's +namespace.

+ +

Illegal:

+ +
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
+goog.module('foo.bar.baz');
+
+ +

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.

+ +

3.3.2 goog.setTestOnly

+ +

The single goog.module statement may optionally be followed by a call to +goog.setTestOnly().

+ +

3.3.3 goog.module.declareLegacyNamespace

+ +

The single goog.module statement may optionally be followed by a call to +goog.module.declareLegacyNamespace();. Avoid +goog.module.declareLegacyNamespace() when possible.

+ +

Example:

+ +
goog.module('my.test.helpers');
+goog.module.declareLegacyNamespace();
+goog.setTestOnly();
+
+ +

goog.module.declareLegacyNamespace 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 must not be a child or parent of any other +goog.module (for example, goog.module('parent'); and +goog.module('parent.child'); cannot both exist safely, nor can +goog.module('parent'); and goog.module('parent.child.grandchild');).

+ +

3.3.4 ES6 Modules

+ +

Do not use ES6 modules yet (i.e. the export and import keywords), as their +semantics are not yet finalized. Note that this policy will be revisited once +the semantics are fully-standard.

+ +

3.4 goog.require statements

+ +

Imports are done with goog.require statements, grouped together immediately +following the module declaration. Each goog.require 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 required dependency, +whether in code or in type annotations: the fully qualified name is never used +except as the argument to goog.require. 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. goog.require +statements may not appear anywhere else in the file.

+ +

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.

+ + + +

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 goog.require calls that are standalone (generally these are for +modules imported just for their side effects).

+ +

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.

+ +

If a long alias or module name would cause a line to exceed the 80-column limit, +it must not be wrapped: goog.require lines are an exception to the 80-column +limit.

+ +

Example:

+ +
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');
+
+ +

Illegal:

+ +
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
+  // …
+}
+
+ +

3.4.1 goog.forwardDeclare

+ +

goog.forwardDeclare 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 goog.require statements. A +goog.forwardDeclare statement must follow the same style rules as a +goog.require statement.

+ +

3.5 The file’s implementation

+ +

The actual implementation follows after all dependency information is declared +(separated by at least one blank line).

+ +

This may consist of any module-local declarations (constants, variables, +classes, functions, etc), as well as any exported symbols. +

+ +

4 Formatting

+ +

Terminology Note: block-like construct refers to the body of a class, +function, method, or brace-delimited block of code. Note that, by +?? and ??, any array or +object literal may optionally be treated as if it were a block-like construct.

+ +

Tip: Use clang-format. The JavaScript community has invested effort to make +sure clang-format does the right thing on JavaScript files. clang-format has +integration with several popular +editors.

+ +

4.1 Braces

+ +

4.1.1 Braces are used for all control structures

+ +

Braces are required for all control structures (i.e. if, else, for, do, +while, 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.

+ +

Illegal:

+ +
if (someVeryLongCondition())
+  doSomething();
+
+for (let i = 0; i < foo.length; i++) bar(foo[i]);
+
+ +

Exception: 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.

+ +
if (shortCondition()) return;
+
+ +

4.1.2 Nonempty blocks: K&R style

+ +

Braces follow the Kernighan and Ritchie style (Egyptian brackets) for +nonempty blocks and block-like constructs:

+ +
    +
  • No line break before the opening brace.
    • +
  • Line break after the opening brace.
    • +
  • Line break before the closing brace.
    • +
  • Line break after the closing brace if that brace terminates a statement or +the body of a function or class statement, or a class method. Specifically, +there is no line break after the brace if it is followed by else, catch, +while, or a comma, semicolon, or right-parenthesis.
    • +
+ +

Example:

+ +
class InnerClass {
+  constructor() {}
+
+  /** @param {number} foo */
+  method(foo) {
+    if (condition(foo)) {
+      try {
+        // Note: this might fail.
+        something();
+      } catch (err) {
+        recover();
+      }
+    }
+  }
+}
+
+ +

4.1.3 Empty blocks: may be concise

+ +

An empty block or block-like construct may be closed immediately after it is +opened, with no characters, space, or line break in between (i.e. {}), +unless it is a part of a multi-block statement (one that directly contains +multiple blocks: if/else or try/catch/finally).

+ +

Example:

+ +
function doNothing() {}
+
+ +

Illegal:

+ +
if (condition) {
+  // …
+} else if (otherCondition) {} else {
+  // …
+}
+
+try {
+  // …
+} catch (e) {}
+
+ +

4.2 Block indentation: +2 spaces

+ +

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

+ +

4.2.1 Array literals: optionally block-like

+ +

Any array literal may optionally be formatted as if it were a “block-like +construct.” For example, the following are all valid (not an exhaustive +list):

+ +
const a = [
+  0,
+  1,
+  2,
+];
+
+const b =
+    [0, 1, 2];
+
+
+ +
const c = [0, 1, 2];
+
+someMethod(foo, [
+  0, 1, 2,
+], bar);
+
+ +

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.

+ +

4.2.2 Object literals: optionally block-like

+ +

Any object literal may optionally be formatted as if it were a “block-like +construct.” The same examples apply as ??. For +example, the following are all valid (not an exhaustive list):

+ +
const a = {
+  a: 0,
+  b: 1,
+};
+
+const b =
+    {a: 0, b: 1};
+
+ +
const c = {a: 0, b: 1};
+
+someMethod(foo, {
+  a: 0, b: 1,
+}, bar);
+
+ +

4.2.3 Class literals

+ +

Class literals (whether declarations or expressions) are indented as blocks. Do +not add semicolons after methods, or after the closing brace of a class +declaration (statements—such as assignments—that contain class expressions +are still terminated with a semicolon). Use the extends keyword, but not the +@extends JSDoc annotation unless the class extends a templatized type.

+ +

Example:

+ +
class Foo {
+  constructor() {
+    /** @type {number} */
+    this.x = 42;
+  }
+
+  /** @return {number} */
+  method() {
+    return this.x;
+  }
+}
+Foo.Empty = class {};
+
+ +
/** @extends {Foo<string>} */
+foo.Bar = class extends Foo {
+  /** @override */
+  method() {
+    return super.method() / 2;
+  }
+};
+
+/** @interface */
+class Frobnicator {
+  /** @param {string} message */
+  frobnicate(message) {}
+}
+
+ +

4.2.4 Function expressions

+ +

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.

+ +

Example:

+ +
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();
+      }
+    });
+
+ +

4.2.5 Switch statements

+ +

As with any other block, the contents of a switch block are indented +2.

+ + + +

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.

+ +

A blank line is optional between a break and the following case.

+ +

Example:

+ +
switch (animal) {
+  case Animal.BANDERSNATCH:
+    handleBandersnatch();
+    break;
+
+  case Animal.JABBERWOCK:
+    handleJabberwock();
+    break;
+
+  default:
+    throw new Error('Unknown animal');
+}
+
+ +

4.3 Statements

+ +

4.3.1 One statement per line

+ +

Each statement is followed by a line-break.

+ +

4.3.2 Semicolons are required

+ +

Every statement must be terminated with a semicolon. Relying on automatic +semicolon insertion is forbidden.

+ +

4.4 Column limit: 80

+ +

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 +??.

+ +

Exceptions:

+ +
    +
  1. 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).
    2. +
  2. goog.module and goog.require statements (see ?? and +??).
    3. +
+ +

4.5 Line-wrapping

+ +

Terminology Note: Line-wrapping is defined as breaking a single expression +into multiple lines.

+ +

There is no comprehensive, deterministic formula showing exactly how to +line-wrap in every situation. Very often there are several valid ways to +line-wrap the same piece of code.

+ +

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.

+ +

Tip: Extracting a method or local variable may solve the problem without the +need to line-wrap.

+ +

4.5.1 Where to break

+ +

The prime directive of line-wrapping is: prefer to break at a higher syntactic +level.

+ +

Preferred:

+ +
currentEstimate =
+    calc(currentEstimate + x * currentEstimate) /
+        2.0f;
+
+ +

Discouraged:

+ +
currentEstimate = calc(currentEstimate + x *
+    currentEstimate) / 2.0f;
+
+ +

In the preceding example, the syntactic levels from highest to lowest are as +follows: assignment, division, function call, parameters, number constant.

+ +

Operators are wrapped as follows:

+ +
    +
  1. 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.) +
      +
    1. This does not apply to the dot (.), which is not actually an +operator.
      2. +
    2. +
  2. A method or constructor name stays attached to the open parenthesis (() +that follows it.
    3. +
  3. A comma (,) stays attached to the token that precedes it.
    4. +
+ +
+

Note: The primary goal for line wrapping is to have clear code, not +necessarily code that fits in the smallest number of lines.

+
+ +

4.5.2 Indent continuation lines at least +4 spaces

+ +

When line-wrapping, each line after the first (each continuation line) is +indented at least +4 from the original line, unless it falls under the rules of +block indentation.

+ +

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.

+ +

?? addresses the discouraged practice of +using a variable number of spaces to align certain tokens with previous lines.

+ +

4.6 Whitespace

+ +

4.6.1 Vertical whitespace

+ +

A single blank line appears:

+ +
    +
  1. Between consecutive methods in a class or object literal +
      +
    1. 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 logical groupings of fields.
      2. +
    2. +
  2. Within method bodies, sparingly to create logical groupings of statements. +Blank lines at the start or end of a function body are not allowed.
    3. +
  3. Optionally before the first or after the last method in a class or object +literal (neither encouraged nor discouraged).
    4. +
  4. As required by other sections of this document (e.g. +??).
    5. +
+ +

Multiple consecutive blank lines are permitted, but never required (nor +encouraged).

+ +

4.6.2 Horizontal whitespace

+ +

Use of horizontal whitespace depends on location, and falls into three broad +categories: leading (at the start of a line), trailing (at the end of a +line), and internal. Leading whitespace (i.e., indentation) is addressed +elsewhere. Trailing whitespace is forbidden.

+ +

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

+ +
    +
  1. Separating any reserved word (such as if, for, or catch) from an open +parenthesis (() that follows it on that line.
    2. +
  2. Separating any reserved word (such as else or catch) from a closing +curly brace (}) that precedes it on that line.
    3. +
  3. Before any open curly brace ({), with two exceptions: +
      +
    1. Before an object literal that is the first argument of a function or the +first element in an array literal (e.g. foo({a: [{c: d}]})).
      2. +
    2. In a template expansion, as it is forbidden by the language +(e.g. abc${1 + 2}def).
      3. +
    4. +
  4. On both sides of any binary or ternary operator.
    5. +
  5. After a comma (,) or semicolon (;). Note that spaces are never allowed +before these characters.
    6. +
  6. After the colon (:) in an object literal.
    7. +
  7. On both sides of the double slash (//) that begins an end-of-line +comment. Here, multiple spaces are allowed, but not required.
    8. +
  8. After an open-JSDoc comment character and on both sides of close characters +(e.g. for short-form type declarations or casts: this.foo = /** @type +{number} */ (bar); or function(/** string */ foo) {).
    9. +
+ +

4.6.3 Horizontal alignment: discouraged

+ +

Terminology Note: Horizontal alignment 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.

+ +

This practice is permitted, but it is generally discouraged by Google +Style. It is not even required to maintain horizontal alignment in places +where it was already used.

+ +

Here is an example without alignment, followed by one with alignment. Both are +allowed, but the latter is discouraged:

+ +
{
+  tiny: 42, // this is great
+  longer: 435, // this too
+};
+
+{
+  tiny:   42,  // permitted, but future edits
+  longer: 435, // may leave it unaligned
+};
+
+ +

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

+ +

4.6.4 Function arguments

+ +

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:

+ +
// 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) {
+  // …
+}
+
+ +

4.7 Grouping parentheses: recommended

+ +

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 not +reasonable to assume that every reader has the entire operator precedence table +memorized.

+ +

Do not use unnecessary parentheses around the entire expression following +delete, typeof, void, return, throw, case, in, of, or yield.

+ +

Parentheses are required for type casts: /** @type {!Foo} */ (foo).

+ +

4.8 Comments

+ +

This section addresses implementation comments. JSDoc is addressed separately +in ??.

+ +

4.8.1 Block comment style

+ +

Block comments are indented at the same level as the surrounding code. They may +be in /* … */ or //-style. For multi-line /* … */ comments, subsequent +lines must start with * aligned with the * 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.

+ +
/*
+ * This is
+ * okay.
+ */
+
+// And so
+// is this.
+
+/* This is fine, too. */
+
+someFunction(obviousParam, true /* shouldRender */, 'hello' /* name */);
+
+ +

Comments are not enclosed in boxes drawn with asterisks or other characters.

+ +

Do not use JSDoc (/** … */) for any of the above implementation comments.

+ +

5 Language features

+ +

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.

+ +

5.1 Local variable declarations

+ +

5.1.1 Use const and let

+ +

Declare all local variables with either const or let. Use const by default, +unless a variable needs to be reassigned. The var +keyword must not be used.

+ +

5.1.2 One variable per declaration

+ +

Every local variable declaration declares only one variable: declarations such +as let a = 1, b = 2; are not used.

+ +

5.1.3 Declared when needed, initialized as soon as possible

+ +

Local variables are not 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.

+ +

5.1.4 Declare types as needed

+ +

JSDoc type annotations may be added either on the line above the declaration, or +else inline before the variable name.

+ +

Example:

+ +
const /** !Array<number> */ data = [];
+
+/** @type {!Array<number>} */
+const data = [];
+
+ +

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, Maps, or Sets), 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.

+ +

5.2 Array literals

+ +

5.2.1 Use trailing commas

+ + + +

Include a trailing comma whenever there is a line break between the final +element and the closing bracket.

+ +

Example:

+ +
const values = [
+  'first value',
+  'second value',
+];
+
+ +

5.2.2 Do not use the variadic Array constructor

+ +

The constructor is error-prone if arguments are added or removed. Use a literal +instead.

+ +

Illegal:

+ +
const a1 = new Array(x1, x2, x3);
+const a2 = new Array(x1, x2);
+const a3 = new Array(x1);
+const a4 = new Array();
+
+ +

This works as expected except for the third case: if x1 is a whole number then +a3 is an array of size x1 where all elements are undefined. If x1 is any +other number, then an exception will be thrown, and if it is anything else then +it will be a single-element array.

+ +

Instead, write

+ +
const a1 = [x1, x2, x3];
+const a2 = [x1, x2];
+const a3 = [x1];
+const a4 = [];
+
+ +

Explicitly allocating an array of a given length using new Array(length) is +allowed when appropriate.

+ +

5.2.3 Non-numeric properties

+ +

Do not define or use non-numeric properties on an array (other than +length). Use a Map (or Object) instead.

+ +

5.2.4 Destructuring

+ +

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 rest element may be included (with no space between the +... and the variable name). Elements should be omitted if they are unused.

+ +
const [a, b, c, ...rest] = generateResults();
+let [, b,, d] = someArray;
+
+ +

Destructuring may also be used for function parameters (note that a parameter +name is required but ignored). Always specify [] as the default value if a +destructured array parameter is optional, and provide default values on the left +hand side:

+ +
/** @param {!Array<number>=} param1 */
+function optionalDestructuring([a = 4, b = 2] = []) { … };
+
+ +

Illegal:

+ +
function badDestructuring([a, b] = [4, 2]) { … };
+
+ +

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

+ +

5.2.5 Spread operator

+ +

Array literals may include the spread operator (...) to flatten elements out +of one or more other iterables. The spread operator should be used instead of +more awkward constructs with Array.prototype. There is no space after the +....

+ +

Example:

+ +
[...foo]   // preferred over Array.prototype.slice.call(foo)
+[...foo, ...bar]   // preferred over foo.concat(bar)
+
+ +

5.3 Object literals

+ +

5.3.1 Use trailing commas

+ +

Include a trailing comma whenever there is a line break between the final +property and the closing brace.

+ +

5.3.2 Do not use the Object constructor

+ +

While Object does not have the same problems as Array, it is still +disallowed for consistency. Use an object literal ({} or {a: 0, b: 1, c: 2}) +instead.

+ +

5.3.3 Do not mix quoted and unquoted keys

+ +

Object literals may represent either structs (with unquoted keys and/or +symbols) or dicts (with quoted and/or computed keys). Do not mix these key +types in a single object literal.

+ +

Illegal:

+ +
{
+  a: 42, // struct-style unquoted key
+  'b': 43, // dict-style quoted key
+}
+
+ +

5.3.4 Computed property names

+ +

Computed property names (e.g., {['key' + foo()]: 42}) 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., [Symbol.iterator]). +Enum values may also be used for computed keys, but should not be mixed with +non-enum keys in the same literal.

+ +

5.3.5 Method shorthand

+ +

Methods can be defined on object literals using the method shorthand ({method() +{… }}) in place of a colon immediately followed by a function or arrow +function literal.

+ +

Example:

+ +
return {
+  stuff: 'candy',
+  method() {
+    return this.stuff;  // Returns 'candy'
+  },
+};
+
+ +

Note that this in a method shorthand or function refers to the object +literal itself whereas this in an arrow function refers to the scope outside +the object literal.

+ +

Example:

+ +
class {
+  getObjectLiteral() {
+    this.stuff = 'fruit';
+    return {
+      stuff: 'candy',
+      method: () => this.stuff,  // Returns 'fruit'
+    };
+  }
+}
+
+ +

5.3.6 Shorthand properties

+ +

Shorthand properties are allowed on object literals.

+ +

Example:

+ +
const foo = 1;
+const bar = 2;
+const obj = {
+  foo,
+  bar,
+  method() { return this.foo + this.bar; },
+};
+assertEquals(3, obj.method());
+
+ +

5.3.7 Destructuring

+ +

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.

+ +

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 ({str = 'some default'} = {}, rather than {str} = {str: 'some default'}), and if a destructured +object is itself optional, it must default to {}. The JSDoc for the +destructured parameter may be given any name (the name is unused but is required +by the compiler).

+ +

Example:

+ +
/**
+ * @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'} = {})
+
+ +

Illegal:

+ +
/** @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}) {};
+
+ +

Destructuring may also be used for goog.require statements, and in this case +must not be wrapped: the entire statement occupies one line, regardless of how +long it is (see ??).

+ +

5.3.8 Enums

+ +

Enumerations are defined by adding the @enum 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.

+ +
/**
+ * 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,
+};
+
+ +

5.4 Classes

+ +

5.4.1 Constructors

+ +

Constructors are optional for concrete classes. Subclass constructors must call +super() before setting any fields or otherwise accessing this. Interfaces +must not define a constructor.

+ +

5.4.2 Fields

+ +

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 @const +(these need not be deeply immutable). Private fields must be annotated with +@private and their names must end with a trailing underscore. Fields are never +set on a concrete class' prototype.

+ +

Example:

+ +
class Foo {
+  constructor() {
+    /** @private @const {!Bar} */
+    this.bar_ = computeBar();
+  }
+}
+
+ +

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 undefined in the constructor to prevent later shape changes. Adding +@struct to an object will check that undeclared properties are not +added/accessed. Classes have this added by default.

+ +

5.4.3 Computed properties

+ + + +

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 ??) are not allowed. A +[Symbol.iterator] method should be defined for any classes that are logically +iterable. Beyond this, Symbol should be used sparingly.

+ +

Tip: be careful of using any other built-in symbols (e.g., Symbol.isConcatSpreadable) as they are not polyfilled by the compiler and will therefore not work in older browsers.

+ +

5.4.4 Static methods

+ + + +

Where it does not interfere with readability, prefer module-local functions over +private static methods.

+ +

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 +@nocollapse if this is done), and must not be called directly on a subclass +that doesn’t define the method itself.

+ +

Illegal:

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

5.4.5 Old-style class declarations

+ +

While ES6 classes are preferred, there are cases where ES6 classes may not be +feasible. For example:

+ +
    +

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

    2. +

  2. Frameworks that require a known this value before calling the superclass +constructor, since constructors with ES6 super classes do not have +access to the instance this value until the call to super returns.

    3. +
+ +

In all other ways the style guide still applies to this code: let, const, +default parameters, rest, and arrow functions should all be used when +appropriate.

+ +

goog.defineClass allows for a class-like definition similar to ES6 class +syntax:

+ +
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;
+  },
+});
+
+ +

Alternatively, while goog.defineClass should be preferred for all new code, +more traditional syntax is also allowed.

+ +
/**
+  * @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;
+};
+
+ +

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.

+ +

Defining constructor prototype hierarchies correctly is harder than it first appears! For that reason, it is best to use goog.inherits from the Closure Library .

+ +

5.4.6 Do not manipulate prototypes directly

+ +

The class keyword allows clearer and more readable class definitions than +defining prototype properties. Ordinary implementation code has no business +manipulating these objects, though they are still useful for defining @record +interfaces and classes as defined in ??. Mixins +and modifying the prototypes of builtin objects are +explicitly forbidden.

+ +

Exception: Framework code (such as Polymer, or Angular) may need to use prototypes, and should not +resort to even-worse workarounds to avoid doing so.

+ +

Exception: Defining fields in interfaces (see ??).

+ +

5.4.7 Getters and Setters

+ +

Do not use JavaScript getter and setter properties. They are potentially +surprising and difficult to reason about, and have limited support in the +compiler. Provide ordinary methods instead.

+ +

Exception: 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 get foo() and set foo(value) in the class or object literal, or if that +is not possible, with Object.defineProperties. Do not use +Object.defineProperty, which interferes with property renaming. Getters +must not change observable state.

+ +

Illegal:

+ +
class Foo {
+  get next() { return this.nextId++; }
+}
+
+ +

5.4.8 Overriding toString

+ +

The toString method may be overridden, but must always succeed and never have +visible side effects.

+ +

Tip: Beware, in particular, of calling other methods from toString, since +exceptional conditions could lead to infinite loops.

+ +

5.4.9 Interfaces

+ +

Interfaces may be declared with @interface or @record. Interfaces declared +with @record can be explicitly (i.e. via @implements) or implicitly +implemented by a class or object literal.

+ +

All non-static method bodies on an interface must be empty blocks. Fields must +be defined after the interface body as stubs on the prototype.

+ +

Example:

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

5.5 Functions

+ +

5.5.1 Top-level functions

+ +

Exported functions may be defined directly on the exports object, or else +declared locally and exported separately. Non-exported functions are encouraged +and should not be declared @private.

+ +

Examples:

+ +
/** @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};
+
+ +
/** @param {string} arg */
+exports.foo = (arg) => {
+  // do some stuff ...
+};
+
+ +

5.5.2 Nested functions and closures

+ +

Functions may contain nested function definitions. If it is useful to give the +function a name, it should be assigned to a local const.

+ +

5.5.3 Arrow functions

+ +

Arrow functions provide a concise syntax and fix a number of difficulties with +this. Prefer arrow functions over the function keyword, particularly for +nested functions (but see ??).

+ +

Prefer using arrow functions over f.bind(this), and especially over +goog.bind(f, this). Avoid writing const self = this. Arrow functions are +particularly useful for callbacks, which sometimes pass unexpected additional +arguments.

+ +

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.

+ +

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.

+ +

5.5.4 Generators

+ +

Generators enable a number of useful abstractions and may be used as needed.

+ +

When defining generator functions, attach the * to the function keyword when +present, and separate it with a space from the name of the function. When using +delegating yields, attach the * to the yield keyword.

+ +

Example:

+ +
/** @return {!Iterator<number>} */
+function* gen1() {
+  yield 42;
+}
+
+/** @return {!Iterator<number>} */
+const gen2 = function*() {
+  yield* gen1();
+}
+
+class SomeClass {
+  /** @return {!Iterator<number>} */
+  * gen() {
+    yield 42;
+  }
+}
+
+ +

5.5.5 Parameters

+ +

Function parameters must be typed with JSDoc annotations in the JSDoc preceding +the function’s definition, except in the case of same-signature @overrides, +where all types are omitted.

+ +

Parameter types may be specified inline, immediately before the parameter name +(as in (/** number */ foo, /** string */ bar) => foo + bar). Inline and +@param type annotations must not be mixed in the same function definition.

+ +
5.5.5.1 Default parameters
+ +

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 +opt_), use the = 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 undefined.

+ +

Example:

+ +
/**
+ * @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) {}
+
+ +

Use default parameters sparingly. Prefer destructuring (as in +??) to create readable APIs when there +are more than a small handful of optional parameters that do not have a natural +order.

+ +

Note: Unlike Python's default parameters, it is okay to use initializers that +return new mutable objects (such as {} or []) because the initializer is +evaluated each time the default value is used, so a single object won't be +shared across invocations.

+ +

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.

+ +
5.5.5.2 Rest parameters
+ +

Use a rest parameter instead of accessing arguments. Rest parameters are +typed with a ... prefix in their JSDoc. The rest parameter must be the last +parameter in the list. There is no space between the ... and the parameter +name. Do not name the rest parameter var_args. Never name a local variable or +parameter arguments, which confusingly shadows the built-in name.

+ +

Example:

+ +
/**
+ * @param {!Array<string>} array This is an ordinary parameter.
+ * @param {...number} numbers The remainder of arguments are all numbers.
+ */
+function variadic(array, ...numbers) {}
+
+ +

5.5.6 Returns

+ +

Function return types must be specified in the JSDoc directly above the function +definition, except in the case of same-signature @overrides where all types +are omitted.

+ +

5.5.7 Generics

+ +

Declare generic functions and methods when necessary with @template TYPE in +the JSDoc above the class definition.

+ +

5.5.8 Spread operator

+ +

Function calls may use the spread operator (...). Prefer the spread operator +to Function.prototype.apply when an array or iterable is unpacked into +multiple parameters of a variadic function. There is no space after the ....

+ +

Example:

+ +
function myFunction(...elements) {}
+myFunction(...array, ...iterable, ...generator());
+
+ +

5.6 String literals

+ +

5.6.1 Use single quotes

+ +

Ordinary string literals are delimited with single quotes ('), rather than +double quotes (").

+ +

Tip: if a string contains a single quote character, consider using a template +string to avoid having to escape the quote.

+ +

Ordinary string literals may not span multiple lines.

+ +

5.6.2 Template strings

+ +

Use template strings (delimited with `) over complex string +concatenation, particularly if multiple string literals are involved. Template +strings may span multiple lines.

+ +

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.

+ +

Example:

+ +
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}`;
+}
+
+ +

5.6.3 No line continuations

+ +

Do not use line continuations (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.

+ +

Illegal:

+ +
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.';
+
+ +

Instead, write

+ +
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.';
+
+ +

5.7 Number literals

+ +

Numbers may be specified in decimal, hex, octal, or binary. Use exactly 0x, +0o, and 0b prefixes, with lowercase letters, for hex, octal, and binary, +respectively. Never include a leading zero unless it is immediately followed by +x, o, or b.

+ +

5.8 Control structures

+ +

5.8.1 For loops

+ +

With ES6, the language now has three different kinds of for loops. All may be +used, though for-of loops should be preferred when possible.

+ +

for-in loops may only be used on dict-style objects (see +??), and should not be used to iterate over an +array. Object.prototype.hasOwnProperty should be used in for-in loops to +exclude unwanted prototype properties. Prefer for-of and Object.keys over +for-in when possible.

+ +

5.8.2 Exceptions

+ +

Exceptions are an important part of the language and should be used whenever +exceptional cases occur. Always throw Errors or subclasses of Error: never +throw string literals or other objects. Always use new when constructing an +Error.

+ +

Custom exceptions provide a great way to convey additional error information +from functions. They should be defined and used wherever the native Error +type is insufficient.

+ +

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

+ +
5.8.2.1 Empty catch blocks
+ +

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.

+ +
try {
+  return handleNumericResponse(response);
+} catch (ok) {
+  // it's not numeric; that's fine, just continue
+}
+return handleTextResponse(response);
+
+ +

Illegal:

+ +
   try {
+    shouldFail();
+    fail('expected an error');
+  }
+  catch (expected) {}
+
+ +

Tip: Unlike in some other languages, patterns like the above simply don’t work +since this will catch the error thrown by fail. Use assertThrows() instead.

+ +

5.8.3 Switch statements

+ +

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 case FOO: or default:), followed by one or more statements.

+ +
5.8.3.1 Fall-through: commented
+ +

Within a switch block, each statement group either terminates abruptly (with a +break, return or thrown 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 // fall through). This special comment is not required in the last +statement group of the switch block.

+ +

Example:

+ +
switch (input) {
+  case 1:
+  case 2:
+    prepareOneOrTwo();
+  // fall through
+  case 3:
+    handleOneTwoOrThree();
+    break;
+  default:
+    handleLargeNumber(input);
+}
+
+ +
5.8.3.2 The default case is present
+ +

Each switch statement includes a default statement group, even if it contains +no code.

+ +

5.9 this

+ +

Only use this in class constructors and methods, or in arrow functions defined +within class constructors and methods. Any other uses of this must have an +explicit @this declared in the immediately-enclosing function’s JSDoc.

+ +

Never use this to refer to the global object, the context of an eval, the +target of an event, or unnecessarily call()ed or apply()ed functions.

+ +

5.10 Disallowed features

+ +

5.10.1 with

+ +

Do not use the with keyword. It makes your code harder to understand and has +been banned in strict mode since ES5.

+ +

5.10.2 Dynamic code evaluation

+ +

Do not use eval or the Function(...string) constructor (except for code +loaders). These features are potentially dangerous and simply do not work in +CSP environments.

+ +

5.10.3 Automatic semicolon insertion

+ +

Always terminate statements with semicolons (except function and class +declarations, as noted above).

+ +

5.10.4 Non-standard features

+ +

Do not use non-standard features. This includes old features that have been +removed (e.g., WeakMap.clear), 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.

+ +

5.10.5 Wrapper objects for primitive types

+ +

Never use new on the primitive object wrappers (Boolean, Number, String, +Symbol), nor include them in type annotations.

+ +

Illegal:

+ +
const /** Boolean */ x = new Boolean(false);
+if (x) alert(typeof x);  // alerts 'object' - WAT?
+
+ +

The wrappers may be called as functions for coercing (which is preferred over +using + or concatenating the empty string) or creating symbols.

+ +

Example:

+ +
const /** boolean */ x = Boolean(0);
+if (!x) alert(typeof x);  // alerts 'boolean', as expected
+
+ +

5.10.6 Modifying builtin objects

+ +

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.

+ +

Do not add symbols to the global object unless absolutely necessary +(e.g. required by a third-party API).

+ +

6 Naming

+ +

6.1 Rules common to all identifiers

+ +

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.

+ +

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.

+ +
priceCountReader      // No abbreviation.
+numErrors             // "num" is a widespread convention.
+numDnsConnections     // Most people know what "DNS" stands for.
+
+ +

Illegal:

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

6.2 Rules by identifier type

+ +

6.2.1 Package names

+ +

Package names are all lowerCamelCase. For example, +my.exampleCode.deepSpace, but not my.examplecode.deepspace or my.example_code.deep_space.

+ +

6.2.2 Class names

+ +

Class, interface, record, and typedef names are written in UpperCamelCase. +Unexported classes are simply locals: they are not marked @private and +therefore are not named with a trailing underscore.

+ +

Type names are typically nouns or noun phrases. For example, Request, +ImmutableList, or VisibilityMode. Additionally, interface names may +sometimes be adjectives or adjective phrases instead (for example, Readable).

+ +

6.2.3 Method names

+ +

Method names are written in lowerCamelCase. Private methods’ names must end +with a trailing underscore.

+ +

Method names are typically verbs or verb phrases. For example, sendMessage or +stop_. Getter and setter methods for properties are never required, but if +they are used they should be named getFoo (or optionally isFoo or hasFoo +for booleans), or setFoo(value) for setters.

+ +

Underscores may also appear in JsUnit test method names to separate logical +components of the name. One typical pattern is test<MethodUnderTest>_<state>, +for example testPop_emptyStack. There is no One Correct Way to name test +methods.

+ +

6.2.4 Enum names

+ +

Enum names are written in UpperCamelCase, similar to classes, and should +generally be singular nouns. Individual items within the enum are named in +CONSTANT_CASE.

+ +

6.2.5 Constant names

+ +

Constant names use CONSTANT_CASE: 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.

+ +
6.2.5.1 Definition of “constant”
+ +

Every constant is a @const static property or a module-local const +declaration, but not all @const static properties and module-local consts +are constants. Before choosing constant case, consider whether the field really +feels like a deeply immutable 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.

+ +

Examples:

+ +
// 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');
+
+ +

Constants’ names are typically nouns or noun phrases.

+ +
6.2.5.1 Local aliases
+ +

Local aliases should be used whenever they improve readability over +fully-qualified names. Follow the same rules as goog.requires +(??), maintaining the last part of the aliased name. +Aliases may also be used within functions. Aliases must be const.

+ +

Examples:

+ +
const staticHelper = importedNamespace.staticHelper;
+const CONSTANT_NAME = ImportedClass.CONSTANT_NAME;
+const {assert, assertInstanceof} = asserts;
+
+ +

6.2.6 Non-constant field names

+ +

Non-constant field names (static or otherwise) are written in lowerCamelCase, +with a trailing underscore for private fields.

+ +

These names are typically nouns or noun phrases. For example, computedValues +or index_.

+ +

6.2.7 Parameter names

+ +

Parameter names are written in lowerCamelCase. Note that this applies even if +the parameter expects a constructor.

+ +

One-character parameter names should not be used in public methods.

+ +

Exception: When required by a third-party framework, parameter names may +begin with a $. This exception does not apply to any other identifiers +(e.g. local variables or properties).

+ +

6.2.8 Local variable names

+ +

Local variable names are written in lowerCamelCase, except for module-local +(top-level) constants, as described above. Constants in function scopes are +still named in lowerCamelCase. Note that lowerCamelCase applies even if the +variable holds a constructor.

+ +

6.2.9 Template parameter names

+ +

Template parameter names should be concise, single-word or single-letter +identifiers, and must be all-caps, such as TYPE or THIS.

+ +

6.3 Camel case: defined

+ +

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.

+ +

Beginning with the prose form of the name:

+ +
    +
  1. Convert the phrase to plain ASCII and remove any apostrophes. For example, +Müller's algorithm might become Muellers algorithm.
    2. +
  2. Divide this result into words, splitting on spaces and any remaining +punctuation (typically hyphens). +
      +
    1. Recommended: 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 per se; it defies any convention, so this +recommendation does not apply.
      2. +
    3. +
  3. Now lowercase everything (including acronyms), then uppercase only the first +character of: +
      +
    1. … each word, to yield upper camel case, or
      2. +
    2. … each word except the first, to yield lower camel case
      3. +
    4. +
  4. Finally, join all the words into a single identifier.
    5. +
+ +

Note that the casing of the original words is almost entirely disregarded.

+ +

Examples:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Prose formCorrectIncorrect
XML HTTP requestXmlHttpRequestXMLHTTPRequest
new customer IDnewCustomerIdnewCustomerID
inner stopwatchinnerStopwatchinnerStopWatch
supports IPv6 on iOS?supportsIpv6OnIossupportsIPv6OnIOS
YouTube importerYouTubeImporterYoutubeImporter*
+ +

*Acceptable, but not recommended.

+ +

Note: Some words are ambiguously hyphenated in the English language: for example nonempty and non-empty are both correct, so the method names checkNonempty and checkNonEmpty are likewise both correct.

+ +

7 JSDoc

+ +

JSDoc is used on all classes, fields, and methods.

+ +

7.1 General form

+ +

The basic formatting of JSDoc blocks is as seen in this example:

+ +
/**
+ * Multiple lines of JSDoc text are written here,
+ * wrapped normally.
+ * @param {number} arg A number to do something to.
+ */
+function doSomething(arg) { … }
+
+ +

or in this single-line example:

+ +
/** @const @private {!Foo} A short bit of JSDoc. */
+this.foo_ = foo;
+
+ +

If a single-line comment overflows into multiple lines, it must use the +multi-line style with /** and */ on their own lines.

+ +

Many tools extract metadata from JSDoc comments to perform code validation and +optimization. As such, these comments must be well-formed.

+ +

7.2 Markdown

+ +

JSDoc is written in Markdown, though it may include HTML when necessary.

+ +

Note that tools that automatically extract JSDoc (e.g. JsDossier) will often +ignore plain text formatting, so if you did this:

+ +
/**
+ * Computes weight based on three factors:
+ *   items sent
+ *   items received
+ *   last timestamp
+ */
+
+ +

it would come out like this:

+ +
Computes weight based on three factors: items sent items received last timestamp
+
+ +

Instead, write a Markdown list:

+ +
/**
+ * Computes weight based on three factors:
+ *  - items sent
+ *  - items received
+ *  - last timestamp
+ */
+
+ +

7.3 JSDoc tags

+ +

Google style allows a subset of JSDoc tags. See +?? for the complete list. Most tags must +occupy their own line, with the tag at the beginning of the line.

+ +

Illegal:

+ +
/**
+ * The "param" tag must occupy its own line and may not be combined.
+ * @param {number} left @param {number} right
+ */
+function add(left, right) { ... }
+
+ +

Simple tags that do not require any additional data (such as @private, +@const, @final, @export) may be combined onto the same line, along with an +optional type when appropriate.

+ +
/**
+ * 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];
+  }
+}
+
+ +

There is no hard rule for when to combine tags, or in which order, but be +consistent.

+ +

For general information about annotating types in JavaScript see +Annotating JavaScript for the Closure Compiler and Types in the Closure Type +System.

+ +

7.4 Line wrapping

+ +

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.

+ +
/**
+ * 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;
+};
+
+ +

Do not indent when wrapping a @fileoverview description.

+ +

7.5 Top/file-level comments

+ +

A file may have a top-level file overview. A copyright notice , author information, and +default visibility level 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.

+ +

Example:

+ +
/**
+ * @fileoverview Description of file, its uses and information
+ * about its dependencies.
+ * @package
+ */
+
+ +

7.6 Class comments

+ +

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. @constructor and @extends annotations are not used with the +class keyword unless the class is being used to declare an @interface or +it extends a generic class.

+ +
/**
+ * 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() {}
+}
+
+ +

7.7 Enum and typedef comments

+ +

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.

+ +
/**
+ * 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',
+};
+
+ +

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 @record.

+ +

7.8 Method and function comments

+ +

Parameter and return types must be documented. The this 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 @override annotation. Overridden methods must include all +@param and @return annotations if any types are refined, but should omit +them if the types are all the same.

+ +
/** 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) { ... }
+
+ + + +

Anonymous functions do not require JSDoc, though parameter types may be specified inline if the automatic type inference is insufficient.

+ +
promise.then(
+    (/** !Array<number|string> */ items) => {
+      doSomethingWith(items);
+      return /** @type {string} */ (items[0]);
+    });
+
+ +

7.9 Property comments

+ +

Property types must be documented. The description may be omitted for private +properties, if name and type provide enough documentation for understanding the +code.

+ +

Publicly exported constants are commented the same way as properties. Explicit +types may be omitted for @const properties initialized from an expression with +an obviously known type.

+ +

Tip: A @const 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.

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

7.10 Type annotations

+ +

Type annotations are found on @param, @return, @this, and @type tags, +and optionally on @const, @export, and any visibility tags. Type +annotations attached to JSDoc tags must always be enclosed in braces.

+ +

7.10.1 Nullability

+ +

The type system defines modifiers ! and ? for non-null and nullable, +respectively. Primitive types (undefined, string, number, boolean, +symbol, and function(...): ...) and record literals ({foo: string, bar: +number}) are non-null by default. Do not add an explicit ! to these types. +Object types (Array, Element, MyClass, etc) are nullable by default, but +cannot be immediately distinguished from a name that is @typedef’d to a +non-null-by-default type. As such, all types except primitives and record +literals must be annotated explicitly with either ? or ! to indicate whether +they are nullable or not.

+ +

7.10.2 Type Casts

+ +

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.

+ +
/** @type {number} */ (x)
+
+ +

7.10.3 Template Parameter Types

+ +

Always specify template parameters. This way compiler can do a better job and it +makes it easier for readers to understand what code does.

+ +

Bad:

+ +
const /** !Object */ users = {};
+const /** !Array */ books = [];
+const /** !Promise */ response = ...;
+
+ +

Good:

+ +
const /** !Object<string, !User> */ users = {};
+const /** !Array<string> */ books = [];
+const /** !Promise<!Response> */ response = ...;
+
+const /** !Promise<undefined> */ thisPromiseReturnsNothingButParameterIsStillUseful = ...;
+const /** !Object<string, *> */ mapOfEverything = {};
+
+ +

Cases when template parameters should not be used:

+ +
    +
  • Object is used for type hierarchy and not as map-like structure.
    • +
+ +

7.11 Visibility annotations

+ +

Visibility annotations (@private, @package, @protected) may be specified +in a @fileoverview 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 @private names must end with an underscore.

+ +

8 Policies

+ +

8.1 Issues unspecified by Google Style: Be Consistent!

+ +

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.

+ +

8.2 Compiler warnings

+ +

8.2.1 Use a standard warning set

+ +

+As far as possible projects should use --warning_level=VERBOSE. +

+ +

8.2.2 How to handle a warning

+ +

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

+ +

Once you understand the warning, attempt the following solutions in order:

+ +
    +
  1. First, fix it or work around it. Make a strong attempt to actually +address the warning, or find another way to accomplish the task that avoids +the situation entirely.
    2. +
  2. Otherwise, determine if it's a false alarm. 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 @suppress +annotation.
    3. +
  3. Otherwise, leave a TODO comment. This is a last resort. If you do +this, do not suppress the warning. The warning should be visible until +it can be taken care of properly.
    4. +
+ +

8.2.3 Suppress a warning at the narrowest reasonable scope

+ +

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.

+ +

Example

+ +
/** @suppress {uselessCode} Unrecognized 'use asm' declaration */
+function fn() {
+  'use asm';
+  return 0;
+}
+
+ +

Even a large number of suppressions in a class is still better than blinding the +entire class to this type of warning.

+ +

8.3 Deprecation

+ +

Mark deprecated methods, classes or interfaces with @deprecated annotations. A +deprecation comment must include simple, clear directions for people to fix +their call sites.

+ +

8.4 Code not in Google Style

+ +

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.

+ +

8.4.1 Reformatting existing code

+ +

When updating the style of existing code, follow these guidelines.

+ +
    +
  1. 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.
    2. +
  2. 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.
    3. +
+ +

8.4.2 Newly added code: use Google Style

+ +

Brand new files use Google Style, regardless of the style choices of other files +in the same package.

+ +

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 +??.

+ +

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.

+ +

8.5 Local style rules

+ +

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.

+ +

8.6 Generated code: mostly exempt

+ +

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.

+ +

9 Appendices

+ +

9.1 JSDoc tag reference

+ +

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.

+ +

9.1.1 Type annotations and other Closure Compiler annotations

+ +

Documentation for JSDoc used by the Closure Compiler is described in +Annotating JavaScript for the Closure Compiler and Types in the Closure Type +System.

+ +

9.1.2 Documentation annotations

+ +

In addition to the JSDoc described in Annotating JavaScript for the Closure +Compiler the following tags are common and well supported by various +documentation generations tools (such as JsDossier) for purely documentation +purposes. + + + + + + + + + + +
Tag + Template & Examples + Description +
@author or @owner + @author username@google.com (First Last) +

For example: + 

+/**
+ * @fileoverview Utilities for handling textareas.
+ * @author kuth@google.com (Uthur Pendragon)
+ */
+
+ 		Document the author of a file or the owner of a test, generally only + used in the @fileoverview comment. The @owner tag is used by the + unit test dashboard to determine who owns the test results. +

Not recommended. +

@bug + @bug bugnumber +

For example: + 

+/** @bug 1234567 */
+function testSomething() {
+  // …
+}
+
+
/**
+ * @bug 1234568
+ * @bug 1234569
+ */
+function testTwoBugs() {
+  // …
+}
+
+ 		Indicates what bugs the given test function regression tests. +

Multiple bugs should each have their own @bug line, to make + searching for regression tests as easy as possible. +

@code + {@code ...} +

For example: + 

+/**
+ * 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() {
+  // …
+};
+
+ 		Indicates that a term in a JSDoc description is code so it may be + correctly formatted in generated documentation. +
@see + @see Link +

For example: + 

+/**
+ * Adds a single item, recklessly.
+ * @see #addSafely
+ * @see goog.Collect
+ * @see goog.RecklessAdder#add
+ */
+
+ 		Reference a lookup to another class function or method. +
@supported + @supported Description +

For example: + 

+/**
+ * @fileoverview Event Manager
+ * Provides an abstracted interface to the
+ * browsers' event systems.
+ * @supported IE10+, Chrome, Safari
+ */
+
+ 		Used in a fileoverview to indicate what browsers are supported by + the file. +
@desc + @desc Message description +

For example: + 

+/** @desc Notifying a user that their account has been created. */
+exports.MSG_ACCOUNT_CREATED = goog.getMsg(
+    'Your account has been successfully created.');
+
+

+ +

You may also see other types of JSDoc annotations in third-party code. These +annotations appear in the JSDoc Toolkit Tag Reference but are not considered +part of valid Google style.

+ +

9.1.3 Framework specific annotations

+ +

The following annotations are specific to a particular framework. + + + + + + +
Framework + Tag + Documentation +
Angular 1 + @ngInject +
Polymer + @polymerBehavior + + + https://github.com/google/closure-compiler/wiki/Polymer-Pass + +

+ +

9.1.4 Notes about standard Closure Compiler annotations

+ +

The following tags used to be standard but are now deprecated. + + + + + + +
Tag + Template & Examples + Description +
@expose + @expose + Deprecated. Do not use. Use @export and/or @nocollapse + instead. +
@inheritDoc + @inheritDoc + Deprecated. Do not use. Use @override instead. +

+ +

9.2 Commonly misunderstood style rules

+ +

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

+ +
    +
  • Neither a copyright statement nor @author credit is required in a source +file. (Neither is explicitly recommended, either.)
    • +
  • Aside from the constructor coming first +(??), there is no hard and fast rule +governing how to order the members of a class (??).
    • +
  • Empty blocks can usually be represented concisely as {}, as detailed in +(??).
    • +
  • The prime directive of line-wrapping is: prefer to break at a higher +syntactic level (??).
    • +
  • 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 (??).
    • +
+ + + +

The following tools exist to support various aspects of Google Style.

+ +

9.3.1 Closure Compiler

+ +

This program performs type checking and other checks, +optimizations and other transformations (such as ECMAScript 6 to ECMAScript 5 +code lowering).

+ +

9.3.2 clang-format

+ +

This program reformats +JavaScript source code into Google Style, and also follows a number of +non-required but frequently readability-enhancing formatting practices.

+ +

clang-format 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.

+ +

9.3.3 Closure compiler linter

+ +

This program checks for a +variety of missteps and anti-patterns. +

+ +

9.3.4 Conformance framework

+ +

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

+ +

These rules are commonly used to enforce critical restrictions (such as defining +globals, which could break the codebase) and security patterns (such as using +eval or assigning to innerHTML), or more loosely to improve code quality.

+ +

For additional information see the official documentation for the +JS Conformance Framework.

+ +

9.4 Exceptions for legacy platforms

+ +

9.4.1 Overview

+ +

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:

+ +
    +
  • Use of var declarations is allowed
    • +
  • Use of arguments is allowed
    • +
  • Optional parameters without default values are allowed
    • +
+ +

9.4.2 Use var

+ +
9.4.2.1 var declarations are NOT block-scoped
+ +

var 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 var declarations inside of loops. The +following code gives an example:

+ +
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.
+
+
+ +
9.4.2.2 Declare variables as close as possible to first use
+ +

Even though var declarations are scoped to the beginning of the enclosing +function, var declarations should be as close as possible to their first use, +for readability purposes. However, do not put a var declaration inside a block +if that variable is referenced outside the block. For example:

+ +
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');
+}
+
+ +
9.4.2.3 Use @const for constants variables
+ +

For global declarations where the const keyword would be used, if it were +available, annotate the var declaration with @const instead (this is optional +for local variables).

+ +

9.4.3 Do not use block scoped functions declarations

+ +

Do not do this:

+ +
if (x) {
+  function foo() {}
+}
+
+ +

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.

+ +

To get consistent behavior, instead use a var initialized with a function +expression to define a function within a block:

+ +
if (x) {
+  var foo = function() {};
+}
+
+ +

9.4.4 Dependency management with goog.provide/goog.require

+ +

goog.provide is deprecated. All new files should use goog.module, even in +projects with existing goog.provide usage. The following rules are for +pre-existing goog.provide files, only.

+ +
9.4.4.1 Summary
+ +
    +
  • Place all goog.provides first, goog.requires second. Separate provides +from requires with an empty line.
    • +
  • Sort the entries alphabetically (uppercase first).
    • +
  • Don't wrap goog.provide and goog.require statements. Exceed 80 columns +if necessary.
    • +
  • Only provide top-level symbols.
    • +
+ +

As of Oct 2016, goog.provide/goog.require dependency management is +deprecated. All new files, even in projects using goog.provide for older +files, should use +goog.module.

+ +

goog.provide statements should be grouped together and placed first. All +goog.require statements should follow. The two lists should be separated with +an empty line.

+ +

Similar to import statements in other languages, goog.provide and +goog.require statements should be written in a single line, even if they +exceed the 80 column line length limit.

+ +

The lines should be sorted alphabetically, with uppercase letters coming first:

+ +
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');
+
+
+ +

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

+ +

Do this:

+ +
goog.provide('namespace.MyClass');
+
+ +

Not this:

+ +
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');
+
+ +

Members on namespaces may also be provided:

+ +
goog.provide('foo.bar');
+goog.provide('foo.bar.CONSTANT');
+goog.provide('foo.bar.method');
+
+ +
9.4.4.2 Aliasing with goog.scope
+ +

goog.scope is deprecated. New files should not use goog.scope even in +projects with existing goog.scope usage.

+ +

goog.scope may be used to shorten references to namespaced symbols in +code using goog.provide/goog.require dependency management.

+ +

Only one goog.scope invocation may be added per file. Always place it in +the global scope.

+ +

The opening goog.scope(function() { invocation must be preceded by exactly one +blank line and follow any goog.provide statements, goog.require statements, +or top-level comments. The invocation must be closed on the last line in the +file. Append // goog.scope to the closing statement of the scope. Separate the +comment from the semicolon by two spaces.

+ +

Similar to C++ namespaces, do not indent under goog.scope declarations. +Instead, continue from the 0 column.

+ +

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

+ +
goog.scope(function() {
+var Button = goog.ui.Button;
+
+Button = function() { ... };
+...
+
+ +

Names must be the same as the last property of the global that they are aliasing.

+ +
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
+
+ +
+ + diff --git a/jsoncstyleguide.html b/jsoncstyleguide.html new file mode 100644 index 0000000..1bef466 --- /dev/null +++ b/jsoncstyleguide.html @@ -0,0 +1,18 @@ + + + + + + + Redirecting + + + + Redirecting you to jsoncstyleguide.xml. + + diff --git a/jsoncstyleguide.xml b/jsoncstyleguide.xml new file mode 100644 index 0000000..3a2ac25 --- /dev/null +++ b/jsoncstyleguide.xml @@ -0,0 +1,1187 @@ + + + + +

+Revision 0.9 +

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

Hooray! Now you know you can expand points to get more details. Alternatively, there's an "expand all" at the top of this document.

+ + + + +

This style guide documents guidelines and recommendations for building JSON APIs at Google. In general, JSON APIs should follow the spec found at JSON.org. 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.

+ + +

For the purposes of this style guide, we define the following terms:

  • property - a name/value pair inside a JSON object.
  • property name - the name (or key) portion of the property.
  • property value - the value portion of the property.
+ +{ + // The name/value pair together is a "property". + "propertyName": "propertyValue" +} + + +

Javascript's number type encompasses all floating-point numbers, which is a broad designation. In this guide, number will refer to JavaScript's number type, while integer will refer to integers.

+ + + + + +No comments in JSON objects. + + +

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.

+ +{ + // You may see comments in the examples below, + // But don't include comments in your JSON. + "propertyName": "propertyValue" +} + + + + + + +Use double quotes. + + +

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.

+ + + + +Data should not be arbitrarily grouped for convenience. + + +

Data elements should be "flattened" in the JSON representation. Data should not be arbitrarily grouped for convenience.

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:

+

Flattened Address:

+ +{ + "company": "Google", + "website": "https://www.google.com/", + "addressLine1": "111 8th Ave", + "addressLine2": "4th Floor", + "state": "NY", + "city": "New York", + "zip": "10011" +} + +

Structured Address:

+ +{ + "company": "Google", + "website": "https://www.google.com/", + "address": { + "line1": "111 8th Ave", + "line2": "4th Floor", + "state": "NY", + "city": "New York", + "zip": "10011" + } +} + + + + + + + +Choose meaningful property names. + + +

Property names must conform to the following guidelines:

  • Property names should be meaningful names with defined semantics.
  • Property names must be camel-cased, ascii strings.
  • The first character must be a letter, an underscore (_) or a dollar sign ($).
  • Subsequent characters can be a letter, a digit, an underscore, or a dollar sign.
  • Reserved JavaScript keywords should be avoided (A list of reserved JavaScript keywords can be found below).

These guidelines mirror the guidelines for naming JavaScript identifiers. This allows JavaScript clients to access properties using dot notation. (for example, result.thisIsAnInstanceVariable). Here's an example of an object with one property:

+ +{ + "thisPropertyIsAnIdentifier": "identifier value" +} + + + + + + +JSON maps can use any Unicode character in key names. + + +

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.

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, result.thumbnails["72"]).

+ +{ + // 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" + } +} + + + + + + +Certain property names are reserved for consistent use across services. + + +

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.

+ + + + +Array types should have plural property names. All other property names should be singular. + + +

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 items property name is plural because it represents an array of item objects. Most of the other fields are singular.

There may be exceptions to this, especially when referring to numeric property values. For example, in the reserved names, totalItems makes more sense than totalItem. However, technically, this is not violating the style guide, since totalItems can be viewed as totalOfItems, where total is singular (as per the style guide), and OfItems serves to qualify the total. The field name could also be changed to itemCount to look singular.

+ +{ + // 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, +} + + + + + + +Avoid naming conflicts by choosing a new property name or versioning the API. + + +

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:

+ +{ + "apiVersion": "1.0", + "data": { + "recipeName": "pizza", + "ingredients": ["tomatoes", "cheese", "sausage"] + } +} + + +

If in the future we wish to make ingredients a reserved word, we can do one of two things:

1) Choose a different name:

+ +{ + "apiVersion": "1.0", + "data": { + "recipeName": "pizza", + "ingredientsData": "Some new property", + "ingredients": ["tomatoes", "cheese", "sausage"] + } +} + + +

2) Rename the property on a major version boundary:

+ +{ + "apiVersion": "2.0", + "data": { + "recipeName": "pizza", + "ingredients": "Some new property", + "recipeIngredients": ["tomatos", "cheese", "sausage"] + } +} + + + + + + + + +Property values must be Unicode booleans, numbers, strings, objects, arrays, or null. + + +

The spec at JSON.org specifies exactly what type of data is allowed in a property value. This includes Unicode booleans, numbers, strings, objects, arrays, and null. 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.).

Good:

+ +{ + "canPigsFly": null, // null + "areWeThereYet": false, // boolean + "answerToLife": 42, // number + "name": "Bart", // string + "moreData": {}, // object + "things": [] // array +} + + +

Bad:

+ +{ + "aVariableName": aVariableName, // Bad - JavaScript identifier + "functionFoo": function() { return 1; } // Bad - JavaScript function +} + + + + + + +Consider removing empty or null values. + + +

If a property is optional or has an empty or null value, consider dropping the property from the JSON, unless there's a strong semantic reason for its existence.

+ +{ + "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 +} + + + + + + +Enum values should be represented as strings. + + +

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.

Java code:

+ +public enum Color { + WHITE, + BLACK, + RED, + YELLOW, + BLUE +} + + +

JSON object:

+ +{ + "color": "WHITE" +} + + + + + + +

As mentioned above, property value types must be booleans, numbers, strings, objects, arrays, or null. 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.

+ + +Dates should be formatted as recommended by RFC 3339. + + +

Dates should be strings formatted as recommended by RFC 3339

+ +{ + "lastUpdate": "2007-11-06T16:34:41.000Z" +} + + + + + + +Time durations should be formatted as recommended by ISO 8601. + + +

Time duration values should be strings formatted as recommended by ISO 8601.

+ +{ + // three years, six months, four days, twelve hours, + // thirty minutes, and five seconds + "duration": "P3Y6M4DT12H30M5S" +} + + + + + + +Latitudes/Longitudes should be formatted as recommended by ISO 6709. + + +

Latitude/Longitude should be strings formatted as recommended by ISO 6709. Furthermore, they should favor the ±DD.DDDD±DDD.DDDD degrees format.

+ +{ + // The latitude/longitude location of the statue of liberty. + "statueOfLiberty": "+40.6894-074.0447" +} + + + + + + +

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 Orderly format (which in turn can be compiled into a JSONSchema). You can few examples of the JSON structure at the end of this guide.

+ +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?; +}*; + + +

The JSON object has a few top-level properties, followed by either a data object or an error object, but not both. An explanation of each of these properties can be found below.

+ + +

The top-level of the JSON object may contain the following properties.

+ + +Property Value Type: string
Parent: - + + +

Represents the desired version of the service API in a request, and the version of the service API that's served in the response. apiVersion 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.

Example:

+ +{ "apiVersion": "2.1" } + + + + + + +Property Value Type: string
Parent: - + + +

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 context to correlate responses with requests. This property is a top-level property because the context should present regardless of whether the response was successful or an error. context differs from id in that context is specified by the user while id is assigned by the service.

Example:

Request #1:

+ +https://www.google.com/myapi?context=bart + + +

Request #2:

+ +https://www.google.com/myapi?context=lisa + + +

Response #1:

+ +{ + "context": "bart", + "data": { + "items": [] + } +} + + +

Response #2:

+ +{ + "context": "lisa", + "data": { + "items": [] + } +} + + +

Common JavaScript handler code to process both responses:

+ +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. + } +} + + + + + + +Property Value Type: string
Parent: - + + +

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.

Example:

+ +{ "id": "1" } + + + + + + +Property Value Type: string
Parent: - + + +

Represents the operation to perform, or that was performed, on the data. In the case of a JSON request, the method property can be used to indicate which operation to perform on the data. In the case of a JSON response, the method property can indicate the operation performed on the data.

One example of this is in JSON-RPC requests, where method indicates the operation to perform on the params property:

+ +{ + "method": "people.get", + "params": { + "userId": "@me", + "groupId": "@self" + } +} + + + + + + +Property Value Type: object
Parent: - + + +

This object serves as a map of input parameters to send to an RPC request. It can be used in conjunction with the method property to execute an RPC function. If an RPC function does not need parameters, this property can be omitted.

Example:

+ +{ + "method": "people.get", + "params": { + "userId": "@me", + "groupId": "@self" + } +} + + + + + + +Property Value Type: object
Parent: - + + +

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 data object or an error object, but not both. If both data and error are present, the error object takes precedence.

+ + + + +Property Value Type: object
Parent: - + + +

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 data object or an error object, but not both. If both data and error are present, the error object takes precedence.

Example:

+ +{ + "apiVersion": "2.0", + "error": { + "code": 404, + "message": "File Not Found", + "errors": [{ + "domain": "Calendar", + "reason": "ResourceNotFoundException", + "message": "File Not Found + }] + } +} + + + + + + +

The data property of the JSON object may contain the following properties.

+ + +Property Value Type: string
Parent: data + + +

The kind property serves as a guide to what type of information this particular object stores. It can be present at the data level, or at the items level, or in any object where its helpful to distinguish between various types of objects. If the kind object is present, it should be the first property in the object (See the "Property Ordering" section below for more details).

Example:

+ +// "Kind" indicates an "album" in the Picasa API. +{"data": {"kind": "album"}} + + + + + + +Property Value Type: string
Parent: data + + +

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.

Example:

+ +{ + "data": { + "kind": "user", + "fields": "author,id", + "id": "bart", + "author": "Bart" + } +} + + + + + + +Property Value Type: string
Parent: data + + +

Represents the etag for the response. Details about ETags in the GData APIs can be found here: https://code.google.com/apis/gdata/docs/2.0/reference.html#ResourceVersioning

Example:

+ +{"data": {"etag": "W/"C0QBRXcycSp7ImA9WxRVFUk.""}} + + + + + + +Property Value Type: string
Parent: data + + +

A globally unique string used to reference the object. The specific details of the id property are left up to the service.

Example:

+ +{"data": {"id": "12345"}} + + + + + + +Property Value Type: string (formatted as specified in BCP 47)
Parent: data (or any child element) + + +

Indicates the language of the rest of the properties in this object. This property mimics HTML's lang property and XML's xml:lang properties. The value should be a language value as defined in BCP 47. If a single JSON object contains data in multiple languages, the service is responsible for developing and documenting an appropriate location for the lang property.

Example:

+ +{"data": { + "items": [ + { "lang": "en", + "title": "Hello world!" }, + { "lang": "fr", + "title": "Bonjour monde!" } + ]} +} + + + + + +Property Value Type: string (formatted as specified in RFC 3339)
Parent: data + + +

Indicates the last date/time (RFC 3339) the item was updated, as defined by the service.

Example:

+ +{"data": {"updated": "2007-11-06T16:34:41.000Z"}} + + + + + + +Property Value Type: boolean
Parent: data (or any child element) + + +

A marker element, that, when present, indicates the containing entry is deleted. If deleted is present, its value must be true; a value of false can cause confusion and should be avoided.

Example:

+ +{"data": { + "items": [ + { "title": "A deleted entry", + "deleted": true + } + ]} +} + + + + + + +Property Value Type: array
Parent: data + + +

The property name items 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 items array. If items exists, it should be the last property in the data object (See the "Property Ordering" section below for more details).

Example:

+ +{ + "data": { + "items": [ + { /* Object #1 */ }, + { /* Object #2 */ }, + ... + ] + } +} + + + + + + +

The following properties are located in the data object, and help page through a list of items. Some of the language and concepts are borrowed from the OpenSearch specification.

The paging properties below allow for various styles of paging, including:

  • Previous/Next paging - Allows user's to move forward and backward through a list, one page at a time. The nextLink and previousLink properties (described in the "Reserved Property Names for Links" section below) are used for this style of paging.
  • 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 ?startIndex=200.
  • 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 ?page=1 or ?page=20. The pageIndex and totalPages properties are used for this style of paging.

An example of how to use these properties to implement paging can be found at the end of this guide.

+ + +Property Value Type: integer
Parent: data + + +

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 itemsPerPage and currentItemCount will equal "10". The next page of items will have the remaining 4 items; itemsPerPage will still be "10", but currentItemCount will be "4".

Example:

+ +{ + "data": { + // "itemsPerPage" does not necessarily match "currentItemCount" + "itemsPerPage": 10, + "currentItemCount": 4 + } +} + + + + + + +Property Value Type: integer
Parent: data + + +

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 itemsPerPage. However the size of data.items should not exceed itemsPerPage.

Example:

+ +{ + "data": { + "itemsPerPage": 10 + } +} + + + + + + +Property Value Type: integer
Parent: data + + +

The index of the first item in data.items. For consistency, startIndex should be 1-based. For example, the first item in the first set of items should have a startIndex of 1. If the user requests the next set of data, the startIndex may be 10.

Example:

+ +{ + "data": { + "startIndex": 1 + } +} + + + + + + +Property Value Type: integer
Parent: data + + +

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 totalItems would be 100.

Example:

+ +{ + "data": { + "totalItems": 100 + } +} + + + + + + +Property Value Type: string
Parent: data + + +

A URI template indicating how users can calculate subsequent paging links. The URI template also has some reserved variable names: {index} representing the item number to load, and {pageIndex}, representing the page number to load.

Example:

+ +{ + "data": { + "pagingLinkTemplate": "https://www.google.com/search/hl=en&q=chicago+style+pizza&start={index}&sa=N" + } +} + + + + + + +Property Value Type: integer
Parent: data + + +

The index of the current page of items. For consistency, pageIndex should be 1-based. For example, the first page of items has a pageIndex of 1. pageIndex can also be calculated from the item-based paging properties: pageIndex = floor(startIndex / itemsPerPage) + 1.

Example:

+ +{ + "data": { + "pageIndex": 1 + } +} + + + + + + +Property Value Type: integer
Parent: data + + +

The total number of pages in the result set. totalPages can also be calculated from the item-based paging properties above: totalPages = ceiling(totalItems / itemsPerPage).

Example:

+ +{ + "data": { + "totalPages": 50 + } +} + + + + + + +

The following properties are located in the data 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").

+ + +Property Value Type: object / string
Parent: data + + +

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 items array could contain a selfLink that can be used to retrieve data related to that particular album.

Example:

+ +{ + "data": { + "self": { }, + "selfLink": "https://www.google.com/feeds/album/1234" + } +} + + + + + + +Property Value Type: object / string
Parent: data + + +

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.

Example:

+ +{ + "data": { + "edit": { }, + "editLink": "https://www.google.com/feeds/album/1234/edit" + } +} + + + + + + +Property Value Type: object / string
Parent: data + + +

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 itemsPerPage, startIndex and totalItems properties in order to page through data.

Example:

+ +{ + "data": { + "next": { }, + "nextLink": "https://www.google.com/feeds/album/1234/next" + } +} + + + + + + +Property Value Type: object / string
Parent: data + + +

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 itemsPerPage, startIndex and totalItems properties in order to page through data.

Example:

+ +{ + "data": { + "previous": { }, + "previousLink": "https://www.google.com/feeds/album/1234/next" + } +} + + + + + + +

The error property of the JSON object may contain the following properties.

+ + +Property Value Type: integer
Parent: error + + +

Represents the code for this error. This property value will usually represent the HTTP response code. If there are multiple errors, code will be the error code for the first error.

Example:

+ +{ + "error":{ + "code": 404 + } +} + + + + + + +Property Value Type: string
Parent: error + + +

A human readable message providing more details about the error. If there are multiple errors, message will be the message for the first error.

Example:

+ +{ + "error":{ + "message": "File Not Found" + } +} + + + + + + +Property Value Type: array
Parent: error + + +

Container for any additional information regarding the error. If the service returns multiple errors, each element in the errors array represents a different error.

Example:

+ +{ "error": { "errors": [] } } + + + + + + +Property Value Type: string
Parent: error.errors + + +

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

Example:

+ +{ + "error":{ + "errors": [{"domain": "Calendar"}] + } +} + + + + + + +Property Value Type: string
Parent: error.errors + + +

Unique identifier for this error. Different from the error.code property in that this is not an http response code.

Example:

+ +{ + "error":{ + "errors": [{"reason": "ResourceNotFoundException"}] + } +} + + + + + + +Property Value Type: string
Parent: error.errors + + +

A human readable message providing more details about the error. If there is only one error, this field will match error.message.

Example:

+ +{ + "error":{ + "code": 404 + "message": "File Not Found", + "errors": [{"message": "File Not Found"}] + } +} + + + + + + +Property Value Type: string
Parent: error.errors + + +

The location of the error (the interpretation of its value depends on locationType).

Example:

+ +{ + "error":{ + "errors": [{"location": ""}] + } +} + + + + + + +Property Value Type: string
Parent: error.errors + + +

Indicates how the location property should be interpreted.

Example:

+ +{ + "error":{ + "errors": [{"locationType": ""}] + } +} + + + + + + +Property Value Type: string
Parent: error.errors + + +

A URI for a help text that might shed some more light on the error.

Example:

+ +{ + "error":{ + "errors": [{"extendedHelper": "http://url.to.more.details.example.com/"}] + } +} + + + + + + +Property Value Type: string
Parent: error.errors + + +

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.

Example:

+ +{ + "error":{ + "errors": [{"sendReport": "https://report.example.com/"}] + } +} + + + + + + +

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.

+ + +kind should be the first property + + +

Suppose a parser is responsible for parsing a raw JSON stream into a specific object. The kind 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 kind property (usually found in the data and items properties).

+ + + + +items should be the last property in the data object + + +

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.

+ + + + + +// 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" + } + ] + } +} + + + + + + + + +Here's an example of the YouTube JSON API's response object. You can learn more about YouTube's JSON API here: https://code.google.com/apis/youtube/2.0/developers_guide_jsonc.html. + + + +{ + "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 + } + ] + } +} + + + + + + +This example demonstrates how the Google search items could be represented as a JSON object, with special attention to the paging variables. + + +

This sample is for illustrative purposes only. The API below does not actually exist.

Here's a sample Google search results page:

Here's a sample JSON representation of this page:

+ +{ + "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 + ] + } +} + + +

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

  • Results 11 - 20 of about 2,700,000 = startIndex
  • Results 11 - 20 of about 2,700,000 = startIndex + currentItemCount - 1
  • Results 11 - 20 of about 2,700,000 = totalItems
  • Search results = items (formatted appropriately)
  • Previous/Next = previousLink / nextLink
  • Numbered links in "Gooooooooooogle" = 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:
    • Index #1 = 0 * itemsPerPage = 0
    • Index #2 = 2 * itemsPerPage = 10
    • Index #3 = 3 * itemsPerPage = 20
    • Index #N = N * itemsPerPage
+ + + + + + +A list of reserved JavaScript words that should be avoided in property names. + + +

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.

From the ECMAScript Language Specification 5th Edition

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

+Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. +

+

+Revision 0.9 +

+ +
+
+ + diff --git a/jsoncstyleguide_example_01.png b/jsoncstyleguide_example_01.png new file mode 100644 index 0000000000000000000000000000000000000000..d7a86ee5502a516cc0f45cd92d74e1b464694560 GIT binary patch literal 319109 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 z zl*(@u2nfKWPsD%|j`kMJEOR`|FN^!n9E?fv80_3}GCO9HHSq|J?l`Cc!s*oTD{A%Z zi+k{1X8z$%_~W$zXcJ;lyLe(JqMY;-GLVx^UI`zc(7E4t%v-menuT0314Lvfqm=Tc z@UMK(6A~6jKEK>)rAbI=IQjhjGORb-Vq3kR;UBQ~%!{i%Tt2#)i_s04@>Q`+8mNsN zGt*B?O=Zw&WHtzAH0au<%`RO=zcVg-`dMUV9+b4YpO#i;A*TjbR_!aJGG+EXr?SZ| zzJ-2va?MFP+i#YTRh+E&`?t}nG)V6Mv|eQgH2NRCO8w0e{@3f(|8Rem6dOYQZyqsq zSY=Ey+<0Rom$#>aa3E50f5CpSPYf(1L$nX-9=zv;OzJY+rXjICAjKN?; z76eR2gBce~0()oF7|mdJ5-LY$RG2Urj6fc~`}Rxj{I!>h5rsK^Lh-3dk_kH}SCEWW z15c5YVt5OJpwx+3b^sR+@1}aY{?sh&W;Lz^vvFlI8j)p%u2McQnM}yCU@bF%(In!V z%M+8N>_W8Et;s0in>&}a?gg;QNR}0yu*guU78CB?d2kRFU8r2QEmOWK2G+(aDY8Pw zXfPnlHgXh%9L;PjdYaX9PSWNiO-|xu)ahiEM|OkSr{tYo_#7IU@t4s6@;Q9Sa>kp_ z{~h|k|L9fD!hiJY^J#o4o&S}3B`8h~wWvZZfJzjwQ-htD^ZL!mz{@J6jrYk&?zW6s zerLq&rzmJ<3<{zOm0)>Rj@qk4i;<&3ZCiLjK&4h$pFRCcv2elSRCEPVREB<0rQF7D zzDh)}Jln)osZwZxV6{|jc~pSkK$cU`-)-XwqKH})t;UrsW2I}AwK=ZZ%)3g=DE}1x z?QCH9Wm!h0R+}3z*x9Mg?<})L0kv98nOO(|Y9VD!UY2EQv>U+gb^}t?fgp&eRB4n; zmXQU~dS!?ps?5mu3O{X!&Zez}PeH)eBV^%GK}jZ+93)w=mRW6%XJ!JGN=%iWRP zBv7kV=Jcv`dLzp+&R&XZ9;;3YX0&%usnvjtXd~}WZBzi_Kpnq13F&9MC_LGOjPgr0 zYfLk{vrUr~uNk%LoOYDi&C)IOQ{rV$`*UX0smr1ONrH0R`ty1kQndryGJHz-oB`*b z)T^A(`<(p#tMw|o?^zAN|4PV8ul}jL{-amfr}^*DD_I6Xr6BX$se}|HceOIkT5yfB zqW!65Oshwqe2Orq15i#C+4g;kdrc9rWc4aZSO#oKmaGdpCiC5in6D#H22cyYrL0_U zV3UU=n=l#;2qq1O&u&34h!`c4GT6z=l?Nu-WK%XXJ@dd}$xoIgOtMMI)7+4hYYmh# zzYD#=M{N?%?)=8B&?p29HdkgSX)PYJSMM$nX^^>heFG1ok`PcZyu#j|snSSR z<&-d*^ONM%1F$5UFq%D2AS0Q}WNGk{^_mF9!)20;SgP^z#f4lC)2FK=OTCCf5{vh( z#V82Ka*7x5b;wmh5)3Iaw&X9TSNTBcN!3QKvVl=5oh?lF7UGK_+N z!Dv7b1m3(kz@#1PtTK?&=!f!bK}NHDmyjfrxh}{+uPlA zP!E6p8{6-^umbGnB&3}jX4FTeb@AtjcmO(!S)IP8PU9SWWJvY!Rqa@4DLol9C}#=qKS}*TNq?8$O>%)0Z}%h z(d*1SiRL^lmpBTj1dHcHMx)c1`A|G5I(?k7SqnIQdo?#BV~CBqK%z+`Sr==?+!93r zO>(T2_k-7d=4pbCsPHo+nMAZY4FKANM})+`Q_=_~H2Op<4M7k|(kV17`^qdH8WjeT z43;toh=Ku)UTal8m8c>~ACD-A2y!w8^I!{b=H+op`C8Cr(g#EMIb!WpsDUJ1EGDxT zVc(I_JWEoXp(k{yJllmFA)?Rk;=!3y3zltbBX=;TVr&6P5ZGBqTZI-cVUqCOpcOP9lySwC4xfB_h|>A}z`P|OyO7ZUm6Jg}C;io@ zc>S}=|5FFRv~e=yBP+T&EyJgV&s|cIi>p_z54gjD?t!2Y7IyxiDZKb zjn+tfvI$MHOoA44`jm0+pXSjvd@@V}q_4P)mMpSMo9>(z4}R zR1Zh9Cae-GJGEo*#&xXh-hnY&CgYwcZW2BXV4Giv8_{9Ijd&)=1am5R|}?HtM#c0`graC6AT%lBvaw(lLPIbY$O>li$h zN=#EviqGcyyI0f=sKeRIOF91W8By;-=+$Hv50gWPxpjbYHFEL&{vYskbtQk{9*n8o zlyNKS;O1AIpztJS_Wzwy?h0KyyTZJ9-Hb`Qx)K%d!7sfhGU2zMSv!0sAwhfC@-&w3 z+YSRnqJs}H>+j>Zs9)k*Z~{&3UUC235duR;^6<_??!_jPpfxhT=T_GK-iznSzPO8b zs9$>xJpw9OOX1@f%F-i)@sYzQ8!(eG4QeoELuc%re26yXW@E4U^!>R#UjAi}lAqz@ z(Tw2Gt<|FDZC>G-94x{O`v@-<@mcWqwo?Pzr2ztMjc1=&wu}~zV zcFd-buLtjw^RvG95~giyg~`s7z?b`&Uw;oD9U@|IBRP^n{ksyL3bm zE7%dNul=?6-n+iaYwz{7i-L-ZBKCqJMWl+-2_+#tAw8Q-**fL-$7YkwWM+30c-!yI zd7gcC%DLy9d+zt1d+wdxJF`~(Mw-n{|B|d3>$fsQ&f%x+Rh&EJX#O_$D3%xQz+@l7M>nr#)vBABy?!YUOD&h5 zwwCFAn)vIhlQAWqfRjr8GV@DLO3vew53Z%Sv5-k)pJUDicZHHULBP|nn_Fj}gPdTe zQX0jq!%k$4kU;jLv)Qw16iV;OJbT7H{Qb@T3_EfqsdhU~TQZHM-!Nm&ZHOitmmL2I zS52AJ>iefYn#ne|nX<~|r1!squdaTD4cop!O*xEtFC0pq*q@-3&)5+!VXu3ERW)WD z(oP19dWzGMmU7qHEu@PcE;?>5mrps6Elra+r)Lt9EMty%oQ>MHYrl4q*A?o@NsxmCI3?ODmV;bWP% z;z>?9?OmR~Xc3w6I@XqKK}b24$1nVpTZh?LULtYUq}#Y)>P1M+Rg698d7iyu8A-M4 zDEFmt_EFb!-sBrdk(ZO_>%l4GZsD?H&ZeoMni5@(Z@cCH%5!Hhbi;ym`^*TzdG4)ca~%efj#zcewrH?|Jo#W&CAe7IS}inT!AO zJuh7T9Ta@XPkZthGx11XzW7_bzFpjO?n^v)>{V>8*v!^lt2t@RaKevU!;fe~j~PSl zl2@>uky(@2R`LxQDTi^zi8nB1%w&$qn8dZmpT+#2W-<7HOStr~3;BN8gXC0Ikk*IpZH3ob2b@9l!F$k~?0G>YdE`q74KZi^xnCu@m|&U$8ls6+6D-x7~}7BND4d-{4op&AAp0<$s zt*7x_^)QYdGKN05cy#GI%sqDj*UcTz@If;fbKv!4|8^wX(w^p${xw|t!#qwLJ3S;& z@gj(!cQe_|36$5AGB~3@HXw+F1d9c~B4W1-)FN}q#G5!|!nNeDo6c(6U0grX%++7N z#Bt+J!5ft5k(dI2)9S$E_cJkTH~^wK5t|52ejlP}Ly{E^>^A_YC(+T9ypnI3zxf;L z{7s}L48|&|H2Zzwr)Oj)hir73O~|SWs*I$X$Vdq7;O?|o@yZ?&>@DZEbObg0J2Y@f z3K@wZ4>o%039437EujrNlO0I}WE(vlBSL<#P9a@@#$bRX!OyxX3!}0|5_)tbwmc>Z z{XjqTD5#lDjXs7Zz&X?2=cqxMtlRiLbN^V1BA76lKvEJ(bBff0KU~2Y{|THpIDy^eyU5?WiQXe_ z=5HsRO-1<<9$D}(^#K`4RY37#xAr5bl+kP8xtu>{96`B1DGtDF!)dY5(6pC=svN4C z>JUv}6@h?+!>NAAy{q!fbQCL9(!!JtHnBMrB|f~iyf z#=$)-SWV*r2&lv8pJ=Df=Ox*mM)vmEEZX%4&8nXiM=EAf#b$Q2U?ve1KZqg;c7 zldF!p6>n1s`BgcT)Voj>uv?QsNXFezjw|5D>de9k*vxipCNlyiEG83*62xY4Vj=V! zLAR@fcNbsFpEV8i?LCP^lNp=cK~NC@OK723RSC)gQWGHQaCIK9R4O{=eaD;6aSAKXZlc!va6;K5eAYd_h@CS;J9V5By zkOz^Pawx3MrL4XTlV~Hw(FZV-WJ@F{`!S0)?6xF!Y<`l5*01O5+qW}3)xwrP?&kj0 zYx(fTd=5-E@#4ZO$acHvnUp}Hvo}R$n{j5I(Gn{__PZ#m&ZVTbAnHFrqs6XpQnoLv z6WT{jotYtP%V~dCqIX~KkxZM7~!vZRsxu)ISiUPtAR3z;zN7&dI|Nk*Tu0GKkc2VbmInKXJj?m3MdKYAiyqMxaT z^g$CjQd-Y!lZ{EeoIE-2Z`^tD6HFUa!Ho;<#Nt}c)FYlH;19h%L6-c~H2JuC+U4B2 zMZ6J!OYkUE4>fCfUD=6#tD-~vAjHivkuQ>VQJ`< zHi3W-uPiXsQODbhZsCG-sr9wpO+F7OLA+8mdBxjUTT#ogehZ!fKQ`C*;r@efrL6cg?*6=p{N0~&kUPn>VVI&C9JE1QF z`eyRLg15Q%@bh_m=?{p594xNPYkiBa@kN+&OaoZXmx_k)-W`x?-SMoh;cihA4 z&ULKMt>xLP55Q(WfYiDx8F1VmKoXZu3%!;od&Be0TD_jr$M&OV`apX3Ihf76&Sl-$ zxlBy+urzxO`NhkaKJ5f7lycjL*DyfHWAymHF?!%MMh~0@!1`b7Ly4=XQrA$$=t&Ro z_g7EnAHgXs-&4qY7ahXQpZ)}ZKiGg*k}=s8>Kba9aPk$@{c#Oj(|mlHy_1*EJe&q^ zBLLoj8^5F=BIEW4AQ+&*Q^u}*4+X_r@g4U8Qr+3Suy_lL)-2$W$+Nj`^qIWz=jV(| z_pr--Fn>MrHpcWj0)SlWgIqFqDl>j}5X`ua858?b-B=g$o4=0cfQl@8sBo3jZ`_0Q zSn>f=pBRQeP{ljf7b2=&cI19Vv8R9%M=_6_`xu|Sa|Y9PK7m~Yv&GH@Qy=8&Pe!wB z`9S;$r}D$pY1o*?F+fG>cRc;eET)g0PGZ8L4DB(9+>Bv7`tb>jyLA^gp71wLop&=g zoN_Y&9&aTspN)%;x{6DFUQB6j13miAh7T>L($&M|VxGa5neMB#A zU*x85-Je{v=x^A}X0CiCjh;#8Vi!KfFUZ{Ys=(k;PtrfZ!p59MSQ=c=XB}VszKt`_ zy|6W2*wYW;l4*y81BhXgWfUNdc;caGGCLznD@SkgsyBEW*$^osmfTqObhd0XnMR35 zH2Hd~9g*kpBzIl4x3hfRxcb-ON?V6W`~5*U|F{IUykE`ln_$R58(DOYQzNVlXOH1cM#Gzn#@c8!7z`2&1_=ZLtslLOMkA?%QzJGS zZRe;!6EQruL}n7$JcfS?@u=a*RoPe8_L4gJ8_ z*IY<$eIsM~jzdJkAC$0J>;!{e6w!uFR4A`6AuXW~X0r{mDB$sXaoU_z*X^PhP!?zWj+g|`-FD(bvNcy+UR9W))-I&c!J=xT50xsaN3+m zk{?Nt@B}3?5>ilQKehe_df3x(c^gSfNTtqOg+&%IJ2G&XLhY7cz5&6W#o)9|P<#}* zsu-9tfO_{H%9;a=$r_Enegkt?e#MLm*5wA(bH*TciDQ9lSh-8l*p~`U&>9V z&%&zM8JN)*A~q5A1w5F|4$Oi=b09#1&4C(pv%MmRA$=y3V1Xu|mqfb*f6$94+OUWU z%>ju7n;j)kOLk>GL;Fm|X;EqN`$)7o@CCe>&2~&kcqD}ctBtbCP53Q+=$DX$YDvU~ zj~(T^=#xH_WNQLulSp;#c4~rlM)esMN(>_E>-APr(d=b#k3m3?2CtuFMwL@ zYWgWW_}WQacg-G-?VEyF~*ne=<;lb>vo;(6`4p60IVN9H64HniQ*@ zWq&-x)9VUZb?=X%UHN@(1aks*vl(|oK6OD8gEIyKO6#9bZl605d!MJdZ|Vq~&LLO? z@c0@qnH>azp|=7^svnz}1cHRDNJwfBt2u*2GvwFg(>rA_D$O+dWHM8FbXXBh%3ag1CqZm4ueCF@mPPlzkzYILZEdrV1?~M4VSKy#3Iv;r`DOcdPCj&I z+cpg?JncJ8sLbo1oQq?`HC%D<@$L3_?+~~(8rys$^YJflF!R`(Ni(S}a&-cYPTku3 zt82VyZHf_G(7~G?#-i!!Sid%`hxdzexi<60kB_sts*;1p-N4Pq{1vCEW8jQz=XSme z?RbVD2xPB+nJ3pR<gl) zMgxG>e_9^B^T@JB<)hU>&#q`T>)CBIu*4d?jpA-(f@PGX7|Am7v0j1|&!8QxzVQs` zdNPb;>s{BwW;d?7fGaxoS)+RD$%=(5tv)SZRb?f)d3j`{r<0s$#UjWcn6NsMvDyzNYTI-jlVN|MghVY@DTPuhXf~P zzzQV>u>y`>auK?%Nnj(WD*;QZKic(Z{)*&}rcbYq+OkIVh$kS$x^JvkCA`6Bt8PJP zd(o~zf9z;)TYu^-t|H}jW*{{3e>}J{8XO|&zZO>p3D!QxE7dr`GK$xcb=uzvRyVHn zum2~-t9WI{6R#>OE6K~tBRxHx*zH)ZZ9L01PDUMRTM3MJb^Wyz!r~vk=KlZ zT6F*D^TcJNsDC565>-j-xd4H!E#b@!5k!?nPGa4v6 zhbv<{qUrpvz?CM}#baYUZPqzl#V0@Bwu#rqcx>y&)xR!Y?N3}qlByd2>(Ge8Jn`l= zM)q}jAFOy4Mw=<<8Pa;MrCjK~#De*GxO^%;pUmI`dU4t@JvHk%;Tf^edj7*#xg2)d zNP1eszzD?=J)l(WF6Z}h2d5pIj-ZB;w>BV$%DBp0eD-xI)mDVtnL zoIEW}AGoT-7xN1^?2sPptWi1fu=J?lh+J)p^oJk_lvUK@@ksQ|OvdSGd1*8%b@d*$ zXV)-nSP~Aq4OLZ1XS z&K;Gl36@ctYeCq)^R!$;=)h+*I}$}xhYrx0&JdE(enZoE0;HaOMm$D(Bg^R>N0XuD zi*_9CS~MO(5Ia0_MKe{=+OF?Ak#PDOtB*&L*s|%bQGNAf=;0)qFQU!5wPic+zu5Ks zuf$bE+%=LF%RVC=dOqt)(h|)sJ$c=@`VYWW4BdLvS>GDPtIj6ZdK4>Zi+=OUUcDO`K`0o;21NQ$y6DRwIm@UwAa4cU7dA@pJoc4gPHb!P)0Ajt}Q zOWgdqu?}xAv;tLG;%5DZTABl)#t3?SY}isyS#O7iPjzp<8@ zMhRq@va&`tZFdt;R0JLH2!cRey%$MV7(S#2O^q^D)m|#Ayi`~FFbfvOj_pBSaXqrE zv@1Voa5`Cild(I@3>=h3Muw9>Kx$pF3V*LzT}WwZJpi>e&8+w}uS;zfX?HyLx&qv` z#QUE^otYu;ZyqgQXJ+=Dp?^j2F>0rM(cO)!uJLI3x^WeM*=}6L&-b5*Vd8b6j-y?MMHHRU;bJ{Wnnd6u5^)}C^K(D+K9y& zUiD~OJ&Uw!q%F2z+lx{0w;fh-7D_p$(PA;{c0AGGq zh{qq~hp!6osUkMJNdC48mThRHhg0JHxdqg_eSGpk4!esRQ54$kJ{{@PdUt>UnJLJM z+VVr=&>O-X4l`zR==U#4P6vL!+`*4qHt%I;b`{lCO|5%cX=&`ZJ`@+#vvWr!IXN}0 zt6JJNGWuxS)`(xfjWLuJO-3|3V&O{fTTi~WtezgD@2<$uqi8%vzKw^+$On4& z3wCmg{CMgEY+1h-=K&c^o!pC&2|-quw7vW{e`f{jwtC1KnaGWPZ#S;GaTTk4H?G>(qZ?QMdg@9dwqJH~kC(zrZbsl}e_decKqo)^ zv=Ib?4w=i5JtE;wb<<@R7nL11QBFKV8DnB zW}Mic$&=H_%5>r?^8ip)8$gUmGcyOIa_rH47(Xm~Eg)#yFY;UO`M6Oq(5`qI1rn`(Eky>l zcyJZ(l5b~%xe-O{j9poFj>qTm+MyjFV#(6uiMCQ5c^uD-wHsIQ(|;4L;?doWtB!KI zaiuRS-gwnjTf52^t$bWNx$9-&u>|V@*hsb(wBh4PM-8Uw=X~bQ&qreD;1WvPod(S%cZV(u30}fM6ma!OXFz4rAU&d3=&vftsAe zQHS^7@F5;Pn4d>;y`S+%^=h@*kzmK6S?D?Uk^^{uZaxKDZMfVr=Ugxx$KG-hlg%V5 z76OT8a9T)839Tw6C0j^HFq4#GAt}*}Ll7A=F@x_`SMzy+fHl#AXfu)2@@O(tUlnJf z9cN;j|H8f**f*Vex1ZdCIz|lcLCzjGlHeuD;b6qzUYIRH%fIK^Y#u$P54E+;_sbs*wWP*~4#jNtvFJ)M5R{HfZV;PW0(_RD^l(d$${tDDchq#mt!A4~tnq5R8|%Q&OxHR|Lr3QNz%o zDLCvYx;~6_XL7Qgp~Es-&rK$=^~KHM??a{xXvcrVk%M*HQ`>&gI*rzck;g{-;W`_Y zHKNYoDq8tilLc+ijb%e;{1r>@e=6;(@AYJK<0`rh-MH$SjBZ>-x8Z*QS6b@Kidt6_ z=zaPPR+#n$_*xm^J0_FBant%B2tb&>RgXZ+?uKmwI`C+zeFD>3Mh)$kWV7l&Efqz9 zV~*+_vRSLMvm^*DkKWoRL>6=OSsOsT+mF*~XW-BjEM`-?P9EY3`PFVWvukG+f)KLZ zWD?o!szMM#t6YNyr2&wcmCVi^m58Q}^;Q&>9zEMH<3*c!MXz#ufEulgX;(&L1+91k zLbPD0<>@R%vmu&ajOrSTKU!doH;_j18}aD*KibScmM!tv5$|>F{cc=!v?-e19r$Am z*xk75#?^mgyo!h7tw(3&M$$edSVkRWf05IVZ8JFwERX48m?2OkQqjLWXxazD#BWJZ<4|g6qCL%`qw8=@l zHfTGP-t~Ag_h`Jaz@e3?S1wi~>&evKj|V75_8Zv~t-PMy(Pp1onR-6e@r%v5wG?Kbu~fMQkR~6>CGzQEu(d)kqkY+#A+;~#t-X^ zW`j}PA{*C8UpyTs+I1t~>ID#O-L!Qw@~>Xq^@4&?9b9xl_3t8QHB)hDv79*@y^xXk|-TFF^7r;$D*T}FJJ?F_MaVs#L`d-2vI7GJdM@z~MX>s{%5u{wQc zZ12WZbQ`*H^*@d)%|NQh(~Yb6?dZnUe@49O48>cfE3)_dzX*+tFmh&Ovet6Yj;F(Y zj2k@GEJQC0){~*tt;eUWTO_}c-FoNIWES};6s=Fbs zG(6q7>c&-MS*@-AGq}>|-k-PCtfR(*^*Ni_OrHTu5FjwcZ5>4-Jk=qxt$__f!f z1?H~W+l{M#j_ht+b>k|mTkG9!Ty@>vZe0C)WJjZDm~59|#gn0Fv)Oo+MrNl*^7M2H z7=uc0mZ0|?O; z>_^Wot=!JcEVcaqX}Hp(Zd`TaDpnng=wF2^RaHqzw2+!;iJEM5e2e3U4msKEZ$5tR!4~kfRVhas)CMlLzi1-2})$b7mgfoln1TVnkqug1(XiGQ z6x;ap{1_{c8wIGg`yF-amD``ViX}H%yT-CdFPItyY@>mrv$%>zVOjCuN_$`LTh9h< zUE+yhosC!8^09DbME_rK6`71^2gPn&b>k|Ya^bSkWOX$`*BiTybjK@K%NN(X2#u6# z&!YjcH6hYeDiWOf#s+xdxk`2w2TAK~0uMu{#zyUwu(G+Q%_n(SOh`kv**ev z&2n((g&8QS+B(2TcJOG9jW!$5y(b9Z_wwv>Rpiwwn9OD#c{q!n2_^ts)ycQKy0clB96znQ5GKcuMGCv}KHfdMq-Mt><&2a&1X${QWjw zJB;)jm1&<;@1K8r8R_k8ywZ~!3s>4f%P1lFZ^e~XUN^3~aTSgBXS|AsVqvW-acRzD%jTAP*jnfZ zLP<;{pcJL!>P&c`)FU-wg-OrRp+q9U+2`)&^@R<1eG-emt7g(MIn=38v!Q|sXB1*_ zMEI#irYHi)%z3+#<=cHab#Jp(RYCO!dGGBi7Oicdw78jf->Kx#6LQF{k?}S7$S?Fn z^=IU<8nNo73m|WRd7szNf25fs4l;A_P=V{N$>Wvp8W1CrD`;DxQaZR$MHK`jrG34^ zpjH%ZkTSM6@;q4Y<-Ivoytpvb_Npl0tE}UihpX6}=Z|Q+wpBk@Sp)NyHE_ff3r8Gc zAyJf=F?}~HcKh4e)#_`ty?;U&0k0gACyE+escox~ZTjip6Kyi5(s8Lsr2OywR3wzj?KS#bqYue=wYnXAkG=+5O2B zWq#k{!;xU7SBA)YFBLH5n4NsTrU?)@c#4hV$6Ej}OFkaHC5O>R?%<{QRiS|~;APew zyBReln|q%s!Q~A(W%q_Ejy*P;8=o)Z!?z2W|8qT}C{UT_;)3&cap=rlEZyAP>hy5c zg4IDv_5?Zl#0)-sb2z^*?9YTD0#zj*X1!1YeuaAcsOIqk|ks+!bxkJkhf*aW!k@j-m?@hCPe?2l6IXZ=PG!-m;7 zW~vicshgYc%;oWC3wiP70-kxdoK34Lx#_MwJpODU&%cn*iyu}XhyqI&lyKOg*_?QJ zF6(oB?ZG4n^y+2dt}C)Q_na&)zkVPuU7gC$iyHyRUS7@-CuVcn)p^thL!Djp`ndJR z-5fq+2cIo#1Wfcafm4L9KPqAF+!BsHCYvYTt!_y$1-^c#kRzsLbM34WL@|`bL?$6> z#ChvAV8R3&o0oMrMK|l~>UVU^AQ;ylrlXI&PMFCNe`RE_{9DTwLZhfp2Nt4WpYLF)$ z%w_U%*}S%(HgwJB<)-U*GG+P>KK$8@C<+wstYz-UGjAxs z9W)NOTHnRf_q5mJT}?158%w{@YIrREc*DG`hOd^!kF!AVOrk#<_NFl)FnY(G!tcsW|B7d%{XT!Q$o_yJbM-=JR+svA^ zO+5c*BUT$os)@S2ULJa;o)5ojMl`D^f|=axCLVag#iF$VcC4-7go`V===MHLumm{n z%>33i3zM%&;mOy^`EY&(b6zjwfw}dZc}@n^o65Q9fqLGVJDAIlvT*zvIe^NAf7yjN zB9(=&XL84tyV+3cVZoAmg21W;HOyV9@cCzh_&dHiRI&%YYNL9&lit}6xtOrE}nv1erR<}Jw_ zbyNvXzxQ`e{A8zN_Sg zpJkT)JQV*97x%wg+YbK^U9*dgJ_p}_(4Y4nFW{q<^_)9nCrRTo`0C9}X5E&@?8RP8 zlAmiIuHi2?^=7xZ>FX3}|fT?=MwH?NfTmS8LK9F;VJl;Ebj(nr=PbXaj9bM<9ueEy`Hhi>bKrM!+?U(936ZV#*0)-(F>6o&V<5e$MO0akq52m`GQ?Po>u zSty?4;`gmSj-Sx>LS~yoV9~r9Hhl@IN#xq=`*6Yp2eVhGI4mj&JyUq|#bo||)eh|G zCO&<4AmcJEym4rdOK0w&-&hA9z0{xHc38X2N=|`?>|B{dS)>_Ai1584tCSS`Dc#`X zt*@JSecl0FHPz0ik2YW*U}DuGH)c^~+oA?G?{1{TYvSWuL%#tl+%*x4MM7*@ne#{{ zo}JZ?p1n-G^l%^U{;ZA~a}%jO6Zq--di=>E8-J{)fdM1~f}pT;aSc0*WUO`*7hKqj z#PC!=RcQ>Ec;G@OPkia-SepgMpj3LNtE{b;8FO79Tu<(zk^Vftz|FO{jX?0a@HWYm z6!_S_&BIsUHnX+zKn5k7_{Xmer1VVU=kM$BC5vqSv4Pwjc6v|B;O?{2fHcat_d;?v zVri*QdQU5JXJwH9ymWgCKYv!imOo`ioh0$`7jDusMCN~4&$SOF;oe-%<@c3y;mw1X zIwcXpe{LYi`rR_0tn5byuxax|Y70HQB|2DeeJ=pMd$xf`zpLZ8D+MmQsyEXoC1c-M zPJWMcjvtpq#(4?6zkUDpw|@ueO~m5ikEdKLp8Yj={443d(dK^#b>pgY^xtUnzk>EP zpV{Y~+@W*NWy2tjylzy9ehw2mcX`=X7GzRi3wyI`Iq8y8?s$3xqmxA}&QQ6AW))Ek z{~oC2cU1zIOn@b%tF+LIU{SgK!hE&}R^~j{he@9|p@;w~vJ629u&5|<=uwm)stAIJ zEo_hy`u&ZkIY4b~06|sB&93FL%lGp9g3)~Njv4A|Nf}*0QDuP4pbBD07MW>WeuR~q zZY!dGcaXo&?+r+ydjcSX;sJkikkkQA-k5D?Sl{-|<7-y9{-wb@a7rQp39Q!8eHBnz ze(UtYojZ8pSBYe1#7 zKyW0RcCA^n_8oS2Bmr|`u$iS$bl5Tv%n(ApXwjzlnr ze&>%hS-_Fdvf^g~vkHE{!XXDGF?_HEX{dvD4@+3Ysxnm6qSlg%ba;t*WGg0#bsB z@rNZd*dZ`(w4H;RM0$@);}cbk@BLgP;1Zi?1q^H~2@+_M`bavc8dRCkP$??Q9gwyK&W? zHL-rj+MiEarqW3wU*59c6VY z6T}7<=Q{u#< zlQ`huK0JE=KpuHu5L1RHkS+(g_WYeZ{9-8=TwPAHATq4K6`xn7zC6GKPm}-xSKg3L z!6qNUK2FY>YzIlj6HsVsghNkCps`M(tXg2p+9n>J?ZRS<2pkGD`V<@%6Nu(ea@FEH zSysVnV%M@V9-QxIK!(VY1(n?RPzi55ki+a%DudGn=DbqEEf4Rdcy9o~VI?C4zWu5R zlbMc5j9#b4LJ zw4-;kxlTn6gakMxnFk-)i{IoY$$*22y}Ug3iOjiE9r%3;!ImWR$_sn*&<({*Ji8ALLcd@0 zHp}7Sy!_r^%D=DSqxH?4bXYRWm%150#eplkj;rt8%ZS5zP`k#(7i$_R+E&FeCl%rj zLNFMzq0uez_3l5%8&!#jz=m8dYU=)gq^HzG@;Zq^UNo8cxxND>aJQ2otA>+kz2Rp zkb(-5+&00HG!17o*l06T7^n#`yMVqu4$%!Y}X&)771G`p# zXW~_)Eqbf@Ms<(WrS-e^x}M*)^)j+wThDk_YP7a@<4T{parK{#t9U5hGJ5_nvMo%V zUcri|p<|Ub%7nwRTID7tv3kn^+<5O^7X8vh=C~BLf7_o_z@Fh?>Y**GB2F7e9+`xM z%9x1>*azAGGv9tUoSSYdWx@B&Tzh|Cp1LuMjbp4_|7acGhz_2-J)Ph7_#q>MuRhG= zmG?Xxd`22O^8Hv9=r^hdYZuDg^=KVG%K~rCAI2rqlaQn~ABc$#maG`TJ$LP8=`W3l zW(!|`IgmrM%=nK^=J4^&Z2r?j6L84%9t=*c$L>TA|JgzguY28Bq{VrNfb;Rd1Mlq>7krBWP^&?EYLg4$sq@dD59AYrY7OA32fNl zLrSqSakPUO$6B!pDt~V9BWJ*qcMjz0ZAHBFY&DmhpMhj+Ccjc7zO;lB7Yf|`$PlItcChdO zCng|ZHZ#!aW9GRssIC7x)FYD_uvr;5Dzp{D z`6u_nmkM?ut(T2awh)|q9hkz9DGp{HpA3LA*}^PEJoe{W{&pwJ&TQu{g?FNadm#9mH@ z1dO|IJcEti%up|IhQEzw;98y0`nVpio_$93(3{a4*=ICR8O@sY2AFu_m39`dy% zM)i#~bJnYKJOh^?bX>tQvOSu8vC4Mi>VFVd2EPAS;HtCK)pC*c8MdPuQPZ&TilVfB z%d(6t%dN-3U=UfBktB&=FxdJX3}T35_X4~M5l@(3rGl9O_05~oD;4sW!gDCIV3~jjwkAP^qIljcXb*bzd%aMkCS{} zl_pQyqoP*72?A-UCRAC*WHQm*B;)lfh$fNrR1pwZ{bL2szF5Q0Tm8)aY7}Q5WTU|g z8EGa09+?KOf-S*Jf=xvfM4Fpqe1W!qD}+qG zUk010-6iT=GO4K|q5%E?*sKCg4HABd(33GSq|4=!P(qD_U^bDSEaI-05bY+C>?$DA z=#~k{3J4JaR;q^clVL{bw4YHK8H$!3ylP+cwIOg3W$TrLlbKdt1cPXhe0{s8x zO2X-MVz=9|SS*O5h%C$G=H^mRP=MKN#%wlYwOX;+Y*;LocAxNllgWg|V!>oGA&Md< zlL?c_gdhlrqKGJpt;uk!T}BC3ILV49!3rl-`y;^;PCXSxQIRB-J0C0|v1P+f0dxo8 z@PMg3*Iw7V9{__ue7`aPM6*DmQ=qEChffmd-`|epS7`P|Bsez$Xtcr;tBsB7*X~$n zVryh)JUU~Q?Z(yr2(CI|XFNJ%mDL`{lVIiKazp8ETfyc>3@yF6QpPZRAi9S_EGJ*q9`q8LmR`2Elamy z8L`Soo@;}BeDNWqJG^>r7<3f{gzzd}e9QfUAhg!6wOoY%j3#stdb5Hk8b1b!rc*l* zMfxLjO=*=Mz8*O#iqz9te@3=Jhru|`vPS2f!BuB$izTmXxN4(l34z{V9xrt@>5FAY zXUiBRZd%-FZQgIVic$WbjjL!BPn$;irZc_>(?0FwzCZZ%C|sFveH2+HvTmx{@rOEX zWjcPeJmF*Qx3)}VSy@)1@kGc{C2S64jpI&TP|s+de7pf?*2B_u-2%rX2f(pYwck}|b*#;MXWIJC?} zBXJ)|q2MXDCRcj((hd%h$01*aUg@Rh!$|px(w6M$C3ErAF<#!z(*7v7FXO}hlo6(V z8LW*G0wbRNp<`cVbXLy)60Ra?Ut`_BY$x~5kpP5dma`wYjz7vmGq}&6y^GJ5k{|heJ`aA0+CG+F59+DskWTb>mfkg4CpS!bWYW!GNCv8P`| zb{&YCcF?x3Ac}nV*j?l_xB2VI`|jb7q6UOWUR}Rv+FOG)qado+27-Z~6QsTZ9>0nkZ@ieh9(xLeHmqp-nXV3Aba(LU|u9!+^<0McGJ;%^Jw zq2DLT<;!?)>p-RqF!A197jW*qFHqYMVtMe~%Q@?jPx#x6L0tFPya?MuA-s6UTGsrT z3kdj{8u55TNtnCZg$(!uLGm`PV@q*O%Rm7o`MX%LetXCSpfGzatJmiMVDEnvS=n#1 zwxa!@6=*DD>9UnA=TN+7E59uJoqz&@8pPMw#O6)w$SN_9*6n4})@%UswykI7@0$P!l&U>fQM#Ak61v%SUwQ&~!O?CB@6lGJiw+2sBX!m?yb0f|E&`Qy|-vBw?_iCwar9e@)6TH{+g$l_ugC{xnMY#UUFrqo~{CxEM1Kf zf%!kz{L1bYn`;VI;#C2;fxUYxxajH|7@1+lFDVr4SjncHb*;E8-S!8Yb{Es^u18W^ zl1M=SrGdpi|3Zx)1VP2;53qavDsn4A_3?VW)RgWaJGUa_v*kZFe|;Y67jN=?QTu*YvU44)|HuIZDRv1SiTSFCA0uimqbUw++$Nd$A+0i;vL zPn)aTC70XQ|HhV`p}I6yY{t{rz@ICY(xif*1Zej9*tO{onq=_R<@3vu)oqg|Z#~(& zcCvHBO8nj+Ad<6n4P|?a*}SJTRKGwoi+@>4tv}p;L4IBFC;5B#lATxEiUm2~#p7$_ z_cbeU1;V^C%a<)-dv55pP#$*!6{Wk$&)vow&(303h18mG3W7l6-h37>3DsW=>}5@M zB>;PicHmjqWmj{cRlp>({KJ%H?kDL(vjSqifL;(0Ixk@#`g+M*8Bl zE!syYR>(d$%kIaqHo@2@?U4M@|%0P`kpy# zT=6k8&wCccO48FN@YcK^Ieq4lqKSMOfKJuj}oSMd|c8HY3bi|=^jzMFaI{hwL(?qggzYd-n8g)~;K zVB3x&t~u*W)@|F&8K=yo68PqxbGY*#^SJ+^r*NBmZEY)fxL{fz#veSHBPLAXk_X>H zapm#c>p!sdrx!VC>QPKPIFpP)C-U3kg&cn16o!u;MX&y&S+epoMvkAr{SV*I(9FZA z3V@)7Ru9&F{}Sh2cORd=atl}7wSfC?KAlO2-@*?+eZ#!BUI1X_7mxAU4}1CK>GN5* zY6mx7b_R?7+{l_*7i)g~t+id;zkkJybFSyh&)(#fFV--2xS3i1$KHE~Nl|qD-=FTD zusH%t&PWy%Ng@K0ksK8SL`f1vf{KU|3fPx4}P(Vb2fG9Z!CFdM=7ucL9clY~8 z&&s#B-BzcuUyK3}$l_ugp2@@+A!`SwG0T(AST zXxHOoAeHA@c3}6OEi|ZAg6%gz=byloQ6pF|aX2I9ZPPlkr=iC0Mpw2yZ?vh7swgz= z^8wqI&f(U%KWNl-AbWoMnP*$}0APCWmdsl5J0JFL!^*QJBBF{C72u#v;|4^h+gLE` zORh&p)4g>q7OeS|QT-b8+i4T~HqT?=gjsA@GL~9RyI|JBP6#B?tJ`o+UOG+xhV8hT zV4>f0!F;=JI}OcJ0T`KmK4q-_GngevZjwUg4L6`{>{6brNKVJ-d}x z$9&};2vh+iV9l3bF??cADB6h48@}Q6o<;0Sv(UJlmQNG~7JojD*Qd_s+Zk^&dd4!c zZX9IgnsosDFnC|roo0d+d?Z6e7udSs+ug~~v z_mA`+HG`Nd2YC0Lk2$_`HQo9R24Hlr3ar`iE3PQr_639aa`T^j@%|9z?Yu$xC(AOi ze@8a2T}Jy}Z-Z#1Q_C8RpE8$Y`+noK!J|2OVh?S)4g$=yc%db~to@F~TMrRhx(K_c z_Gjeh%a}U-Gaf2-AcgkrTJhJJWAy9On-r_c(4IZ`VaqnAzd4-}rORlx2Bcly%#)3u zW%vFqv}@Imbn_j0wQ0e@zs~aBu-7LyOOs^R(^u}+B)=n=LNLE z>(|?*nes##6o*9fCQaCI`G^xDA&GlxWhV-@9{~X}#}EF-#*M%6T<@3pWqS&n4y_`D zEV^_ZLPW!-(EB-@3}#^mO4n-7$6w7R;mGGq{{0$hcbD+#`opv>4wmF-I(K-Hip}~^ zIv|?)KYz>n6JDikjd~6JQKP!D7ZX`M70T<5Q1Z1i= zd5T4IrgL=WLvG(oB1pN)&AS!o`qo&UEuW2_knu2{nVau0pvEnpD0`6p6PpqfBk;wt zB}^LlI+iE;V7xk+(MwM8cBk458hnCFzx|A{?DH(1`yNMI)a1aui+s0e8KqyIOqk8W zw7H|`+hhtakDI{P(?*ec?-IJ7emQJ5WgZ6RMFdpHTGYTJfC_D~rxvrbWnMgs4$W>NJIfxH~-k;!OT}t|da)GfbTK z1+6+Y<=P8%DIHXs0pA{^RnzDA_?>IqjE!giA8Sa?f?}Z>)y?03&)iLCc{T*>SqXIL z{0(RC?WX91KUuKCc~+uiz-krI*<`L>z0M20-=h69PjjMvWBQKi4`^@*pMJlNF`uue zcjGc-JiN}?-Fr9{TY;@xzl4;tygYg;PgM`4h+P15*z|$iIJ}(7ofb0XgN9T~K1rO# zia{#Lq%}WM-~R-S`s{--IX`80m`&gp{CLY z`kW7@zCdmJL;SPu@Y;skoI8IAEXQg8))6kRnaSmpBD@?KLG+m&d_3)aq_Xw+X7&^g zJ{!(2Hy>u}#gR_c=RRlBd+n&2)r+-VX>!k<5nUuDJt7f{6f1Yi($Tf zk=NSSV%4Ha{CU~N@Hcvpnv_Jm38u}MMSwAuWn&w&tmGKf*f)tgu>nc75|e0Q*_s7( zDu0{$FMY?H&ll0D{XiaMLOG*%oFZ4sYoc(KDabZaZkl;L%j*@9+^?BqvNU||d8(F-#9~QD8|E!! zIIO7lEL5X*V05}&MFC2MY2a3wCObxhA4XKHnE*C^_;DL%T@)RA^rC7&D!Q^aFalXt zGj{}kH}7V968Dm<031HPk6oY5q2#2+3~!#yf*&^mDtf;f04RYHcGmaeDUbLuUO_+{-9R;?@1=%~_Z&0@X_x0TY5C5*QLp z(nD=aBkuM+RKMaFBZ6u3Vi#%#JVR)i=TYnm215w|+I8#Br1@KT&J@JvdvQP(SvD&u z3Pme4qW>#BC>o~l#M4#S`dO?dq-sD>J%O}D40^bAJBCKZ9sn{rNyIN82*q-nps;7? zH(?nw-fW6B?Gn$Fevxx3*NbX3S&(RPj{L?lQGrU@<9*!e-TV2>=-;^vB9E+__PeIjVwm| z0u9(Qw7q3pRy={|ao8*bh3dhUiOuf7px1Njh9-0L!$hJ40V5(&fk09Q27~KN$n5us zbmf|3yEvH3$)8a@LLlSfcIu4T#-z59n6k9(-Poi!LMsMgPtw|ngonsFBN_23TlVi^ z!svDkJAD#^B%sO;LW*g$Gcs)i1{g_6&*DJ}P&}5z3OfwL@f=tG<$$D z;70;BAnW*VtlDp8{5#$G@YXTD+j5ll&vXVP?Dh-|JzunuW;f#}sU&4-4RPnrN$Naj zpkzoOB9LyfVKn$-6jZDk3ZSrZ%})G82MwBcp?mw1sB#HPM3v;zWy=XxZ&APHb3C|r z0|Pd60onboWP<@L?N^J7E8phDL76OW>PL-|0YEycXhc$FLW*j6Gt4SA8@A%*J}nRf zgQ*-4%kO8jE$`Um6e>vp_*))0&*IeMP<4ocK$*IA=-s0yAx4p)00Rp)oYe^0t>g&& zs}76-W&rLdo8Z(I#{6-Ll|L=u;i)4Cq61N14$&clnn6ao9UV}mYD4^^1oTo6?=1X| zN>L7;e7+eww=SgH_#b%s_9ABQiDqn>ARrylP!XLXlAfGSNN6=c!@$#fu;Ocs&1=%m zYg{hK1nnzdK_XYa^5r#=73AXrcyzKY=*0cV`>G9uHTh|g99J~C0r%F`- zz-CvmJ3kd4JNlwJ&b^%VkxGbz*Ieclq_=Jn$Q z74PYm;iC_x)3!?|ewh(U>87vIy2tZOne_p;OWW~J${@oE7Mt^nF`E^=QR0VBhVqxC z7-~isuQz$ZO-r$6;Xr|HTGwa*03ZNKL_t*I4H@3KA}{yt3lEPoap@rh1?-B1YByt7 zR6xXPHBq)jH(osR2ele?AvFFJ-9GKd+ml{p;INkovE1a@S7*~gr^9U3+|9O)Dl_ZD zag-??&ed}PKncX%Q(1TO08N6vqkHGBT#7ZZ?f4*;kLyL9I*kcT_=}_lQ#@KuBsdt} zAKHV#*H19o!vM;aYlhsz&3g5frsGr)+~!G@RRx&fUJpbnzxriW<0Q%5ton-Q8`Ysyg(5t>oyvDV?c;??_o>>X2gg?Hu@!xuz5Uzae|!mzo^M7* zLMC5sKS|OTji~=l3zolDmEL0)QNj?2Ll&^RzAzN^BxOi^GH)V%+C0trx>1<$%Rcnl zAhGO|!Q2r_V9P4b)MmAq_U%#Xx9NiEeiA>QIK=ty4x>b>;9rR+vMw-Y)Nq2+u9NJ4 zmeDZg-3Jfrc9@X^*Q@yD_ZVeKvHHXzwVml%n`(A z@3-X1>J6z9lt}A0mr|?6lZ+hMi2XZu^XJJc{4iW1-lDw#C#V9M=}GjPI*VsoRA;t6 zkXjvQu;lYEY1DNP$A5|>%h-a}ZL83{`v{({Qj`{524DbU51*n|?NV+Fyt8W!?+rOk ziQ-23fAAsJQzx*iTECEyQ4|%Mswt|^$Vsee-=DsJE#Q`;5@&a>pycw#wCuWxbHDFp z%k*Nbo;sAqH5(9azRcaqW2m}#8YP$1X$r(2< z0YMemII9C~&a}c}c$%Hly7SEsKQZ#P{#dSDrgXbI*c=L~D1s1ze{dGh_g=!$pN43| zLh?mAcI`#AO695EvG?PMTkU_h&naGm$1p8}SB`-H1%^F>!tR;Jo_K*tGnX=c;uK~~97fUR?=rdH z(>Tmom@&Bd2AnuX0_kZf1c!zrpsj#K0UWY+Fmp;u3gO}5+3Gi?BO5~S(>ZNJQ4ys? zs`*!9OF{+}3^ICy7Y6f83RZ`RQI{=RKFmM0z5ePD<5u*WBxmx=w7=O zvre9;R;b3KDroOsneXjk_#%N7pSA!reQ52fl9G~|LwBH(oSI2QST@gD=_wdO!rk>} z+n=_z>AvmJN0!ZVUyNy~B&8ss{CQg-$sm#*w2r&`>)8`bwE2F_eX z{n9$kWJCeGIUS1-NU&day{>-YO^?Z`=|qHuxSyq^r4bq$>eh~I$-pKB-kBSFMZ_$=%mt+SitzH)o|V+j;rr`={tUZodE2wv*3! z(3!l|U66LoYwPjvM0g5qSGk<7|7pAW--6^WO`SS*syF3$dX1icp2z68{yZHpPlrrV z6p9rqMp#%_{t>Ke+ShtQ)vDRbl_IHDB!xu3DwGH}qR27|F02{_6$t_DXc?FCMM1;H zkyR0$s7-(ZV0WlUl7K49h?0aNI}k((6d73oQ3QvqpqB&$*OsIzpc6roB+~AkMtPzg zO{*98Xk-=HA*0vpv8xZoi0irN%p*v8 z1XV#4B@{&l1W;sDglt}eiX)|8=Z7_0DfU!b-W%8wK~<22Y}rv&WJSXgQe+uPr*}He zDmqETVYeZO8g0Gapvfj`vM7RtsLCiR8WxcNf*=tR9?la_)+1Q&nmASG0n926hr?+D zS|ld>T6>}2;gAtfHJJnv(PfaTibGY=Nw_%T$PNcOogP(@Q3Vk}RY1}ssv4G& zsyI+p0Z|e`5D-vt*k$xO5k=8-h$t<8s%0aWZz1eF zSHDh#?}G7{e^xh_1sJ#sYOndxD9EId+Xl$Pt^^@F%Im%_2sz}+tq;{jw*aZ2Hk~`K z_veruwN?=d2)OyUV}Q3wDL=yu|J|+%k^X7B5`@B?Md*r5c{?hnun{c4{U81&l6zspj)hrexfG@-iZeQr{W-GW z^js(0aPDc^4%e$T{ij1Oa&efmWzGLh0WVWvUhBJ4q2!bmT<2sTf zC$OL^I&*0Aw`@N6z&VMzWKnbS?W#+0Izxiy2sk|QsH%c2D{kDLoW>{QkXKc4%OWdI z7r>K-6DafNFK3bAivBp;PL^diIy|b1-R1ymJfF|_62%25scO#Ewjbv)^XnaM=j#0F zJ;bCsw`HC3xF%}N8PCbTAPAh?y@qZtzrstsUuN-^V+ewP>~1$rhgY|)WXr+xIq5oS zdeV34|Io(y^y>8zUAuN?_?wft@*tJu)4$QL-@EPzp09{3P9$)L!$J1x08V|#@q9Gq zCHnUpz~JF;5}RiAkWF?wAfC}oSCVCiN5mn!tz5}766|sya_G=YzwkCNd)lB|CePKA zj{!;aD1)1WY?_eM+06ai*NV-vtv&hjmM^zm=YF2EW^y=JzQz&nH1dA#$zN`r6=b~1 zO~Y5czUcUhmgMHy+w=T*_NDjybd|e4Z+U##V{V!9;=>oO|7pAOR!4sA^*?P_`L%z3 zbp9{fRbi92GM@9r-=XzbNbUvA_c+1=?$xv?iintqOGrf!1Rgwin0+3aC=wGL;|!+= zq^6{il&ppOaM(#nh$kg26Hyeg*)?909>$WKmW3dIAc%;VNzJq(2m*-@V=y^1+Og56 zIdjv(l`DS{ldNsYJcx~5rPOIiXC5=?G=iK2t(==)9@9{N^QP&EfpwxkfBl#U<(f{@UuS&qk(2b7mgIMq^g8QKikv@uXy?b9(3YY+NK&1uV>&F@=dA zPQi)U$t)KAR zpqYf1uf>b)8f*Ncx>pw}T4W|Ww5$D2N=$OwmCL?=o%22k5ihXnhn4gw^?=^P=DYQJ z@7{e>r`@^UtVJr)j@HxJiap4`toy~4c8x*{JR4(rXDGr^RX z_7Ya7JNB4kB+89BwEbgxv~GwcxI8IV1KZcH;j0-lQ9}dxZprsdn6Z$g{XY^|p(bCy z{}C&%#&Y=U5nPVd5tndwYEf?AN@vraO&t7cJU^VcO?sT2(Vxwwj{P)KXRRX1Y@=4Iu6#Pa2ZMTa z#SvVQL~AhHe_E(HO{(+7W>MhA?)mh1=XWCf@6lxVB3ke(V;7#JSV$ZlUt7al9gVc^ z(uc5+ay+z!ad7KW0*VwtB8w)qpJw@<(|k4QWsXGqftt*Wx!bT^TgJ$@zo%-+>ztxd zc1wsNHx8|*e4CG0S@I(D*I#5}H-CQFbPZjrEo27VWckhu$QRDhXTg3N+CF9Aw98b9 zvSW#8$NI%15KzGwPLM8(uRdGJyQ8~u`urIT{wh6NH0NP>b#(U+FnHD`nwWQUF`_x) zJLWNY%>it27KTn4&yhKc`DFhNf^M&(<2&i>T0hchXCl=awxC_xj_4*0rp>fOGSW`- z&DuX{-$+l{=ilYY@(%tyAITpZUT6I9X&536oQ(Ek*N*QQ_-tGJOB*rkBRFyHJVkYy z!&I_d6o(i5%=T7I>F~jN8fMB^9{ft1ZgZ(zqZn837GeM9(R6%sJv)}Y&#&KqK}>LK zN}G1`?eCZ1(s}xPy@Q}V6IpaoCMf1S)d$Syqru@cZ7_tgmHaq=z|8Nl`#Cau9BWSA zCG~-g;Zr}QXS3Q~S5V%5=NjDyYf}%|8~17tW#82{TC)ZmV@Q3aq?p*uP~_d z;*saqAH=Zuhl4a0exup=ot*gf5G~t}V(XWa2x~c+r4xJd$K0VzTe^)eXV2u?Z|}2Z zUw_8E(g9xSz>l*A(R}PQUU(v$u$P8VCmsG=KbI?i{fXmYA}e<8pZFSC{zslL& zOBnRl&rBIuf?5rRV~*d$!rwFa<(H4x`Rzc)PXC%4KmEqgPv;R3y`D**eaUw(RUlD_ z;@BJV6_4qN$>TH}jae#M* z?dRC(BLoo3i!Fx}99NU7FMiL0v9(zCVOu`m98WMe2^5QPBH7Fn8Nai5;|&%spU3t^ z6ZmAo7lhuq!2HbzXiz4J@x2G(0Cdimsh7G?!p`FJiZHm>jSPo)REqF8+(t&aBIoWygB(>Kn5iI zf+IONa~x0X_=5Dbbe1gr6)EEkcP?Kgyviq}UaNsFq#^^}TR`)+uW|BvYs!X|qd|xH zJpWW3W-OV9HS;>JkC@K>%Vv7k_D4}v>h=DZwH0C<-^*6lZjOx?(bZ#3qechU$A z4`S%>#YCrMkeRG~GM{O-Vhd2Xa(XwBB^uJ9eFt86Dx6G1Ki+)GO2Ro4i%%ZqxqCR64}y1tI({!J!+v6)FTEs(|=|PXZC2Hns5B}eb(Qr&gwaD19zA>c`@l`2SH&Wga+sk4AqGY zHR4E1BQ!LG;6NkgYPR5m(VfUlH=(MaqT~McgG`vY5LNOgB&;HV0Y*1}(dn5OLNqAy zl!W_a$rb`bBp`!;z#tsfO#H$t;IFe$v(1|fexW=WVo8dI=?O01j4}N>QR(?UOdb0& zao7H&?;CF;>qCf)DvhM7bQ$^?O)F@S5rW57;dPUP5FLPnTeqX}_X|MdDv;v-0x}Z8 zM(s{Os2_HRf?|tc)|_{l^xkKn7zrsJiN7fDT!;P)?$jK!)#e22G-~gnxhk_<=Eo~l z=v+g=QLPQ-;&yN<1LQ0#Hekf$?|7-rvs^s7o_D|ah3zvwVfXEHf&&8y@OS#}szAcs zW3(Ok0Yk=r!NC(Zc=d?{em!-O;Gh}=0_b$;4I&5w=}nMC8)KIPi=8$67U=k-nv$uipzB^}_PUa^Y2_~sl|d^!@;6dKp8 zK~#$=9QtV_S9i={=;V16EnAn+0F@voyP_yCV@yY`>*}(8;})XhV_5#}2G0Jtge5!9 z<8L$&7+}CCD%fNVCP1&)$+B1&^4>S}YyUh~Pi|t;2Ve8{C)0_`QV0$%L3mgZ><$?} zy;jC(^aI(1;#Z0yVLC#}w_xJXm$dfw7|2z?ZnJ9t?RI1ZRN0PQ&R$g(BnnWNs6k;< zLFwhr=WBtM-^w-jsyDx}sIam>&UjT=`o1D1dC@7zg7$Iw^H%@AcJ;4a6}0~UCcFA4 zQ(lhO|2UF+LGJ^krDft!1W+8Lq-k&e+>c42{o7x%s8LH^J@X7F51(S|t~aSsvKeJM z4y14I-ZW}dmNDaJ)Agm{^zPo3LGMo^Ea5K44(~#_bBWv5YSeUOAlt3zqMGn_)6y(l z`W;!94$=CpE=1YQSoJEh#e%^<08{#X_U_%u)>A1wU*kSd1%OZ9dV`kzJF>f0IpU4= z>HUnJL|J=BDn34$;4+no4xjQp`Htj!somSoFg$ z#Gm?!F<&2K^suJ%>fD@0Rl_)aE7OgmwCa;7bR0T>elPb1po+Yo(Zl93zIipe_FBN8 zY6sYIC74KS7SFVJ0!y;QiQ|6~eDOApdv`Gb0fI`=at*1kyh^nOXQ@|K;>?{0&Ocp~ zS+>h`=+_77&SiQ|TaO{}2U6A2yxA{=x-ENB+;WzdBfsXwwjJPbUm`{?#}72%M!=Gl zL28yMhux@l6B%*! zD={gwtFGZ@_3t;7hAp0?S=V;NoH@aO32O-S+rg=e*V(Z-p7isFNYquNYT9yo4!lLu zu7eC*+>iD1$FuHY5XIFDp6OYO(>K27$dUcnQ|@v2g2cAJex&{LPjP5fL$+=>!1Q$s zdA&z@zMH=iCF>Fu`^@6}`Z@e+X~d-d&uV?dd=CG>x@4*QTxUOoJ!JRY8G9UHLp=8oVjVUA+g; zs4I`vYDcHnA);V)fS*CaY_{R=ZvZTuJ$;QzwVxzN2d2z)(o$0~+hu}7f(Z^Vl9ZH; z&8`qpvI3!ED(5aoQ@LslL~MwH9!V!5IX{cLap?^DqE#qYG!VPZ29h2@v7^%)FsH?F zEhd#ZHLH@9WhF4s=mrl}vL15oRw{LCS3`B!a0oi|l7QJ_$KOwjK3zC_ni3Uj5*e&r z-@SGbM?f(umDbMlh>yKNTsqXQURl$HC5_Wp@A71wCy{`e)5go9GG!7N5aetp?JLX7taO6>1GpWXM1^uu+`e`Jhp`w{ z$`u3P>iIJSm#ReZAOS@egw7*Q8gu75sV1miqY4sM>NR|gjoW5{)sM2JB2nx%97q`S z5_fJ~M)4~`#nMGdNxR2e&ARdKv6IyB%ckeBS+T1k{zg5xAT?z>W}Awi0n8RV4yzS( z0{(u1Zd+Akm59i2OeyzCFzYEB6^6+Ufqr^7BmhbZ7ca#ST&yf*orfkqxP66m0;yV| zI5vkKgU-ykvp1<)rxrT9jHH*ibNwPVeG#509|hPsckUt;o~TWbpTy;TE7<=ag6@sW z(eah{S+Qv|HHwJby?OyhU=)=~7vYPX>x zVKC_OT!BB*;k`W1Ya;N~Z*wPaTNl3S&1<5}t3J>Cd2N;W%AfmpZvMRS>~p;GkteSS zFt0q`CP8nqdE+N9nLO+B)~0OTs{Jkm&}czr``51i58D-w>c^X`|0%nAT%gf^8m8eN zMRK>>?O3hWe*_0h5Cr$<_!@6G0UMpD=uS8WO&|e9&c1%cs6-J#RlQfiMjdmfDLffC7`;Y5?uT!isC|r(!N@| zl}y=+QO# zHq3eMyLz-OoVMgL5m7|2++os$DP&1u zlzpx%<9oGm@|Z1aT+BlviWfsCWrMIPii#kK8VIf6v?EvB=GV6h`0Ssi;j7%^lrIe5 zQ1~r{{OCWf%#TYauZg*!vN}=L_kosy^aixMa-fI6itzihJ@_^&ZX@ z8lO(b&$A(O>QY0*&epZ+mfxi}7mwi7AvyUV*FEQYjx|5US9HeOL?t!^D2{H-n=FeZ!2_P(E@K}yz$|SA8&2!S=QGW z>y56rMQ3g~@~hLEF7nc+FT2Y9%-i$)Qhqj)mtA>2_a#SucAFPZzWDGt5B@jXm5=$~ zo16v7Q&_tyNXjpNZhxjA^mFIS;b0Zko6bw%!U~&{ORc;q@igyj_=d`%QFQO}5oP_I z$MOI=QF|dtQDr1i=9j%|Y4+SeA|)A|$IB>A%qUS1kX0E;)Z;oAO%w$85j2V-qXLpB zAuD!N1azVvK@d$mCDpiR#95H%oARh3bkde)9wQr-3@3KFU!Ba0I8w{~#OUYD|# z9VCWylNS9GNKg2SZ})G( zPYOYnv#46D2kooX@@f+<{`Hc9Q-3ZYy+~J@S15`s+nx5W%VD3McIK@wM&J5_<7r{^ ze5wHs70A57+LKp#rCI)wi$^*q0)pz`_w9GN6KAJH`EWYD5XGH~4@fbF@>Jyj4fIyU zd4iO7ER-WXgFpT<^Fkd1r=kU(ts9CWt0=gDW3`h4a7L?rCD+)Jnr7u;Qaac*TayJl z#Ug?z5}AGeq{A+A^JWr)AfVHW*&c-e4!ahmuUIJ(yeHce2VEZ2X5Y> za>YiJiwJVk%Wg}TjCx6Xr|z%lKS;D$K#Cs(KgA?NUf@2WTlw6 zb;F|ZFS)|&TK{*I6L@q>-_?fzuHQ}|Bg;(XvXNA)8b;M8!l+)k2oA;0#Y>6K#S>&^ z*(eqjM7i?es4D0U5_*G#szSN);Y39Rla-}GZCI=hs#PyW^%_xBt5!_=tFHaks1Zd% zVwRhioa5EwO-?R(yzKyZyUr_5VIn==A_#?*!IN)q&;Cwy#~00l)a~neLGu@667@Cd zdeX@6e!=F!f9)#wv;Tx6=quv)Po%$%gXJsb_Wpc1Wv+Z~0|Qi5K(NQL^6VA@Dp#P$ z1BFJVTk_l5P8_%DxswvlD;+n|vrHy$t{4h_!CZ(*2BZZ(%S6^roE z(ji0(aY$i(8Ct=>DItQ48(*^Q@+s`LES`DtLxwkcnn|mAlcdNL3G2lt-G=hrmUp?3 zb&=$xip(DJ6-AAj%tuen;p?MYkW@d$^jS?n{8~OdxDlPr!RuXqrnYdD!E0AiG(3i= z@MfsC2V9H0!Mu@2Fkf8C3k~1l{DHTabaDsvYA&W#=q{FAJc-U8%C!D#u*Ixo^4{er z78u-Z6I|U!&2r6Hzq%C{9HAs$B{YFW9&9EtcKAiQe*%pt4hec*Za9N2Us8N)BUk<7$jpH;&|V zna@Yq)zPN;$d)E?VKSPNpr}FLEq10==h|@7!>CKAas9ars#}v!mkr{M5RZRwTPjEwIDh>vm+p4u z(*1i>i40=Gk|AUUWDpeGhc9}*!Q7t)aNm^7wZu3+7;u1;a|<{apNUaWuoJ*ry(aPd zmcDFFk+G*;ph1()T)ecIn8>~yIWUF4(&I_a3S;@uB}`b{i&R564(k=(?)4i%hDd^R zdbaGJ#HOof5J{s?>($&kw~$h`$I!828K$jzgN8MprBrxjN);^)l%|yNO-!=FUuPDu z==c^8LmAe23H3u$8Mo|BGL0#Ol^(~7fzhNFugHZz-{X(iTcl>1==l7X^nS7ipRDdi ztV6~xus&b(nnv!xkE^f6JvhbDjEWeOk1%EL8vGrx7>m48fPS8hzoy;Owo64xz-qRW zVN!UpXC)q{3f#W(kgVV$+&&%6k;^vxbuvXu1d^U)#;)_{wXQ`t@Mi{Ho)IzlNmvq- zS-v5T0DlocAPNE&n~c$@qf(_vva)Qbs!C9h24j+*X2D?8WfK7Q?7l(0XG#$o>d*CS z38bc4sNbMWj;NZq?V7yx_~^B_t*XLqZx(cW$XglLv&V_Zc-z+UeD=6oD!%R&W^2xy zJb9JLD@c%E^0vj5d#>}fg_h?$_^(}gefFPnvV8IJckBAwNbc}>UVom7Lo$Gd| zT>Yt}?C*qCffP#;1A89fDf32#?LA1bI~%Fhco{=$mtpjho>(2(5+zu(czf6`qW8VQ zZ*p6Hcg z7(=E0eA~PW$F3eFJ#HHoKL=@tVu3MdeDn})w&adS2XA7t!5m) zyNN*^wh-WmBhWQb*zdCN(0NwAxes&FX>MiSWY(@td_8(Mk&cTD_D47{Tm4voYS^ z%V)3erL6S^eCUq5D-x|b#mX7OT)bo#Cw!2qH_UBAwW zTWNUq9=)Gz&9~Rql3^)9g_;eR^WxhqT-}=6DG&Jm&Mj6B`IWmDr!n`okwbrsLMhUZ zdCi`u|MFIxsIU~((2TVc-ggR|%A!4cSu}b#;)CBeON5#RF6*@h9oU`cOnY zM`+1W%;?aXF-v=sp!!j*Olhv3pUbREH(5Po7FVwCWqh~JWW{dgr@Oy#R(}@C_2S!> zy*YewH>Cm_ksNT3YGE>G@1?N*z;voNna1mNpJD#b137Z<1!9r~-Wj?L`^_aRKD(K* z^*Rumo`!^iEQVl9*u##j2v)wnfP?!7anR<#%6;tCME2Z0PrtTH36bIfm1OY-vj?3g zJn0WcZl6c(2t6tarHVe!d$mS!J`|%11CK)A52En-vDoM0#Q>)d61y?^4#V{ZDn z@8vF&o3^j|3gX20a*Dj=^Q7f#+|Mn)ueyCXVtGx*zWC3b$6Gt(<@Dqg@$%-J__B}u z=Forbs_=I8I8n35c~+40SX+eNl=@FGq^j9l0~Xna)nP|fb*MnNe-vedKv4vO^#&5G znG_4wpbo+VLy=W&n+G5&s0@*SUi7C)g(_e-6QMJp4}6lR{IBrIPZMd;;C1x&2Lu^Q z0A?V9w2Y&iPdC%IQGXKB9#A@}5&)$`iej;A?`J83j^fUGi|8RXH61~p!M?jYd7;K& zf&+{5QP*FHOWeegKR)A3f_7FRN+yC>1`!Ahu7D#e5z#M-2oW$;rlepa(;iIO&}x8* zVE-2g0Zg)r-4uh>ltEb?D5^hCmM)3alz`69$ff9QI6|JHWy!ioih*Dq5Lgnu&Vj7z zP*n)@D^7$2_!UJjXJA6YYP-mZgzNNbFbo`-*k!9z^Ew<#Af-cV08la@64{Z7KA;o; zrNU}q6a+FX78Eg&{r3*g;mOeisVNwYr94{Gj-ZAR1O$duz$lxkS^Z^VudU#-W49Ro zd~1?TX@mttX|?Kt5uJ^H=6)LQ_u7Djg@fnTvHjf7T+6&oxL+s<8OfB0(jYC$h888& zlmA@C(tF zI08kH;4%X#m9>HCzs{!nv%^VAiKcU-B`g@QgYosdaVqW@;6N0M@E~~?w;iGMd%7L> z($gp(RStj>LE%^&c2reCm4Yc2C;(vu3ksD-a__FB}#^1G)knWTPR;X96vwb>rii#NPc;|mC3KHtDNVbFPeGL$d6ZF&-1&^ zFK=!+@+y;CMsKqF(wjH^6ei`Rqx{;+8y~)C{~bPj<@wjH955C(vn0UX|jA%Om(}TS@>~Q499!mIUFk{oJ zNdA=wHTn}|3}DT+ahysiOT*Had2j11ru_IKH-wV3DJk&Ymg#)9vJ0VA+EPTyB;9HO zL{d%h09a*}Ytcusgp_v5l#ERVV^nkMhNf`eq~q50U$F-jqiK~;W^SI$j1}!U6qAZz zOGFVME#*8PZ=c7+l|!gndnAL(H|ETZ>sZq6@#n4Upc6lBM9j`iVvj@-IJ z^P1h*wf!B|9G%6;O*04%DaP?r6FK!Dfeed@?sdB`_xt|*bnH`pJReKFl2u4CWuO3x zVkId(ou*Bv@llVj_@KuErgeUg>Q!1|yuF>T_AOxa)(=p0M$A?dc1tWD{yq`>E8}O> zoP|uwRVHrvln>U8=eY)5FlVJBD>m*tyiJLSC@c?SIePm#0R3v$=9kz=+LtzxYO#@= zsX5!7TP>vM?LjO*oxpPyi*hM8i~ILaaw1dV)u+3#;D>>%Iq*J{cK?8YgjvxODqUj6 z);E~9zB>V>deZutj$|g?K(Q-qJ-45L$SBrrc$2#pk!`!*W83W{;;*e@;i0nx>K$aM zQM9X2mX9`n!UwCml4Ozq6EoL+j35Ynym~OPc9A{1KVjdUL<9j;RpP~lW0}}_K8;J3 zboO<$&1RmSE}K~cyuIW(KH$jGva$s(gT6s!)F z#3VCPuz`%^EaDSvWSC|CKlaW$KB}Vo|L=QuH@zpMhlGS4Kso{n3MgH~ief=g6f63m zsGy)&!HU=s3l>1IQADtSbVL-SL?D5L07*#QWRuE9{1eh^JdiJ-K?#Hm6PNr{0ZCIk}| z8GxnM%IQKQ`2}UPPmgFATL7!oPHJi-ty+Z;6BA5oS|m2B9kqYOJbI)UtJO|IVi-q{ zlu%aIa2rx>yi$I=<$JoVtqjv;s*_I?w7HEae$kt_O|!at@Z8p(+QBR#xUC1|}g_=V1s<#ca$a zI6M`dt%}oCwIoJFQC#vTf0dPx5ZR9Os6>vH93&+=lPY5#Vd1T@m`-CeL=$QdD6K3e zEG&WioTa?@`!N0(&F_Ew7GCeklHg6^rk&;jLT+3YPmMCa7uvB>O;HecnZq1@DIu$ z($B!|?C3-c7V*EIX_@Aq|iI1BNj_3l{SB3f&)2ORzy-{JeAdDRM(o2b*+dG z^{3L9hd#J9fjYom%g*c#1ckS!Ynq$ z$z(_VhkN^W##~cOr4&r7;6Mt>3y2AiM=wA@X%@ku?FcpKuvDL5citZ)#`eJ=TS<;i zp{DXMyG|aZOWG)+17x!EcMuZR9)A%cLZT@z+sodfLb|oNlt@2`(`9Ffjf}%yYoxpu zVnf1^WT|d`t?SsfGIr+dBsx5W=Z~B*hLUBg&6k7ER%yG4~@$ zk#tFHN3pSx(2zK6RY%x!>M(8M`+{U6IVyoIyXUc~Dvg;JU4z+NPNiK(t6;~$t`>7S zC#tNpjcLUnIqR_Llj+^s@t(`FlHb`^QbM1MVF=~|bb;}_v-C#dx=o=?XgGaRyE*V# zmCLXB`)HeZ35j6=6cqnOL{tY%RY$?UHDOXIMb=Q_0_~Jrb;JY(v;X){SoIOahozGc z7R-s_lcdC?ky~pJ_bsm4m-NfSk-wSfg41op=*r}+NiHK?{~@G~Pi}Nxn0I~3<$fdHIu1`|{`~C~ z=I`0d;@dw&?^a*+digdO)K}AUz6y4<1`lnjV!^66m^yX_2De%_rtCu>Gh@RB7T&pp zct3ah!1KhTmiOhl7wF#qVba6ZedEdR^*oB4#_is?P1FXpU-uMKZL-xLbSl;RxURTd z_fv4y(fC^w9Y16j<7#Uq($hl8NDuWm&{tHM$;~fAFZ@MRe>GtLis^BS(s9*Dj{X0oK{@c*CSG6QLF#oLzvW zRu4~Q)ok}gzAyb!tInQC%WqnB(&AO)^JJ%%4a)R?HLlJgz*4J+r?P7Ff9fQ6=Z;lV zPjYv4q;dz#S5j+4PkgS8BFS>yIo*wU)MToyMtlL0uW6pZ;o|LRHZYUMpm4z31xYeZLBYAXk2x|&T&KF1kYV*N?* zN_)KPavWgln&z$Ep6cg`$J6RTO`dvv!FSKf4;Ev}Tc`QI3?yyrJnu9KQFUa94K%Jao8 zEj#|{dC;4UXN{}>@;vAZ`NHdpCtpZupW8$3O;PCjTdkZLpqxf}3dFpnd*X5GP}AeQ z76bvE#%o4g%Xrf7d}WR=wz}HmiPU(Mws@1J?Oy@s>wvU)e3h&GsFhcbk`2Q*n-HeTxLI%z5G zK3hL~OPYaix~mf-CKI`1g%h|Nr5tspJcmd?jVv)8zjmtRK*PFsv!jq?U|x zT~-U+&C%sc2WhH(zLxb?UaQl2)7_lT_-~^YTxpkW!Bz9A1y|Z-TX5BUYQdFu*>lm} z=W0hxjsEeI+|~H%erWRgvVE#0U&{uq-8Z##Z?^lotLIEt3qF-wvYupUk*A%+rruWa zrJOf;zU*u&gLQB1;w`Ny{4KchjaqQkH2xM``9>|cY8rnFuKphSJA?AGdKaM*Y|7uR zq_$P7mF{i3Rcp&oEnTggCsNbvO^#L>t@<`azg8W!%KGX%Z}zCAE9>N~j%w}Ml(zN7 z))rj(WW$CWGEEM!)Rg$r;I6z%8ETI5MYb>7vRc6LWoy@4 zy*%yYd6Vbsma=PyRRgv+K2M!Nd99|y8<0GeQPZPkpITki(zR@B!Ikf}x8SM;S6cin zxN_%f!PUPHS4|~f%V-6?o-pTji?At?vFmSdpmy?VMb+N)_+pFewU!=VqU+|YG(1Jt z&5`L^w%)gO;PJMSP=23Fz&Yi)ew2FLe>apBT&}gS;EU~Q{4KaTd%2!u{qNyQ8#^ty z@@_*5u3B*AP2Rs5S4|~f;ulZksU6*Ruv{a+=0<~Bq*V#m0Kzp*l4Jy-aXG2($Y|#~ zT4mY$gL1w^=Yr7qd?8QeUCSx$kYpLrLw%Kg)mq8OiqqB|c@ABYEV#X_x9*s$dcCqF zgP^t&!jZ0_TbWibU&RkvBnXa!9CfY+3IdW{MyCUtT|lp^lZm!JlseV?q-K*+x3aC& zbSS@-{E{R)P8~-bKWgbpIZhdZAgE$Q4OhzFTI4IPd|fg6ny;01u5sn9E}r_RmhPt7 zs+E2=xKir$WxVob*Fl-Ci7S=ySF5a6eOqwln`}?~|L1V!h5kugHHCbwyRYRnZxJ>n zxN1(6?FyK>A8y~GD6sGQGrYCNgbYZ50=>EfF!{zf^we_OUHM!;Ie{U)0#)_91u7mu z>Eu1UvxsLus>YxPn@uJrR^-0>5=n_Ns0LHYx(R|n_P#T$J*4N}Ya<Y*eIz~-L{`Qj&u1y3iq+4l2_6MS_t zfCcxr($uM}qq4r<+F20l-suPEbTU7Fdy2)YYLH}s(N{)t!^lWvKrdLy%eT`yIY1Q` z2Y)Hx_3iN1jCkylTpvt3^Ih9x*ZR}E_nj3{lF<2!3>+ND#L=y=6q}g#U;(#0VwD+e z001BWNkl;rt>Px{eOuo6}!F3KUcUqn;^?m`!+{zlW!5al550!wvnS! zCP3ESN|tMMwWh6-pIBZlZ7+6wQlKZwz=lJ0@lr!a^o~-edM~p z^2bl}xN=GXcD;aXG&AY?Z00U0L%>e&0e|w%9-EtNS#Ho>kZokqXO22Zc11fXI#F&` z1s^Rfp`fgm?0ps7c0(R_y;y{Qh)6-1g;SM{>!5`h?REf=`DJ4%6@dcdhX-=y$Uu(n zGIIW?!>azPZ(l__7((^<8AQ!8sJzNZX}24<7hHP6uDA5&^lK%CyylIAVKrYdYoIn{KP`~ZVM ztJDBieB2%b@cvVWcyMtAHWE1hJUz)tdcOYX7~lPFBQaJFHandzh^BI1DZihTiHp`@ zG26J{iWEk)k$7NQ9^dY@F??(oFFf9wP?zx1YKKuHq8TwV3V_SU#EeRX6s=ab6-g3 zqHY1mRn^>n^KpJFlX!G?D%T7S#Zpznqcd{(<$#@QZi(aJn`0coU!7h4{$l+OjvzR0 z8NTp%0VhI(*!^P%(!+K9vh*bPzFtmtsSW=?9gz`s7QcRsd7oGF_?#prUK&AED?j>n zcQkiZUIlmGf0C`mGIO6yZx2l-C$+(6`?%wU<&bJI{p2P7t5y`SSpYOwi*b75Ztom$zL|I`Tz%n%)^!&E6Vd`vj& zzbwV-ClVPZQeGi(%iU=t3YFYG^(4O@mzg{zni+Q{pmV{tAi$Lq5*XFTAAm7q!|C1i zAo*5EHrSc>ST;+4u`p(0EKg0117OXkxjgf}k)+Nce6g?%0eTyDoq*|7Ig7qFvVTVv z$1QpmzmrZ%gdVEROu0LU-MKPTrX_LbWf7Q88=3ZCJ_kx7v*~FbIN|E zwzB-E25YT6tyQ$A+XJqFr&f98SmtSh@HNd>UNzmWc6zIqCtYg0?`m?q+2gH@uhfF8 z7F;!@jIVSyxH=c)>n^C0l=hv~N$ySI^R)e^SqVYFQe|i5`XZKobc!Y4SqM(@LywK; z78?08%Su?Nj_4>qHvVj6?n~tyEtCii)e#$^W98RIURYp6HrTl3>Z9y5>Unc+EI)j9 zhFPziakDEhSY-W|CA_`p6mPwEni=;T!Iw`Xr4d zk00fyLlzdkoJ&buB)h+B!*_4w@$GK2mxx7!^i(xDH8@88jh@y<0QMh|*)O zmC4PmVN0=raRUt8dB<^1%W!;u6|XEa12qg7aD<}x0H%!z;QG;rS@%aZufLSTTWba0 zUy#6_&r6uQ%m}6m29C<3ILo7^ryp%sq*decs9s_eQrvz~A06kZXJIs6QjSjo( zOdmNa8hxdils0=9c1;fUgmCV-Jc_VD5r2P~peO^aV***bx||P}mjhN_S$Kw{CLIw$ z0)i+2GS`mDVpExp*JnjD^WGfZ`PQMw*=~{qf*|q5PsM!nPCh#h*f8h>>=m`VFwe*z zc{YM0^t6gG@Wx^zFE2JyWP-pj17V>$=D$(Fs~?-N)>@c2^eAO1VZ8Qu6puf2g0FVh zxOqMxP-N*_r+9bKN#0m=iis0)2tO~1WCJ{Z<01A5VeI&!9j3i!n7yQo-RttX{mp7V zTiTZHm>K=RDYE~pVMmS)KU*!+o-O05M^c$S%AbqJ=KvDdj>)3)*aWt&O5^K!xqSUs zH8ZY1PREIfZ2ByjCm%UZR+;2;aOLb@P1%xf4yg@DYI?mb$~@WRX{_*87p+??zNGtV zgRi!@%5jzF>zJvgt0{}!=K4^{+k&eWT=`<(|01ru(b)!wPCBb|usrQ}`4TmIN(T@{ zuvOZb_snSw0tCec@Y&o{Kq4^M@f^&MD_Ya5YYF|A6m$8MI3Bw$8i?kvpHK1jTUPFW zGKGX1h9L+b$nfpR9d;YBE`KNO^P-tc8(+R}ASj^=&CeX8IFvBklWXrEroE&UrPp+P2cSTY7 zMH!+_fZA&I=G*BtM2Bb)@iz$ku-V8Rmxa~8*H@N6C)k-g`y|1BBJIx$W&Tr12$m{B z1HmR6xa+<&vVJ+qGtb+&`H^ID_k9oUS&RY*dyCeEwNEerZ8$`??KaVdYL6{Zh=lzNiGjAn@g?aw0O#%zh?~wAesq zF6;=vd$Y6Ai%?;-GwHTihIbBz&cXEh_z!meQAu8@op!k<7JX{MUk9JRQ^MGbf|&70 zF6O)A`1s@Ybc_@ogQn|$E7Xyvm8cR|YO8*=bWie?V}U2#u3Pw?b_le{({6@0S-!5w zn_`2Kly&q)m$IyKM?#sdT+OS=_q6lkD#I5aD(zF_ZNZiM?-pGB@8HT8I-8)^8#ODy zawTOT(xqeDrD}JATh;WM7R*V%Yd-9=$(?M;}XI)CGTX z*Suohd^iegEeshPNt{liPxlZe`WqOFrf#>1Nn9cjBnT+)CnNjAT&b9 zh#`^KYGitK_9r+onDdfCIk2@A+kY%#%J?kqc(XmzMuvH4SRI|ib$qLg(keNJXAphY=ko_ZHIk`T|Bwi0ADG9k=e*Ezf1l{bfvlB8C5q z4F`KQg9iOY@`xB-xj&ZG%a0-J+&iwhMq=XKNlYFT#DDHI65s7GOMWqN;~)caut@() zqi7o}pgTX9(Ka2MmK`J1DZ*}NUzQ13Cm;xp_Gl0>tz+WVw*qVv(m-=`LFx33)Oa0t_E5=`CS+(mHT(#gzt$x1P z`cL4hsR5T3|Jep^(9BomI7uyn^kl3uDpqrbs{?ClWom0B{0w@R;L1VOCJBRJ=b@=N z>@U|5Zn1Lj14nt{xqKdcM#zF3Xv6O2k z#WAA4fueHBqrYWDo_so8M!<*BZsjQ^Z4mcGp1^Z*5?JVdyA2s$0YXds3zmGC_4B{Onoqi zTW&ba)^Y*41_liYrYz6Qq+7Fj=)og=o?~bH;1B>r9e_ZO0Re1VcZRE`X7ljFNBMA< zncf`&K_}p+gT*i8^X(sI(k_Z;K(w7bS#~C09qnifn@mlO1pa|^3)XSyu$8@gEj;vC z5nFyWyZOX!moZx;42bo?6*!JWsJ4MvVPx#&Qv?R;kOT{pr)INcaSk^9>s_s*Yp-x^0ASw zT@8Hl@(C9IT+O&kV|aD;aSAGGcxlEFX1-BLkiUS{E)y1}htgH`3DKl;`?!)uXmT)>nbxfBZx}|g`yW6 zD=oWSMv?(Z$FQLh#6{|9pBcuLVTj`;E_#!NVl(5V&AUKio0rv%{Gg^?sjz#vJE;3GIKn!Wql z(mz4R?)|llxIUIYHnj&JHYu1P7lZ;3(JFwE!@>y<5Qt3;Vc7ZpKp+QBnaMitS`Fde1stRrF%a*z0fdt;4n*jJR?W!1pgJi0z?SO%? zV*&_jWnlOaN01hg7{thnf&q~g8#^#CMds@ts+c-6iO24YL6+qDc8hHt%!nc3h=44~ z^)?s+4U8NfPF$oP!!8bI#ISJmacwI;`y!3Q-xf3as(c3DnaIQeK{&Vgy!Aol;H}mVUDMS1qObg}JZgMet5GMP z>&G?SIZk-nVNk1^vmR=;YfYAFb}0F^eB_C=>{YYblaG}=o+d7}iQChzfU8Vzx?6D7 zf-6sQ|690fD)}0i`GUtL>19rpN<>BL@DpWhR)Mk##}Na5K{~>N91UAiY(wX-BP>MZ$fiQ3yi>)t z6>YIuCCba}SnM)_AQBZRB8oDWYN#;T5k!HgC>=Uv>^3MZw`8-_rUsBj&n#a8q|dO{5{MWuEGy+~x3 zqb;mv8KX(UFHlEl5D2nBtsO!`M6$P?r1KT07&SVYK1njOo-g6?chY%qTsUS~BqBsW zM#gNCF_|SqmvCK{ATU@@kiU!s2zG(eI==-+=m^vc7*AL8^t^n&SYsk>U=$k`rBYFD z!!JlrL?9HE*pLy3h;aNTrEG&TV}pN?As|>!crX+e*>JsECWs<2F*+*C>;#4C>Tkyh z0#uu20{k4e>cH`=UwOF=Q7;k{2v!RS1`)koqPW7LPm&-aLXX{Sr^@2EB`Qe*G0}SL zR*BLIJJC^kbUGPifszs%5)c%kCp19DZg=1~C|r+VgM-`id1@7`d$Tnbi$qzO1LG17 zJm>|ewaAoL+R^Dnq9Q~D0cvYxN{x0}C;O=mg348~l1DjkH+N7{l9oQD4&{WSm9I8l zD9d`=c~DMZYC8s6HYn44$p7e4yqBEgns|t5-X|>&9KRa%yE;aMgk< zU*vi!r&jh{;i|B(knHSiqN1V*4GkqID2RZ701O5Lq9|gw+c|RN2*-{cL$BAP*X!}~ z^Q-?D32!#qh)$s zY&CXFX370Q`#P&#>r?+*5bAy?Y!n<%51DJMgoGOi3D8ki?j9sHSSmOUS(O{>(Wsfn ze2;VvFw&^JN}3=F1Q?*&;=qBs&1&u1kXBtI^TLzK*zK}gP}`tR{do+vJnd@u{tqm^ zlGa4&OF8gurK!g2i#~5Unqq@DJ_%O$hANLqwxdvIHD0&UB1i}6G0 z{}qzuhSvdkT5UV79k-fA(eps6HE_DV)<^k<0$*0|+IHc_?+d9a4$(EH(XSH_=OV-@b+UURUUf;9L*{BuPRP#b!_TzVd68Rkc%*=j#rOH~IfvTzTg8 zl&_}$Yy-&Vl+h}y951xm^WToErs!6Zt6Z(!Id61U+e2D|x+i|uZ%vutc$XefdFmif zK02MbuY5?A1Yl>?vgMqvvf~`UYD$mt?t5PW4YxU+c}gcKNtvd+-uUeoe6ZvbmaSOH z#~;4W($znEmFwIIRFb)(kZ-GHXpKmu;vUB?`w|@Bh=2aXzVN$H51T3awfy}34_Jh{KuZv) zDm?>&!0#J3P$_AjNUgL_xe|8$RwE^k)m%fRsTx6OoTv7kwd+UrWEVI1tn?VG)~sRG z`mK&M7eC}3+{xxW#}P#vWmOh8Ii76xG`>d9%Zt9%tG=g{!8Lx7|f=e4eOT54mfB$XhwrZ>2mpkRl_9 z0+qW~5}w?Joq1KPdg(60{LVu{$K2bliqn4M1)GroOVC8VR3|n1OvFqajTQu_|-b~z^FLD%~wuf>Do=a`|=FZ;}WO= z_U_utiNeOO{c*iUW6)9S>`ES260uQM3ermv>dz+{au4+=Pi#X2M z0N#G%J+ccVDr+44uG_y=r}pr~{jvqr7c4*Y}E9FQkD^|yE*HV7GG4o+J-whjn1p=_;)tN|QLwU!$;??_-yIqZS z)?Yh)N8>s#dv^{WuKTT#&9aMMoiD5hkSh)_^N~6Ad2c>;C%X$Q)Kpp<*;rF+0e^pf zTJQ+pY(CV;F0C=v(-_g*$;nfY&=gtT__P8SPr-tgP0g{vSNqg{`x1yL^Str6lG-A! zIdVMJ>)(p2rjV!cpt-waPHNUk?#)rERYraH#PR*`{1-^O=vmf&`Zl``?_=`4<1t&S zNJx!g;f(tT7X%iq`i-!#P+GSMLI74Tet~E~Af?@voUW1Bx8)1cbwNb53T5d}2M|Sp zMRP7g4Cuks+iqjVv!5VP%>y@#LJ$NdKk+e=c;xZNIk0ah z)9$^Ri~CnX z+peH(yEaU`<9P%@;Dr}o;CO{V)yZAVe0nVhwtd7^WBPIPJ+JW1$1l-4Bb{#j2k}>x zK+eWbxO>ty^lFpL^!GMVw0|u-cW-0Hf*qi9L?IEe!2}p2a*NI&NG9gboI*xg60_b} z%dYPivfzUS{IY8=#Z^_<&+K8w%qa}NFr7=TdICWdS-a#V5?Z%m%8irwVtp3nCx2%^ z|GxC?IfNhoG}Z@`C8rN?-GE-SYulO`3qD5_1YVhWGdB$CP5OYV$d^P)e_c-BJ{gR^ z;c+5U8=AyFB7&mQ9o#&y5ABCcq#Q7o7E&Y1tekTvnQb$<{_a9va4xn4t?);Ed!LbdC`C-oyL_y%S zmtP>iu$Wio&tS?8JxOjmoSZTNTh%eH?$?9SBRg|QA3{K#YqGa3udQb3d#`X_xBgsn z>&@Ky%xXlPj^Dq0fmhdNA&Pa+TgnohE}4Sy_;F5E1DxTTgF*b~nnC=YR{|9C=v~*5 zo|eS?rN1E5nyDzNJ@+lL2Y^O zl{o|%g0NN=p=&#ewI4pjeGg8RFE?W@+|Jm^kFYx1$dePJ+5Y=cs%v59^3A+_ zOKa|%^&G`nYq|Z&KgcQDiN0_nyHAzz{v#7vc`T9A@+^LT<7Q@kunlNf#X>dJRvTs@ z;=JK(etjkYOV+QWQ@eP6JzB)qdk!%+F`s8X{*_1Wxs|7u?q>JL_b_6_D4YR`-Dble zK)1ew=+(Y0d6vFh)-jYd?|;a_5`P|k@f|K~eU#;2{7Cm+&KTx6001BWNklF(en?)GVTsCYnPp-&j{IZVE95;1ZSokl*$(Idw&9C@7$hpWgta+E4FSj|Ru9m(g^k%NTyf1ZyP z-oq(#7`wA`cwl%2%fH%$y?8f;u><+-SU&rgze-G(QCv9qYUbW|zT-q#9J>sDVl_K| zJxt+_PkC#zm7~Y9X%`{W^^ym;?e>Ql)HjB8KmUbJSH|b741B*ihqiuuS@q2~y!!r5 zPUjutf@D4Wj+gV=?E4ux^##6qdlq(6!^^mfPM+Y#*S_G$(Y>sD3H*S1YO{mX7v zOiALow>L8BwnzB(*K8KtIh1O%rNMckL{@$+uWkL61*1gfE;&v~{$39MxsL_QcJRyL z16(&G9DVG?TsyEg&p&h>lSf{|`(nt0}DCwu$V|UM3${_vI^u zb-mc(2Mj#@$W(5h^E8Rpzwqnz44=O}ieWb_W!s)(eD`u6uDbO_sQQzF$X;yC+QX6= zvskocKbKi{@LPes9{)K7Rjl9kC)>Whiy1RNrpB7j34JO%R)5C$5kq+VlWpw#^Bbm3 zeu#pi<5X5x0y0@yN3jV4OFr7e;~(r{*>gR3`RyN=_rz?5KKCPQR((YWU2Xj>>5Kta zG3cUedE&9vhsfR83vJ`oz1$JZ{g=0bKSc>P26|KY_=RY z!23_#&f(vF;PP7*@x{&@_O85u!!vVlVaL{$jKAwOmcRQ9xm)J}@aXd!x%}de^%u;YVo^o z|2e*s;!;@m>4y$8O$V89^SzW*o2b>rGj+-c+I8rFpFR*-k_ib3pr-O9v5`siPY-3% z!%x$%Z6bedUB!aepJx4^enbWbb0RMfT3MS<;mS<@ zIGm?ytAkoG;hGE{ed%3H!eF{58yJ20H2`!Sb}6NKM=_l=v1Gwx+%b18Q?9?1s=Bi& zMNz~i!JOAVVCm}Z$np*V`~v(44v)s)vY&gOKg9Oq7B0*PA)sW2-Xa z7vP6Z3gz<4dI2FM$47Jcx1$KvMNFMMiJGwPw25fApX6*(16G1`0@$i(*KZI2dPGW0 zq0D<`6puZ%m^Ze>aQmPn%ytor&C1rV-sYN#x3l%6KM?_9onKv^D-vy-*QY;FgBTXh zJ5Nku_M**<8F2war#!F@fPY&9oX#488CYB7oSA8Bi^w_c!1dnaRg*JlR<<)&+|0IQh??;VB+^y<+Xol7)be((Ud-EtL=zPOy&m=H`gAzU*2asbW* z^<{7yfK(DA04D%A=f08ATY-bu6fPT<0-)Pq|29iuqn4E zU9X$7gQaDsCp-R^an&5z=Zepj&dC`FzBGm!uQI&>WRA4wUVNUcZ=U1)fftjK)P;>Z zcM}~HN?CCcRVJ`hS7IzTf@Gtpu!zXEmk{b#LC?VxX&n;Jik(^fv|%L)nf*z%SCOB8 znjRO8qmShiGCK6)mgkle84<))*WAIvDSf%)u8B-vRK~+M3~yv>Re4$cRB_9s=`5Un z2RA+W1O&^x@%($N{P8CqzxP=#yKw@2N42F(pP}3_z6+;IO9-hyzsg351^V^Rpk4d6 z^|DKfjZ~l7PV9LTff63QeJ~U5o=dO6cT!~y=IyZ=JT&K3zTdEiz84Rnvf9j%BMlEb zBiX2^ay)$AA+saN9nWXRy;t)6_kS^D+$ffPFoms~SJU%?LCArjlvkJt2!&g2c!@Rd zK7r8?&afM=BFwLZduPodl9ME+C$Me#A~xQ&Uz* zyODF)I_EaVKlC(Ei>a!bVg7 z4X4lWNsK&UtoraN*4W$g`tuL7>8CY>2EvwaU*_wtmvJVkAM##{t>MG{`dN(`+n(Xbh~H@kKHkf?EK@L zt}tV+DMbP-mF1N9XD~VT2oJyYEic~r0Dql6)6i!miJH3IFte$W8kU2Sdq>{E0d5e$9)IJV2{X zUFe!>;k7s4pAk(tGvCjhD8hJP?@uZ!b&Su z)iy#x{8{$tCm5}bcRti6RbR&3rrh4~bURCFhn6f)dOhh>etfmrTb^35(41X3=ca?Q zyxO&vEN^Y-OW@>-Uz>8v@!y84zk__mjw|Wr%$YMsO^~aDlpoh~vYfwN4E3G zpFVWS%%n@VPIPGBfjcHo#B3_$>ieHy@|Xb(y<{|{IR_YW>w}Ey-;c=XAh78fdFym8 zNGfLa;b5M5;$g17^gIg7{FwLNV*0m_Q0&eLWOV36Qkx7!z%RnecfVKj{M}sqDj7NbIYxAhpzqL|IlgNxza6(RfBszbvK<5w^ucuPmPux(?)bU5Aw4sbuHDb0 zcek!webrTTY~PvT7Y$|PWy2UfdMIss_vMnyuI9$cmy`9!G46e6COx|)(IGv}(MI}6 zI(N<>H6enY14j^CxQA7{j`8Y?&y$vt!N3lYtX#91XI}e&wh6Ih_UuCOFP{=W=pypZ z2)y$0bOH>qj2n7B@4oX91IFLYh~6E@-TD#hsxukdIR=3E4&A^~LR{ye4DOXdQfw%# z+q9v5+hl?R3|ugF9GCX#NN|9T_@q?2_P&(%Ax2jIcz~IYJxY393?;v>XKx-1?CZEy z5)__9#}26^Lk^LMoww0klbPLt$G%ITc^^gZ3^874xwxC89rXUjmdM~ zq<_aW;#=vkMPxE+U`LXY+tRT^Yf|GQNKS1-Ot_v7UHegVs*-kHqc~n3$K#Lxhy5Fu zac_1&UCnnZKBaZ9D|zImOYnQ=1{mqM32~L=w_c>sO3}x^^VLyo!r18BJ7N z3I=^7o!Z5d-gz+nG9q~A!>_q@`U`YRiEtc*D+r9a^;&j+vxJzzw{Xw6fsDUy0^7e^ zL14-SJTq+~-TDoo=GYEu;s^5Z^<#-@olZhxD$%j=ghjWeUE4(Z_2@-)Q9gq&zn-oc z@dWyb5E{K2ckQf~fVlWx0iS!yamV~MU zEZdUJ!_U1=|Mu~uq$JU6@BpgH3Q5cCO{k$^9QC&Qp?2#?IC8}CyF&-fa>{hIhmF1E ztMPcVQz=jR;I!sk;)8v@`h3Qf2VH7qmF0ZR z*Q$rfWTLFBjKIJ^{Qdpi4hwY#z@??7l$V#+pJC-Z*UI(dOn2pR{=<{&;i9g7aauM4=S>D^7St{+&tyF`m$;^z`Wc4R+6 ztvV1FVNjG&@f+?f+_=TPlUDr!BpJu^Hw~at-NIMeR$oq2S0#5}Kb+K_SFq-nJ-of- zGdhL4^ESqWf?TlM$PWs89A__SZ$`WJ3wK$rS2F*(x+^u^?&HnJr?{=e)mHazX)3nL zk{!YEVoI-d)#@{<>@FFN+Ci3Zp3AlnfC82pq%}tRc3L^$^(1#S`;olU}(hjRY}uFlm-?#{sMA3e!klBD{e$~C~UTCG?t7S)s7 zy)}}vqYGolDtH=#5m&IdI^R9bIiNd(BDwzBb&z)+*4Mba_5p25i z3WyuZGz1)4wtKp+_k~<{fTBuXqe0rK8yZfCuN%0LWh6lWNk$N8B%ivM2#canKgzrL zL}-|3d>Po3epOBkjRRUOe>9ZS3WOS$b(B-u;NG_GJW6?L`SrT${OZPE=bz%DGsMKU zQpjo?xNA+e>VCw{cWSch66@PiO-EyWG8T&+e}6sB!!n&X&>9T2Y|_NA!ls5i>UF95 z*vkZ0UzfV}a0YbBvW?rm!8hLfV`CfDCplM)0}Y%)7Ypri7Uz1KuonyDg5HgINTKbwB{jYo|1g+FUmY$ zgTrRw%B2o!dcDayTU_~il6!7$E;^mg>#K6k$w}^>8qpJ<^V&6COO{$A3XWM`gU5Y> z&?3RDysK@ljnvQp4N;~BNYv6~83adg)nJ|D6@f~AEqfG(H3EiOVCO1GaKCJ%PYFPw zQ8~vXCqmt>R9#w~pM*LY%3U9)OwXNAIdQtz4?uSAvI*2rI9eT1dF|SknmAIuZrm>J z{&G&rD*jWE;aQ(tKl!-@SB=`Pu?}AbQO9phwt7;-qo*JX1pNJ-!-0UazH0tfPjk0b zb%GKa?*M7_8E+Gzsy%MDH0}@HFszp6=~`W$YtRO=pu{G+7H~W08hbLXW_^GMnNoI5GXo`KlU`>62=vi)4A5b#aZY{M0^15AVgI zRRV5$btPTvRu zf*|wsf5vm|eJ>&i0(QHEdm9P}qQDck-N1X_WFrcW*RaTSr>8g6Q~h~A*ACIxufE~R z6W$ut&5IuOJomxS)lZ&mQ0n*fqgGZa$2DEe{yJ_|nN6|9H~(nc;R}zlE}q)jTRnV{ zb#}ON{Bhz!IbJo#Z%wtKxoxRdRw+l#Z{GAY$CegcdAGrvU(dA--hA-i#8p#CtBf)L z^F_8Y?rGLRqrR-TUHO_Szy7yPs^9jvTO~lCq#&2vf^x?Wh(z6MbsV=e3bGGVZfgko zP98tPnM%ih@>EsVugO7jtk5mhwe>^Z`qf|J-{u-_8`~ME;n1POZUN+pQw3OM$F;>$ z3qr%KzgoK^xHz1ZMXl_RZMRBw?>LtKAA9E==S0>0|M$!!+1`Pr_l^ayp`xOoqJj+@ zj|g^n?25f%eJqG#FW3OP0xAeL5RjsvNMG2(0$bQ#lg*~g%rQ#<)LQ>-mN z$f5FD%@>{nob!(v)XE~V$K%r}fY*zsu7vMbtV0DPNusFWpsw9D&&h5FS=swFd5)dD zwxpJK=H8{%Q4&$TUIam)qP#4Sb)v?eQKWM4RbeIIPiO5TW9Z*ObL=*#P`h0^u^i`ttB zisCA?9y5DeQznY5D6Y(S!{I6tGSV5&&Pb_U`(TA4{p`=IQ-pHxO;_K__F^}VqAlD# z<3ax1u$ZZLJj;_;U%(x+*J?W=1Jv*1oRJy)>t9cE;?bv)C&LGKO=jwy|Kj>HN3%S; zh?`G4n;KyL-J`hurFG!=k#lCe;hS`M`Rd!B`SaHm6d%~axRK}a?6VIral#GQRX3AH z#xQQmZDf}=0`SEwdmm>)9;ALa^v$&c|&L7RQv!CbqQRmV~1>?rvi~wx<zGWUZ!8K6z+U!iLZ7Z7BAnx`X5&D^~W>0;K~Pi^_jbwe8(po*f^JK9{UM^J1>~R zuA(w-y7UC@dE!~lIpf~7GT=Nr!x51Q|K`80&>fI&*umt_QKU1H)=G`J#!o9U;h-V*KVS0|8IQrSUQ~#z^V`5W_wv3cbwUuv(7w;E*)aH{H`~-@T~EiI_`J`A%WMv z+|H60CXzn#TuvU^pP5fD(SFqyCJ=|iRcix=QQ1&I$xlYuZ%rpP;y2RU+Kz7~H`IV& z^x2-EA58uruK&~P(SJ7z{zg1Tb%|u~i{dJZE2DZuab<49e+sTzOQ9zG{?E2f-rBvB zyI#4OA!aGgP=?pKT&RkQs=9E?^;8#UQ}3welq+uG)+>hx_+&>FT~D~2*FIRt%QKJV z!#5Z6=3ffGd^4Y=tLJg=%?r5s;emXxww?{kbND^~06)LKn#os;LCeHgxc~O+xqjvg zeD}$_jDK)83l}cov|%WcE2{>pm3diFZa7g(8j^HgR$au*j~bUnAplQ*WJz)C--O4bMKJRvp=hT ze36SU8^`1KenQUT7wOV}B*zc#fM|;)XXS@1{CW%T&3}hpmEZEjdyBNT2VTALPHy{P zJqzY9<9Pcr7|E(0Ud>;ihUgrL^kLl-j zqqM3A&pdW3->v$EZZ;P&-3D;|6-RUYggcn`^qri3R0=Cs?=r+rYjNd2A1b(ox(#3? z!$_u?UOjIlWy}I%xK6Jh49slN%hLO%E&dIbYgWfdZiPhJ-r?-?+YxM&kq?8R|x>bgD>!{s|^gpDUax52E_i^#0yLsT@$v7+P z5PjDai;6`Oa5}YprLCfhDvG!oR7Uj60JK|X0#NU$qtT=A?u?t*QlH4c-aSZ&1&|nX z#%M0Qcm_uve>=%>E)uP_fV@;mB(Z}PJkaP?uvsJ;>@|42D!9CK=+lGlUAi#spZ9a& ziNgYZdg+zdc;S(0T>%b%Rs;X^qaQ6#$5Igii7B1^af;t25 z!>4oU6`!#+tB}pxUSwAG+l)T%awz$YOCC5IxzUbWmH{zPe?^w@N;0<29rHZz}?!nfazAdbN#y?hSmU$L13TX(Q<`Pa;O@>#S;tQ4y2y>#q1fQ2uQ z;nYjEa=hhLo_Ogk@-{8wrNx&8{PfNnb6L1#AN_}k9Dl_sIJ^pR!e{TZce=PDO6QuWLFU-VKkZb>rg!^ zDU!fdkIbX*h#o9_^Ch~9b`HwFkhgOfkIvi1$1mUC;wSHs;wpHRX~d_Oqc3AtHu!od zTlDA57Ae8!TeIQ~RgX~h)!QZrEmxC9=Z*S%xE_~BGynh~07*naRC1x($;_@u_{{i2 zl{c!hoOy@lHcE0T>y_4{BM zIWO2y{YInyO$5t|_9G>CAtTWOf<$e3Ar%c4`t|CpJ@hPy;QIxXD2m#z{{#_Hfa3i* zNEyAzOtNVcDIt(pK~+Hzd?x`_QBYKnBoWklvUAEAIIyo~i!38Z68P%iaX0eaM=!8& zdnXpnz0og`?CczR4;UEOrG5XtTrzv~C(h#gHJ#5cO}8&)jDRS>!Mtn|GJBDcARwzY zB$1|leSDw$a&qX{YXC_$kQD{dS9e7LNfL0>S3_JH2^PrB-b-e$fh5H=*Hc$nM4da9 z?p-o8Bi#<_y%s78cXH=t$Kn~cfbU+o3RzK56(x{;DlXVhMvvaa1lr8^aC&1cxrH?h z?B5Ge@yaR|N%U8e^G@xD<%}9>#Ky)U ziXugY#dPl06;*bDD$wYWNsNzc5kyRJ6$1RB0%!2`U>>86Y!(=df?hbDaB@SH3sp8! z*=?mr>Kh4PsCL!2m(gc9ej^=`w2hI>P`(J(>!<%nT!qMY_?bAT-aewK{{<9x?-7OUL=M6ABrfdjOy)0)nWLnBIlNbl)CIfsI0gOKShC zs!C>$zJcq4pbhMzs15%9$yBf{{!c}Tr(eHb$clm_2!V;2UyZYTD+|8e%PU_#9MG#M z3jO-^14RZ&LRA!c^y&l1D5{7tG*s=Ms?x2uwwt`HfGBB3D~h5upih3UzI{R4*0gEX z6;$ik_#^~T`^8|Ne*FOj6%7CapsET9shvr{zoRwCf|aCr8(%G+hcx05UVU&10HPou z`)_+H3YlGdfGnd1UNzwJvo(=^eG&um^!2>+eo&N zT(dxFw6fF(V6*xd1!}W%{_ke|MuUM~zur!>0nThdF_IZdS19?116TTX4Ytv!E=Kkl z)y-@`G{Z|2S5aK)?fY-UReQ+D_V&We;`MPEAvo^=cOR%>@7^7BZN{)!MN zV-}d3afb+${%aN04xA1Z0Rh3PkeQKy#Ui4rO?H%*+i^B{T5QOwqHUAWrAsoRDB!TW zsi<@qzOF}6R61uS5fj_whhRI50-v5IRIo7{81w^KYX&|e8D_f7uIUE@vw_7dQ0qU9 zg16aVWad*ddrae%jzSIaW^HCx?{GdcYX>tdgv6CWTkGqg*BQlC6jw(2{*&TWBxK}o z{kdS7ZJBH}d&oVKiBd4>9UDqkFkp?qqL=Brh@!~IiuPc5RoO;f_ngYqLtBf_{~-n7lNR&^q2Q3b||Pm*?yZH6@M{n;lsFn@)T7;_T7T@%3c&zLGjtA z*{j*7(i}Ll;>9a_o7Y3}1}1olss!wkWe;9O)+RH8z{lUePq9-*FxW>*^}U;|FsFj~ z3-<8N`+M0_+!$yFSyqu{e;aApF_1S4zlh7_#a{2GQ)UuY ztAx!aVfFnbC&v&MYo(%GdnWMU!D_m9PoZ146gqZHq+`cKI(155#z-G~! z#LynSwU>{G7T-1P9h-g(1kwggvZIezx zP@3xODJHveJ00RAWSaY4RaFF0penzVPrfVT^mF@i>3LmPGH(wBbuxmWJ-0=mZM6Ng z{19?fIVrF3`h4xPSZtcK1=<$@*(&@bQ~Xinh)`D z4C$ZJHpl8<< z;$p2>tr8tG5*Rw5Be8K3`wOcA{OCRs!zNxT0pNg}owsi}^>bGvtyVzCIs z##)eNg}r;qvDqZUz7Tw@|8CZg!ci!>;bfWhTQm7a$D#O){(`UR%Z7?0W;TZk!e#?v zYvPreEur|0Y>UJ$v*S>5qPU9UDx6(r$A33m9ZqU%(#cP)zC~!3#tX$4d~9^y_eC?% z_gxSKiVIhA)50q#wpTFbBiClJVP6uL9e)D%%{!U3 zMLDFWox=N9zs8$iUd+$scH*pEd3XAc#MG~5>RaPT>@a~CxrA#k{ej`~8m4`GC#B8< zj6LCVo}Vxgo3%48`&RD#_&%)3@zgi;=k4oe^WeKzP%b3V(6EUq=P&1+^g5=$KbeG# zY~_s)_7iV|^Z}h1)yc-z^#zm{lpHM0uRX;1mvqA-Nr0CR-p?T>(MF|R=Gv*f z`Q)8!sv2a@m^6sv`o!v$gCKCI%+A0*8F;-=SX>{N%(>kPNl8{ZcS>MSuB+*lLB5Gz zX6Gcb_m)#%@8Xzay8}>H*YrzDzsm&y{`{keL4!N8Yi9|WnMs;@y&q`4YSMo{9BFVf zec|Nj`9j$jOh$3QOn<0VZZLm1IpO&Awg&TRL)GV-VbIzGRuyHI@cPTqqvIV z%FGx4ZMZsI)Lvcf+6OC?aZ>-;$+I5v}0aflDUznNoB{gK7D zyoR@SGm5*KC%*kBXN>uZKOe~_ck5NG%qbw=;>II%=HioYW9GP7cpI`f)Zn5*-NRGU z=JD1=vna@4$;a!SVa(Y}cyY=+j!v@TRTL`ie=_yrWvsaRWoCWz1a*z|6jp8^K64an z?^#BLb0gh*AH_wd-p#kS&!e_<4PA%c$$*YYOg!O19yt4Hux7Dt4O0uLG>zF(=)jG znjwhgF3!4qAQML@!-7+4xc009S-()&<)O;iRUda?p*?Y?=FL$6QDw{VIwCoqYufvY$ zOhSTxd*lQbK1+ir4e%Pmfa~+ewd2A}%Hti`9nJngU`b zaS|x92e+coJ$(S!deI>vk!q)lSX(Rw2Y%p_P0Prs+KnaFMy%*2MmmlZ3n;{pZnM&$ zSm=_H2tc>QUU(D_q8LZl^b|7FdLqa!R0J$y3|8RLPtU@ZaT5!!oP#76asPX#((|~_ zdHdW+)E)SmxvO8GToFh~${<1X{aO%+72-&?0hV+WxgL+0LDx6{8_6+N>@JxTdJP2{ z8QEIx5Cg;} zSg{0QqqfFLZeAS+e6Jr8M1k#V3dyOBW$M(y+7!`9zEj$=$sit z0$`COY!>YnB!D0Z)K%28Wore+6&@s;1)EL8Vv$G)%GG)s+~nuilYh{T?={o(=#oOt z{wmyFg@OH3>Dwon9^JLJRTYKY0~K^kjcrO%ivkXZn~Dkt-MS|e7iS?Z&O%;pC01+8 zZq?Z6p`pQz#UfH$>%{9-TJVJH8*SkUw+L#l{!nGYrSc=WRncC1%1N%Icq0 zJe?lqy*>k|sMjU}c4r0gUKOv$PHD{{h8+JOjy0!n&U3@4b64}+MW0aZE?~#*E#x`N z`J-SD7oIkY=?l(f+@{{BfRF3R7fg}4(2(+Jyz$xeV;MLc2__V&BSZ4#dju`Gf%f|L)UNXB0lk56a*cli|clE`<&a9U4jv}-Tnw%2>&zj7$9jwf$hC1WqoWa!WsKKSw= z$&Om8lhXk$OV+DzI=%X)H{nPS7<6P3FMpUr!Txk4hn?6yX>>{!+2WE>WCgFH;lk;Z zQ2~!z#v`jZonBN`rNOD7xV$**B5r3Rl_d=vJlKH8BL{B9sj5nBMiS%3CizdG0#>WY zuz{V(*;hkivPAdH6pBh3us75rdnLMbOd>5UrfIdLs3auVIO*ix96D4-eVvOVkJ4^| z2Hzr7eGmWtw&4K1dZ*E+Zw6UeW&Hlz0Zty>C$j#~#*ThC0!~{3p4lyo!$D>PS0w(4 zq+ac{)#$cLTV%A=CZk(9A$ePET@+WL%0_YZpBt~*ORbqq2d=3>p75vGLTxna-$2y= z=ig*Bl8r`Z+lb%0|=kD5y>MUho=OG~5DXVWFBO#75dpV#YNFs4kA`W*w2r8l&M`lu2 zDyw!<>9vv>pN3aVCP}QtNg8Q!HVz#6gK8y>;oY?TvI#C-aI1*!Q z)Y;2PO3cLVtiUBJG!jFn#FVB@OAP{4O|1vF(?wxX176WW&+c(Zf`F^RO+m4f)DCe- zDx{^^sHtqAqF$j_&qP$02bUs}lps=D>me~E2HEMRps0bAjtO*1wV*00g++E$iu@`e7I5r6QpnVfI~h8af8+P+1ZrAxIk=babUP9vM5xQgQHKP_HC>oywo zZy@@AzR_qTxA!8w7aR&m`q^I#IsPmG0-e$a(aC>aN~CLQBC4vAlH9|0GM&ybnp|64 z2ZqLV2ABc%v`XP(PzBJ@H8u`s?sri5FG=mB|0UgqXPZ9pWMu> zcx#Min4zrZ5Sidd<<@dlLlTydSW^qQqlkwq(m}PwOdVH(~_FWOHJt5?6_mb z5i~y&ORUcwy}BGrFP~RbRiJz4QFQkmTVm2k^zkJpW`e2`6W4(lAlby{!EJG<#6d-c z3&|n?Uh?wl@z2NvL7=Ka%gB^hH2Tg#eqJ5^=Zg;ccuUI~17)hq8>lMt>jQ9OuXEva zdPqyP8Fr51Vh80FjaV!Kcs%6g`Q9fP%<7*h`gAoNYoBH1jXr$}C1u_~F6qyCmaDgh4;M$s1YPf(N>451!4*oQ&hZ%3U zLB@Z+Rq=|JZ53|tHM21i8;oQG+aGC}D6X3GMRCRcolV{Gmv%zu5%K ztdS!Hyk1sY&xdkgu$_@~u3#{B?>d$jt{)pL8MOsCeV=CfL(RBtow?`Am+=py8c%aM zX7=fM%mE|N+~i=t=)Z&~RaF@>C=~`pT%_G(wz3;CD1{+|QvNNv%>q=%4zYCV*v-ca z&^#z<-(k?;PJz9@^dtyP812(H14YqpqZ*MY3Whc{m)EudD3ZWo7SQzH+Y_`7X8>yt znb{P|*4D-=BU~8`5N2%{Y61|B+BA5Z*cgeP*78JgWn3mwS$`{BMPO5?a;@PxoS0~< zkIeWF`$O(+x&;{(KZyt>ZbIm;;MDJ z{+DnS%5JlTf26Y7wUc|KldEt#`~#X%+Sus4Q5r8)79dpGFBIT|?TRD~+45FW=uA!U zx!}Rw=vsSH?nbk4|AfLXU#~;&BQrml`9j~hL)Aks+bG3sWM8<|MHE+2T!pGv6jxDP z>2*eN)tvsWxM~fBYU8#for0-NJGn>7r&neMFjZB-?^s%bTwmTSqY$ahk#-!jj%2oK ziDV{h#1pEHMm)i?%;cJZHMoqCe?x&h68{*romqRDwVjzw;c#J8*KoE4^F?tL#nt~D zuKdRllr@zR#+E3q{s(boLjMk2wPliJW@me4wdolwGr;S4%o-*Vqs?aVMm&+oige~3 zi5+HT!mT_)*%!`cqjQn0a6+|FYuiV^iZNQHgz`slzzC%))b&X8grX>}qPQ};9>tZh z?$+py;wp-(P&WU&aMfB0H6aW)X$?p1dQ}dztWY?E!gU5cPoy*BQ1Zjg$V1sb^yT#5Lv;=#xxwEI(dKvjge=drvD6Ya$6jv?vL~+&9 zHod-Z6vb6bJ^#OP)f#He1huu)u3r%vRi-UQgrZ1h{;i!Ex5mauRuHX`+ghJRl5TCQ zj7U3uD2g=51*gozk=e?py|#wZVI(t(t0=BoOHo`!aTUeYe@ge>U3? zQg^LsGSGBh4=y!~?q<9`U8-X6D-tl=5y?!pqJ(;2&-fwAX0lW@uuFL)oju$tK~-DU zOY@CZR#A1f`t%2MH8V}uzCzP^JtmCEtgVf%8@6dH(#mGKLfK&C+hD9kl5#ilLu-Os zTY_}(Ia6GP(cM~HMapaD-$?9;;>x@ZM*LA+MRE0a##L+Ra8ADU`Xkz=;cy!riu{cu ziUPkcF6E`qsJq zuMX^)6<#+8A{@-OBZvY&ykEqMT@Jo@v5*xzoQS?jR;YRhAB&>Eub&^{k}0`Nou1G1 z+wz$@V;@&spGTP|^iOhC-^(0p${if4ltZS#Lj{KB*Hr{jpm=*F7f;IK)vs%OzR~<8 zH9Gj`EqPotIfq+k6;R^^Q4sijZ5h*UEkw}m5B2Nf049CDyF2VMn&Rh5X=|x4uq( z%IIt3ya@@MJlM;(>z$l`ZUSeX6i<@1xqiR91Gf04Ecf1cfPJ$0{rh0u{uO{f|Bql}zoILUTL7urg zoBk(lXa4dU1VNzD?&QuHyBT@f4kq7{hX*eYyjV@v)*3!qTT2{noE{k2*T%4;UTijz)D)4o=jPMv=pD@cv_fl>M2SKDB>=p3Cy(B? zht7j`@W7lR+z7bq8+rKdJ#^~7jmvM(CAZ9jAP8iwE9IEuw{!77_cQO6Jf8iy0#Ovm z*;c`26LvEAq@65SUfrU@wPhvgZ;Rlxy%DyJ((l1-8VcunGD>+zYPV+d-19=e{Hr?>B~gr zWx3f^>9!Y zpx&+^yS4i5`Q-rjed1;1PeXX^u5@mApcrs-_4I>0^!h+Pd7uL~-LjvIK`9LDY2(VP zJF{nF2{*snz_+W1@Z9BzTy}Xb;AF~!mAwDOAl`c*jccdo1+_7(``{q=zSYP#%LjAa zNh0Ge%BIWF8H^fkVdBILIwtwyTX52ue!qIZ&rqNp4(E|ZO`hjK(03ywyWl9EO? zRNI&_DUSPR7LeNrWqA#}^r@C1oIW|5H~)gypUL3$r;E7n^>P-@+t2GOM85gFC*`Z^ zc=D54aMyF@B?SyQBb9T9s@(Zh4ZDjJD6Zw?GxBlujOVsV@l2nV$LvMb04O@_nRT2{ zpZcH`>UuE#^?^zsV2$k1_b;z`&pG#GnEI`sAjmkF+~kvyXyua{+{ueI%@ z=QZ+|ejw483$8;Xa`oj}V{a5!QCykH)t76Hz5mO&YAuD**)?xl8H-8;aE!z>kfKYyRwRFr}kpr zLp9XZz@wiHV(H>qo_(>1U;lE`|9ohAHeO}uQSsb*VJe_7F0+zCyUMd~4&kdsHOzVO z5P#--8F`Y(pdnV0(^RYosG^F93X%m-89ma*EmQNDaeYTVo8O;~)+SKZyi`0-zdhc3({HB7f^#UiPNfiBVr_w5M-_2b) zvWJCjU)RzQ3mezeW9=Ht+b{Q}vlaHObFgf6J@-sXLs7sYneWOR4s&K?6x_|O8C^FE zC`RSX>zkzFEj;*b~`JOU{xGWT7Q!$+&@8FO|=uDT$OMpyIlimamL#1!mamBbj8d#~KZ zmwz}p^~{c3Jw6e^tbx zODA^V+=(5TKd(1QqLq2?58|75dSl;R&FSZ5Q{33pi7YZmZhzaVcx(bz3A{46edh(A z@x#(AtX@~oeushptY2C}-(kD>d8>=W1ObbrwT;WEU=y_$A8S8B^hp<>&MpJ6bwf3O z3rE5dO0wbss1dLu2@RvAY8?U5BKt6(P2EGyvuemH#G8vU)25ye&Hc0_R% zxs3lsT(w1Sd*lUEyLNInnze_Tod*AfI}hNIVf&gYzFAtrC!ZDb;i7T|o}9p&&lmE0 zj)QMr+sBH7F&y7NmY6gvugxuH>!vd1eq|>np}8!3qe8u1X4LphR=iP+(mjP(QN-m^ z5EO;%QkgT($zWKzoA*AoBZw-Btm5)bB%H3Mdbt}_6h)=rpv(p5rPDjn%}Wcaaf&L5 zNfLkjQA2*c2SEk5|4yaoVeGK&EZOU3+O!VzP8JZXO+HKQnaXW9_29OfdU4#4_!g@L zRZ(%e6aY#K-Si!hz(wQYSnys6xlR>})5%FEY-MwW!1e#=KnGMjfZOin%P-0}c1#C; zTT)J`pi-Gt$)z_JlSnp@24W!Mz2_j z#zq;h(u4s8fd`-HLa!1hqt4pR?f2wy&HW`vNwJI@9)sO3)8N!>7iDddC95j3SHaE*J;+Q1lS~t_CWOLiC*(}`S<>E7v0FcDySTn+%*=kN-M*nGaJ(P@am^agF_7{qb z>8%;;N-Bp~|&} zA}!MvJ+xN>{ zIxd+Z!xHJ8X$d?SUt8>^^AU**=^cmLqHyu$o#>GvQdH<-_z4|2XS9X6uT-%7cNf#H zPs8q%IBBpAx5dh_Lv0ikDV%X~5&|k!#U4hSmddFkY`p$@IX`T2bN{Uw9Qe!2S(7?a zyT#7h12FEW7?QfjGO(+53-6M1VwwL=C7*rg;MxbeF=1pvV2>_UZT{y!=W9;fjWU&u z5@(*6$j}oK+3|A?bLZD^+Qc+^+g19X-hrzo#4zWja+dw-VCh5{$sa%C=<(uo)D$Yj`%81`wlL;p9&ZYFVQRlq}25CQcrY z2U(W!dcAnPUOXO8;Lq)L2mbumhYcG>@7}!)0Tk>=mMzoHPn_tp0Se2!q$i2mZ72a$ zS*4=Vixel3>dR17RmsSTiXe$}NEMM4E%PP26dK&xBkHOOiK!AaD%3eu($g$7I=nbN zke+72Ugtp-CDKy_1fbplaWN`&PKdWctwSX}MWnjMi;6%>nuMc92CGO)l7J*aZM{lT zqCk1MOj-vCi>zYzfF!FpTq*)8q9l=)Dj*8rs8_HzDiQ9nr6O4*QW6BJYQ3ncKx(=~ zj0ARviY;EmQSC*MMADMAI@s$K9E}RG@fK2(1u9BCNU;`D5&;#etFQ6M%}BsoC< z96{s0puF6R6eE(BDp6bMMU0h5vO#&Z=GU}T2>}&B6{xK7Vu_JRP5?m_aC;#s#X{j9 z#TmX>&ljn!Ms`M`GhEqFwwh(G&5pwb+t##&*}xI1twOa~u>Mf|k^19rhbv#) zWx|B8c1EHzT-hkD{zq`t3Oggw8Lq7UdueGYd3kxHr>B#Yltg@dJh8E{Sglq>QACzy za&mIW&(FtVv0$-Su-R;ZKdaRmn3M%i&a75zvx%2~!ls{S`Kj5XO5qw&PoeljHHy)! zv{_j|R#e`9zl`{VcD*h!O8-ry0+Pg=vwKro;-tY1Z_Mk9(kS!cr_naP)t@iXhW-CQ~aEfG=7JM#LUocy_gR7S@}{kFBbjeH)?PP5f= zD0yc5;cPaOZDvQPI{fW$74#WOS0s8NimOO$HM8Tt3RnN1fSsM!Q7-0U-y zP`xpF!-D08TFI!YiYN%!tOAce)UDOFL@7#ol7fCgXtb&ez809JsVe?lp3%xsFH0YQ zTJ#B@Y(rk~Wm;SIg(hCVh~}&LP-JvnRnV(9@E) znQomdvsj_m87{8)WvRZl6$QNxe@j5Hp=RwGn3Ndk(c2X)M}I!p2m1DHIY_l^tG4*U zEY?R7|08LK;Lk{LWmG1dPP0i=B=#RpT$xd*F*OpoVdIqnPg~8?pBs<%mv`U_H``zVN)}n%}YOF>DpZ_^yzIfs=sN6(_YGh zvt%dNUwaq1RUVpJ&$xbmQI!XG^Xs2`0=%Vreqq_VeLlJ7Hq;g6uz7nK&32(KWpW7Tp>8U@1u z73{NSebeorszJq3xQQ=+*r{F9=@opRA`V`8`T=gd?LKxD+7U&8zg92hmrZ%iZF>qQ?N}&^$WL>4IWhLDobhb=-W_0X)I;IhhO2+?N8T&R24yWvSP(5+z5eZ zDMQ&1uC1yHcCmJIKG}b*W#i7G7VWV4$M2|Bnzxm{{-$kiqSMHSZN-(o?s_@laHY4& zOt0CoS^doFXvAw&zesQusca*=%xn%9uR_^mL~Ze(-u}M>t|FyK>jII_jr4r2-pSpp zVxjngl^YG#!PorX1z_=$m+*2 zj6B$;!rkBU`d6iFTmJ>$ZK&6D`gsT+C}qWWPHlc&QMAvu?t7VQZoSITCjv@HANoHf zYaCrt1+KYj3MFnp_abFgRZ(PZTZ5~QPUYfTJ|HvM&cu@j@Z|DBs(*ij$6r{{tV~^Y z4kcxkE%XUQ0_v7^QB@UGZ3VyRuA3Nm?o|4xTWP+g*JDHt$ST{tfo02n3UFF%HdJhZ zQcZqsKG4YD+$S zN0z;c@3@I~|Ic4BdD2)ae8+!&H;3zPypBdd(A}e-JNI1*YrPmPLN zpQJYHFRIdl*C;y__$>LI9^E@*vFfjZ=qzI9O^;D8==JM%x%T}%|KegC-ry{q|C0H@ zV%FCj<$HN~{!hduCnF%Er;TqtffDqKSffmZS$52bjQGvsv%Z{JeAnAzwonbe9&Tao zml^zBUw=KXkqzPM7%IaSs_sTQjCg|kXr$v{qzir{9~j9tJ2o5p|Bkq7Erlx6T6uc= zTm68O9w?FUwUsI>>gjj%@nocTWE>5CSu4Q4g;Ph3;>cmcS-M4A-O7T5T(OS%+db?q z-NmyneZY4g&!ta-iY+aJ@`HbJ@ljpqd(=2&K<+5u@FoH>_g;B2f*>&Y)@P6ff!A)m znE1p*1|BnpzYc*T_glJjietp-H*?XMW67!%s4f15Ba@O5;(M}S`NlvXa~;^kZJ++i z`jt!ZI1g~@s1XbvIh@zN-hm)^x#g;J=rd>_H#{{TK@j=ntCu*Y|6s0p;1<-hE`j#8 zR~D03BeQGe8{Bf+MEdmX%M)*|LKFo)d2Twxh7RVu$q(U4N+h*w278yi!OCs>5d|;L zKJzq{^)hqr9Lv$;Ch^kZpBOkKne3dsxIK2}K6fWKOg)aw?kBOM7^)7eVc5{4xMbq# z+%fZg1kv9WM3PcF`Z|V&pPG`rOub+@efu2CYl}8hzIP>$&-nq#BJ#?N>Ezm*2GB-D z<>XPL`S^oB0QmO3KNxY&O(^afp1Ac&`VAVys4+JIkeuF`82f%^Jv@Ucla6A*Q5RG0 z7RcTD17{8!!hnIjnfuLVc5hkB!k1s+%XNQpU~3UQ$Bg3C;XTOz=>x_OAHv`fmy%sv z5onKt8<#NVloJ^`a4;`@`WHg|Hm-mAGbBmm^S9n)@scI1`EeC@KE9ToV|wxA`4=#_ z|3KdOekY;;|C%|49{u`r)dR1B(#W$<-Nv<(N7A*=Sc)3pr!}8&?|pZ%b6*8H<#kZ` zJEt5siXlfF#h057A_xK&Nnra|Pg9b990&hc&g&oj#9L3?h2WOS=+u#o3tpyA*EB|5 z{2~CcqMNuh8_1=c*|Q^p(1C|vT!K=wg=3ByNNh?vm*4s_f+(`_AX;%2? zrF-e#yB`y7e1Jv-ayEQPpT7M$=B#tsSp@rjTf~`XPhr@Q-rVubhk?noAPD^Y*(>xI za57V_dw?Fj22)jVfSP)Vy_>#c_%S0m>A3UQUIobmRPLEDfj)zVvusCMyW?w=q7D0Xk_BuPgj=!7VH~q=3UzSi_ zTg0YK#i;Hgw(L8R)$6iI{o{4M-(8I;D1d^?)`wrVY~`&x2k_|2i%3b1ZL-b(nKTev z*3bM_1M9wgf}|71^T1_S^Uj)G?Ao}1e_eeUg$*?vJfN+z|IFTph{CGfJ6OAUCu902 z05E3eEGCbiz|?U^Qch?7+L^`6_l@M4w|CQTq?@01sk||JE@$0x5>v*V!<}!hX6Nor z%)a+g_7`NK^gN4gi=Jc8=2fKkJ%tOdxR&`ZOkm8Y@m%+>CG7b5Wu~1!4H>YCP_%mo zmLaDxBpJN2!nyyrohhgFpuy2dP32DBT9-@5(v`fn!A{MNZ`hhu%gT8-@lkGnJdXWz z7Aq;KchPmoNo?4(ftb3TeDM8drcb<*bMEx&BYW8nP~)9 z9Tv$-Lunp%mlIIgx4(>KAJ5@e$9T5=yojT^SWs2S-n|u^ZO!O24J-ygL|?-bj5-1>HxSL*CxKoZP31FW2qICJ7|Od-&vwQa)O= zo#$qB<*kqZq`~Rs@g-~6{KH3l{>*(0J!KNN-uVERjy{S{m#v`B@i#MJNC#%!J&UW} zUdht;r=fbAe$rW1;o{j3mb3Ny=Xw8~*?@zc+sXjgUzkr~?~zsEqpn96i>hW3+G*U3$y3GP5=0P z?8&R;q3f>anZ>`6wSEcZ`?3OdHQ%4U*K+F10e`F5Fbhcq{XhcdMLe{RI+5Po1 zlmXknT||yu;4e@&0_u6FY?7}FVf(xV*HeQ`DjZiH;s~5 zv+8r~)%!VN(w%(0rI;@tJCC!*jHbA@k+QNwc%7x(dD~3J&3KNtU%U}XkhtW+^NE$< z$rqnwa7s4sF5SxSpT9#+RUbNcO+d87@auQ4a`Ov$9I7ecr$?qUcd2&kS_Gy|nZm8_ z7VyKoyRnK;oBJ~lf4Ggp{dpYES{|CSklXHjl+V}h;e$I)=KRUisk9fNbQ{dBtoO&{~Ql+wgx;*6g}jW~VLkBc=ApF{{JBL-*k*@0aoa*gNkqDT?jy zf4Y0Z?rhG1wB($#B1VFM*MwqLz=-J@uGj1}XUsVQ21Lw)0To0=5hUj&>=HKT-O1D4 z?;jI(cIck4tXJ>v-Sa%KGhHWD)wilnRrj3!zl5u{mWzhkJd=A{bu7TkPtE0D4?N4x ztsB|>(?d)-`4$p#;^;GYAOOi}-jfE&XhM;#jF~nOfD^_Pu)SnKW@MoFZf!yHtw9C2`{4_DR0Lfb3y@i_Ed&v0Q6)+Ka~U33KmNu0C90f zz(&XJ)5%Np-q!HyawECDY2bJMxRjZ*X7ko(Ye8E=g5)GipxRg{(csS^iSoP^+T>tPw&OPTWRJ^b9>Ck5gp6y?; zvmOkR$igSC;-2?+5N{G0GVWTklM~1($O5Me$zaB0lqfGPq0jh<7%W|wHRC)i@*y67 z>TMo-@-31SGg*mlw$vpuX~Hq2cOOs3tRxg$8Gkh8GW+6TbQy9gnemBKG}r@uW|Usi&8Qnb_fN@6;<>0{vEEWp@ zDRJ=xKS3ocZn8$42Ad1H<^C01KY1{XRu`@cD?fhmI+tB_HNR{vCoMtp{#w@ANQa># zyu#+LSWF(ui+6G7^;h$+2VWsKF9+G<1VIKQjFKVX=gZ4hviGf9IsdXd_^q%i;KQap z+j#1R+1&d0LQLshK=oiSdvTkP6p!k0;gVA^0!EL8Q%>v!Dx{~UQ?hkGioKkhubV?! zkK-svl*t)5lx#pTb;n|s5oITFqKY6Iu*ensZ12msPC!a`CXMP7@S}ULfvj9sh>SPc z>zy+u^8NlMjDpGuXHO(9t$?06@u+|~&WzcpQd?Ec*vKXWFjDOJ4k_!C?@^I~54-OW$m ze2KEBo@Xz1Y8XFDAvxjn`enA*Bz)I+*a(+Ii*CTX_ES{aiME zJQbBP$BrHZz?4a2*;VKbcx%e`lhdgy07FkY2Dj6OB${ZjD!lvkDmH)i9M|0Y6u+$5 zL4HO7$MiKoVj>B~gaBOiDB4B7Ef%J>ocCKR*BXDcZe>OCEtZA;&j?bEgxb1(v0jUY z+8S3!LPu)9%`>@&yO*o=%vQK(f8wil(4ogEEc*BZuDSdrCY*aF?wTsD0ROjK5s zH~S8t%2?~_K(66~AFH_b-#5{RZW{nLTN5rMEVW-T_x&HZXW~%^d83$qd=GZ+D8&GXs*IF9mPf8Wi9V?UCywdN zx&L~ZVg0hPH`d7dJZ}I1AOJ~3K~zv#<$c+4O=Trc4>%fYsH(Lx<@~Gp`N<18bNVO- zopc&|N^4oYXB+(n^`Nn~luf&2UVq?3&KcU7@h1-8K&cBcr4!H2OrUqKF`U%DJ1GN( zF|KEPpze;kD(V{G%-P2?>-;(F;eSG-+1}2_Rzzw(G!l&~d=AB>anR(U_mVN## zOTPJ#HWt&&>Q%z59x$ZoY_id)m;h?e6 zjx5X6)q9^QwA-3+d)$2a{t_mibtPw?(1YK1>_$rN$krX}_t=YZ!d)3{upCoO9_F*ekb?nvq0RO)U!GblPaJdPq%8(nVs8Ct;U7hT4-pMPdgJrs28LX-73D#>Bes2&t_?#-}a=Thbt z>D>1?M!L5${G`eB9yF1D!*Af;2kvCaH{Wyhu|}@A?m}!G$1?e--Y5nSq9LBDIuEn% zpHGKzbLi|`&pz8IE*+nTVslegR?f&_6Ud>M^t>FF{I~_loEd1}drr*Z+>7tw-A8Za zy~V2-c8j{I;$bx2wT>TIzC8Z?pR+ zOwGA9+96zn1ObvT*X@c=g&QTEFz_6wXF8eusY6t5c-1 zSld_6exx@3yW=WWidH6?IOi}KH7G>$N88~NjrtRa1}7TzCl-yAXw-k(Fxa_(`JjY% zg5Z7FRuo|KuM7EV<$k&h8PAMKW2h_J%|T}-1G=R0>+0ZXA+DH^ z$5E%uq<^R8*UjwT`U~?uU&XZ3&%jzIFubpUeT|u9s{3(Ry3skqgd%$oB?C9jIh#}d zIgjId#RDpf=f6l%LpC>Da~2Zt!>6yX*Ot!c{v#PUIG>fP_AvgazRfMFy4d>rAM_tR zmJPoxrF@t;2rHgm5X{y{yku8f{ zLkUf$0t&K3e*9$@#~$6Ex{^YkeeFF?I^$xF>Yhk(wUaKLI`G~5FSETdk8xx27%*rQ zwHtrr&2Ro-XurM;Jz*mC2ey;jxhI8%dl)#dACB5G_EigbO4hKe#z?mD09QY}h3&sQ z?Q2aBzph-))}2MDicD_*v79n)FkdcSz?Py~=3IXr$wpYe@=KN%)^kFi0(y=)ngm~v zRl0LMN_uzlk`z{N+RfNeBUt_W4n~ja!;%l@vGqVbr%XGJ__#D0YHf7up2OBXm5d(T zlhOl4Sfwnw84mH>8w=?%b`tr?3Im3XW$h1NQZIESEz!W};k~^NuDffP`_xOMcNxqj zGo}IF^aD!6L7skT9(|6QN`@#g^5}t-Z2pROzS_amQ%|R3PA)>(R=(d^&QX2xNa`_^ zB%z7lHkUAFa4)KgH}TTE&p3M0nVc}XAHQ$h!N|dVs4YLpp@w({_O$T92cIx<+%Ys* zO$_Ok!;<-P+3o4fwX>!lwrl(Bqj#vaiJW@&d8C=4c*Cz$Cv<06&tz77w~DbRoxtv& zf56ydG`(^Y_~rXgSiifPvoE-m>;wn%-gp~J)<`<0SJA!y2$n2(ml{%;IIw}y6Q9B6 zE(EoP58i$sXG%XVI^%fn!|?tI*HOpoZ_Yza=)lDnPsap&_30wy%-&2JH<+0PNz_e$ zj!&Mr1l3i~4=Xlu!o=~^?E9SspZv_|$>%Y)U#@q4lodpS#1HddU~8j^!NW!|e(Yde z^#^$B`T6u5KAtls9|O2~o$a4n zwHAcXhlE>v4oNf`DicmuC|~gWuJjdaAx3@yUtB4Q+Txcx2iCmC^FNK?(Hn;bHM;i^t4PtNmj|A> z?gZAT$ML~)cQ;?u;0yiUqHaE)RYeJUaN6&F^EK5ctmRoVh*a?B8VY=B=JDT{JREQe zf=)YWUDE>XZ|~m1h4*}d%k5$03A0)J)}5MuHdkBU&u|l8u%6KC{vcbcExmFfU8K=x zArb-aK7ILemTpR*spbI3Ui}zX9MjFWSRMY0$;10Sv<}UwCl0HFM*C}erqM2X4rsTR zz7Nr~i;5q&Dnbiv_(X$rg!Zw&pF-=R+1Ek(19HK-Be@DZf5U}5^W`tNJPK#t^fq&^ zIqvWpseVrnZ;xObHyq!YMNI?vX4z5(r0OscvX~Ga_u&o0uz4}G#Yp9-Jn{9!sSOcuK%;XLP{z8}&EdSrXGQc`)ccQAuiV}zv zH3N|-B57@4skq%LMx*GR#56;nVELf*0p5aE0Si=QSw)h90xu1FzCu(%@GWL~14!`A z!-|jBx0oqPAi7p$+3UL`B8g&P?p9>k8_1~Y;Q>vUHqr9+NG65W^7+dk(gdp_2qGSP z6T~NCz~7hpHlw{BX~NQ@KWoB@MMqmKgwZTGvG^3qtEvK_(2Ue~+O`hgoG7Y_2%3*I z9qB?CN&YXxRVxFma6X5V{k!7o?>t|%#pTE2{ugcMV1}m0E ziiI~4>FwrJUvLrpvc@2(KyVlccw)DV!Qj&?h?;)*uX*kJj|4&0@i|hxygmy^lIRVH zG}9BSS#p{g^nnbdoZ9|V?36q zT@VBWPX*_nax|Z9ZEO*}2J@-D1yk!(C)mf}2`^Yj^Y@mEZZMy!$OwYM6ZbztQ8fs9 zlV^*%YS&Q^O1a>o+XG1`gUj%>>(<}DW$VETwtn~uE4G#(2>QNz|B0+$JePNVE)LXt z!LyIDX0HlO+qiPZNnCQ#C7gHBOe*buIk@tIbNT*{Qmx5CSTx(H{#%H~DjAo2!O%QrIBJt|!Z@JMp{O9vpV^gagqMdJI z*9YGK{ zbf5?~fFXtRF1?oixh7mTJ1(~y#qGxJ_TX^Zu-l#9+n64&?xNkhD6MKh5I|9yeH4^N z)~;Dgz1s&0L7;s1cJ@>@0nkuw^#xY~4dwMX9o`&6g3IX*MpO@|RtgX7rM#q=4MDH9 zsH-^0ADg|e0YO#3?O@-&LIeR+M+IxwZ}#!}+be@xZ@JX_QIXlPZ4-6Y=A1?Vi|4=1 z;^l|1RcyrNw6k;lT0B9M(Z+RaC~0Wf4|T=AQ`X=N*x9##J61vDjoWXc@7WLW_WZY* z(V>P}cPs?Jx#wM8d3Pa?y|TdD_Ht;@7X3~=xNpOqNCwM=;|;bSIuYyfNAfdP(zB^o z-{5wOX3`0r%tQ4C+lt1|;O}}mBJt|!KWyWpv(XAI(~@h)RXeUieG8Ro$5lJ7qTy{z ziWC&sI88dtsX3KH7R5wpO{2$6HOPJQTD+9+J zLsDEEk1hI+^CnN_xXDLjGR5=wycOIvZ7?UFdm+OIb>;r|wjzpN{nnz@oHFeKKKXJn zXCHMEdu(vcge>lS=qb)UejHyOaPia`V_8-PC~G)*%DK$B`8ohj7}<~aHac0i^bH<+ zbrq=%8@TO}2e@_4bnbcSH!630&Ogq-lEn+|*NG)DHtVH4uhpTAiWBIEk7fR98L+f)S zAN6D-UDMMY&W~`m_39k@Ia2$y;i$?ShTV}~El!soAKf2Et=M~!9q7jH8ErKb=(oVT^YzN1T z8A^s~=iwKgY;HWsLs?xT_^fzjD|J;(jJf0`zJBR;KAk_8L0yeJz2G;Xo;MdS<@*(D zNUq+^f1dva|BKrEw_Bt67uwh1%C&fd%d~D0gv#s5hQn1jU3#+N>Z0Xqq)5HB$;^qx;{L%Zx~f;-p2wwf5pkXv#g8*MVqkLchPg)X?QY* zGPzF&65>n&oy$Lcfkzkr!q}t6(K){tk|5AA&70M_(eA-wl*t`Fo%*s*d1=YF9DC~V z{BwE=118Mk;RP$GT{?j~77t})CP)?!iU;Z%+*m9oR6(Tgu%QeYIfmz-dYS~)N?hUq z02HU4{zJzybl6Dlz4sOhGMjxeh!UzQlHlVtX2fHVym_(!>gyX&4RN^aGJ^|J0ULtR zfrUZ0$9Wan3@2&}aU-#uohKx$&+B1ewXd1`~J_N6Ox|pXs!i+4{noiIz!to+%7v(owVxMj;nTD1?y=ZoQc%ddowQ2z58K~n|Tw5R^_w1vMaN03bYD!O)`S0&|vev z=TNpad0*bA2<=E>e zxO*()Pxy?cL;DzW{%sThH~;G%#*gpJ;BjNww`mt|EMCFYGY9h0*X10Y!m#P(xaGV1xY&mv{Gvjg_ebW4(wd_UH7oqmG?1lQ(jw@|y$5l(-c3l1ci>p72S`&!1NhbGb z@?Ztq2z5wR)j&QL;gnMXJm*jC$ARt-u=3f-fJMW76_27~2ue2~%QBMheQnh>wPd8H zf$Tw*4B*r2ver>!SINyxL-xo>2FV*;`TVjr9OT-`XENjMRKgZ{-w_MQF>vaiVt{!_+Bj&^;Z=N2XtA5KBB?pO5 z&m$>LIt+Z3WhDr4sbr>FyuW@FCBR8ZNfjws9Y`>OTTwBJ{uC8ne-zn`tOytk246k& z!5{9r-rrDOJ^fm`!trS7_3IAh2_3k>ypjBhG&x4&YdC+x$%OLg`5sPpG;JDfee~=_ z({9o7g&v-t9D$4tIywgzWQ%wau)>sJXkGGu=FC*Xe0e- zbj3oK%)W_oV|T#f3!Ef89yg*WAImo zqX^#XvaBGA5~?bbo}CN6Tvow-rN}aAnc1NFk|>JaKvI@Pva@pl4=M%(MMf12{`e9( zP{-EyVO#Dl{JQ?^9ZPF=fvwqvhO1AcT~b@^O#f{9v-;})7hL_B_Wzfu9ak;wwBzc? zsV(~{bgpj^VCgkjYZ~!Loc8-M;f&b<`=aPe4(U6cG8hakBX`Mgm`(98-@TvxQKw%v z@cJ6xFZ)KHem$d4_m)Y%lO0Kt5CBOs;63T{>hW8WMDKZ$!RMcAcRc_tEDUSTCn{{c7yAuB@_HN*oR0Y2m;l0Hkuk`Pz6MT zLS|Y#@$t=VEC>QM)ixR$9Nwg|AvzRAp<{;>3`Pm3!$V1FgJ$wfMN!Gfu#lV_7tya^ z+p$tK{TQxHZ}-_26lv!lt!(INKwJ5$wE>M4SJ9rvgtM&(O5def64!DL{(M5ciN+CE z{XbD^QxF7DR1Y4-<2~^KWX1bk5CjzGA$~8~6R_)%-9ax?^?p}^7JRR)j35ZOtb4fr zr4yOIW*dSaAS)hZU)iE1|K`h``w;~1OK9B!r%dCc1P%-0ADoJ+6i5&-(%4q zdQ2XRj!38CT3Cp5>K7{O{~S(NYZs4bPAc^Rd#wOMPp6(g(X@}2-dLy|SM9h8C-Zm3 zRjl^(4i#ddBMPuW7xhTI!GD9V2mkY41W62!U6<2!e!w_k>9h zMBnb;Tkdb71fPXbqn~I>VtCIXcuPe@6a>)_ z@JSLSWRw=RRl$2pQVMDp1UcxHH_f0BMG>3Z7LXT36`RNIYddebBHO&TB1HwK(%g?f z?<*oBwNs0JYB_jZygY9Y9R}oc#jIW^2g~^Qr&@2h>V2nUaDRK;zJSo-qO{cQ>)YmX z#iJm5548aAyXF*CrKZ%1)vkBj8of~^EI8atc|GpV?$xkKD zP7EuN-8L}t=#nft2}+_bKLUs zcutz~Jw4rD^4!uF=rsH>ZWtNI>2n|ElYcMZlP@pe^+Gc*UGoMNt1e@abrO$F8Nnql zz0KQK{RbMhvaxz6;+nVF?cT!5np)JReT+JKK4+x-%3UkI$Ea?nbH9h^XWh%DqRnh9 zp2TOrTt}mrfZN@hr!Tyh*FO6f#cDPC_S$)L&ij;axtF=?*I{@VVIOVuY`SQCtJhJLT zM8(FXGYT0ee8m-u?jSBMj+`#H@%oG_c=_Y=czNSj4A1P1E&eRtpM5d^e(e;N6>lXu za~$tq@dbGn(Hp+GOSty+3oyo~Atd(U?qg2n=7s+uIn|9R^Yd7$|FyQ;8;#H>`t_Dcj{+Vq|rtWw#(vy_il zG?1GDYDNm@PRQl61>32W4AeSAPCq7vvi*mc|9%7Yjd11Vz1Xq#Air#}VOC{^pVW;3 zsWLCWwU?A^6MIWkMw-I`MZ{uI*|D>Zgnr3facwVzIEimR-piBpjS}w1$ z(zQbxAh7>nlQ&=#z~fdh8bvzfCs18$!fJPsU};Xtk)54LaZxRY4%IVibY~0(5w~0R z{osMXhQN|wWaEZX`u5LecVQKYiD4V!FQIU^a@uNv)#Hz59%`$_yEPPPkvmeo|1G({ zg4%HvS$8|G+K$2noUOgx>8Dm@a&HZJZv{n8^5!K4DPbVVW+(g0wop{Jm0hKqShwYE zrcQmDibD%1JXFLU`yz^KYx%yh7mps7%cq-5*nD6$+sbyad*_ez={3l!F1bHrI~~W& z<1b-Q*NI$l(hW@QmCp~`f1YSG~d8%OBv(5!W$w>=W3_-ezfeA2vQv z&#hyoBO>5*)iZ9)^DO)KZ>-z)K9$x+>K%J=*6-tq)t~Ut0sHH%> zY9{~yAOJ~3K~&D+#i-FJ(q#3XdODmkZnuonDO1oTi4OS*0JvN-lGJkW78TX7e}63| zlf>%Z_TzN6d@Yin3JTK6@0iTa?UlsE8R6F z8`1g~Tox)D%I6RM!_`YqXEb$=G+*iQgtM#16Rxcy@q}9x!u5Z+`bMI5T(#pWlFWY_ zS8YLU6~MOY7GbdQKck}l+bYv~#B=3>E4kv7MbvHl2VYip#Rjw z@zx-EbeYP4p;xix$79%(_AnQAs^W^J3z#r)Qb4Cw@nDhRjWtiQt)vLSluUvs(tYsl z+<3wX?B4qU_kHv@c3DP7#_4upNlK#3x}QmdZlFVQ1~*Onocx4JKKS7gzTLZ?goG>- z0HhppB$-B+3y-^zMwcDYm7kr-CJw4(517LBt@LkUee$F^;4-h%+VN zY^-4Zst1|BZUvc{*<>0M5d|4ZG-Eb`MT*BH3OHpe3Gtl)$V$w@<+cXu>U29vF=qf^ zk((&DE95381CVGkBP%vcap?efBn!z#19;q|CFfJLX&%FRO$5A=jondAVcBN(RFwtv zXXTiwZ?FY0P+e5Pg0CysyQPYq`p>TP3HRVX@CLqfbnoVht8KEVFsI(qcT zL=Xh>^OM=Jy#k|AB9uHHg_>#`Mx%($=EmCO)EzIu6wPEBjyKYH4kx4aIou@wXHSyR zkd_~<^-E8#wTqWtd8|I`>4=5eaTOc2<0?A(vvJiLAEGUbhFX(JD z?O`&$@=-(PP_pzyhV(p;)Zi*v{xc|RKP`5V-1SpqN=`}#Ef2?)~$exp6Z08 z9AetU%@i0^s+)GPY|Uos>)a^muXFCuN|24B==Z}r`q+!FFkEkIrj>aX}F1 z-#dqW#SPTd+vwRjgR%-c_0~o_ZpcYbCNnb*Me#mw=12VaW4qDV;K1Wi=-SO2 zDM$RYX7zqj)8gsdFNgj6YgxVe04JQ-Bk<#ZXr58f8lS;qF8FUS1z*$S3*F&q>1l0Q zIGIp?g69scc_nl+82X${sE$y(QO#E&_0jS*)IY87etExKxH&WQbLeSHxHb>>tWZ0y z+Hn>9`F|BxvCyA&+Zl*G(Wu+)4kR3PyWMy^o!-obQ&5$Bif&FbE1(w@iY`NNr;^Nr{;lWGlr@ zO?0v(u%&z}T{4Ft;UqCWnab)dlsZHPb?`o%Ufr-4DZU#iY6F`}w^EQlh7_X!ii52O zH;|UzkNiaMX+?3_I$Xv)dS>L|@z`)F1}r8McpU7j-a}S;e-e#gwbvjSQ;3sP>g`sN z;u2_bG?8FQMFI|0Z3k069g0$4lYWnue3FzCmw}!6W(%HGAg5G_yb;rt%?G^Ot+p=71G0tl?xLs3=Lmkh$2I>9Tdtt0q5z9gTab~OP5E%P9?(4(;f z5(ET1EdBLy7Oq}`Ik78OO?i}I`T5PjRaMj=&E88PZ6f&6nySs5T7E^dOE_3!rFg&9 zce^d5-2?sv9v9M`AcKVbR+_(ioyA}f88#$CQ|eHOjiTZvj7AMVVj{0Sf7|#yi8D(K z9+<8v;ct(IMi+%eRdnf)N@jXIs_H{f$iz{&s}fNZ0s)u7AO=qJWJM)2!$L-80wpC4 zSeu;M6N%uJ?bfYjdxV>?w0zbp|0^h(i9MWLIKH-6>|0A(<3Acdj&u=@Sx#%-4U+Lw zJFZ&tKs&BlEBD{Pl|R5rOHCyyDT#QCh4?r#CR6i|g?8@TNpW%U5eHcQ;OZ~UG!u;hqk^@d#XQR7*f&ok(TT)I)Ew){+gKZ}jHBXn7)i57wjSbEJC3;&ZruYsXb=^=QYH zw%)%QSKjr$`H)EQ$jGwykSMUOhM8xZ)x;h=>IPVmDi+CT@bzeTVwH`C^y<(WJx3xJ zs~`II{6VII;tQTcK|i-hw0_3|el6Z`fnlTxQj0&>PN=M2FdS-2Pp2N~1@7U3Zw)Od zDuMi2dTpV#324bfL_WX0Sg;w6x2^Pq^0fw6e-&x@5KSH0=c{&H#p**lu8z!JEWW6! zH(|A`c<;cuJ#Hj-^J$Z!D7ZbIr~=JcY=`nib%Ld5H1vDuNr#r<&;>CxniMp6v?`&s z_yu>W9-o#jz3+N{gwq=?0&gApZ?*|75{l|_YxsPm!I&0rv;#q_ueJEKfEYs~uM@b^h77isYBp_rJ${72cO< z_}X#Rjw?Ni1y`~x<8gbR4fo&5Q&a^30a=!DIh|qs)7tFE>R(hRSfMsnYq-|V^43K3t&O1Dioy-DaQvaCP6QkEpy2 zqR^-=8a^%FP#vKsSb7e}Vnd7HuT!fY!PlcX8r0$q0L4H$zr7Z!C-{0K-(v}OwfMFC z3Fnj6t|=CP>Gi3WJv|KRwZGPGLT}*e*>1;GboFV+RXeWQan+8i|5aQ8sEUduA%W78 zQqnWLza(@SUD#|k>gwv~)VUKDgN3rPGHrPcY_^7uC=XURiWVSRgQT^)pGXa*XG80A zG(KqYhDPpMKI&Z$=WjHm#UJWpINMq}!pTMBM>O`d>Ku(v;rwaGRZF>cT(#q>9aoY4 zXvbCbK8NG|D{%#&C<^&`d8DVOv1Q8^)I%yBkB5ZB1p4&pOaFfT*}i@IVYc+@6iv*d zMXd_3!WoYydJYEwftC?*B(P}Nk0cvft`((+i`=!M?@+yZ?GP?5mx{nkB0&M2auJO zh23T+At8Z;!~_x(5)adFO3YG^Iei-;pdy?UJ++ z0?b$kV`~SmUpA7wRvU%-t;eVJJ@k6GcG7C+NWO*(*2C#)$CZBFVx@LmMfRf|SFuw& zt|I%JmCA!VN5~dPMR!Gzbstna*ye zrBBVDgWK9~D_AbvKo5u27JVJU*Os`7mX2idiAG0T=ntne(ggV5!j+a^{&FpQ;rwpP zHfzUK>+H4TDm=C0swJtaN>XAHPN#MP=V;eatzbHmUoi(*;Ue~E<)XRnE%g4WI%wnT zWpyn3sgYWnFHx9=Z0I0SRqeN?2UED<%{x#Owr_62?okoK1$G{pO`EN(`NPVp->q!f z+59r(LwoErIFvR4pehKs9c~JXoiPM(DvAt(042pXR{mVaFRL4I`}|Yf9#*Yx!s=?d zv+>y6tleV6DIY#zwDpdVKz=6=Yu7fi@|Sux?zDULDPG_Gl@NkV2X<*L4{JACsrR*W zxFB41xLLcti4B{qtlwy3SCQRUrc$)k%DxiUVF6p{-y^|Qv~;A$)Bg+fXX8q1;f!Y9 zYSnzD!567Mp?}+P)i%_QtN*`orK)P+y{$&0k+o~r^6IOv5+5HQQ}7+FEj?=0Ey6#O znvXR>5Cz_QrjWtM?cn2YD|!8;BKnNk#&7#v&B->^=93wJJLwIUzz##v2l?TVzRZPF zx3aIX`4q)p)}mqSn>c0qcCNZ@4-Y@Om-9~F!N`;M0Px7o`&e1z4#X!zvoD&4?EmIc7Y75~`IQPXxY?d;u*KWQ76JzS0`39MaS z!pWB&@@3R-mJjHwYT)R}+xTgRGte%9f3zF~j)S!vH+ehbr|jV9iQ72(#O<8@??V7w zGkpgaJzf#y_u;oHg0Crx_T;2B=(HxeNE2VU>qk-+j`SwxX!S=kp|{q@BWbr#nOJm1 z@<-1`B%apljKyXDx8v&Xfh$1}K=j5CilVUS!$quHw~oTX!a#ZkEz*k_ zT1%~Z$UT&zX_(Nc-~T-{Pzk=i=erXA`J$aaHVvbb?~N!+=I-W}I}fq)-L9{*$_3j*Ng>rZM}R|Nk!Etvsb<0&s{!eM~lezekL zFfw~adLW=$vY?7BPJt^f%plb)lGDL}K@>r7@&0?Ylr@UXnw3F{QEXo11%ZNYaV-C8 zfG=uQm_BhmpKf+>=M$Ys=xk#9+8T-*R7_@pcmc9ICD3rNi3%H-6GTiNl@7g<>5^^W z*YB(NexrvO7i7>g+em3~BXxF#mA|`~bW$?U|I^p;P6zKVs^?Gx%s3~FP8p^aAoKfI zyQ`L2ca<~blpMZ!p%aCx${2KXF%QhE=Ea!?q%;#slbr=`T1oF`Vd|J9%z4Rt{3dix z^S-=z_a8MZS?#9p$ap4>Ohy1|57hJCR}NA#MNXZTPLfFiRF;2T#jYxmGbhEdeUFFH zqf#)5uw`{MEB^2>;@CvS^iS{wk03};yQ7BJesr?*r@l-cl)&6uw(;!Za%yhLWWg(y z6xLcO+TTdgZWrALCeta)h`qtV+I4pNb`{9WG-C2aUp4z1dG~W01w-RG<>+K@bmzyI zBx00AUS80H8OO%)*loq!x3Geu2l9F3)jVwJ$y6L@Vpp*XbDV&vsu+^Yq=+&l)gDYH z0o9`tpApZ19`S5nQ_ZqJWIA>>aN3k~#GqRR{(jI5q=N#)(22`0qcuiCb!*A`%d{xc z#2hLgI=P11!Ry@`2`vk)V<>N^?%*~I*CtxGY4kp8QE=U3nXk0QT(DnSwnJ@&!-!UU zwF$05>fes5c3l0h&sV`@kPN)@&O2<`yaiQNnLBqbFTVI927`9!6VC6}1Y51jY{~!-Fq$qgRT|Ip-CU*eQYD78m*5N~t|C2vbnqWfhu$WK?jw zskaGq?jZ2s>|#!NsyCj^^{gyaiK}w+#GCazv#1xw?X_&PizquCJoBZM73&AF@;^m9 zzt+P!lg&&xZYv-CGMEGJmvGg44${)%$W6BM>NhG&Udm(Sh|LT*HIsg3nX%)`*|2#K z87c@;%RX7Xp`J2K{4}>S06mY&qqHIeQ;G?9V-4x)0y8e$N191x^)?q@{4j_UO-)>I zVP8GPYtDWl~Yrtp}X{>hB z=a_U(ALQnh#SUzCmBwl}lP>GRE&aJj$La}((+Sl0ga|E?YJVKM^CmL zSNe9s`SiblE4RnZDW{ymv}x0*Z)m`5GNC9+M7dBK!NG1g3T=ZHw+LG^5TfM^jsW#K z)$gF6cGfxR*57+{WiP7X^cmYYeZ~$hxwizxERvWc1$YyajUX%3)hooM7`gWLZhZei zCsbMHs;7JM;o}8de0dgw;{+P53QiTyyef~!@9xIDr#fKU=f+iB$?vL#74v#<$CJId z>KIt?t(76e(g1~q2AQ~I0~cM}h2NKUMU`9D+1cb_+Ns-^I(-LyhHb&zC!1mEM#MM? zw?pORnO%AK_HLLJ59j>56SF3!a^dwoc=*zNA=JKy; z@!WAo2?mqI^b2#@_G533>2F4q1VG~9$9wVS16`PLb~?Q>WcF3a2tmE-Z(l>4h`}ge z2s#~2%`#yzfvP}Lz09@ucjdPqdows*VAWPTX0!M80&1O$*FUad%&9qS_-P=EU+KWa zUIx_EBtHA32j4B~$k>4<9Cj6t-N^^b>N#sp2i7hhz&|G^BB>&cl})_*dOa82)`?B4 z264~D$;^MDjDvP>e~YS$ketkx9xTi#kB%&G~jN{AV6%7I1r1Od>4&umV?d9IJon!`)XV^Wqa_)OlMYQ1|o-Q zrIXe@n{Pks&S$UZ(5JvaO+yGMg8CtJ=N5{0Eg3x?tzCL3>6L{Wo1wl%GZ{ysXcmLe ze_DQN?Y#BsrFS9_+-_QaY3*2}nXmMA_ImyWe-Hf|tIl>@X_vL*>i0H9E+FL!PG?JJ0$bae~cuX+|0bb z8d*pWI;9a11%-Mn{PucS~Z$!mfNh?*Mn-10#kfP@5uP5W(Sw{BC9d zoGO?s0uG15z=F7dZv{gwtati44(!w*c2%u#tm3vU&B~G_X1_3lfXouI6L6j3w2= z%o7u7++e3u*LVOtDhQ$gs4RT0hzDOcGptWMwJrgZK>&>%g(R!EZ3;z)JmhvV05bR9 zx|f1u^SOAufYT#z+yD#UqzMRypxdKjty3uI=e2*rlq^Jpfs*xA+;;r|@<%6<=>U^S zKvq;d4oDQek=&5JaR|TJP!$E61E!st2Eg$n6L|CsCmxpy@dAP_s0ZEcDna!9@ra*ud4fbLQ__gSW@?eEC9;vZHd0T$>{ypuI41WEvj2Azy zM=(nC?VHG!wT%?ZU^EL<@3vE>0`+!^4++FK)pN$2L%i~QcUJ%22YZQw&%Y|=n?jLa zzwO6!59eX1R8SNU4d8V7>*M_|xnmrwR@PJIPymIG-mN1u%eyKIvV+quDdLf5y7AM` z{YbMr_)pi|kol#ji>t%NO_I$$K(MkQF4O zKtrj6ids*LJ~;M-Oh#tP%$U80^}DUSc;6oW^JpylK=Ji~$tYk+ zGEmUVz>3eRDXDgF`T5&8c2+T~m)CPB*TNU?c4tJUfhL=RIl(}7hRAm-tJ$=)=s^yaI@q<}jVcJFCyKa$ z`dtq8R(UYyCUV>mGjG3IPp9q{#`Q9yx>XDY0a1j6cnMV%c>cNWjPET_xZ6Ww@K!?b z{)l4K$TWrxOY;R+z9NG_N}|Y@9~5!t^L8d&n97K*9@ed|YOsb%=d>Ae43XN>VGCS&*^6=`v4>p>s7dvC3tNPcLY4rtj8m5J2{y+yh;_0w7m zqLquaJklvcv=nXuj>Uc~y7hS5aiy=T9apjO1oO59uH0@nrKP28-MWoG)~;pk+O@1- zzn=9Q*0W>B4$8~RvDv)8^w*11jwJB*(-CEI*K#D5$hyUKe_4P>CB9QCzb!3b_CNn$ zd*>ZqMbU-v-|oHXq4y4pmYH+ToSB_{_srbcOU#;KhC~~t;(q)zy)q_W zUxqyCOS6_IX;8{Uvag6=@j!YsGEuYPNy-(6y3LF5c#krynRl8tkDaAh0Qi@3aNuYv zjcg#{)mKcu^n1vUhQTMORz;+6^@0p& zlo{;;NJ_H1X8B~YZ2>7o!q+FA&)$#2+uuy*9;b+lv(w?J!tDDYmH4tYIzMuXxL6y5 z->$;XKUbztm*bSF>BF5AfxrH$#K!k;lTykl-C=i-m}IAFixL#NeUone&QYL%gCsvQ zH)Cx4{Yfa{^~&?^KAg$u1F}Vkbo~@!^M+d1~Ng%2hl?g}T1XUsR6fBvSU9D+E?LLHD*kTsUCiY>dcn zKUHPKm}@-T|2nTe8OY)TcDxGs@xzJ=3>h3wu`+M#Z&)r+FyWteA7ddz7wd~VNr}vVm zSB{))kkjPkXLt5#*`Q^Up3QgFuH4kMC-xcb%4k>lt-lfk0dFsF%9JTXt(vs}=cjYx z;^Xo6^T*fMIqnn_6O*kx>T=#I$r2=m1UaTlstJe^mKUOUgg|vx}5xWw{Z6W0W@{1A251p?zg>n)vngAb>`{W z(`B<>Ikn^%?dtCEpKn)r++W?gb&EUEcc@XL21sDH*@#O>Ai&=r|BQK9At51LxpD=w z*^Jq2cFxnv*u1>F@bdD)Y&N@o<;`R=VKSKzMbY&u2!iWZXz>~?45L2^ilBF;HYIGt{H2nZRgl$*VrQ5Q!>Kuk1&*(6}IN=SkLIETX! z1VkhpfLU}_n$6)H4s$ppY|hcUEV`VKuxDID0Fx|wAafdV6{tRcmM$~c?sOUnnpm` zRQ9fla`{4rO-?UKh$aEKcowUKSBCBO3|(eX!eVv$RY11Msmq)(|IKEVoa>F?TocOM z3vS;Q36F?lAjG7h_h&E}kwCLv)GGkulmM+uwF>32zTrWG^%VRtxf ziM*Ojc$`4p>OMUG!X;<5X87M^a{9<_mvBf<8OnMR1gHP3Hm6@rVy1pca+X~%0S?Fr zaJuq}BG~Pj#|YqM!r5Lj5FKl0?c!<#_=^wh{`fE9ZaaQY^4;s(XMV)JKG^?XV6>~; z;lJ9h1VJD!E)Iv?PGVvrmh^PI74xvb^ZIlbRnzmGN6R$mvCo{sk?xFh7t$0(0bd`1 zzgE`Jm2V)wLqd}52*Q0?YE4r<{5v`XcW-eyg~gR`fu0OSsP(#gOV*R+&L+LLQg^!b zh8oo6b7z;{+q=8;dcITY&MBWee`u9gtB%xlt#zzttNN|o-CMqvF10+PT^a34ZIjYw zwcT1e^Lx9>5-T7xhPz?xTC%h%)15v^ z%KYw})-~lh^`<`WE^k)(`m!_5X!}EQWXYqIF1xJkwySk$<Toy%3rNv0llFD zwG4L;KefGDvYf@rs1wNc&A zL{a~bNSggXE}%|-Up|#{Hw4T*1SE&^n{v^Y_Vdw%@r-$W3|kIgcKc>>f8e~qt{&OS z-jGNQ2RkeG%CYUt`0^X(em{q==KMmuRpffeF4k;2m0@FU^*ZJ5So9N7)|~%BDCR z8MFV)$R}x%BoD0qN86Pk2;91OkTqM5YRVS`fjeO#d_VIGrcL{V?|xWFWU2s3SD7|# zI*}=Nw|cNFTMz`+&HJ4jNfM$UaA3+=VUq_KL*pBeX-)5fG5r&zjnpCWDU zAs`Wc^%AzUcs8tF_Yd@O_XiKkMm@O?(kBnPT^aBk_rqV3BspJtGUnv;@86#mEm}|| zs0ucF_D{d*>2^otJwX(redYe|g zhh&aFOPL?K{_FRT`E=0^O`pryHs?hqf3<+bJ6Gu2yDP7Jv!;0K7J$KhMAR5dfQKyiG`)BZ~}xpMF`%?Nq@P)l!$u+phot1xj-5 z&>~)+wnWD!0nsFKbne?U?lG6q?|ne+!q=%B#y*0yz~B#E;*9JjsUEhF__1P|CmKb()C?@@c9}!CF-{6{+`b` zmv)*SgC=A4Ekwxxe@)x7`X_gter^bAPSGKC8Pxf*_gDITy=G)t=Xv7JpL$VYtw^)n ze%wXX-Ic>r@~78UwaV=d?$W5`Y4_ir%hO8Zu6^a#cBO{JVxe*4#ytQ0^Q5MvI{ON( zsJo6mo}|-Db5AR|=Z0M62C|LszcrJucb=hVi~3Zk(S_qD&r-LToo}a1W6!x*gtY6t zJ7N;?$r1GI-h;-$b@_bZ8AuA@g~3lyt6D`qTfB?7$W!!c+K{@ngLrw$_XwiEN3T4} z(;Zq+sc{cNlfWK#jJC}iQoC_|rmqO0Ue7LcX;O)EYiHA=X?<$e?@dVft;|X``|`}| zPt&|r2PRDYhNAID3A+}~)o?2dXMM<{PrOLq0gv(WHmILDMEQZP0-|ms1f0nHxEslW=AQ zJ1>eH4?W1_k7u*_mrtotssvWS3m?-RhCb8+AFrZ>rGhy<9-Eg9ursh(Frw%~_opU; zATWN=BNP(7393_Ef7u1-@8xDodTGB*qY2 zrvW_&k0s>DcDj~Loj@}nM6SGN)!qR1a2{~OHBkp zV9N46u7@9hB*LIqCNlN&@0j;;Gj<)@hczVy-(p_uTJSFITDIYd$GXzK?^u5LY$Cxe zyU@E=4|+WH8KfSgUT_tB3l*W)3)4UlaM&HWZda3sPrwd*{B#fM1UF;&Ti+mXnf^T< zBDi*KdJgymK@b={a5$ZMJVmvdRoQkv7VMD>eY7XFgR3&>i=~un*pX1@Ty4{yIh zjoLMNvfnGDAn?cB3B2^mAS%{s!_2QH(Y9eZo*MH5qK}=h_(Y;ktY_#`-RKltna9V@ zMi2zn{yL4am8&!Gksi#Nw>Kk#Byj8OE{3*mOyz3rS+Z$ANC^xd(2`m;8ZqYMc?bf0 zHlaTa>(!yl6XQS-S@-p5o_X|PYE}zo&bDy;y`glC&aTeLA)1Igyo3)nM$)`xy)1o| z$t!@s0`k9gon@alV>A`3)uiLo!?}|V$zg|hymL*eR&B?kt%o?g;%l0=Y(c}|hO9n( zizQ#oBxK)uwja94)u;$SV)BcFs8Opb!$yCC1Wb7~v%k8KCUE1(V!A!tiQw9G*?9V9 zwuiX82bg-_T_5hraG3I(rw=Q4GCYMR_N$>s#?&(04dv_EA@Aqb$DY6w^5lsOPvp3( zn}1Wgl8KloidZZbL{Y?Mvtf7GaoC-!BIxPO4GDHvhFlL3daCel$(K_81xIb#)h!7m z^LoFA1T}ern<*B;Zbg!mY6V9c;Zc{_y=pGjl8xB-=W<%sDb1dWL` zwvu#uKSv^MY@hZpyM0<LW8b-*>re6<>SsUd&O>EdUg=6EI7#Gw;$o) zzO6V?@6h(){=7MNC%2C;;mxO;a5@GA(dmmhtBz3l>W>7KD@*&HLy0vPPw2 z8DC5yEqpuM!r_PaW>UFfHwyYn6e;A#SL2>zb3!L>hOTFF-?p5JaSoLL6ewJbIg>`x zv`Kx2%s#}>r-owi;#a6HL&v<&&r_dg&DxE$ezYCdG#EAE zBX+Ks&f1@65{1)0xoub1B0{-yZ9f~Y`mlZP8lHS8n8cU_`i+>t*^s>?T;9u#R4dz$ zu3`4VZOa4a339>?$Be?r-UipY^q zA;LC)M8l>{snDP|jRy>&pcKopmCHy8tjoGX8z}Vm61K#b;>DL{wI1x(!H(P1k%zG)X;)_A$2%KDpu z*aJ(L^;ZI67ekraJ%EqD_=$;c&ESQvPjTte5*#ttN%yVH;y-t@UBBSW6#RY!qxBVT!}wQ1?fE$(HAP|tQP`|rjcbzZ%PzbAFBWv4qm zT2aQFbmWJ2WwY5xO-&^&Esf~tXs%zsPFh-;b4yJlEjOK1l z?|1j-l@TNP=I6CsyL6h*Kl+%rr+!PpB1N$PP3yLx1mIhyH2w}7w_>3~<3a#D*0df+QG@tipu42&3BN5UAXw$ka0AAic2sZd*)qLI=GoB5{ z;wWCYknC0D2v*q&H3_>C!^tQ>6q!BZalTl&p8!9JqLl_vzZ4WNS02&oz~tqHpRbv? z*jqGh(hQStVY>Hz8lS|={QTWCep>hk$v*xBiZ*QCUevDFkU}*(Q2|Izh#}6$mq#C} zO_5rCs94-ec$C~Q)0z6}i+sBMI+7$YtaCAXzrLKRRSQ$RY!$rlV&WV97~Q)obIv3% zVQf3nl9DiC=eAWK=E4QOnfDiihP+M@uT0XBnv}ppgGce#roV|vwlLx8nj|Eq9K95g&1P^z4hAF@P&E#iWapI2+%$)WG>vtT+-@6pvfaqn;G8E-W zyYe$Z$x1Ex@{K-B8aggtv(HszaChrAc-K)2T@nz>DhT zO5#(k8=sHr&fBA2=EIruNObt%Z5BvPu_1^>u!?4`9NWyBZ%wEBu(6a7(lbg{h_bfh zoV?{c5=EH$>IAl)N}^G__5jps)tuDZQFs?COi;ywSgjIu+qQ7t2Zf3u*_=bV@lmM^ zc>ECnij*tIoro|hSE~a+-A-L7U`uuRbI2#Z(N+v$*vL2db?ttvVgL<;oNKUk?$Vm` z7j6(--KnEPm$ux#lS%=vqI7Ll2J904-o8-09$lN%bjdvQ=VBrPtxSFQS&nZ1nID%N zbPX3vNSM9+TxoBFU!zSMXY{LKvrhP=M-b;IP2KX|Kv}vqufei4%b51&7=BrMl0wBx z0%=HM@r*hXxgPDHeV3L1)NIm_I}wpItKZVuUzIM2EjoswvvyHEegkigdWB#AIHag| zeJK0n+zx%@^q|Qp!jMyb_47h+h}4sOxxw9#s0Sh69q#2JuNRrq8-Bi<=XQQ+_`gyxVSjiI#+@qIM?h%pt< ze#+eMXYk(p(+Fa-hKC7zML|d$;;36 z!Jcx1eVevXu~sK~wW~&G_!S~zl1WR6!2wuOlZlLmfukPfxhKXjfA)vWJq=weIPDqq z+(3L=^`%|oid+lNBv_WTIP4Bn78lyARwO~>t;dRTAfPRGj{M51<@50`S`(krkF)L9 znf!I=67AbJMDQ&`yGCVLy(J7kUy0~g=bLd_Vm#K=C^jBF$DkLVCBY(c`C2qm^g*W1 zS%x5pI3y@g=V?Ce6->j@C8$!l1h0I*jml-}A=nbReLEU}q_}8O(ygQ=#&Ij^4v!6g zpFh5Si%uCDvMk1}ms5Bz*fa(v55rY%3o6B9q<#_?^G z>F^#EfIBfU+)S|W!b3eMY(0o%Phs)qFbV{S$R7cWkB%XrKp@466{U#3Gm>CSPsS|R zc;ltc><^uGovG+E*u85cutziIfU{lq=`YbKy=Bfqq3vv7972KAAUP9Yvg! zyLNRX#=`YWyLjoR%?y8KB+)V9oZYjH$f6y2s#9$o=Z_F)u@M&=hZV3{Qn?jxWo(~j z41aP6%NKsllI5pp*0?eNU%m4jx5TOp=+%tV=We*#j6E%hB)gdsMT%3pWZ{gP$WCIs zg$rAMqyNXdNxyQ1mc{*eXh1){TX6znmt!j2fO%U^5tev^vL(HVyd6VCSRx13|G>6W zG0yuaBg$B@SP>2$Y(#?qDBEEWM?%A?@mN0!HS0{p!cjEr{3wp-q;$=Bbmtmur zGxaqtQjMaqn|NixE{4B6oSWA#V6|FFN>8VVZ#t{zjHPIBE6gSz9(}k0%l2gqUd3tl+Sw6PM_m zXP20ih~1h_YHBK0OEPKc&hrTgF;r{!1b&vk8U5i`4C&GvsYC^rKW9#Pl}%}78T@2d z&YU?$$A>%e*|g_axo{TazB|mcPsVd}^C%W9TSmuczTu5gEr_@p;rxn$-9}g(MaC-{A+d}Jw}fqFHpExF;0hE2mCp=VG<`oB1le3WI)d@ z%pE_P#VZ%^;d{T+`Qa8M#NKlDS7~WD{C$}>;%TmUHDGYJ`dp8>t2px)ycYEAbw{FdlILkVa3?pf z+La_p1O^6Dvt~_#f`X`7vnExlRH1zN@{}%Jni3^SP^3r^N|Y#(&CdIce{3apdB{*b zbm&sASjjyr8;<9XCCj-P=b+UZhO5I;6#hb1gBD;EF}qw`Dm8 z&s%uzrKc%qcHlrnbR_WooL?wXp)UO%>w-Ly^-kCcEQNw8Tgcm0rugVcZm0MlMIYt# z#aNP3(+pq&&8V0d*)k021+ZguZ5YnS>5}E8v^@>HfarOu$ zgPU;U%wAS(KSj^SdJ=y}qDG19Oq#TsS@S+|`bPpm6ga$h6Boi_Y2U3E<%;-WNr>R! z>3G_beudU7n)P8DA}yEd%gT2es<^zDw>wXCW0t@-G-4V=CaL+ysmX>o%-hvH$aO%h&+H`stZI$C*}V4*y#~HSwbK49n?ILS?_#uR zRF&f8s&X;(28|lmz@BiMTM6luFJGR^N7k}>?@gY3;Uy}%mYKJ*YT>WkN-NIr=lg)e z;hbA$+T)(%Q@U62w+WO$NrNvZcvl``wt_C4lE8c*0rnH9S&?ZZ#s1C z%&pLE?7wKCb)AwVNo6VK7lS>pI+aRzyV|NfHjI!MGxe&L1>oG_15|F@0$&lN)Z5IS zyO1jNTJcDy=3KsThI5xsaxKith+#tzfaClAV%z?6^cg&oN`BFV-1ebvDvZ?^gE~dalvNl_83Tqnx(mR zIg|pWYf_jfPT!EIU#%3O7cNkycu|s4(bn!eziWcI~-hITR29SJx zGuy5=W#Q-jaDGV>RxbX9sAMmmec>5=f#dtOu>D{tPd_(;QUy)KT))6?OV-l1+fy{F zQ<0nJj!>{h69S|pPF#woetFm(>Y!bt3K@Nr14(lJi*Wyu2wFC+?&`lBX|ZhFvWLW^ zM66aTEqV;3df+W)|FD9pP5RKSO+{z-wsH~I;~fltZV*W~&+^mKO|RSWa-Jimv$wePf1DP=FOX&J9qA`R&tkD zanETb_goV!nK;RtOs13sOG&(x1j}6|X%Q@S#bjh~h37NRktIH^l|&Pg0|Zesk5A}uAUUN*p`*KI?SWhvm0oPXEXN-tx}PoMDmXLE^5 zvC#3^Y0UrV85|Ob*?c1a8jV_= zWwQ~qhhY?X^*YY%b>)<(*@+3lJujiE<-4r5NLhSuIj~Fs0338lL_t)oWxJ|qSG z3w7t3)59$DI8&m!ooc21@U@;;3N~lo$@9$mZ6UP_<$O`i6$y8#a?mO%@Bt*KtFp*O)OmxX{*zJgN8i#}^DD?=L z@&UUfVUibdlN>lqCE0p4*(FQ#&^Z1LqO3QJ_Rsx^--dOc3-sf9K<0A}KYU0Dr$sBB@hOHSxP} zU>gDTI+J*6CuN(p=gOgd)N0WRZ!KE^(PU!BhNYZ~GBJ4QllTKyPV8dK{xJGHH;Cfi zAetO3n>Uw2H9GQe%UXcMiT!(sO-;il`O~p;D_0{jIa2xUyE$CGBQfa3;nXM-nDOAZ zuw~5-TK9Sgf8fZDEflKWhH7Q~hzUDIXnZkR)hnAx4D8A5-XB7nHqA&&h{L;35zIo? zRpYgYrX01~y=gT!5^OkZ(7Nj*R4net;a$6^)}k$i%??mJROR10SB?{5FHgg2#R0f= zHH4k}Pa-)4idLyZ*H(42Jc65*K!g@|A)NS6G`qfIfWQB#E;9S^k z{QZ3~;Y0n_&G1i&;O7Nvsnoa&U7FV*^!RSV?pW~i^~LP#Pu;rp2=p}(dGQRX1u9Ub zR6$H)8q4O*M=H^Pemz>@a7enOOv`?~drIqma~?~sZ)y7Y`@7PqBVJm0wMdqp-W>ZY zopX9bPMt2l^;fxhFsk!uMH}4tR=uyb&C`eI{cTs-(|ID-Xjj?uO2%7$=s{Wpx6xfU-!Gt(zO&ww|V z09j=@A4Uq+jKJ-XtxS1$dX_~%fh-@1&al|^z>&?cUcLbS@b|RWh!J7a7w@p7Ncs*aCk$7t_ZCcbP z0eJ7-&xn--5JgwJP}W84g$;Z(=YmV#(dD!GcEx`D1L5rfZJ0cFL$)@ct`k9k8yh}g z@*hXkmF4@C2eN?DK{snyLD_1-FkLr%f&HD;9+ZQiOBxP!J#wWNL-@i71 z8EZ~+@#J1+%>9i&fBb+}?O(#=YvTIu#gwUDmlNSu00uTK%XPn+oLN1Q!5?iy6thMM z)ei%A_rAOSA@f*&_(j=&X~|SSXteSu&wJWm<)lL?-<^Hxa_RX`ty?RtQifW8PI9%L z18UNvl{Tlk)p}@al}E1*a`KBi-8r`_?RqfU)xW=834%acTAGVo?cBMO;w4HD7#NuK z`Rj%NEB)sV>N09BG^)qu)R2cvw1x?_zW1XhVY+0@0g%GdU27RNY#1rG!|Bzf9rYVD zVe9EzE^;G?BCDs3qfSsQo*wxnqA2pm+z%;LwmgF-euXHCEc)_eTDI&!-xmk-;o|+6 zOeXd${+K_G-(lIT36w5hk(WOD1woJ}stJ7FcPQ8FA|~+;BZhoMOzcGlb`Pd%&93Y@ ze;Z50F;=eGfGCP=SvHGZmr_{s`Bau|x!@{8y5z^;r=F$vqffGO-lyD-+7H05pN^$m z`Lax$_B)~|uBBE8HuK$#EhI!=A)wtz z290`?7hn#I_?ayFr7cJu4zNH#BgkGeIh(&xFUh$a)e7Jkmy zq5Y{@qb~DzU&$z!0Fs5OZ5s31@W&Z8W;(r^*X2rh3PsCQX7B9T{IYN#qA0TV+nM~e zKaQRA$5N|h7v7q)j9Lu}y6jE1*%>o>B#-v$&!&0PNQzGYV9L0ml&MsOiQlcqBnnJ@ z{R8^+>rbtE4Y-sDi`E}t_Sg|zicR9}k$tILGnfzN?Z6~Dm^5+{y`FfSy3Ja1D=C%N zCcjHqf(^kM&u5=cBPzv2irq%BGJ$v(@WQ{ibH3dtZ#+l&3g!9Yw{02siR$eN_+b1z z7A%>;_*cIGz-F`4t?!F;==d#lHa(MBC>M#pZF2WlwUT{r{6GA6O(}ydcFERul4Q3 z2Oq!2!M}FOH*>aoTI&r^Yg6|*dM|A`y;ZvFXSC9&^=j#NCqJjoS<44nI&-@2uI%pQ z>+S2w&&hUo{&!cmS~A?#y_PPcU1f#QuCmKi=1EISWA*CQuEK z8ET^HuG}(omuYZUG4iHlk6KQUCxv+;FUvVm0Q~9N{z(=r`I#X-nlpONE>50U!^lCS zora4daD(Z;Zs)}1a}4NGkl4_5O!)N#w{ApGH*qy{HlAbGp*1`{Vm8aZp3I(w9|Q35 zoU_!m{KeGu(L_ds;dkm=zTa}$rN3U60?e6rid%b@P_9)$Ug|%Z=e`T!(%Bz)?fHJ( zypu#!5i{xW><7I0-ZUcr{)F9Wt+{$7j62(ZV$+#ORxjGd zQ}68M*osGaZNd`j*Qv$w6`SC~QubDDO~A=z#7f{JNcaFgzJ=NS*IX7~XwJ2;P-3=C zVDX7Ggp3JV1BO0FVH1oW`4raXuh6$cb-tbdEoli?nR)aE*Uy|Gv6OQ?9!gch$998s z3-|^|9NqZ`4O_G!4FQwc4EQtit69vQFo5>$8uHFhyQo#An9CmxTXmsuzD>vH zKLDXH=ZOgPBW7{=@>vcpdxz*WZ_-n3w0&X(O**{9v&};o@?|ooLoe}c z-Ghvra|X-RH57hqBBAG(@#V+g066Us3J`wm0E353;)Ox2`ToF78dUJdZj2 z&1+XUIe#o??xeB!&u^GGeFdo)z-_wOQvl=PC2$}o*<3FS7D z>kMWvGJ{--k-M5)8evM9O1X?N7={qTE0Q~tka`)ng!1N=%M9`6(zqpK{Eqs*>-Syj zd)E15pY@z|*51#v_h+B=InUmQxIbQF0;>&lFgBfdV~WuWQ(=&X4vQUc$<6uVh4NN< z+K_fCtn$kk*=Wm^e(mpwo}t``cet*o{DVmSv3RwBV=v{4wS!hdc=^_v*pan~;U9CD zn`8LA!#^Cb&H1V)zn?N5OMe$r`{f4Ey)xa#(&eY7+U_G0jGU17#v+_yKkagN^f8-XOmm{iSb!yA|zN_uJFl)^I zOZH^BeqZ%onZz1YQ>aVLydlEVUdB9urpQgmsOqIYX8)-okDl+Rta4r^<2J`PV(X(UsuKTh}(Ot}WV^*%Jlh)tAjeJ@QO1 zDq)_W1lGqD6mG1ve>t+Uj_v=_=HsgOpjVgI!>*qJC~dtav}~n4FA7orP*H8+0vNzCQVM$;~Miozc z93oJAr9&h7gKnJAr)aj>Qe^9m*Cjh|at9obFMN1_?L^zW_%8l7mWVs|E-fYoMfM+} z-9MMMWEqRnT+mJSBi2mKH>N!!+aqFQZs<)*q>=hA)XsWDM??9AK1?jB3H`-)t@G%u z70w!aspsQcm(g#&oy)JCOfv75=xYV5$cLZ5KBw0TaW0j}C9Wlt7r6Q{iHUO3Y2Eb5 zO$Ql+x*S%pbW|b8RhlEz2qqZ+td9KFG}&5cD(&4reKXpP?b6gX6P30<(rqbY+~|AtaNM4gr5Jjf#r;Y(WVRRs(O%<-!L;U{@RU z=@zgE7WNn`vgG5V)`=TY{cV9^s+~_q($WF}E+hL>ryXJq;GuG<+VXelf$96!SBtF)%| zcxrnbHkAn#cF5dpdgjXv3A0AinU9&EYnHX{=6XnpCX2(Qya{~^LS2;UxiQ7vjE|2D z1n}!~iFaUN>Z>yk>xP#0E)yrIK%v6eD^X>M%o;I#G}0`S z&ZjVAfCtYj4^{zmj|GVw;KLsj6ohudhT9%->C_aAPQqsJJD&Gcz*4tQ*-JY7gMor2 zO?c9b=N8%*6)(@NR)HXXnwIk>jUH?~{tGEvC)K&a(S~rz^tF4)v+D21B z_J4lvKvr7ieEmHI-H*B{1}|KtKr;!2P-MuoE^YMDyM@<}*E{9bNj-s;Pc@eB{Zr*s z8rV5k)k%3*#`xred|%<3ZjMcoq2h7QJ)5b3scoa*W&n1jhaGFU;yD&H%u}78%Bip} zJ*Pfg#)wqSfRhw*QqE_jw6}=k-FoB&qvJ0?U?frzBv+r(ubi0Lq){QJ(s;>dzs<4d zUP->%z+n8@KSQu(A!My5--@!Hw#6)J)4=V*w2jX-0>$SHhbfY}%asB6TtJ+D*t2y{esXg=+K{IjFetur@2fQ;DeZK=MaRC2Y_VNBj|#XSonu|PeFomb-ka6( zb&BuyHG&(HGnt+^F>r=HjKmre0N>Nd?EWlB!QHcM6v9dBcFpUArP5Q?=y6lCI;ywx z`ujClu>tGDqOEf4gL3%M&;taPI-&g_sPc1G5O;T7DMMg3G0XoPH@S&>a``~Ls`3Vr zTOy-2AhZj@Oy{7BksHd3clNkM7aYmEe9D{$G&o|oKX-%&3uS% zm`rWTF6=L{!H#A1u^s3X?#LWhebX43J(0K_XUOT$Zk3BJ334zi=jCkWVlyc!jhfj* zUO%RI2AizN(p)H;tIVDWAbWPoGVMCZ=L-;QKz*4OJEf$VD-hvAkUczK0kS!X^{UkA ztSbUxMGtiBLl>TRZ@#;G@4B4EOOji}fulcajpE&lo5YF|JZFx#!a!Cj0-rU^uN5{LKkF9s%lc4Q8 zHnJc3sEGxNP8AUwgW`GYwK5zSqkWMCl4SNt9~&Skr>JPPa5$U}iB&ryfAyQk*&xp;SK0G4ieQ6U$HFKKFO; zVqIjs>rWJWSV!#_p^b|8W^s)Zp;2UZUz*_wlju{VjH)dwsVmZ469` zvWOw)TVovsDdCS%u;2lZW&KKYwuqJ#Dn*HXC|9PQ6cpTe)y$)Pyyff4kvPKz#Pz5( z^QanC_2B92!walorE1e$*ZUfFY|pD2Rr-mfF-36|JVc<8a8wCfocq|d*nIt> zd~|`F>B@I34>7wZk3Z`EUgEsR*F`yS6cVEpV64L7%-QwpZ!7;twAN+6W>`>k^9r=& zEb-6Hd&$OezIzHy5>iI0z1o%Y(Hz6w)tnA76&MMq({tqAEHa(+jO-AkIyE^2caN$> zv9*v`NN18X&8f8{yv9I~7H23z7%2_N{xRhmz({M*;O4$SbplZxXUKyQSXei8<1tCT z0HCDVzev$(?xYD@r$D7Zt+8fz;HMV5C?WHC&5)CcmWs;zD?~B z9|`(}e!Ut0`s%Cyh})sVA_P_=0{J~?nRuK@T2Ec3k8E|?EMipMN{va+{EZZ)sC<^z z52}Qo>N}`iP?{0A0_@xoe%()uLUKv%8-~P)Svi@{Lh7=eaQ`Wf4z801%VQN^eQwz!HvG|c z8vg=BgrJWB77Ul8_JW)2764eczLSAAy5*eSn(62lS>-3_`dG)H=^u1w5`?jp$UX>- zy0VkFUz0^vWt29ubm0Z2e-2bEpv?n*#jD8CAKQ1kY*+Feooq|99#A+`ySVVEG`+k6 z%W|@rGK`{E@l4U(DaJ~+pzo9u02ez!vwLsY-V8pYH9^YHte@0yK^xj%DBM1sLn^&; zulwb#vrS5>Sl+R_7PW(K*IsQST*H9W{TW|$7e8qu=Nl!5^^=2s$P<3bH;r@xVU8Tu z+JVuW@^00Z4-egEw|wXQ*z3U$dgox3Lbu2&}<_>a2$3x9;ibd0_p(^6Rf9&^P= zO^_mj)r8{_LEC|GJbkU%96>**_l~!2?r)U~qxUbhjTZdI*MEI>Cy)2yn*x?WPpBZD zC(S-Coz??N@jWAlRivE6RN45(mGD8FU){gna`%|dO`%4=@P66?C1*sdr7s$s_xPmI z4&nj^G#lr z^WFtNzRn%g{q@XU4|Kq1f342Wb&~Ya{~sHNP7%hYlf_uGOE-4`2h0>jZBK05PA0ZBv2EMd#I`-jiEZ1q`Of|Sci%fzXZNnI-c`N2 zS1)|u>Tm@)arhtDKfu7i;3XwQeuII1QwRO|VW2=g6{#hBpa#-WNKzRF^z(u-4g&)t z1d|jIRCdcc&vwm16F=EELUUWq2@sMKXJn-^0Vj)P>D2%ft0`2X+tT#F-9*D#J3MgN~i2i9#5H#m?10GYSZ^?yGBeVhxC z?k4ftwGr+6v$q~5iOh>!C>hsO4Q6TbS4qbX_s^CF`|}uBw{DYQ(5QB{*+P)f^gGAz<_U7Bs;20EMizp)OdEDX`-k{dt7<3iQHN+3XJ zc$0?uSMq(L7{AHSiJPHU#`vtIpT%4{2WOM3kI2*&obC6FOqp;^Ic5J}Sv8F7DvqOA zoS)dwyv#y)6KAXmD))!yB$KMosFu?EoKp3j&Bj^&yKuw#B(rmP$O~8oQsgQpxJ4Zz z6NChJlx>LE8P%}4`n0pn$auLB=Asw)=0?=<)q5f!*38Mbc7<)~| zb^Y%G#ScvO5zDq$w~+ikF_@LqY&WSOsbA7bSRm`ICq5l+ky?6)>i=T~t9JV`nYR7^ zw))H3iIp@h+)Cr<1d=A*O=C%?C>1svxzg!O<<*wkQNUBL%4s%P?l56aYHGQ9{cJpG zIonQ$_vuQafqTb?%KJRRO2hkHb7k~&&sUA$%jQ43d+;Aw9xWHd>kp`2xOfr36j7C` z=fabn!}8N+{w4ZkkE?N!XyQ#0kBhj?hAX}rAeDl4VaCjZ4>Vf49{2w%-gFL5VXhgm z5?*k_Fj|^14a&n;EsN4i`<0m;vdCVn6B8}`EK$Ni;A(2)iy;AeU!t}pdt6?le z{tdD$g*sBiA|s^wOd=sksJPOuy_%vm;=#)So7?FA#38Jf#4=H|dbTF<$}&StM+dLG zeAkZS_qeUbZPI@=;vKhEBHre>KcA6QGT&?}he|jQeW$)pE9Q1Y#L_G-Uf-miTqE2B zdvZ*qvGPuxCS-1h6!k|FiAp{x(TWxM&aAVtXs<+uN*Zhe4aq1Q;NLXMyn5xB%&L_O zsp2<*1!ZNGliT$Fo~zxSp8@z32%?HI>U9ZKs^|$Ls%qWp*_ySp z-nEr5bD`g=9A)QzOQg_@^&8f?*n6~{R@tjR%0bt)-@IzhIiFqz$KYv z*L(QhGfdV#0FX$Ekg{i;!mS+!Y*3n^4>};lo8g255+aBHrTkG(Q&9d#4B9nvtPl}} zoO{7FST1{=+re1=E7MDTFEhkIzhPy$)&PPowIW&{3o2n_^7VlF`FfN4Smn2r;+Buq zR&9;|&0v{tM{G_}k$D{^X>1XfHjU2nj{i@J6Qi!Ro;<83f1apl5A3muVG> z8UhsCOz%eQ)^N(|6&9z1d_W#pCYzQ1X*Y%a4VD^mc(BXKca!*mDFi`3^`B>K>vBxgWh)J5)THj!R zgHUvd+hb7gae=Q2iS&nfCHmPh_#0A@bY21Y==X0Je4y0h%?%Ft@6s;sm0F{vD!w-m z+90tgHwjS#eWl(2;=6a~wj+$O1Y0D{Cxt#HluJjpK10~n)fGb&%@`^gT6&hq63Rmg zAxsd^AOw*hraa>z`5-abM}43A#a3MI`XsJcK9`R-Q9s@Ex#-QvS){tsQ4nBmWhK(Q zQhWMMF`<->{wSMYXVTz9nqz1EC&%d&`)q|N_iD<5*X^Ze6z8J|B%Bgfi2uaF&Rgte z@n`lM=S|@U$N5*aQJ;kw!*CPcS4ME9Zg&V#Vl0%bY~h|$Yui`2)(W<6zs3;(Fn6*e z(|a&R=qdT`vc#4+i1)nfsGD+Sr;o;`iUAH%v2Vv|*NzJ*v*&PkE!BSIrKfjVZ~-nW zhSF8rhxRSk0iBIDVB@5pe5^DgfO5@_3onegv>YnHZ{xDh6a~OQJJ1f!7K#_T5n^C| z?D5_K1QQl$UbE*qH_wRBH&eO3!TOjv|i7fII-O=fcBm4?$nbC0$$THeft@KatZMRl6PhlfET~ zC#sAFlGrb%{3QH|S~?+}03_UqL_NIXw4yV3C@_43Zs*ZG&3Qr;72oNXaKw6PdB%Nr z{qU|Ybp6EOYLlf#qd5{MCueDSL_Q^Dgb)on33_B6<&Oij1Fx=q%Mduc2vSK{A3s9S zA#`_lhYeVGOq{;76(=n((1=23LZ6>nV3(H1+XW)6D8_$!0vzkM~hPDanls>P)vY5+w#l)+YBG zTvfRGhnRvT7EfbP#Fd&MHC|wgIK7jsXbS1CUoE$n37lCEZ^Cgp3K+{$O}=<+EtAJ} zA1}{cqB5IL=Hnrxp2o3yTSQ^VbfJA(j(U4*Di2ZEyM`7`iHeth_%!OniGWafzo0xX zI{4{Ig2w3T^f$G;wVM-q3m)_9yl87Cv*nj53-!V=I@SgdBlS#rTPEBbNzW0WId$pz zX+8qjx3ok~{_);$Iwz817WWvvv=5AD_xR}sJ`%RugJXOhz`mxSBSk*fx&O2uM$Rji zatVT4q}LqoNAZ=8nHiU!;+3D)9sZ~5-mgrHpDVY}j0gE^khwS*m!u|2Tmu)B9qEZN}W?Qhv1jIG+3 zrM<(tjv8an8fN#Ss}_cX=>pEXe#xLfBHS3vJ6-p1S?6CykC+lPfAmqX-Ctf(%a**O zaJ6M*62sZ(4qkkHMCD?6P(?*xtWCA%$NIa(W;MHlQ+3@l-~9`yoM6o}VyqhOUfwyA z$wYzBM3@HUqc~;nJ2;~m z-ck662f&ui{f2=|Og>Y@#ji6GsH+x?-0mmvZa$LXCZmK(Jwf*g{FS{U4iUkBTeE!> zxn6xmsk)=rJ3uTJbAWINoWb^Ae>i-WH1H4T=@vabF*pK28uYz2+a8noQbqD~rg4LR zAlEo`B&?#+-jJe7KD&ShewJeCrM6hbA<5yxCh&*|;4J2_|9nsNO|*RQ%B*!6f4J+B!q zx4r@wk2kRpwOJFyqlf>ZOCPWv2E-!SN)^AFMfN~wKrw%4Nu>XeCIa&;xm@a!`DM8M z>s2wnb0U||2Rh$f89jEKX*`}JcHWNs@Y2ohsOd)5@*(o=IF#vL#x6GVhhCU2TTz|t zMtRy@!D6o^JKl>Fw>`9N7{g53`u8%VEf~3P^zts=dbQ%Z?5WJCruVLO$_kwTmOmld zcuP{2R$9FxD1%|QT%hgy?mj;(Y@z)Lr>4!H>t%+QitA3+yy|_;Ib@2W<2%T2@rEuBvfu4be(_URr{tM+P zv#&Fg{@_(yj{-Td76)FY=anr)F6-a;T8R=;Lg_|(d=AN@(M3Rs`^VhDvxC*T`(S)$ zn-fHrl=iyw=!jSQqWo13XHY(pSHhsRD^D1pde7g}jEGCe{FPo$w?X{zxeZ~=j@f3N z-a0hfZcR?-38PFE4HcFDiLj?!NnPhkNKKH6 zDdCo|caZm?OcWSdIspcb?EhLpr1n0{tF{>CK(|HQt%*h1vq zNtHhD3^9=z*;0tfITXClWQKprh}JO{y*(z1VG`x0nNe(zXx)0Dd&|pbC9%J}aU3G% z$Pq+-+KQ)3=-iV}Q~%r~APh2atR@g3mEzYGl9v7{wqf{s?uZ>b+3EjXUb^yn=`T)! zU3(T}g<3;debCXTJ?l&{6r4_xS`R+Y%lJ?uWJMV3)pnb0dD=_t(Mm(;aOh8V5?CZY zw@cwqjx(cTxW}3Hd-%=gTk-0w)ldQD-UTBDpcixchm`H7#~!AY6al#$*5v1&I0}{< zUjvZ#kedC-QdyENg7rXZvBhKwoakuT{@AuAP=CmV5 zn+-L!WlhO^H!DLSM7#IPZbx}1<9ZEvia#5c;*acKBokpm(cmB;MTi->*>a(((0Fdn z)wJCfKdnyNpyfY4A)UU|$?+ZODwZ&IGaNWDvRI;vKW;hS=;do`mmm?kZ=bT^nJ6=q6{2)6>X?<8eq{c3&jtVXKq~Eq^Vry&qRoPo6eIs|<4>M8tm7k!ii(O9%pd?Y5l%tQ zor=T~oxKhw#Q+nOqila$G|rA8f7S3!Gy`ZpCBBGsXap@fz>Of0iD$`W%%o8a7AQc(?2UX5mONvAcE07YgqkpXC39WFR1zFSD7vBkaww5{tV@(evpC_Ue%y_grgG+#5n@R z7+=mn(^RF&$&u}>dfj)Ni7d_wuj;HD^rMSZ>4g}mYOXJ@Y9AZcz#PtOF-0L{C#MZU zR0fXM+cVBzpN!JPL48O9U|MuW9!IzHd$D)-X7-2yJQX#~%_ed56ukTGK5yn7?=zk7LhA5jm8fX&qpCRiyJGpq z0}+GD)^)=TVPFItt;u41NS=*Hew=?Nxp4$9y5xI*i5YUc7EE4LpjDIOjgLI?k={64 zQaTtGWPwvw$+Hm0d#V5FszZC$(#%jVK!U0?{XJennwQptIzUZmY5d*nEllIRMu3?` zN?KZ@=?|JfMDQ;xq4lZLM0q}g=dhjr{5m#aM2`S{4Q(+%5UOFamwE&2T&iuYKBkx< zx*=1$_DB~AvyONJ?3zX`93BJ&37?U8^Z=&QHR(?-pg^>_*GEkguJbgSpFwp=vWdFJ`zRqSSIn+=>)R6w=U&=JUEAQz zI7-Q$ooc~}ej=o?un0SxgErgn#n{J_-r#^4u6WK;?*t-0aAZ&W-L%gim!~#t?du&; z*Ync-vh$OU4yJ9~ zAj`{6DDi5HqV6c_>NfwktF}mKI*#BaU$>mCC>${wP2re1C{FLzyUQ_-vsU3@`!&v& z@;A<-Z6C%=r<=8$Qb0`s6Q8d3kY=A9(0^zh8HpU%G#?K1rvVbhZ)!Wyz6rzg{kD&+jO_C1>- z{btJ6z7$^D8;A#Y%$&eYhc{&(dLBsgPnf=I%H9ljkZcHd*rEh?co*?&uo0+BwnYZ< zizvc5sjkShJaY(b9|z z^&=*{hrp%8t3HkV3$AiefRc5F{VGr5ur6r z*~YF$+tDHYS64M192}9+X&@jZ6F@;eE47+oWYEaONFL+%km__`KzspAD6m*qD?!Gk z1c!HCVx!oViVkMmX+&8Cr!~@7SnjGWC~)E;>FD9P^w09Y*W0P#kvRpGY;#KlPek4X zTr;E{2}>6@hDbeHC*h$z>b|39q6jEw=Lu9aw`JWfh}arv8>+sTVwj>XPem<_m<=U? z_^CiTDVC+B-BId3x^!k3Je%;E9PgBRd>~b|d#*U2rT*jiTUZD%DFqe$FBQ@0X(r%1 z5^%b%%?tIwT_E9xeQ|oW{I}-p&v{BDQKQF?BPA6(_&It^0bzl{!bS?`@)$RDOk0wps0-z{5D9sf10I1(n~^4FveyrCj|&KAOZ( zU7l!w=wD&P^Gl0_ZFj@YBc&PsL1H@I5an_h5XMkk#JnE&BIu|ry&=-SskU?jDQd#B zV^3Tc=M}^m@)OjSQCf6F&<(`B@p{XD@V%Hqyj{-azS(pHI2O}y|J%XWP7rhUW_}Un zwO=zahCMB}3_J15OH9;@T0+P$7lwZ+v%TG$peCL&f{-k(^Wb){LEmCG`t!7}bbLn`0mWTjeuJJ2u&E@s;yBhw6SlU_UO}38L~3{@2=w=-UkY8j zxMYYbwrpf+0Yr-_WiN>O`|%4*)w3K4k&)&UIQ(xe=U<@n!HDgCeqB!e}*Fp{50gNI2sjr_7@u&I;nW`n@ z9wS`TbF@rmiwhJr9>ebk2`#UYH6zTBbOK2=jh;`>=B38kqi!Y4d8J}9%s{uz-=3}3 zXYobFW}~)U>`EoXnB?3nQH@=bB1lA^pH)j~2~Z(zB4W)5W4penC!ag%(=%}Vf()># zighb(jbX}MBlQT8#u~n~(y65BDGk}g>L+}vc%1cS#A*@wq?6wT^@n2cp1r!GDjIM? z47kb+9|eMKXxPlTng;if`)yPhJZ71N*mFmSBfsb{{ep(h1VxGl2t)uyIxf*{U>zGV z$dR+jACxyy;A|c6vf&@%oF+Jaz>~p)IM~-rMJJ>ie)0GJ0I2Z!l(Vz5Lb3R~07xRi zd>RLk7bB%k*Ds@Z!U~0bzG|4t2*29ah+c%qqRm~5jg`rZhCLelr0j$C#pxGAl z2L7ItzDPGZ&$?0}-(A`$%g`A~fk}LHbUiqWu}WuKmLvFm(QMT>dBjVtWxCQH(ZhY> zq{o)**F)yBX=<^mvXUR)io&_EMkfYSBR4s{$Uvh_%chf zHXB{NtX>Oh<#li!e$0K0HZ@seUGcfJZIlI34Tyv$f=*)&+2dw3mkH;cIef@VXzirx z>BM9E*Eu7zCMLv*SoCwweW(=SVF77j;^FihtMSg%CWjtX+^# zt$GXYjgV)*pL|HkaosEFNtNrFDXg!Zdk|-Tc+A!GRe$0lR_h>Ln^N#~a`6QTU|GiR z10ptlJ8N~ca>Y&T(oHw_I=&jjS2zhPnQd7yagnK?RMPVLJ0&FFtea=brb)&J5E70t z?bxNAp8mvWaH z={atQgCFe+v#<}Xa)M@~mGQ`j;y34Hmc}kqXyYg4lVurjI_}+k>#c-lq37V+Ttls( z#5&?>f$y&!^jgp+RXXk5M44oI+$&5fAsxbO5>#e*Y{jbSsK0@xQl4riW2Cvsmy@F@ zRG&cz!K5#9zutAq_}e{FH~Es2AfLRCJ8L<7 z#3QSzJ%oY<81PY(+Fa@yN7SvAsWV-!D{Y9C)N5FKU>wV^o!P9FYzl6ers469`7*6| zB-;!~9q}%@hKcAqM`hfG@-jfVlncx>=` z)l=)kb*vJiqTel-Dos{g$1pkc34?=!Vb9bf#P*D-l?3HEfU~CcGM}~WCgiNEK4;^o z8QS3`!znappjE;zAvB(RlTVp2k8GJ6G^Q|-{^TXwB>k3MnY!;fU43&|ZIvB-Cc{Q_ z@#Ge4g;~}^HkLx;8k+13m2Cpo!CW6-*ivmwQsyu9CB{6GVvhTpnwr|HgQp~wmEpC8C-DEMb2Y6Str4 zhBHf|)q%EfDD0mR)#Xa4(!o8cZ#r0tq9@Yt%nBgIgb5Jz;*%MA5brFQwdtCK8!Rx6 zF^aHkq(;Pxue3o#(nNAL?vi?Hlj^qBp%6|I3FsxnVYe|JO`?jz<7OknlU=&@=#0W; zOo%5DLxzKLKdWk4t}}uz5RbiVE@&T+qlJEV5_K{qpHSXWcTXXO&74R{6P=FdT$P%_ zK5ZQIV$LgQq#5F-o?84V`+`INH^iX&0x5EUD`o8XdEJzK?o>)XMYpOk!8y5(aV(Bq z5MbA)J$x&N28=p3r{ww%$7rZ#(1f>GSamsXo&NU^;5Qkzq0P4p6aaUgwaTYBf|!4F4brC?y|Gdq=$hDguTrSFD&Ao)!f@%3^hPv(MYlH*jTn|M%Xeii%HOV*yiq7%6{%Zx$R!_p}utX3Q28>YC{NTuS<581P! zR8%}ynP4^=_FFt~!EJp+gX!vtGvdzoCb!FkPeD8pk zHCYP_DiE)sA*~AH8~qLZ=7>nbzf~C&Z5%7Bng97?sP)3u{d!6r0*56eDJj{3;Njr? z$N9C=g{g4V3h}76Ns;2b#$Xq}C<=!&>ys>)!`K{-G7JGH0k2a1yMSf5KnRy&SZplq z`>nKQhSteON04?d;)$=<36UTmYykDwsiwN#%D)u9Y<)q5a-0ZU0};k#In67I7aeEQ zrqc)ovQSBU9cc|{>U3PP#KQfBwW?q-G*QV)cax9k0mE>hCdJs*Q(|gr>TXq!^O-6X zJZ^s>RbrS3u_O)$&L&O5HUZ-{_wC$n1vo$hxW7mafq z&)b10Cs-i@-qJryHXqPZ37C@_ievO|28L$&mHlbfVA$uC?2aN^pEAPoG8W|$gKSKC z1EyAdzdo=y>tcsnLFK-vJF<~*-P-J+PV(=t-_wl>f*pEYL(uywPGq*oliYqRDa-QbcJtoOzy+3W z$X;pW8XbGo-~Bf1-E6CwDiT*j^1SN8(6vRVr`dUe9!Gfgbsw7jJMj(cM=(GXykzdX zU$tew;V*7%t!IZ9a@BXt!rIa_aD4ukM~TrlWYPG;LsJI_2V_f~m5axIgDQWM>@}G*@ggkcaq4j7BwcjZ2{1JW-r458-vvM zs&61ssHbtb-l8@_ozE6Q+@V}*g>_AT)YmSmG+>$~8)W+(7YM4EFw~V%9Sc;1#gQjc z8?GaR$1~YuCo(lf-B?rKHtrYdi!ZPaG@?IUpuTwlA%ayJT)8flT`OtjgD9dRy@RWCL17 zQP%rREI=QTfGx|MWi*9WYnXnReN0B`4^+LZ>CNsyme=hF$o9ockVX}!U(N5-GVfhP zd+B5kmESTP$y~@P+S~Shc|mHi1eIIPcX4Ls^mM?=svwE_D^QN-i$NTKN$Y|G1%3)GSJ%`w7D@_;hji zFn6ExN;lWix{O!daJ`3ehswtz@qbZvk3V60s=#fe5tW`mFilqEG304=9#_tfZIhR*Qr3hT^!R z6a`c~4Rp?{I@b9=UDHC*xQxy;Rk^-FT~?gsJy>5E&ZV53twZ=>#gyjlG1ckWXTf?j zAfzDaW^Zus!2`wm@@9x&s_iHThamO+iWgFl5IgdAIuP+@oO$Z{^X+PGe!d?R>mWfU zg1tEKz+I?CA;ULxGX3i3G}@i0l9Q7$GvaF-$y77clmq<1#POU_*P5-F zsT(*H&0R4UZ3&65_fnY1<#VD8Fhz*tMY7tH?SfCQiawsK#&X=Q0E)w=_z>3RYz zzno~fPhG%B`-X@WlhXR;%am5?O(HGQ8@>R-hgaXvxu zqu)?bS>-5np#rO62{R%x0>xxDEVW_kkVmeHoG`BOmLH&0dG|bo-ZKBE9e+vo_fQ{z zVIEAcs$9;Cqe|sK*}BG3n*N2;QevHrRbe9cJ8Rgs19wRqEEJ0h77~fnA zlm11EnVacwTBP-q8b7^Zc|AdNX{NE+S~Ve;ac@Cs*POkdpvTOGxN=Lz`?J;QyN5Qx z0;|@_%(>ZJGZ;Tj&Xk$-7yuGnX9)lqh>@Eks?v}?h05%yiT``f){!0n>0fo0dbhMj zps!@To+Y1Y(mTDz1Ig{6G0h6U0f1Su+WC0NC4~8=*$J#aKbtDGnni+??on+sud(DE z8JhPnD~?Gto+6DzqZ{$aAJ}Sw1y_W*y$+Nw`0?#q+12JR?wd3e6B_p*}8t)&JZ zV66Q|i5!Dem(5r%eylWLTkoo?-)O4Sze!5N;iaCm<<=4u=gc!12`;R5WU5~=qyO2N zYtb{fh_$PM9n zIZ#?rA*{ms zxN1p%?&2Ad_44vUbx=LW#wpy*{DSHHXeGYGxE<$( zs<%0i)pUJoO7VeeT$CPh1npx4yw&rmP8sx)RLq>}Nrj7foK9$Lo zVv-v~Re#u^VLxiH0%d;$sQAm_CRJHQCGUi*ycj8Z06CO&?EZ2i6I2*wfEgr2L>vzj zFA=o3xcGdFY#p6vfN35gw$<%zVQo!TOlj&-hZ#b6JuQrA(6HimJ3^7}v*u*eenJis zB2NLP1L&V$Zhb=iBhM~PmyE1u@hL!T9sdp1b$u znX;PN-DJnrZ#A`{lakyR3W`t#(kvJPB~;CKpGW)-c2HuoY|I&-LJ0$!F(Zgp)_ng= zazYjDy>PjkSCYT!`$-Q9hwZqspS}2Uyly3RJx<8h@#V8{$;OsOH$AUpot;&1V3(X3 zoQxF|A$l~(q=ktVB&8%3C&^N;$maG$5eXU<5C{TRUN_dXdGC17*#dDs@7cRo zlm%(9^#;^n6&3)30D(x+@R0oQ)^c>d;WO$#C^tR#r`mkln`sF-?l7e@4B?y2l%!l} z{)^2FhjC?o)yHKBnVM`3(GvX^C`i(azD=;|9p^obCyr{2<$(@vC(C zoi{!%H_hOXaQ}%SOr|z3q3Qq)OauttoMg>>5OvmmJ2WA}f<$zgKxhummaI}TY9m5b zV?k&D`wfy;XeCx_Ml`;DK%V(7*qsvTyH4aA6d1r@F*28Uz)@YRExOcHRKHkHO;=7C zWA|!SMjoE^_Ypg6X#TI~034f&R2O(o7wLQ(6? zNZ;M;7rixpaCKEBeOz1a^-~rct}N7<@~6Tq}3nzhaPMq>5#>0O<} zNT5NCB)-;Sn4_j+{6BnAS@D!BDHMC=QX{?T3qLS5p91O|`zeXw*mOK0{@{AS5(mcY6fI zmUizuJsWvgDIpBc*ZbXg7H6V3fp^jnzGu|iRZs5f>Z;3N5XkE(sjEwH;IiSIxOG)g zn(~Gi5Mpxqh!#`PD4w$(pCpEhkcb#D1_<5-e(u$MEGsVki{Fa?b-ph=K(J@ChWBK# zeNo1F!Si{e(uM05%2r;dS>gyByA)rXtdAWq^*SS4=3huIH>3MT5`;+m>UpRpb z(a_SVbO-I0H9(t|#N6De1>epL#LX|lo2a4;?V89g=z{_gBNi%~q@=6pLN=eJX*Br& z8@jo;@H*#yu|#SIiHF5h(r^Jnzo9)M>`3xOaZr-l`F=ab^R(^=6Ce;S%Etl^N;+xK zEsxaACp06eqzvES!I3}ZK(79(`wby=Y@pTvNI5(ufA2&p*|%c{KnMjv42_MAwT1&f zz(D1AqhUKhCGRXqe{<4^wF|j%?8ZxW7M5!uB0q!CA&96oxmayl_c*H(AwhBi5~9N8 z|N0^2wF3DwheJ^E5taciaB)!;lr8L{w>&aaC#y%E%-*E23U@T=9XzVlhxgJUX5p5b*7AJRJzi z6ab_b z?ta7fdg9xJ>y)3_<}+u603PjbbboO43=p&s{^7`$*8!4UQK zCCqMS+1)NeBHe7LA)A*RzwYQ8dfprnxa<*xrQY|W-f3gE+!>ejJicY(WGxq%;JPn# zWHHZ1va|nSaX5r6A?D1&^|_4B@_zS+{pkGYFIs;e$A09!XE|JVg(RB-ELX~SAU%s)@JzdVZe5O%sX>C5|2i-NdpE+ zzs``*heCgOA#5Qw%`jZ^Y+73lgGAt1sbR;(DOEwH>`ut7~jVoMw-% zYaH26wHaw7GUw3q>x?_zVK7^$^F33$e`cetdn`qRv8d7g>b{{jT(1##e|WI% zq;O#e{KzNt%Oh&LJ<-_S379LH{(IE$^eo)^F}kPm{P1e@yLZEmF~eLEr%}_{_g+F^x{0xsuymxK%q1p_rvbo ztFv$M>2hyn5b2)wkq9ie+YKUi+>)>omCUx9 z^<73+uQlt>n>wF|4;QBmhF%wMs=xTgKRxnT$n9Y0$?b&$1UZfy>=^8>@SZIn5;8Ji zn^$@C+LdQ;GPRHXz|vUE0TNOWQ)Y&+hGE}!}!#(*1L1TBsH%Q%R7qeBMJlv{S_QU z$E8YnOojtgQ*B?qE1o+@M+~39bF7ibhASyIPt~`)7~S`qAVZ#*XC|(HqM?u9UvKBl zxR)1a+1_yUZ}&$)Hk)~d4%hA<`2G0`bCKh>VqYr*1EOAi21XIoXfcgeJE8zWyX#)) zJ%{D6KgdJ_`n6O3QBtJkB$2iC<5O5qv^$q~kH%vt(E6$HG4A^?`;4MtBEX1nOUDL9XG~55^WgIFB>)_nNci| zAm_GPL9imoYd|RU6yVn^Wg>?rZ{>YNzPK$QdjWb&VY1X_PQ+T+zgG zcY!I2!fwasABe*~xTm@u_h-z})=Aw`RUjCXNv(p>tro>U03(m2t- zRCMG~IG6=|S z1NCvf9vi_xK~PP>1jN~W%IIYP8OED{`E}+UvR&B;2s4!I6E86Y6@Bj)^{}WIPXl!u zA$gdGs;&`XI*7U<40?dgtDWoSYm!SiYN<~0f*g?$_M+(jPLe&l+}W)C})Z-w&bvhi$5cjoUDw0dC9df(TMdEy7M z#&!)*z3toI&oe*!l!YQvL)YDIgsR`J-dR~!e}_EZBwp-v;jEbFZMz}N9?J3XZ;0iO zOC#ToJ99susd@I;Ky>r7)qSOY@x%k(&Cze4tkvwcJuS{nD-WO{zGpK-S)0}{Zy7C^ z<=PM1`wDzFX8C;F(9ii0W}J}aK2BYVq#DBSpN;L_pWP$Bo{1!|UngU~9oCC6nt!HV z8*RsH_UZ^TL3>!XKAa^9hIrh2_D0q9K9Ii5@J1Yx;m!%sI3gNjYT^52d1SXa3|_#Y z^xWoy!uP?JCRpo-g}&?!F45`Thxo<$`Y7M_CnI&N_!A$GQmZS<*IO@oh%8TB^Q7r% z2A7a`G9kpG^6Q=)tPf3^64wzfmhTobHitb&)ERKi4ydHw+f2W@{X~?mJA@>#za43X zhT9$~(IYwJPr>Mku6y5GTDe{Dq|sIZ1~zQ&?DJ3T2M9wuoJgX)6yIuQbf-_06R_O? z+ws=bKG0BN+Jd&u^Xl8{!}&M7z)61oW4GtG@!l0e$m9us65|>|8nEGqU}kLq}dsu_c6Z75G%h*@4Y4x=6p(`V);>!#(rdw(Y+Q+ zo!c1-n;O--r3~Q?eYbn}ben24WWToc8BSjl_IBwW_w{x`>f`!#hWeA?W&f`3Xr;}4 zl8JCMXK3>u+7ZD(eZt3eQcs@>!6oqcBKaQI4#_Ns3yPgDhU3oErppN%aNugj#@r!V znBN(kqY2R!stX+FmLqFi>=pXrlv%4lJnMN)3$7ToYsCfK!zdVnndG@71QW_Dl?(xw z#Tb46V~VYx!u~};5LaM@*FZ*U!aQSJ za$Kj)t@C=+NJ3qvqQ#Q|F$Bh1bnWDXqAHCFV1lS^&%0Z7#v{ms=WQh?UnXPgHl$l? zSic*XC1N`|7ISst%Sar^B8Wk?_)H+0>gaZio&pn&$@9@_lJ{yoYHGz8OA){b$K;SW z83M_TGkb3H$#vg*8Y9FN!J&aUCg114^3=-P7^10!Zl{F$U6BFJbxxL@(SBD1R3^ig z2_FiKKNUyg2SvI0g0WO}&k6=f5-b6f5pZ~1NizlFN($<6gkmW@@*K$I=#l9^{}3yv zsfAKTpzdQRC>kIjsWWMX0(btFwNb^VprryWs=qh+e0W$P;MApYdM(V(j+ZA>-@JWL zmM1U)nTq?(Z7h0C8(QuXYuBtq@)bbIq1h9ek(&odDY=vLQw8sq-qA(QPU&mT)m zMb@Sb=8WRsT56$FN6dJ4dnaY(QZ_bp4-XIK?J2i1Ea+sIaA_&DZ+lCJb08gpGWOI zgq#*|_?-kD#*`7yLaXUVThYQK@C#f3U4Ot*-tH64)b_Pr^4D9A3$1)tW7al1#oa$~ zXhst^-*pE+;VJKokc(UfmLtF(t&|U7{SJ(BLW~}=KsfU!*i?dq>&@Ge z!w7z_Nyl-6>mc>`ZwD8CRO)>+Pn+>Bm!s!{gd+FTb&|^(CUyKhz){TVXc|ZdX4NP{ z3^x8c7Vo9Gm#^j@+vi2!j-S_Rix1|nfPyrUlxK4$269Gdn`v)QAkgkdWVd#%8^#MC zeKqb~I&p5|;b`*VTjf?*4do!Bbc@~E1iJ%p^9Mw1cXn6E#h4(*=A>csvIw2?B7EJOKT4MEe5zvbQ9Kia!goRI|Fz?80*POgIULbXq7?boIHQ_NFv1@2;`fcpHEW9 zC+55aVeh1p#GpHMBC=)MEv>C7mR zE}8(*`10~!=PsF?5r12{wzYF(SuGc*v8`A?XcBT7R;*~=4T)HrSaI#2k(Mu92BWY7 z^C`!3`EzNj0C)eb1t^H+!v+P<#64pNh6|&~AjXiw#6VR=oKpSbQrI{ym*7AqM%DZEpW2K?1(?{i zjl(01DLvBZpdVpUn7#~tX2Xyvo4&uOYjh_@pjjQ}tAO*4-QFpC61Jo}Qlm!rnPY-o95#xrpoMPOi?*uFkHqD$cCA zU;hXDKm@;B$e1S|;K=^vG`{P@K>Oa`6w6x=)JFil1`H){(!JbrdlTkOG1246J^-|- zRm_js_foA^YYIJu+|sTM7@?J7qCx!@T;HWOZ*FpOZ5`PA#YmkQ30_2cFH6KHVL2b?{ym=VKT(CL)-(}6mBcRyhg}6pMH@GuxJM`q1=1IKw;hPvv|Hkrl%{cPMuN<&9WcaOd zJUsMyQjYAV&(ID$Ipi+-KKckh)(=OC@5RjxfCjhHs$D~NTaVEDp6)vD7pL*Ufaf{w zG}5z14QeJU%o#C(uC1EWsmmD51EzBAq&0w@f&$%S_QLCr@Y;;`xhlcU$hSVBU4!fB z-2g6qH-WqF>rN5?4m>AT(z9PSMQ2i(w0I+G=6o?-MV$7 zTQ_|z@_N0z_10TVojR2{bLIr{sv7J+lZRq35^KmuLe&pz2m;XyLTReVLRVEEvQQ`$ z2P-&SykE)-4ZYyM?j>0JbO%49NeD&-VCdi1E!q@`&ZCX)$s zn3;ltfC>mNTCKEf*)kw}2_bwDZp+6jgur64@Y`>{5fc-G!Jw;-1r-aE zzJt>!289zRPSE3y9%VEq(b3VYUAvaen>S;#*)W^U)T&jBr=EHWlgU)ZylFO@S-)XD zO&T>RiQ(lFMkHDH_bMnTpkv35f#~gi@SET)7E8c1YOz?z$jHzS1cV5p4u^x^|M;CI zjhj&HDJ~V6-Jlpq&q$|c&6+ewZct)sMHkGrZr#eMQ>QSS%?uqnl(}=~qN*xw+qUJp z>#i#il6-!2M~@z*sHlj9#DqWyi9kOgFdB?pxOjoOb?OH0l+?A58do>9VEv;zQHgcI zD`PK`sdLvJhA$k=IqO9fVZ!Dp=EJV9VlB1@`XVwilJ@P}2Q4PLYF_htkPJr9RD{sO zUpR6v;V>nT5EaJ7a~G(aoWKJQ^yj(P=1?;xoa8#Oc-&6hUYW=UGf&;wjXCQ!>ZiJL zPw>WquX**QNq9AZLDtR8ilU%u8j38V37-qGBnMhu%J%B}scN9epn2W6R09^p!RB8N zkZ3s1ut~qMbMuE7fD5OO6PA!n^_VaKytYhEr@Lv|xE=tzcmIJVRF-`-n;ZJS!y~uX z@tGnNpqS&w&yrZH9`Vs;9FAfv;bBNXR@ylnYB9>9J@er^QM>quUAD@6eKjf zDi{qC9wW1F}4}Y3j#lMAV>KL^>_o+{=-JzXKw0gkO>*ax*TF?@*~ND0{(FjcQRQpqRr4PtvMQs{m)DpF2*z8cU0- zs$;dg30G9ko=c@pHsgm(j)QVq>sh@s{)xUU*T-}mnzIx>!YtChZ2_27;Mx8m@+0w+3=Bph}-9Xoa; zEG!HmL?E#9ph1K9>Z`B*rJAh&so)>83l}a>uU@^tSRFZ=!3B; zQS=Sx=bwMp<2IR1U-^F)LvV0YQMzwuq%P@^?o;q?y+ZkL<7b?eZwWy?}^X_|^8E56f360(f%Y6%(e ztM&yO*Z#=$xA!8_q#-N%$u}V+WZ@#aNFlMB2_ZoB7UOWJM8{b4 z5}NKrSyG>(3w)}N9yBx!6h+pL?+Y2poz6S67h_Nzbba_4u4zzR58Dv%@lcQ?J!FCa zpD75IEuKeqZXU78?HGJ-4_yT=(1ks}51b^SNRsa0smS=lMu0AK3ZDRqBn8R^4yXu$ zB1@>MUN%3wkl4f+U04!&daz1f=XHPE^)fm>xr~5S^0zEKlC0>*sqw{#(gcCnc9Mi5 zOFj*R%nxh7r&q7ORCEtONw^1)Bwgsy4|}LclA>#gr4pV9(4ne<`ej*W)$)a$y_A7D z{whWcd{ECH7!NsMnnLKCt1SEP2-QO}Ao;W#zTb+XU`so|_S2E{y!9$T1o}(}p?_VA z;COCQfM!VoL=kI#_>Jzp??6^n6r+#VeVwD;;9Q&qG>( z2V^~zh>!N*7-sUG$2Lo=^z$H(03Y}0*%B6L^a7>Cs>n62OPftVg=3|IxM$EOZGh*Qc z4rlMfq(mSI12488Mwr2f>JQ~1=^rCrRmEs9(4j*IOy)2&)r+cW^zYxFZ@yVxX`BB4 zhSDFiXVdcee%nbLnwc7g9O8^N9I$+)mtq1f?Au=+OtgNhn(2|glKxAZO8Be4ku)OB5x%em z;L*Gkt6n6j^kj0o-9$x2(Xv%bs>PO7pZ^#B3;%`x!e0SZRmsW8Vc-7!sJ@Tfs(hI1 zYo)-hn#t0tQ{)oJ&KzpTnTa-QgoQ=<)~8h{>@5}&5?<9yYPOYQ=dw6*CI{IZK`gl>7>iJ((waS4mMJPK zB0fI;AJt&}BLY@cOoaaQoSYnDVq(ge?TkhvXV0Cb!wnq*X0*zf)~}^Gefl(e_Us9m zm@WrG=$AcLt5%Jqq$KQidnsR}ijISpm*zJ?Mn^}Jo0msMdOAf#MWxa!(%i(v#E?`Y ziG=tBii(QLv^TUaP16Vu4<{@vjMUUr^78VqTCJ5%AU}OEF)`GxQ-_G~a0&_vD(xQ$ z300`XM8}|N8ka6!BtJj@vWtj+JmTWws9U!#LI{eiMFA(<%0LJ~R8$l~2-4Hjec>up z${b~^BKQwGn9XLYRjY=@=X_jMb$LZ&7MdscU3mg-Xx`8x!!{=rwfnQizO@!lgSk9?)rZcBy^3sM^o?!g>aJ~o?H@)g&1UA zs~ilnEMv7=iI0yDjBlub6|BYjj|y0RfvUK;SU>h3bm}iVJG+zy%MX6y&YV3!69`#ef`(RQVM_E%{O-CzFQ zbJV|q3jftb6$muJYjCOh0kc$$+2BSMMR-EO!IUPh3{g>0)TmJdtJR9lW(znfJ;#={G`>g3J4#FGE`?^?AscN|IDLZ2^j;(&-^|h4M^k z92Jjgd9+bpS}1KkUb`G^<>CKV(f-zT}w!bqE{?7X0Khhsm zpbY*}8+Xv!7VJYMODbVf=~LyUprUzE=6$Hd5i~n4hoiE&_gB)S(6sVtgVOw6W!kQY zZvBcZ0i}dC|N0?hm8L!ui%jMEFS%rltvW&rKtPs!TpzN?$E$yGc|98s%m$tuF_CHPAzZ&mf z#c{cE|C4F^Ps0CXUi&X?|9sj1G;LRkw<_N(m&5T-z<-jqs+QADe7gAaPnfR#5Grhy z60j;#ll~Q-7Jnrtjvq$~@~`n<4C?!ArrD`e_{B;mkRSL8kO+^EG0I@I>1AYtM0A8i zUY<%+tb)^~Vl*ol5LlfWiXsygDPyx~L`BG0Z7Q0Oh>n$UST($wer#F@h>2CO6{)Bi zL_{li94ce7gfHsG+S zc)S90gp5gsVpYZ{Y1kYZicuyi3<_=f$+!~Dl>|ayH0x#TPQA^V5X3|qu-m*?A`KMV zRoto|EX;t}s8M8xD2v`lvPmJ*Bq*|L$OeUQGdSFWC<_!?^&|8VQ3`ImiqWE=y1ckN z5D{fSb89#}8qtvkTuzPfNC}r+P^=2VED8oRJeq`Afg*>B!5|YEE|FiTQZ2@S&8DJi z0<*<{0S&v;-####Wg@~QTrLfVOAsBUAOi(ODwYTZlO!m#smKPI*hrbY0xuB}1|$S_ zr=VJljMJgv@<6p18M{NnY?kp9YdGBy9WCQ^t9XP=ltsd3(~yiZ;bwu|s-ns=F_AJh ztBMzy*eD5?L&fecnG8`;3bGJ-KN@AC!X;cz6{klcE?UNF)9`pT3?`Y#aNU2xR;1$5 zAl#y0Gzg09g18tNn^nUjASOzG_Npag85wCn78*r1E$C}b!f2L>us~6vh9yeD?BfBi zs`p`Jq=Z3|u-Y_K-z1KTka5_&c#w#RQm|XSz96AGlbga6Bu(Hh*1zcl5N1}eSR@Jx z^q4TRA`u%clb^2=7NMZIHJrs7Vc`l!N#OKAq*2trPvE4D#UWuGyhHk- zP~A>4v$7GsJ54oB5T96`$nY?V@^dICau5-hfGa->Op(M|Ag9oYB%uEbnkt8L=BZQl*j2yh0Pg^H64CZhWBYfd#!Xm2?X_k>p z78H+_^y~tnVymO5b}&W~6=6mIZifS-+3d4;NO;|aCv`;Hz@@Bbavsd{th)kh+5Ts#JX;W?2bcfHIj(rP6{U8TkJuBqUH7 z1iL|01uAH94yy*lqsO6R^&H95IClRefjUU@8zoHJJ5n4ixpd>K)krhi)S-oFl$m7+y zwYeEru|QHJinAO{dOMQ=V`_6vJtM^q5AVE{$~`0N1_wN0bWC)!E!)Vr;Rzhwp3SG*RHi;xoxB_mVHO3mQQt@uqs*bL>FlJMK-lMC(yN(k!5o;h`TY4UTuubn3GP= z2NL*Vb|!ZXt4W832ELe^N^W8_*H&|}@~F(TQHh+`p3BEuJWPMF8e_(1F!-sOTzi#~ zd}-pKsVa>3?$sE-xrv z5AVE_N`9D$VFTi^U$QZKQ4u`{CegEwhf(hq^2E>tu5KRA`NR3lTWY0P6+H7|ZLY3m z;JfcK*nP&p3q!(qYFsvtjjBo0h+?M9&gYruYtf{J0ab%AgT{h+X%v{kdG5&syiQ$E zH(Mn3{glh%EiPVpA%U+y%;HFaMDHHaTvc1fV1RFyUNS^tWnJ%`9>1U_P(S zwXtA9T~^Iar(V|tIyN)2YgGpO>}GmhqcQV)4{yC#9mVNk((9=_IxZRS;cVXi#=(f^ zY7=!XpXtjTJUONo?dlouXrO5jW>T3s@gi}z#xt;IG>RrzzdW5ar)6eOuEnNBX{e22 z>3MxP8K?93a)-vKf$42uB&tE;r_a+cwv40eH5M+O$Yu3G znXU~rzS%37_G|*FC#<|PH-~4Z)aTbvQ>oc8feuZ~xIO<r z(jsoIZ{hcqpYYhoNhDp@lP{MpAQ~qEh>kEZYWP6DS^YD^C(dK?sC!sEVFY(f`U?5j zQYNpJnEzsT@{5X*WCOWp{@~I3ALF7D!|2KL7(3uL<~`e!oaV1G`H>`U>-i9~zS_dK zlWt*~d39KhB$veKD2cGzvRa=+x^OCn2^4v7q-rR>}OXp$sIx$!x`EmXj zKHXJF_{p7Qv>eLj&nNKNtNplC{eFxmm#}d4VN9~db=`Y%YX2UbHXEwfLA`cknDIFE|*K#?RHUAR3r)t3Pf&huE@y9 z5UHuD;{5sZ;`Hg$;@Gic;?SW(V(;F)V%M%+V%xTDV$-HgV#9_FV$GU0;@r7&qEcAB zTK`ubxLxAOhYpFF&G(7hy6qQntq+J@DJ~&|5U&h5D3aP87Iu5F=-+Ffxbf~|;_93B zifLaJ2_bAEDS5AG+x>{RuJt}K{=>|YHhP5+np3o^w@0+Q?Xc+7X`dMQW_lp~*p5um zpxHs;D2JRMmR}S}4gM52_BteLCH*O$o|z$p5aPt3(sjKodvzWs4?t_ln*R9TBbD9~P(WLfFn`iH`lx2qA>H zxGPoM^x!EWgb?X_QpFwp&k7-gm^1E}XmHzM(WUD?arg6=gb+f!)bFVHX20H-69*p? zi+AaC^y_y>?9JE27jK;s_1hm7_dj}6^m+J@=sf(q5W*{-xO>02<-Vh$RqMSXxsP7g z-fu372G{Ku_dIY|wCr_UT+G)(dQKAy-a92?tL+xV>=yNJI4rj8(|h>!hmMG5eNuG# zcU%(GIUrm@6%Y42D0)41Q3xT#vY97^68onh@=tNc5WP(^C!G*-(jL*I-G0%&?S9eg zsS82~A>MxRgb0t?Ek?X@RVRp7)a#faAYpiT2m+ z6-4b8#O@Y7hMX1!9w9_wk!V$KkC1BY5!=%=Aw;q0a@#)9uuDpy?BwysMAKXK-%DRl z5lXc`g%tIt=r#PDC=Tg|hkNf49s8Xx!&~b=JSQTrIxJ46WD7&}JtC>mJ`rAHkB}^X zirYsV7vV{JMN*@E!koBA5ca3|U|p_w_P&F{QggRxa{D1szu6u!=H0APIKP>5QY`w> z8B&ubW=}pT>NnUcdft6dL^aWIUlNtYwy zmfQA_4g8)l`iS^&olOWK#K~Qk z#NA_4g>XAXv!;8+y@OAR2ZtUJjoKd&zh|i8`xz<1Sa+}3b)xE{r?@(($d6{BS(a$X`T!h@zq*VYl0b%jFVow_A8To`C!m41X(e52nl-u_ zuXpc|gn-Ll6(Kmkl{+8LX5FU^ub@1D#@adO`Pm%JyF=rzux!P!@|_flI@V!e2g~I% z{}=u;?B8^rDPOx8{Zt*I3as=Rkjk3FZE08Sp9;R`WyhvmhK@;P_-hS$_P*GE2=BiJ zeq54*qiHgIZ}{tei~swe;&nrhl>YbqEyQI`z?GLC`tEW#{%QIG@7Ao*U)*)qWy=L^ z4W&&r<>aX-z0mFf0Wp!Kd9Va`iPwzopj{eIFh1ckEtXh5OY-=i1J2C&E(I%NH7!eL zW&Nes>5FbJ$)(&nf*q$NNut=A#)=hdahq!LV86QvS4z_Gw=$>=W!qMgck>U+P!rnG z{ibH+oJ{offzPz&FOzfr7#V6Tts2(!wY%y(cDeqjxSuH1CqX?OV#U@oO8hf?bvek) z%p^BAm&T172counJf1+vBSld-dh{q~&z}94MsmO6Q-ozZvf_Ldby#_f6%3jtDE0{Y z_D>-?QbrRc45=vkv!)7E4GaeT+6;ki%as)wS@V*9&cpqKPa_GCWss%P&Tn3C&@~@2 z7-T3aaC7Fohlb5m9{#PMTz3d9U_;k03zc;j0KDE3+I%-kAP^XhGC7xuaqqaux_Bk9 z$m{w1ehR*A!PhPg34>g+Rd~Gu*`PCL0JkXFEL0T?1`rykn!sR?e9!uO&1bUlw^flr z^$H{({lU*(uRvCGf&yhEfhHu32AyVqUkmiR>V(i~kY&(>jz82TMELN9j-%=oXz1f8 z2`Kgoj0XLB7LfFI`S44Cknqu=*X6H7k|kU=4@XXV7`XEUvLus`Z04PD=a4l2hl6j@ zOQ3}CgWiv&?=$qf7N{!71_@`Li#^BOM8%ldusnx9*XN=My__a|ec|hOeY4Q}B6utD zhO`UcxC>2BGZ-Yi-VmP${nnCFpeRzHyuQKc*R%LF`jRA(lkP?fJI9JR8E;Tb-pa

nzor66k<*ip0t$CFR7UcI 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

X_%3F4AV^IJ&c|e|9`yK7d@w!%v{-Dv1U`}u(I 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 literal 0 HcmV?d00001 diff --git a/lispguide.xml b/lispguide.xml new file mode 100644 index 0000000..519e1a0 --- /dev/null +++ b/lispguide.xml @@ -0,0 +1,3887 @@ + + + + + +

+ +Revision 1.28 +

+ + +
+Robert Brown +
+
+ François-René Rideau +
+ +
+ In memoriam Dan Weinreb +
+ +

+Patterns mean "I have run out of language." — Rich Hickey +

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

+ Hooray! Now you know you can expand points to get more details. + Alternatively, there's an "expand all" at the top of this document. +

+ + + + +

+ Common Lisp is a powerful multiparadigm programming language. + With great power comes great responsibility. +

+

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

+

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

+ +

+ This guide is not a Common Lisp tutorial. + For basic information about the language, please consult + Practical Common Lisp. + For a language reference, please consult the + Common Lisp HyperSpec. + For more detailed style guidance, take (with a pinch of salt) + a look at Peter Norvig and Kent Pitman's + style guide. +

+ + + + + + Each guideline's level of importance is indicated + by use of the following keywords and phrases, adapted from + RFC 2119. + + + + + + + + + + + + + + + + + + + + + + + +
MUST +

+ This word, or the terms "REQUIRED" or "SHALL", + means that the guideline is an absolute requirement. + You must ask permission to violate a MUST. +

+
MUST NOT +

+ This phrase, or the phrase "SHALL NOT", + means that the guideline is an absolute prohibition. + You must ask permission to violate a MUST NOT. +

+
SHOULD +

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

+
SHOULD NOT +

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

+
MAY +

+ This word, or the adjective "OPTIONAL", + means that an item is truly optional. +

+
+

+ Unlike RFCs, we don't capitalize every instance of one of the above + keywords when it is used. +

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

+ Permission comes from the owners of your project. +

+ +

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

+ + + + + + You MUST follow conventions. They are not optional. + + +

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

+

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

+

+ Conventional guidelines are 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. +

+ + + + + Fix old code as you go. + + +

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

+

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

+ + + + + There are many topics for additional standardization + not covered by current version of this document, + but deferred to future versions. + + +
    +
  • + File and directory structure +
    • +
  • + Packages and modularity +
    • +
  • + Threads and locking +
    • +
  • + How to add configurable components +
    • +
  • + CLOS style: initforms, slot and accessor names, etc. +
    • +
  • + Recommendations on max number of slots per class. +
    • +
  • + More concrete examples of good code: +
      +
    • + exceptions +
      • +
    • + transactions, with retry +
      • +
    • + XML +
      • +
    • + typing +
      • +
    • + encapsulation / abstraction +
      • +
    • + class and slot names +
      • +
    • + etc. +
      • +
    +
    • +
  • + When (not) to use conditional compilation: +
      +
    • + modifying the product +
      • +
    • + conditional debugging/console output/etc. +
      • +
    • + "temporarily" commenting-out blocks of code +
      • +
    • + etc. +
      • +
    +
    • +
+ + + + + + + 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: +
    +
  • + 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.) +
    • +
  • + 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. +
    • +
  • + Be precise. +
    • +
  • + Be concise. +
    • +
  • + KISS — Keep It Simple, Stupid. +
    • +
  • + Use the smallest hammer for the job. +
    • +
  • + Use common sense. +
    • +
  • + Keep related code together. + Minimize the amount of jumping around + someone has to do to understand an area of code. +
    • +
+ + + + + + +

+ When making decisions about how to write a given piece of + code, aim for the following -ilities in this priority order: +

+
    +
  • + Usability by the customer +
    • +
  • + Debuggability/Testability +
    • +
  • + Readability/Comprehensibility +
    • +
  • + Extensibility/Modifiability +
    • +
  • + Efficiency (of the Lisp code at runtime) +
    • +
+ + +

+ Most of these are obvious. +

+

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

+

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

+

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

+

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

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

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

+

+ If you don't know or don't care about these issues, + ask someone who does. +

+ + + + + 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. + + +
    +
  • + 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. +
    • +
  • + 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. +
    • +
  • + 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. +
    • +
+ + + + + +

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

+ + + +

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

+ +

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

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

+

+
    +
  • + 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. +
    • +
  • + 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. +
    • +
  • + 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 + UIOP:WITH-MUFFLED-COMPILER-CONDITIONS and + UIOP:*UNINTERESTING-COMPILER-CONDITIONS* + framework (part of UIOP, part of ASDF 3), + either around the entire project, or around individual files + (using ASDF's :around-compile hooks). +
    • +
  • + 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. +
    • +
  • + You must run the "precheckin" tests, and each component must pass + its unit tests successfully before you commit any code. +
    • +
  • + 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. +
    • +
  • + 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 +
    • +
+ + + + + + +

+ You must use correct spelling in your comments, + and most importantly in your identifiers. +

+

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

+

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

+ + +

+ If you're not sure, consult a dictionary, + Google for alternative spellings, + or ask a local expert. +

+

+ Here are examples of choosing the correct spelling: +

+
    +
  • + Use "complimentary" in the sense of a meal or beverage + that is not paid for by the recipient, not "complementary". +
    • +
  • + Use "existent" and "nonexistent", not "existant". + Use "existence", not "existance". +
    • +
  • + Use "hierarchy" not "heirarchy". +
    • +
  • + Use "precede" not "preceed". +
    • +
  • + Use "weird", not "wierd". +
    • +
+

+ Here are examples of choosing the shorter spelling: +

+
    +
  • + Use "canceled", not "cancelled" +
    • +
  • + Use "queuing", not "queueing". +
    • +
  • + Use "signaled", not "signalled"; +
    • +
  • + Use "traveled", not "travelled". +
    • +
  • + Use "aluminum", not "aluminium" +
    • +
  • + Use "oriented", not "orientated" +
    • +
  • + Use "color", not "colour" +
    • +
  • + Use "behavior", not "behaviour" +
    • +
+

+ Make appropriate exceptions for industry standard nomenclature/jargon, + including plain misspellings. + For instance: +

+
    +
  • + Use "referer", not "referrer", in the context of the HTTP protocol. +
    • +
+ + + + + + You should format source code so that no line is longer than 100 characters. + + +

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

+ + + + + +

+ Indent your code the way a properly configured GNU Emacs does. +

+

+ Maintain a consistent indentation style throughout a project. +

+

+ Indent carefully to make the code easier to understand. +

+ + +

+ Common Lisp indentation in Emacs is provided by the cl-indent library. + The latest version of cl-indent is packaged with + SLIME + (under contrib/slime-cl-indent.el). After installing SLIME, set up Emacs + to load SLIME automatically using + these instructions, adding slime-indentation to the list of + contrib libraries to be loaded in the call to slime-setup. +

+

+ 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 + hook to 'lisp-mode-hook that calls common-lisp-set-style to set + the appropriate style automatically. +

+ + +

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

+ + ;; Bad + (do-something first-argument second-argument (lambda (x) + (frob x)) fourth-argument last-argument) + + + ;; Better + (do-something first-argument + second-argument + #'(lambda (x) (frob x)) + fourth-argument + last-argument) + + + + + +

+ You should include a description at the top of each source file. +

+

+ You should include neither authorship nor copyright information in a source file. +

+ + +

+ Every source file should begin with a brief description + of the contents of that file. +

+

+ After that description, every file should start the code itself with an + (in-package :package-name) form. +

+

+ After that in-package form, + every file should follow with any file-specific + (declaim (optimize ...)) declaration + that is not covered by an ASDF :around-compile hook. +

+ + ;;;; Variable length encoding for integers and floating point numbers. + + (in-package #:varint) + (declaim #.*optimize-default*) + +

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

+

+ You should not include copyright information in individual source code files. + An exception is made for files meant to be disseminated as standalone. +

+ + + + + + + Vertical white space: one blank line between top-level forms. + + +

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

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

+ 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 ;; comment + what each of the separated parts of the function does. +

+

+ 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 eval-when, + rather than to the eval-when itself. + Additionally, defpackage forms may be longer, + since they may include long lists of symbols. +

+ + + + + Horizontal white space: none around parentheses. No tabs. + + +

+ You must not include extra horizontal whitespace + before or after parentheses or around symbols. +

+

+ You must not place right parentheses by themselves on a line. + A set of consecutive trailing parentheses must appear on the same line. +

+ + ;; Very Bad + ( defun factorial ( limit ) + ( let (( product 1 )) + ( loop for i from 1 upto limit + do (setf product ( * product i ) ) ) + product + ) + ) + + + ;; Better + (defun factorial (limit) + (let ((product 1)) + (loop for i from 1 upto limit + do (setf product (* product i))) + product)) + +

+ You should use only one space between forms. +

+

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

+ + ;; Bad + (let* ((low 1) + (high 2) + (sum (+ (* low low) (* high high)))) + ...) + + + ;; Better + (let* ((low 1) + (high 2) + (sum (+ (* low low) (* high high)))) + ...)) + +

+ You must align nested forms if they occur across more than one line. +

+ + ;; Bad + (defun munge (a b c) + (* (+ a b) + c)) + + + ;; Better + (defun munge (a b c) + (* (+ a b) + c)) + +

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

+ + (multiple-value-bind (a b c d) + (function-returning-four-values x y) + (declare (ignore c)) + (something-using a) + (also-using b d)) + +

+ An exception to the rule against lonely parentheses + is made for an eval-when form around several definitions; + in this case, include a comment ; eval-when + after the closing parenthesis. +

+

+ 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 (setq-default indent-tabs-mode nil). +

+ + + + + + + + You should use document strings on all visible functions + to explain how to use your code. + + +

+ Unless some bit of code is painfully self-explanatory, + document it with a documentation string (also known as docstring). +

+

+ 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 (describe 'foo); + 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. +

+

+ Supply a documentation string when defining + top-level functions, types, classes, variables and macros. + Generally, add a documentation string wherever the language allows. +

+

+ 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." +

+ + (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))))) + + + (defgeneric table-clear (table) + (:documentation + "Like clrhash, empties the TABLE of all + associations, and returns the table itself.")) + +

+ A long docstring may usefully + begin with a short, single-sentence summary, + followed by the larger body of the docstring. +

+

+ 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 M-. + will lead to the symbol's definition. +

+ + (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." + ...) + +

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

+

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

+ + + + + You must use the appropriate number of semicolons to introduce comments. + + +

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

+

+ You must comment anything complicated + so that the next developer can understand what's going on. + (Again, the "hit by a truck" principle.) +

+

+ Also use comments as a way to guide those who read the code, + so they know what to find where. +

+
    +
  • + File headers and important comments + that apply to large sections of code in a source file + should begin with four semicolons. +
    • +
  • + You should use three semicolons + to begin comments that apply to just + one top-level form or small group of top-level forms. +
    • +
  • + Inside a top-level form, you should use two semicolons + to begin a comment if it appears between lines. +
    • +
  • + 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. +
    • +
+ + ;;;; 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))))) + +

+ You should include a space between the semicolon and the text of the comment. +

+ + + + + You should punctuate documentation correctly. + + +

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

+ + + + + You must follow the convention of using TODO comments + for code requiring special attention. + For code using unobvious forms, you must include a comment. + + +

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

+

+ The comments begin with TODO 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 TODO. + The main purpose is to have a consistent TODO that + can be searched to find out how to get more details upon + request. A TODO is not a commitment that the + person referenced will fix the problem. Thus when you create + a TODO, + it is almost always your + name + that is given. +

+

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

+ + ;;--- TODO(george@gmail.com): Refactor to provide a better API. + +

+ Be specific when indicating times or software releases + in a TODO comment and use + YYYY-MM-DD + format for dates to make automated processing of such dates easier, + e.g., 2038-01-20 for the end of the 32-bit signed time_t. +

+ + ;;--- TODO(brown): Remove this code after release 1.7 or before 2012-11-30. + +

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

+ + + + + You should document DSLs and + any terse program in a DSL. + + +

+ You should design your Domain Specific Language + to be easy to read and understand by people familiar with the domain. +

+

+ You must properly document all your Domain Specific Language. +

+

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

+

+ Notably, when you use regular expressions + (e.g. with the CL-PPCRE 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. +

+ + + + + + + + + You should use lower case. + You should follow the rules for Spelling and Abbreviations + You should follow punctuation conventions. + + +

+ Use lower case for all symbols. + Consistently using lower case makes searching for symbol names easier + and is more readable. +

+

+ Note that Common Lisp is case-converting, + and that the symbol-name 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. +

+

+ Place hyphens between all the words in a symbol. + If you can't easily say an identifier out loud, + it is probably badly named. +

+

+ You must not use "/" or "." + instead of "-" + unless you have a well-documented overarching reason to, + and permission from other hackers who review your proposal. +

+

+ See the section on Spelling and Abbreviations + for guidelines on using abbreviations. +

+ + ;; Bad + (defvar *default-username* "Ann") + (defvar *max-widget-cnt* 200) + + + ;; Better + (defvar *default-user-name* "Ann") + (defvar *maximum-widget-count* 200) + +

+ There are conventions in Common Lisp + for the use of punctuation in symbols. + You should not use punctuation in symbols outside these conventions. +

+

+ Unless the scope of a variable is very small, + do not use overly short names like + i and zq. +

+ + + + + Name your variables according to their intent, + not their content. + + +

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

+

+ Thus, you should avoid embedding + data structure or aggregate type names, + such as list, array, or + hash-table 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 + list or array. +

+

+ Indeed, you should be introducing new abstract data types + with DEFCLASS or DEFTYPE, + 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. +

+

+ For example, if a variable's value is always a row + (or is either a row or NIL), + it's good to call it row or first-row + or something like that. + It is alright is row has been + DEFTYPE'd to STRING — + 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 STRING in this context, + except possibly in low-level functions that specifically manipulate + the innards of rows to provide the suitable abstraction. +

+

+ Be consistent. + If a variable is named row in one function, + and its value is being passed to a second function, + then call it row rather than, say, value + (this was a real case). +

+ + + + + Name globals according to convention. + + +

+ The names of global constants should start and end + with plus characters. +

+

+ Global variable names should start and end with asterisks + (also known in this context as earmuffs). +

+

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

+

+ 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 DEFINE-SYMBOL-MACRO. + You should not use this trick, + unless you first publish a library that abstracts it away. +

+ + (defconstant +hash-results+ #xbd49d10d10cbee50) + + (defvar *maximum-search-depth* 100) + + + + + + Names of predicate functions and variables end with a "P". + + +

+ You should name boolean-valued functions and variables with a + trailing "P" or "-P", + to indicate they are predicates. + Generally, you should use + "P" when the rest of the function name is one word + and "-P" when it is more than one word. +

+

+ A rationale for this convention is given in + the CLtL2 chapter on predicates. +

+

+ For uniformity, you should follow the convention above, + and not one of the alternatives below. +

+

+ An alternative rule used in some existing packages + is to always use "-P". + Another alternative rule used in some existing packages + is to always use "?". + 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. +

+ + + + + You should not include a library or package name + as a prefix within the name of symbols. + + +

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

+ + ;; Bad + (in-package #:varint) + (defun varint-length64 () ... ) + + (in-package #:client-code) + (defconst +padding+ (varint:varint-length64 +end-token+)) + + + ;; Better + (in-package #:varint) + (defun length64 () ... ) + + (in-package #:client-code) + (defconst +padding+ (varint:length64 +end-token+)) + +

+ 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, ASDF exports a variable *ASDF-VERBOSE* + that controls the verbosity of ASDF only, + rather than of the entire Lisp program. +

+ + + + + Use packages appropriately. + + +

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

+

+ 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 :: construct. + (e.g. QUAKE::HIDDEN-FUNCTION). + If you need to use double-colons to write real production code, + something is wrong and needs to be fixed. +

+

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

+

+ The :: 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. +

+

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

+

+ Each package is one of two types: +

+
    +
  • + Intended to be included + in the :use specification of other packages. + If package A "uses" package B, + then the external symbols of package B + can be referenced from within package A + without a package prefix. + We mainly use this for low-level modules + that provide widely-used facilities. +
    • +
  • + Not intended to be "used". + To reference a facility provided by package B, + code in package A must use an explicit package prefix, + e.g. B:DO-THIS. +
    • +
+

+ 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 FIFO, + and it were in a package of the first type + you'd have functions named things like + FIFO-ADD-TO and FIFO-CLEAR-ALL. + If you used a package of the second type, + you'd have names like ADD-TO and CLEAR-ALL, + because the callers would be saying + FIFO:ADD-TO and FIFO:CLEAR-ALL. + (FIFO:FIFO-CLEAR-ALL is redundant and ugly.) +

+

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

+

+ 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: +

+
    +
  • + If you are explicitly replacing a Common Lisp symbol + by a safer or more featureful version. +
    • +
  • + 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 log:error and log:warn + and so on. +
    • +
+ + + + + + + + You should avoid side-effects when they are not necessary. + + +

+ Lisp is best used as a "mostly functional" language. +

+

+ Avoid modifying local variables, try rebinding instead. +

+

+ Avoid creating objects and the SETFing their slots. + It's better to set the slots during initialization. +

+

+ Make classes as immutable as possible, that is, avoid giving slots + setter functions if at all possible. +

+

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

+ + + + + You should favor iteration over recursion. + + +

+ 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: +

+
    +
  • + The (DECLARE (OPTIMIZE ...)) settings + must favor SPEED enough and + not favor DEBUG too much, + for some compiler-dependent meanings of "enough" and "too much". + (For instance, in SBCL, you should avoid (SPEED 0) + and (DEBUG 3) to achieve proper tail calls.) +
    • +
  • + 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). +
    • +
+

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

+

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

+ + + + + Use special variables sparingly. + + +

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

+

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

+

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

+

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

+

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

+

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

+ + + + + + Be consistent in assignment forms. + + +

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

+

+ Regarding multiple assignment in a same form, there are two schools: + the first style groups as many assignments as possible into a single + SETF or PSETF form + thus minimizing the number of forms with side-effects; + the second style splits assignments into as many individual + SETF (or SETQ, see below) forms as possible, + to maximize the chances of locating forms that modify a kind of place + by grepping for (setf (foo .... + 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. +

+

+ Regarding SETF and SETQ, + there are two schools: + this first regards SETQ + as an archaic implementation detail, + and avoids it entirely in favor of SETF; + the second regards SETF + as an additional layer of complexity, + and avoids it in favor of SETQ 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. +

+

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

+ + + + + You must make proper usage of assertions and conditions. + + +
    +
  • + ASSERT should be used ONLY to detect internal bugs. + Code should ASSERT 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 ASSERT failure is a developer. + Do not use the data-form and argument-form in ASSERT + 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). +
    • +
  • + CHECK-TYPE, + ETYPECASE are also forms of assertion. + When one of these fails, that's a detected bug. + You should prefer to use CHECK-TYPE + over (DECLARE (TYPE ...)) + for the inputs of functions. +
    • +
  • + 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. +
    • +
  • + 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. +
    • +
  • + ERROR should be used + to detect problems with user data, requests, permissions, etc., + or to report "unusual outcomes" to the caller. +
    • +
  • + ERROR should always be called + with an explicit condition type; + it should never simply be called with a string. + This enables internationalization. +
    • +
  • + 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. +
    • +
  • + Complex bug-checks may need to use ERROR + instead of ASSERT. + +
    • +
  • + When writing a server, you must not call WARN. + Instead, you should use the appropriate logging framework. + +
    • +
  • + Code must not call SIGNAL. + Instead, use ERROR or ASSERT. +
    • +
  • + Code should not use THROW and CATCH; + instead use the restart facility. +
    • +
  • + Code should not generically handle all conditions, + e.g. type T, or use IGNORE-ERRORS. + Instead, let unknown conditions propagate to + the standard ultimate handler for processing. + +
    • +
  • + 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 do need to handle "all conditions", + you MUST handle only ERROR, not T + and not SERIOUS-CONDITION. + (This is notably because CCL's process shutdown + depends on being able to signal process-reset + and have it handled by CCL's handler, + so we must not interpose our own handler.) +
    • +
  • + (error (make-condition 'foo-error ...)) + is equivalent to (error 'foo-error ...) — + code must use the shorter form. +
    • +
  • + Code should not signal conditions from inside the cleanup form of + UNWIND-PROTECT + (unless they are always handled inside the cleanup form), + or otherwise do non-local exits from cleanup handlers + outside of the handler e.g. INVOKE-RESTART. +
    • +
  • + 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 + (handler-case + (catch 'ticket-at + (etd-process-blocks)) + (error (c) + (reset-parser-values) + (error c))) + + + ;; Better + (unwind-protect + (catch 'ticket-at + (etd-process-blocks)) + (reset-parser-values)) + +
    • +
+ + + + + If you know the type of something, you should make it explicit + in order to enable compile-time and run-time sanity-checking. + + + +

+ If your function is using a special variable as an implicit argument, + it's good to put in a CHECK-TYPE 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. +

+ +

+ Using (declare (type ...)) + is the least-desirable mechanism to use + because, as Scott McKay puts it: +

+
+

+ The fact is, (declare (type ...)) does different things + depending on the compiler settings of speed, safety, etc. + In some compilers, when speed is greater than safety, + (declare (type ...)) will tell the compiler + "please assume that these variables have these types" + without generating any type-checks. + That is, if some variable has the value 1432 in it, + and you declare it to be of type string, + the compiler might just go ahead and use it as though it's a string. +

+

+ Moral: don't use (declare (type ...)) + to declare the contract of any API functions, + it's not the right thing. + Sure, use it for "helper" functions, but not API functions. +

+
+

+ 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 + Unsafe Operations. +

+ + + + + Use CLOS appropriately. + + +

+ When a generic function is intended to be called from other + modules (other parts of the code), there should be an + explicit DEFGENERIC form, + with a :DOCUMENTATION string + explaining the generic contract of the function + (as opposed to its behavior for some specific class). + It's generally good to do explicit DEFGENERIC forms, + but for module entry points it is mandatory. +

+

+ When the argument list of a generic function includes + &KEY, + the DEFGENERIC 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.) +

+

+ You should avoid SLOT-VALUE and WITH-SLOTS, + unless you absolutely intend to circumvent + any sort of method combination that might be in effect for the slot. + Rare exceptions include INITIALIZE-INSTANCE + and PRINT-OBJECT methods and + accessing normally hidden slots in the low-level implementation of + methods that provide user-visible abstractions. + Otherwise, you should use accessors, + WITH-ACCESSORS +

+ +

+ Accessor names generally follow a convention of + <protocol-name>-<slot-name>, + where a "protocol" in this case loosely indicates + a set of functions with well-defined behavior. +

+

+ 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 + Interface-Passing Style 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. +

+

+ For example, if there were a notional protocol called + is pnr with accessors pnr-segments + and pnr-passengers, then + the classes air-pnr, hotel-pnr and + car-pnr could each reasonably implement + methods for pnr-segments and pnr-passengers + as accessors. +

+

+ By default, an abstract base class name is used + as the notional protocol name, so accessor names default + to <class-name>-<slot-name>; + 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. +

+

+ Accessors named <slot-name>-of should not be used. +

+

+ Explicit DEFGENERIC forms should be used when there are + (or it is anticipated that there will be) + more than one DEFMETHOD 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). +

+

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

+

+ 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 DEFGENERIC for each method. +

+

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

+

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

+

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

+

+ If a class definition creates a method + as a :READER, :WRITER, + or :ACCESSOR, + do not redefine that method. + It's OK to add :BEFORE, :AFTER, + and :AROUND methods, + but don't override the primary method. +

+

+ In methods with keyword arguments, + you must always use &KEY, + even if the method does not care about the values of any keys, + and you should never use &ALLOW-OTHER-KEYS. + 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 INITIALIZE-INSTANCE methods, + since if you did use &ALLOW-OTHER-KEYS, + it would disable error checking for misspelled or wrong keywords + in MAKE-INSTANCE calls! +

+ +

+ A typical PRINT-OBJECT method might look like this: +

+ + (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)))) + + + + + + + + + Use macros when appropriate, which is often. + Define macros when appropriate, which is seldom. + + +

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

+

+ The general conclusion is that there shouldn't be + any recognizable design pattern + in a good Common Lisp program. + The one and only pattern is: use the language, + which includes defining and using syntactic abstractions. +

+

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

+

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

+

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

+

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

+

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

+

+ 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 FOO, + document the need and profiling-results appropriately, + and + (declaim (inline foo)). +

+ +

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

+

+ When you write a macro-defining macro + (a macro that generates macros), + document and comment it particularly clearly, + since these are harder to understand. +

+

+ 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 + cl-syntax or named-readtables + 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. +

+

+ 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 -form. + 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 body and end are + exceptions to this rule. +

+

+ You should follow the so-called CALL-WITH style when it applies. + This style is explained at length in + http://random-state.net/log/3390120648.html. + 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 WITH-FOO is often limited to + generating a call to an auxiliary function + CALL-WITH-FOO + with arguments deduced from the macro arguments. + Macro &body 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. +

+

+ The separation of syntactic and semantic concerns + is a general principle of style that applies + beyond the case of WITH- 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. +

+

+ Any functions (closures) created by the macro should be named, + which can be done using FLET. + + This also allows you to declare the function to be of dynamic extent + (if it is — and often it is; yet see below regarding + DYNAMIC-EXTENT). +

+

+ 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 ALEXANDRIA:ONCE-ONLY + that generates code to do this. + See also ALEXANDRIA:WITH-GENSYMS, + to make some temporary variables in the generated code. + Note that if you follow our CALL-WITH 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. +

+

+ When you write a macro with a body, + such as a WITH-xxx macro, + even if there aren't any parameters, + you should leave space for them anyway. + For example, if you invent WITH-LIGHTS-ON, + do not make the call to it look like + (defmacro with-lights-on (&body b) ...). + Instead, do (defmacro with-lights-on (() &body b) ...). + That way, if parameters are needed in the future, + you can add them without necessarily having to change + all the uses of the macro. +

+ + + + + When using EVAL-WHEN, you should almost always use all of + (:compile-toplevel :load-toplevel :execute). + + +

+ Lisp evaluation happens at several times, + some of them interleaved. + Be aware of them when writing macros. + EVAL-WHEN considered harmful to your mental health. +

+

+ In summary of the article linked above, + unless you're doing truly advanced macrology, + the only valid combination in an EVAL-WHEN + is to include all of + (eval-when (:compile-toplevel :load-toplevel :execute) ...) +

+

+ You must use + (eval-when (:compile-toplevel :load-toplevel :execute) ...) + whenever you define functions, types, classes, constants, variables, etc., + that are going to be used in macros. +

+

+ It is usually an error to omit the :execute, + because it prevents LOADing the source rather than the fasl. + It is usually an error to omit the :load-toplevel + (except to modify e.g. readtables and compile-time settings), + because it prevents LOADing future files + or interactively compiling code + that depends on the effects that happen at compile-time, + unless the current file was COMPILE-FILEd + within the same Lisp session. +

+

+ 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: +

+
    +
  • + 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 LOAD-TIME-VALUE for good effect. + In extreme cases, you may have to use + ASDF-FINALIZERS:EVAL-AT-TOPLEVEL. +
    • +
  • + 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 *readtable* + or compiler-internal variables holding + the current optimization settings. + You can often manage existing and new such variables using + the :AROUND-COMPILE hooks of ASDF. +
    • +
+ + + + + You should use #. sparingly, + and you must avoid read-time side-effects. + + +

+ The #. standard read-macro + will read one object, evaluate the object, and + have the reader return the resulting value. +

+

+ You must not use it where other idioms will do, such as + using EVAL-WHEN to evaluate side-effects at compile-time, + using a regular macro to return an expression computed at compile-time, + using LOAD-TIME-VALUE to compute it at load-time. +

+

+ 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 #. 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. +

+

+ Another use of #. 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. +

+

+ Whenever you are going to use #., + you should consider using DEFCONSTANT and its variants, + possibly in an EVAL-WHEN, + to give the value a name explaining what it means. +

+ + + + + You must not use EVAL at runtime. + + +

+ Places where it is actually appropriate to use EVAL + are so few and far between that you must consult with your reviewers; + it's easily misused. +

+

+ If your code manipulates symbols at runtime + and needs to get the value of a symbol, + use SYMBOL-VALUE, not EVAL. +

+

+ Often, what you really need is to write a macro, + not to use EVAL. +

+

+ You may be tempted to use EVAL 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 EVAL + than to build a special-purpose evaluator. + You must not use EVAL in this way at runtime. +

+

+ Places where it is OK to use EVAL are: +

+
    +
  • + The implementation of an interactive development tool. +
    • +
  • + The build infrastructure. +
    • +
  • + Backdoors that are part of testing frameworks. + (You MUST NOT have such backdoors in production code.) +
    • +
  • + Macros that fold constants at compile-time. +
    • +
  • + 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. +
    • +
+

+ 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 DEFTYPE expansion, + or in helper functions used by macros. + In these cases, you may actually have to use + ASDF-FINALIZERS:EVAL-AT-TOPLEVEL in your macro. + It will not only EVAL your definitions + at macro-expansion time for immediate availability, + it will also save the form aside, for inclusion in a + (ASDF-FINALIZERS:FINAL-FORMS) + 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. + ASDF-FINALIZERS ensures that the form is present, + by throwing an error if you omit it. +

+ + + + + You must not use INTERN or UNINTERN at runtime. + + +

+ You must not use INTERN 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. +

+

+ You must not INTERN a string + just to compare it to a keyword; + use STRING= or STRING-EQUAL. +

+ + (member (intern str :keyword) $keys) ; Bad + + + (member str $keys :test #'string-equal) ; Better + +

+ You must not use UNINTERN 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. +

+

+ You may of course use INTERN 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 + ALEXANDRIA:SYMBOLICATE or + ALEXANDRIA:FORMAT-SYMBOL + to create the symbols you need. +

+ + + + + + + + + Appropriately use or avoid using NIL. + + +

+ NIL can have several different interpretations: +

+
    +
  • + "False." + In this case, use NIL. + You should test for false NIL + using the operator NOT or + using the predicate function NULL. +
    • +
  • + "Empty-list." + In this case, use '(). + (Be careful about quoting the empty-list when calling macros.) + You should use ENDP to test for the empty list + when the argument is known to be a proper list, + or with NULL otherwise. +
    • +
  • + A statement about some value being unspecified. + In this case, you may use NIL + if there is no risk of ambiguity anywhere in your code; + otherwise you should use an explicit, descriptive symbol. +
    • +
  • + A statement about some value being known not to exist. + In this case, you should use an explicit, descriptive symbol + instead of NIL. +
    • +
+

+ 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 NIL for either. + If you do use NIL, + you must make sure that the distinction is well documented. +

+

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

+ +

+ When working with database classes, keep in mind that + NIL need not always map to 'NULL' + (and vice-versa)! + The needs of the database may differ from the needs of the Lisp. +

+ + + + + You must select proper data representation. + You must not abuse the LIST data structure. + + +

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

+

+ You must not abuse the builtin (single-linked) LIST + data structure where it is not appropriate, + even though Common Lisp makes it especially easy to use it. +

+

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

+

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

+

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

+

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

+

+ In the many cases when lists are not the appropriate data structure, + various libraries such as + cl-containers or + lisp-interface-library + 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 + Using Libraries and + Open-Sourcing Code. +

+ + + + + You should use the appropriate representation for product types. + + +

+ 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 APPLY a function. +

+

+ The proper way to pass around an object + comprising several values of heterogeneous types + is to use a structure as defined by DEFSTRUCT + or DEFCLASS. +

+

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

+

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

+

+ You should signal a condition to denote an unusual outcome, + rather than relying on a special return type. +

+ + + + + Use the appropriate functions when manipulating lists. + + +

+ Use FIRST to access the first element of a list, + SECOND to access the second element, etc. + Use REST to access the tail of a list. + Use ENDP to test for the end of the list. +

+

+ Use CAR and CDR + 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 NULL to test for NIL in this context. +

+

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

+

+ Exceptionally, you may use CDADR and other variants + on lists when manually destructuring them, + instead of using a combination of several list accessor functions. + In this context, using CAR and CDR + instead of FIRST and REST also makes sense. + However, keep in mind that it might be more appropriate in such cases + to use higher-level constructs such as + DESTRUCTURING-BIND or OPTIMA:MATCH. +

+ + + + + You should use arrays rather than lists where random access matters. + + +

+ ELT has O(n) behavior when used on lists. + If you are to use random element access on an object, + use arrays and AREF instead. +

+

+ The exception is for code outside the critical path + where the list is known to be small anyway. +

+ + + + + You should only use lists as sets for very small lists. + + +

+ Using lists as representations of sets is a bad idea + unless you know the lists will be small, + for accessors are O(n) instead of O(log n). + For arbitrary big sets, use balanced binary trees, + for instance using lisp-interface-library. +

+

+ If you still use lists as sets, + you should not UNION lists just to search them. +

+ + (member foo (union list-1 list-2)) ; Bad + + + (or (member foo list-1) (member foo list-2)) ; Better + +

+ Indeed, UNION not only conses unnecessarily, + but it can be O(n^2) on some implementations, + and is rather slow even when it's O(n). +

+ + + + + +

+ You must follow the proper usage regarding + well-known functions, macros and special forms. +

+ + + You must use proper defining forms for constant values. + + +

+ The Lisp system we primarily use, SBCL, is very picky and + signals a condition whenever a constant is redefined to a value not + EQL to its previous setting. + You must not use DEFCONSTANT + when defining variables that are not + numbers, characters, or symbols (including booleans and keywords). + Instead, consistently use whichever alternative + is recommended for your project. +

+ + ;; Bad + (defconstant +google-url+ "https://www.google.com/") + (defconstant +valid-colors+ '(red green blue)) + + + + + +

+ Open-Source libraries may use + ALEXANDRIA:DEFINE-CONSTANT + for constants other than numbers, characters and symbols + (including booleans and keywords). + You may use the :TEST keyword argument + to specify an equality predicate. +

+ + ;; Better, for Open-Source code: + (define-constant +google-url+ "https://www.google.com/" :test #'string=) + (define-constant +valid-colors+ '(red green blue)) + +

+ Note that with optimizing implementations, such as SBCL or CMUCL, + defining constants this way precludes any later redefinition + short of UNINTERNing 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 + DEFPARAMETER or DEFVAR instead, + or possibly a variant of DEFINE-CONSTANT + that builds upon some future library implementing global lexicals + rather than DEFCONSTANT. + You may keep the +plus+ convention in these cases + to document the intent of the parameter as a constant. +

+

+ Also note that LOAD-TIME-VALUE may help you + avoid the need for defined constants. +

+ + + + + You should make proper use of + &OPTIONAL and + &KEY arguments. + You should not use &AUX arguments. + + +

+ You should avoid using &ALLOW-OTHER-KEYS, + 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 (DECLARE (IGNORE ...)) + all the arguments that you are not using. + You must not use &ALLOW-OTHER-KEYS + 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 DEFGENERIC, not in the DEFMETHOD + which is basically an "implementation detail" of the generic function + as far as the caller of the generic is concerned. +

+

+ A case where &ALLOW-OTHER-KEYS 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 &REST argument. +

+

+ You should avoid using &AUX arguments. +

+

+ You should avoid having both &OPTIONAL + and &KEY arguments, + unless it never makes sense to specify keyword arguments + when the optional arguments are not all specified. + You must not have non-NIL defaults + to your &OPTIONAL arguments + when your function has both &OPTIONAL + and &KEY arguments. +

+

+ For maximum portability of a library, it is good form + that DEFMETHOD definitions should + (DECLARE (IGNORABLE ...)) + all the required arguments that they are not using. + Indeed, some implementations will issue a warning + if you (DECLARE (IGNORE ...)) those arguments, + whereas other implementations will issue a warning + if you fail to (DECLARE (IGNORE ...)) them. + (DECLARE (IGNORABLE ...)) works on all implementations. +

+

+ 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 FARE-UTILS:NEST + to at least reduce the amount of indentation required. + It is bad form to use NEST 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. +

+ + + + + + Use the appropriate conditional form. + + +

+ Use WHEN and UNLESS + when there is only one alternative. + Use IF when there are two alternatives + and COND when there are several. +

+

+ However, don't use PROGN for an IF clause + — use COND, WHEN, or UNLESS. +

+

+ Note that in Common Lisp, + WHEN and UNLESS return NIL + when the condition is not met. + You may take advantage of it. + Nevertheless, you may use an IF + to explicitly return NIL + if you have a specific reason to insist on the return value. + You may similarly include a fall-through clause (t nil) + as the last in your COND, + or (otherwise nil) as the last in your CASE, + 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. +

+

+ You should prefer AND and OR + when it leads to more concise code than using + IF, COND, + WHEN or UNLESS, + and there are no side-effects involved. + You may also use an ERROR + as a side-effect in the final clause of an OR. +

+

+ You should only use CASE and ECASE + to compare numbers, characters or symbols + (including booleans and keywords). + Indeed, CASE uses EQL for comparisons, + so strings, pathnames and structures may not compare the way you expect, + and 1 will differ from 1.0. +

+

+ You should use ECASE and ETYPECASE + in preference to CASE and TYPECASE. + It is better to catch erroneous values early. +

+

+ You should not use CCASE or CTYPECASE 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. +

+

+ You must not use gratuitous single quotes in CASE forms. + This is a common error: +

+ + (case x ; Bad: silently returns NIL on mismatch + ('bar :bar) ; Bad: catches QUOTE + ('baz :baz)) ; Bad: also would catch QUOTE + + + (ecase x ; Better: will error on mismatch + ((bar) :bar) ; Better: won't match QUOTE + ((baz) :baz)) ; Better: same reason + +

+ 'BAR there is (QUOTE BAR), + meaning this leg of the case will be executed + if X is QUOTE... + and ditto for the second leg + (though QUOTE will be caught by the first clause). + This is unlikely to be what you really want. +

+

+ In CASE forms, + you must use otherwise instead of t + when you mean "execute this clause if the others fail". + You must use ((t) ...) + when you mean "match the symbol T" rather than "match anything". + You must also use ((nil) ...) + when you mean "match the symbol NIL" rather than "match nothing". +

+

+ Therefore, if you want to map booleans NIL and T + to respective symbols :BAR and :QUUX, + you should avoid the former way and do it the latter way: +

+ + (ecase x ; Bad: has no actual error case! + (nil :bar)) ; Bad: matches nothing + (t :quux)) ; Bad: matches anything + + + (ecase x ; Better: will actually catch non-booleans + ((nil) :bar)) ; Better: matches NIL + ((t) :quux)) ; Better: matches T + + + + + + You should the appropriate predicates when comparing objects. + + +

+ Lisp provides four general equality predicates: + EQ, EQL, EQUAL, + and EQUALP, + which subtly vary in semantics. + Additionally, Lisp provides the type-specific predicates + =, CHAR=, CHAR-EQUAL, + STRING=, and STRING-EQUAL. + Know the distinction! +

+

+ You should use EQL to compare objects and symbols + for identity. +

+

+ You must not use EQ to compare numbers or characters. + Two numbers or characters that are EQL + are not required by Common Lisp to be EQ. +

+

+ When choosing between EQ and EQL, + you should use EQL unless you are writing + performance-critical low-level code. + EQL 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 EQ, + although under SBCL, it often compiles away entirely. + EQ is equivalent to EQL and type declarations, + and use of it for optimization should be treated just like + any such unsafe operations. +

+

+ You should use CHAR= + for case-dependent character comparisons, + and CHAR-EQUAL for case-ignoring character comparisons. +

+

+ You should use STRING= + for case-dependent string comparisons, + and STRING-EQUAL for case-ignoring string comparisons. +

+

+ A common mistake when using SEARCH on strings + is to provide STRING= or STRING-EQUAL + as the :TEST function. + The :TEST function + is given two sequence elements to compare. + If the sequences are strings, + the :TEST function is called on two characters, + so the correct tests are CHAR= or CHAR-EQUAL. + If you use STRING= or STRING-EQUAL, + 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. +

+

+ Also, you should use :START and :END arguments + to STRING= or STRING-EQUAL + instead of using SUBSEQ; + e.g. (string-equal (subseq s1 2 6) s2) should instead be + (string-equal s1 s2 :start1 2 :end1 6) + This is preferable because it does not cons. +

+

+ You should use ZEROP, + PLUSP, or MINUSP, + instead of comparing a value to 0 or 0.0. +

+

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

+

+ You must use = to compare numbers, + unless you really mean for 0, + 0.0 and -0.0 to compare unequal, + in which case you should use EQL. + Then again, you must not usually use exact comparison + on floating point numbers. +

+

+ Monetary amounts should be using decimal (rational) numbers + to avoid the complexities and rounding errors + of floating-point arithmetic. + Libraries such as + wu-decimal + may help you; + once again, if this library is not satisfactory, see above about + Using Libraries and + Open-Sourcing Code. +

+ + + + + + Use the appropriate form for iteration. + + +

+ You should use simpler forms such as + DOLIST or DOTIMES + instead of LOOP + in simple cases when you're not going to use any + of the LOOP facilities such as + bindings, collection or block return. +

+

+ Use the WITH clause of LOOP + when it will avoid a level of nesting with LET. + You may use LET if it makes it clearer + to return one of bound variables after the LOOP, + rather than use a clumsy FINALLY (RETURN ...) form. +

+

+ In the body of a DOTIMES, + do not set the iteration variable. + (CCL will issue a compiler warning if you do.) +

+

+ Most systems use unadorned symbols in the current package + as LOOP keywords. + Other systems use actual :keywords + from the KEYWORD package + as LOOP keywords. + You must be consistent with the convention used in your system. +

+ + + + + Use the appropriate I/O functions. + + +

+ When writing a server, + code must not send output to the standard streams such as + *STANDARD-OUTPUT* or *ERROR-OUTPUT*. + Instead, code must use the proper logging framework + to output messages for debugging. + We are running as a server, so there is no console! +

+

+ Code must not use PRINT-OBJECT + to communicate with a user — + PRINT-OBJECT is for debugging purposes only. + Modifying any PRINT-OBJECT method + must not break any public interfaces. +

+

+ You should not use a sequence of WRITE-XXX + where a single FORMAT string could be used. + Using format allows you + to parameterize the format control string in the future + if the need arises. +

+

+ You should use WRITE-CHAR to emit a character + rather than WRITE-STRING + to emit a single-character string. +

+

+ You should not use (format nil "~A" value); + you should use PRINC-TO-STRING instead. +

+

+ You should use ~<Newline> + or ~@<Newline> in format strings + to keep them from wrapping in 100-column editor windows, + or to indent sections or clauses to make them more readable. +

+

+ You should not use STRING-UPCASE + or STRING-DOWNCASE + on format control parameters; + instead, it should use "~:@(~A~)" or "~(~A~)". +

+

+ Be careful when using the FORMAT conditional directive. + The parameters are easy to forget. +

+
+
No parameters, e.g. "~[Siamese~;Manx~;Persian~] Cat"
+
+ 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 ":" in front of the last ";". + E.g. in "~[Siamese~;Manx~;Persian~:;Alley~] Cat", + an out-of-range arg prints "Alley". +
+
: parameter, e.g. "~:[Siamese~;Manx~]"
+
+ Take one format argument. If it's NIL, + use the first clause, otherwise use the second clause. +
+
@ parameter, e.g. "~@[Siamese ~a~]"
+
+ 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.) +
+
# parameter, e.g. "~#[ none~; ~s~; ~s and ~s~]"
+
+ 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: + "Items:~#[ none~; ~S~; ~S and ~S~:;~@{~#[~; and~] ~S~^ ,~}~]." +
+
+ + + + + + + + You should avoid unnecessary allocation of memory. + + +

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

+

+ You should be careful that when you create objects, + you don't leave them reachable after they are no longer needed! +

+

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

+

+ Don't cons (i.e., allocate) unnecessarily. + Garbage collection is not magic. + Excessive allocation is usually a performance problem. +

+ + + + + You must only use faster unsafe operations + when there is a clear performance need + and you can document why it's correct. + + +

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

+ +

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

+

+ 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 check-type in functions exported from a package + to sanitize input arguments, + so that internal functions are never passed illegal values. +

+

+ On some compilers, + new unsafe operations + can usually be defined by combining + type declarations with an OPTIMIZE declaration + that has sufficiently high SPEED and low SAFETY. + In addition to providing more speed for production code, + such declarations may more helpful + than check-type 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. +

+ + + + + + You should only use DYNAMIC-EXTENT + where it matters for performance, + and you can document why it is correct. + + +

+ DYNAMIC-EXTENT declarations are + a particular case of + unsafe operations. +

+

+ The purpose of a DYNAMIC-EXTENT 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. +

+

+ By declaring a variable or a local function DYNAMIC-EXTENT, + the programmer asserts 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. +

+

+ 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: +

+
    +
  • + The lists created to store &REST parameters. +
    • +
  • + Lists, vectors and structures allocated within a function. +
    • +
  • + Closures. +
    • +
+

+ If the assertion is wrong, i.e. if the programmer's claim is not true, + the results can be catastrophic: + 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! +

+

+ Even if the assertion is correct, + future changes to the function might introduce + a violation of the assertion. + This increases the danger. +

+

+ In most cases, such objects are ephemeral. + Modern Lisp implementations use generational garbage collectors, + which are quite efficient under these circumstances. +

+

+ Therefore, DYNAMIC-EXTENT declarations + should be used sparingly. You must only use them if: +

+
    +
  1. + There is some good reason to think that the overall effect + on performance is noticeable, and +
    2. +
  2. + It is absolutely clear that the assertion is true. +
    3. +
  3. + It is quite unlikely that the code will be changed + in ways that cause the declaration to become false. +
    4. +
+

+ 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". +

+

+ 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 + DYNAMIC-EXTENT, 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 DYNAMIC-EXTENT. +

+

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

+ + + + + You should use REDUCE + instead of APPLY where appropriate. + + +

+ You should use REDUCE + instead of APPLY and a consed-up list, + where the semantics of the first operator argument + otherwise guarantees the same semantics. + Of course, you must use APPLY + if it does what you want and REDUCE doesn't. + For instance: +

+ + ;; Bad + (apply #'+ (mapcar #'acc frobs)) + + + ;; Better + (reduce #'+ frobs :key #'acc :initial-value 0) + +

+ This is preferable because it does not do extra consing, + and does not risk going beyond CALL-ARGUMENTS-LIMIT + 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). +

+

+ However, you must be careful not to use REDUCE + in ways that needlessly increase + the complexity class of the computation. + For instance, (REDUCE 'STRCAT ...) is O(n^2) + when an appropriate implementation is only O(n). + Moreover, (REDUCE 'APPEND ...) + is also O(n^2) unless you specify :FROM-END T. + In such cases, you MUST NOT use REDUCE, + and you MUST NOT use (APPLY 'STRCAT ...) + or (APPLY 'APPEND ...) 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 UIOP:REDUCE/STRCAT. +

+ + + + + + You should not use NCONC; + you should use APPEND instead, + or better, better data structures. + + +

+ You should almost never use NCONC. + You should use APPEND + when you don't depend on any side-effect. + You should use ALEXANDRIA:APPENDF + when you need to update a variable. + You should probably not depend on games + being played with the CDR + 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 NCONC; + and you should probably reconsider your data representation strategy. +

+

+ By extension, you should avoid MAPCAN + or the NCONC feature of LOOP. + You should instead respectively use + ALEXANDRIA:MAPPEND + and the APPEND feature of LOOP. +

+

+ NCONC is very seldom a good idea, + since its time complexity class is no better than APPEND, + its space complexity class also is no better than APPEND + in the common case where no one else is sharing the side-effected list, + and its bug complexity class is way higher than APPEND. +

+

+ If the small performance hit due + to APPEND vs. NCONC + 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. +

+

+ You may only use NCONC, MAPCAN + or the NCONC feature of LOOP + 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. +

+ + + + + + + + You should usually refer to a function as #'FUN rather than 'FUN. + + +

+ The former, which reads as (FUNCTION FUN), + refers to the function object, and is lexically scoped. + The latter, which reads as (QUOTE FUN), + refers to the symbol, which when called + uses the global FDEFINITION of the symbol. +

+

+ When using functions that take a functional argument + (e.g., MAPCAR, APPLY, + :TEST and :KEY arguments), + you should use the #' to refer to the function, + not just single quote. +

+

+ An exception is when you explicitly want dynamic linking, + because you anticipate that + the global function binding will be updated. +

+

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

+

+ You must consistently use either #'(lambda ...) + or (lambda ...) without #' everywhere. + Unlike the case of #'symbol vs 'symbol, + 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. + #' may be seen as a hint + that you're introducing a function in expression context; + but the lambda 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. +

+

+ Note that if you start writing a new system + in a heavily functional style, + you may consider using + lambda-reader, + a system that lets you use the unicode character λ + instead of LAMBDA. + But you must not start using such a syntactic extension + in an existing system without getting permission from other developers. +

+ + + + + Common Lisp pathnames are tricky. Be aware of pitfalls. Use UIOP. + + +

+ It is surprisingly hard to properly deal with pathnames in Common Lisp. +

+

+ ASDF 3 comes with a portability library UIOP + that makes it much easier to deal with pathnames + portably — and correctly — in Common Lisp. + You should use it when appropriate. +

+

+ 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 #\. and #\*, etc., + in addition to the quoting of + #\\ and #\" 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. +

+

+ Second, when using MERGE-PATHNAMES, + be wary of the treatment of the HOST component, + which matters a lot on non-Unix platforms + (and even on some Unix implementations). + You probably should be using + UIOP:MERGE-PATHNAMES* or UIOP:SUBPATHNAME + instead of MERGE-PATHNAMES, + 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 + *DEFAULT-PATHNAME-DEFAULTS* + at the time the relative pathname was created. +

+

+ Third, be aware that DIRECTORY + is not portable across implementations + in how it handles wildcards, sub-directories, symlinks, etc. + There again, UIOP 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. +

+

+ LOGICAL-PATHNAMEs 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 ASDF:SYSTEM-RELATIVE-PATHNAME or + the underlying UIOP:SUBPATHNAME and + UIOP:PARSE-UNIX-NAMESTRING. +

+ +

+ 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. + ASDF for instance requires you to reset its paths + with UIOP:CLEAR-CONFIGURATION. + UIOP provides hooks + to call functions before an image is dumped, + from which to reset or makunbound relevant variables. +

+ + + + + + You must be careful when using a SATISFIES clause in a type specifier. + + +

+ Most Common Lisp implementations can't optimize + based on a SATISFIES type, + but many of them offer simple optimizations + based on a type of the form + (AND FOO (SATISFIES BAR-P)) + where the first term of the AND clause + describes the structure of the object + without any SATISFIES + and the second term is the SATISFIES. +

+ + (deftype prime-number () (satisfies prime-number-p)) ; Bad + + + (deftype prime-number () (and integer (satisfies prime-number-p)) ; Better + +

+ However, AND in the DEFTYPE 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 INTEGERness + to protect the function PRIME-NUMBER-P + from being supplied non-integer arguments + to test for being of instances of the type. + Implementations may, and some will, + invoke SATISFIES-specified function + at compile-time to test various relevant objects. +

+

+ That is why any function specified in a SATISFIES clause + MUST accept objects of any type as argument to the function, + and MUST be defined within an EVAL-WHEN + (as well as any variable it uses or function it calls): +

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

+ In particular, the above means that the + example + used in the Common Lisp Standard is erroneous: + (and integer (satisfies evenp)) + is not a safe, conformant type specifier to use, + because EVENP will throw an error + rather than return NIL + when passed a non-integer as an argument. +

+

+ Finally, there is a catch when your DEFTYPE code expands + to a SATISFIES with a dynamically generated function: +

+
    +
  • + You cannot control when implementations will or will not + expand a DEFTYPE. +
    • +
  • + The expansion itself cannot contain a function definition + or any code in the expression language. +
    • +
  • + You cannot control when the expansion is used, + it may happen in a different process + that didn't expand the definition. +
    • +
+

+ Therefore, you cannot merely create the function + as a side-effect of expansion + using EVAL at type-expansion time. + The solution is to use + ASDF-FINALIZERS:EVAL-AT-TOPLEVEL instead. + See the very last point + in the discussion about EVAL. +

+

+ Common Lisp is hard to satisfy. +

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

+Revision 1.28 +

+ + +
+Robert Brown +
+ +
+ François-René Rideau +
+ + + + 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 + +@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 *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 *frogs = [NSArray 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 + +#include +#include + +#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 // GOOD. +``` + +```objectivec +// AVOID: + +#import // AVOID. +#import +... +``` + +### 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 *)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 *locations; +@property(nonatomic, copy, readonly) NSSet *identifiers; + +NSMutableArray *mutableLocations = [otherObject.locations mutableCopy]; +``` + +If the fully-annotated types become complex, consider using a typedef to +preserve readability. + +```objectivec +// GOOD: + +typedef NSSet *> 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 *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 @@ + + + +

+ The style guide has moved to + objcguide.md +

+ diff --git a/pyguide.html b/pyguide.html new file mode 100644 index 0000000..6987f2b --- /dev/null +++ b/pyguide.html @@ -0,0 +1,2310 @@ + + +Google Python Style Guide + + + + + + +

Google Python Style Guide

+

+ + Revision 2.59 +

+ +
+ Amit Patel
+ Antoine Picard
+ Eugene Jhong
+ Jeremy Hylton
+ Matt Smart
+ Mike Shields
+
+
+

+ Each style point has a summary for which additional information is available + by toggling the accompanying arrow button that looks this way: + ▶. + You may toggle all summaries with the big arrow button: +

+
+▶ + Toggle all summaries +
+
+
+
Table of Contents
+ + + + + + + + + +
Python Language Rules
+Lint Imports Packages Exceptions Global variables Nested/Local/Inner Classes and Functions List Comprehensions Default Iterators and Operators Generators Lambda Functions Conditional Expressions Default Argument Values Properties True/False evaluations Deprecated Language Features Lexical Scoping Function and Method Decorators Threading Power Features
Python Style Rules
+Semicolons Line length Parentheses Indentation Blank Lines Whitespace Shebang Line Comments Classes Strings Files and Sockets TODO Comments Imports formatting Statements Access Control Naming Main
+
+
+

Important Note

+
+

Displaying Hidden Details in this Guide

+ + link + ▶ +
+ 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. +
+
+
+
+
+

Background

+

+ Python is the main scripting language used at Google. This + style guide is a list of dos and don'ts for Python + programs. +

+ +

+ To help you format code correctly, we've created a settings + file for Vim. For Emacs, the default settings should be fine. +

+ + +
+ +
+

Python Language Rules

+
+

Lint

+ + link + ▶ +
+ Run pylint over your code. +
+
+
+
+

Imports

+ + link + ▶ +
+ Use imports for packages and modules only. +
+
+
+
+

Packages

+ + link + ▶ +
+ Import each module using the full pathname location of the module. +
+
+
+
+

Exceptions

+ + link + ▶ +
+ Exceptions are allowed but must be used carefully. +
+
+
+
+

Global variables

+ + link + ▶ +
+ Avoid global variables. +
+
+
+
+

Nested/Local/Inner Classes and Functions

+ + link + ▶ +
+ Nested/local/inner classes and functions are fine. +
+
+
+
+

List Comprehensions

+ + link + ▶ +
+ Okay to use for simple cases. +
+
+
+
+

Default Iterators and Operators

+ + link + ▶ +
+ Use default iterators and operators for types that support them, + like lists, dictionaries, and files. +
+
+
+
+

Generators

+ + link + ▶ +
+ Use generators as needed. +
+
+
+
+

Lambda Functions

+ + link + ▶ +
+ Okay for one-liners. +
+
+
+
+

Conditional Expressions

+ + link + ▶ +
+ Okay for one-liners. +
+
+
+
+

Default Argument Values

+ + link + ▶ +
+ Okay in most cases. +
+
+
+
+

Properties

+ + link + ▶ +
+ Use properties for accessing or setting data where you would + normally have used simple, lightweight accessor or setter methods. +
+
+
+
+

True/False evaluations

+ + link + ▶ +
+ Use the "implicit" false if at all possible. +
+
+
+
+

Deprecated Language Features

+ + link + ▶ +
+ Use string methods instead of the string module + where possible. Use function call syntax instead + of apply. Use list comprehensions + and for loops instead of filter and + map when the function argument would have been an + inlined lambda anyway. Use for loops instead of + reduce. +
+
+
+
+

Lexical Scoping

+ + link + ▶ +
+ Okay to use. +
+
+
+
+

Function and Method Decorators

+ + link + ▶ +
+ Use decorators judiciously when there is a clear advantage. +
+
+
+
+

Threading

+ + link + ▶ +
+ Do not rely on the atomicity of built-in types. +
+
+
+
+

Power Features

+ + link + ▶ +
+ Avoid these features. +
+
+
+
+
+

Python Style Rules

+
+

Semicolons

+ + link + ▶ +
+ Do not terminate your lines with semi-colons and do not use + semi-colons to put two commands on the same line. +
+
+
+
+

Line length

+ + link + ▶ +
+ Maximum line length is 80 characters. +
+
+
+
+

Parentheses

+ + link + ▶ +
+ Use parentheses sparingly. +
+
+
+
+

Indentation

+ + link + ▶ +
+ Indent your code blocks with 4 spaces. +
+
+
+
+

Blank Lines

+ + link + ▶ +
+ Two blank lines between top-level definitions, one blank line + between method definitions. +
+
+
+
+

Whitespace

+ + link + ▶ +
+ Follow standard typographic rules for the use of spaces around + punctuation. +
+
+
+ + +
+

Shebang Line

+ + link + ▶ +
+ Most .py files do not need to start with a + #! line. Start the main file of a + program with + #!/usr/bin/env python with an optional single digit + 2 or 3 suffix. +
+
+
+ +
+

Comments

+ + link + ▶ +
+ Be sure to use the right style for module, function, method and in-line + comments. +
+
+
+
+

Classes

+ + link + ▶ +
+ If a class inherits from no other base classes, explicitly inherit + from object. This also applies to nested classes. +
+
+
+
+

Strings

+ + link + ▶ +
+ Use the format method or the % operator for + formatting strings, even when the parameters are all strings. Use your + best judgement to decide between + and % + (or format) though. +
+
+
+
+

Files and Sockets

+ + link + ▶ +
+ Explicitly close files and sockets when done with them. +
+
+
+
+

TODO Comments

+ + link + ▶ +
+ Use TODO comments for code that is temporary, a + short-term solution, or good-enough but not perfect. +
+
+
+
+

Imports formatting

+ + link + ▶ +
+ Imports should be on separate lines. +
+
+
+
+

Statements

+ + link + ▶ +
+ Generally only one statement per line. +
+
+
+
+

Access Control

+ + link + ▶ +
+ 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 + property to keep the syntax consistent. +
+
+
+
+

Naming

+ + link + ▶ +
+ 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. +
+
+
+
+

Main

+ + link + ▶ +
+ 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. +
+
+
+
+ +

Parting Words

+

+ BE CONSISTENT. +

+ +

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

+ +

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

+ + + +

+Revision 2.59 +

+ + +
+ Amit Patel
+ Antoine Picard
+ Eugene Jhong
+ Gregory P. Smith
+ Jeremy Hylton
+ Matt Smart
+ Mike Shields
+ Shane Liebling
+
+ + diff --git a/pyguide.md b/pyguide.md deleted file mode 100644 index 0e45ead..0000000 --- a/pyguide.md +++ /dev/null @@ -1,2568 +0,0 @@ - - -# Google Python Style Guide - - - -## 1 Background - -Python is the main dynamic language used at Google. This style guide is a list -of *dos and don'ts* for Python programs. - -To help you format code correctly, we've created a [settings file for -Vim](google_python_style.vim). For Emacs, the default settings should be fine. - -Many teams use the [yapf](https://github.com/google/yapf/) -auto-formatter to avoid arguing over formatting. - - - - -## 2 Python Language Rules - - - -### 2.1 Lint - -Run `pylint` over your code. - - -#### 2.1.1 Definition - -`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. - - -#### 2.1.2 Pros - -Catches easy-to-miss errors like typos, using-vars-before-assignment, etc. - - -#### 2.1.3 Cons - -`pylint` 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. - - -#### 2.1.4 Decision - -Make sure you run `pylint` on your code. - - -Suppress warnings if they are inappropriate so that other issues are not hidden. -To suppress warnings, you can set a line-level comment: - -```python {.good} -dict = 'something awful' # Bad Idea... pylint: disable=redefined-builtin -``` - -`pylint` warnings are each identified by symbolic name (`empty-docstring`) -Google-specific warnings start with `g-`. - -If the reason for the suppression is not clear from the symbolic name, add an -explanation. - -Suppressing in this way has the advantage that we can easily search for -suppressions and revisit them. - -You can get a list of `pylint` warnings by doing: - -```shell -pylint --list-msgs -``` - -To get more information on a particular message, use: - -```shell -pylint --help-msg=C6409 -``` - -Prefer `pylint: disable` to the deprecated older form `pylint: disable-msg`. - -Unused argument warnings can be suppressed by deleting the variables at the -beginning of the function. Always include a comment explaining why you are -deleting it. "Unused." is sufficient. For example: - -```python {.good} -def viking_cafe_order(spam, beans, eggs=None): - del beans, eggs # Unused by vikings. - return spam + spam + spam -``` - -Other common forms of suppressing this warning include using '`_`' as the -identifier for the unused argument, prefixing the argument name with -'`unused_`', or assigning them to '`_`'. These forms are allowed but no longer -encouraged. The first two break callers that pass arguments by name, while the -latter does not enforce that the arguments are actually unused. - - - -### 2.2 Imports - -Use `import`s for packages and modules only, not for individual classes or -functions. - - -#### 2.2.1 Definition - -Reusability mechanism for sharing code from one module to another. - - -#### 2.2.2 Pros - -The namespace management convention is simple. The source of each identifier is -indicated in a consistent way; `x.Obj` says that object `Obj` is defined in -module `x`. - - -#### 2.2.3 Cons - -Module names can still collide. Some module names are inconveniently long. - - -#### 2.2.4 Decision - -* Use `import x` for importing packages and modules. -* Use `from x import y` where `x` is the package prefix and `y` is the module -name with no prefix. -* Use `from x import y as z` if two modules named `y` are to be imported or if -`y` is an inconveniently long name. -* Use `import y as z` only when `z` is a standard abbreviation (e.g., `np` for -`numpy`). - -For example the module `sound.effects.echo` may be imported as follows: - -```python {.good} -from sound.effects import echo -... -echo.EchoFilter(input, output, delay=0.7, atten=4) -``` - -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. - -Note that there is an explicit exemption for imports from the [typing -module](#typing-imports). - - - -### 2.3 Packages - -Import each module using the full pathname location of the module. - - -#### 2.3.1 Pros - -Avoids conflicts in module names. Makes it easier to find modules. - - -#### 2.3.2 Cons - -Makes it harder to deploy code because you have to replicate the package -hierarchy. - - -#### 2.3.3 Decision - -All new code should import each module by its full package name. - -Imports should be as follows: - -```python {.good} -# Reference in code with complete name. -import absl.flags - -# Reference in code with just module name (preferred). -from absl import flags -``` - - - -### 2.4 Exceptions - -Exceptions are allowed but must be used carefully. - - -#### 2.4.1 Definition - -Exceptions are a means of breaking out of the normal flow of control of a code -block to handle errors or other exceptional conditions. - - -#### 2.4.2 Pros - -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. - - -#### 2.4.3 Cons - -May cause the control flow to be confusing. Easy to miss error cases when making -library calls. - - -#### 2.4.4 Decision - -Exceptions must follow certain conditions: - -- Raise exceptions like this: `raise MyError('Error message')` or `raise - MyError()`. Do not use the two-argument form (`raise MyError, 'Error - message'`). - -- Make use of built-in exception classes when it makes sense. For example, - raise a `ValueError` if you were passed a negative number but were expecting - a positive one. Do not use `assert` statements for validating argument - values of a public API. `assert` is used to ensure internal correctness, not - to enforce correct usage nor to indicate that some unexpected event - occurred. If an exception is desired in the latter cases, use a raise - statement. For example: - - - ```python {.good} - Yes: - def ConnectToNextPort(self, minimum): - """Connects to the next available port. Returns the new minimum port.""" - if minimum <= 1024: - raise ValueError('Minimum port must be greater than 1024.') - port = self._FindNextOpenPort(minimum) - if not port: - raise ConnectionError('Could not connect to service on %d or higher.' % (minimum,)) - assert port >= minimum, 'Unexpected port %d when minimum was %d.' % (port, minimum) - return port - ``` - - ```python {.bad} - No: - def ConnectToNextPort(self, minimum): - """Connects to the next available port. Returns the new minimum port.""" - assert minimum > 1024, 'Minimum port must be greater than 1024.' - port = self._FindNextOpenPort(minimum) - assert port is not None - return port - ``` - -- Libraries or packages may define their own exceptions. When doing so they - must inherit from an existing exception class. Exception names should end in - `Error` and should not introduce stutter (`foo.FooError`). - -- Never use catch-all `except:` statements, or catch `Exception` or - `StandardError`, 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 `except:` 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. - -- Minimize the amount of code in a `try`/`except` block. The larger the body - of the `try`, 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 - `try`/`except` block hides a real error. - -- Use the `finally` clause to execute code whether or not an exception is - raised in the `try` block. This is often useful for cleanup, i.e., closing a - file. - -- When capturing an exception, use `as` rather than a comma. For example: - - - ```python {.good} - try: - raise Error - except Error as error: - pass - ``` - - - -### 2.5 Global variables - -Avoid global variables. - - -#### 2.5.1 Definition - -Variables that are declared at the module level or as class attributes. - - -#### 2.5.2 Pros - -Occasionally useful. - - -#### 2.5.3 Cons - -Has the potential to change module behavior during the import, because -assignments to global variables are done when the module is first imported. - - -#### 2.5.4 Decision - -Avoid global variables. - -While they are technically variables, module-level constants are permitted and -encouraged. For example: `MAX_HOLY_HANDGRENADE_COUNT = 3`. Constants must be -named using all caps with underscores. See [Naming](#s3.16-naming) below. - -If needed, globals should be declared at the module level and made internal to -the module by prepending an `_` to the name. External access must be done -through public module-level functions. See [Naming](#s3.16-naming) below. - - - -### 2.6 Nested/Local/Inner Classes and Functions - -Nested local functions or classes are fine when used to close over a local -variable. Inner classes are fine. - - -#### 2.6.1 Definition - -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. - - -#### 2.6.2 Pros - -Allows definition of utility classes and functions that are only used inside of -a very limited scope. Very -[ADT](http://www.google.com/url?sa=D&q=http://en.wikipedia.org/wiki/Abstract_data_type)-y. - - -#### 2.6.3 Cons - -Instances of nested or local classes cannot be pickled. Nested functions and -classes cannot be directly tested. Nesting can make your outer function longer -and less readable. - - -#### 2.6.4 Decision - -They are fine with some caveats: Avoid nested functions or classes except when -closing over a local value for easier future comprehension. Do not nest a -function just to hide it from users of a module. Instead, prefix its name with -an \_ at the module level so that it can still be accessed by tests. - - - - -### 2.7 Comprehensions & Generator Expressions - -Okay to use for simple cases. - - -#### 2.7.1 Definition - -List, Dict, and Set comprehensions as well as generator expressions provide a -concise and efficient way to create container types and iterators without -resorting to the use of traditional loops, `map()`, `filter()`, or `lambda`. - - -#### 2.7.2 Pros - -Simple comprehensions can be clearer and simpler than other dict, list, or set -creation techniques. Generator expressions can be very efficient, since they -avoid the creation of a list entirely. - - -#### 2.7.3 Cons - -Complicated comprehensions or generator expressions can be hard to read. - - -#### 2.7.4 Decision - -Okay to use for simple cases. Each portion must fit on one line: mapping -expression, `for` clause, filter expression. Multiple `for` clauses or filter -expressions are not permitted. Use loops instead when things get more -complicated. - -```python {.good} -Yes: - result = [] - for x in range(10): - for y in range(5): - if x * y > 10: - result.append((x, y)) - - for x in xrange(5): - for y in xrange(5): - if x != y: - for z in xrange(5): - if y != z: - yield (x, y, z) - - return ((x, complicated_transform(x)) - for x in long_generator_function(parameter) - if x is not None) - - squares = [x * x for x in range(10)] - - eat(jelly_bean for jelly_bean in jelly_beans - if jelly_bean.color == 'black') -``` - -```python {.bad} -No: - result = [(x, y) for x in range(10) for y in range(5) if x * y > 10] - - return ((x, y, z) - for x in xrange(5) - for y in xrange(5) - if x != y - for z in xrange(5) - if y != z) -``` - - - -### 2.8 Default Iterators and Operators - -Use default iterators and operators for types that support them, like lists, -dictionaries, and files. - - -#### 2.8.1 Definition - -Container types, like dictionaries and lists, define default iterators and -membership test operators ("in" and "not in"). - - -#### 2.8.2 Pros - -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. - - -#### 2.8.3 Cons - -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. - - -#### 2.8.4 Decision - -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. - -```python {.good} -Yes: for key in adict: ... - if key not in adict: ... - if obj in alist: ... - for line in afile: ... - for k, v in dict.iteritems(): ... -``` - -```python {.bad} -No: for key in adict.keys(): ... - if not adict.has_key(key): ... - for line in afile.readlines(): ... -``` - - - -### 2.9 Generators - -Use generators as needed. - - -#### 2.9.1 Definition - -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. - - -#### 2.9.2 Pros - -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. - - -#### 2.9.3 Cons - -None. - - -#### 2.9.4 Decision - -Fine. Use "Yields:" rather than "Returns:" in the docstring for generator -functions. - - - -### 2.10 Lambda Functions - -Okay for one-liners. - - -#### 2.10.1 Definition - -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 `map()` and `filter()`. - - -#### 2.10.2 Pros - -Convenient. - - -#### 2.10.3 Cons - -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. - - -#### 2.10.4 Decision - -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. - -For common operations like multiplication, use the functions from the `operator` -module instead of lambda functions. For example, prefer `operator.mul` to -`lambda x, y: x * y`. - - - -### 2.11 Conditional Expressions - -Okay for one-liners. - - -#### 2.11.1 Definition - -Conditional expressions (sometimes called a “ternary operator”) are mechanisms -that provide a shorter syntax for if statements. For example: -`x = 1 if cond else 2`. - - -#### 2.11.2 Pros - -Shorter and more convenient than an if statement. - - -#### 2.11.3 Cons - -May be harder to read than an if statement. The condition may be difficult to -locate if the expression is long. - - -#### 2.11.4 Decision - -Okay to use for one-liners. In other cases prefer to use a complete if -statement. - - - -### 2.12 Default Argument Values - -Okay in most cases. - - -#### 2.12.1 Definition - -You can specify values for variables at the end of a function's parameter list, -e.g., `def foo(a, b=0):`. If `foo` is called with only one argument, -`b` is set to 0. If it is called with two arguments, `b` has the value of the -second argument. - - -#### 2.12.2 Pros - -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. - - -#### 2.12.3 Cons - -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. - - -#### 2.12.4 Decision - -Okay to use with the following caveat: - -Do not use mutable objects as default values in the function or method -definition. - -```python {.good} -Yes: def foo(a, b=None): - if b is None: - b = [] -Yes: def foo(a, b: Optional[Sequence] = None): - if b is None: - b = [] -``` - -```python {.bad} -No: def foo(a, b=[]): - ... -No: def foo(a, b=time.time()): # The time the module was loaded??? - ... -No: def foo(a, b=FLAGS.my_thing): # sys.argv has not yet been parsed... - ... -``` - - - -### 2.13 Properties - -Use properties for accessing or setting data where you would normally have used -simple, lightweight accessor or setter methods. - - -#### 2.13.1 Definition - -A way to wrap method calls for getting and setting an attribute as a standard -attribute access when the computation is lightweight. - - -#### 2.13.2 Pros - -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. - - -#### 2.13.3 Cons - -Must inherit from `object` in Python 2. Can hide side-effects much like operator -overloading. Can be confusing for subclasses. - - -#### 2.13.4 Decision - -Use properties in new code to access or set data where you would normally have -used simple, lightweight accessor or setter methods. Properties should be -created with the `@property` [decorator](#s2.17-function-and-method-decorators). - -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). - -```python {.good} -Yes: import math - - class Square(object): - """A square with two properties: a writable area and a read-only perimeter. - - To use: - >>> sq = Square(3) - >>> sq.area - 9 - >>> sq.perimeter - 12 - >>> sq.area = 16 - >>> sq.side - 4 - >>> sq.perimeter - 16 - """ - - def __init__(self, side): - self.side = side - - @property - def area(self): - """Gets or sets the area of the square.""" - return self._get_area() - - @area.setter - def area(self, area): - return self._set_area(area) - - def _get_area(self): - """Indirect accessor to calculate the 'area' property.""" - return self.side ** 2 - - def _set_area(self, area): - """Indirect setter to set the 'area' property.""" - self.side = math.sqrt(area) - - @property - def perimeter(self): - return self.side * 4 -``` - - - -### 2.14 True/False evaluations - -Use the "implicit" false if at all possible. - - -#### 2.14.1 Definition - -Python evaluates certain values as `False` when in a boolean context. A quick -"rule of thumb" is that all "empty" values are considered false, so -`0, None, [], {}, ''` all evaluate as false in a boolean context. - - -#### 2.14.2 Pros - -Conditions using Python booleans are easier to read and less error-prone. In -most cases, they're also faster. - - -#### 2.14.3 Cons - -May look strange to C/C++ developers. - - -#### 2.14.4 Decision - -Use the "implicit" false if at all possible, e.g., `if foo:` rather than -`if foo != []:`. There are a few caveats that you should keep in mind though: - -- Never use `==` or `!=` to compare singletons like `None`. Use `is` or - `is not`. - -- Beware of writing `if x:` when you really mean `if x is not None:`-e.g., - when testing whether a variable or argument that defaults to `None` was set - to some other value. The other value might be a value that's false in a - boolean context! - -- Never compare a boolean variable to `False` using `==`. Use `if not x:` - instead. If you need to distinguish `False` from `None` then chain the - expressions, such as `if not x and x is not None:`. - -- For sequences (strings, lists, tuples), use the fact that empty sequences - are false, so `if seq:` and `if not seq:` are preferable to `if len(seq):` - and `if not len(seq):` respectively. - -- When handling integers, implicit false may involve more risk than benefit - (i.e., accidentally handling `None` as 0). You may compare a value which is - known to be an integer (and is not the result of `len()`) against the - integer 0. - - ```python {.good} - Yes: if not users: - print('no users') - - if foo == 0: - self.handle_zero() - - if i % 10 == 0: - self.handle_multiple_of_ten() - - def f(x=None): - if x is None: - x = [] - ``` - - ```python {.bad} - No: if len(users) == 0: - print('no users') - - if foo is not None and not foo: - self.handle_zero() - - if not i % 10: - self.handle_multiple_of_ten() - - def f(x=None): - x = x or [] - ``` - -- Note that `'0'` (i.e., `0` as string) evaluates to true. - - - -### 2.15 Deprecated Language Features - -Use string methods instead of the `string` module where possible. Use function -call syntax instead of `apply`. Use list comprehensions and `for` loops instead -of `filter` and `map` when the function argument would have been an inlined -lambda anyway. Use `for` loops instead of `reduce`. - - -#### 2.15.1 Definition - -Current versions of Python provide alternative constructs that people find -generally preferable. - - -#### 2.15.2 Decision - -We do not use any Python version which does not support these features, so there -is no reason not to use the new styles. - -```python {.good} -Yes: words = foo.split(':') - - [x[1] for x in my_list if x[2] == 5] - - map(math.sqrt, data) # Ok. No inlined lambda expression. - - fn(*args, **kwargs) -``` - -```python {.bad} -No: words = string.split(foo, ':') - - map(lambda x: x[1], filter(lambda x: x[2] == 5, my_list)) - - apply(fn, args, kwargs) -``` - - - -### 2.16 Lexical Scoping - -Okay to use. - - -#### 2.16.1 Definition - -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. - -An example of the use of this feature is: - -```python {.good} -def get_adder(summand1): - """Returns a function that adds numbers to a given number.""" - def adder(summand2): - return summand1 + summand2 - - return adder -``` - - -#### 2.16.2 Pros - -Often results in clearer, more elegant code. Especially comforting to -experienced Lisp and Scheme (and Haskell and ML and ...) programmers. - - -#### 2.16.3 Cons - -Can lead to confusing bugs. Such as this example based on -[PEP-0227](http://www.google.com/url?sa=D&q=http://www.python.org/dev/peps/pep-0227/): - -```python {.bad} -i = 4 -def foo(x): - def bar(): - print(i, end='') - # ... - # A bunch of code here - # ... - for i in x: # Ah, i *is* local to foo, so this is what bar sees - print(i, end='') - bar() -``` - -So `foo([1, 2, 3])` will print `1 2 3 3`, not `1 2 3 -4`. - - -#### 2.16.4 Decision - -Okay to use. - - - -### 2.17 Function and Method Decorators - -Use decorators judiciously when there is a clear advantage. Avoid -`@staticmethod` and limit use of `@classmethod`. - - -#### 2.17.1 Definition - -[Decorators for Functions and -Methods](https://docs.python.org/2/whatsnew/2.4.html#pep-318-decorators-for-functions-and-methods) -(a.k.a "the `@` notation"). One common decorator is `@property`, used for -converting ordinary methods into dynamically computed attributes. However, the -decorator syntax allows for user-defined decorators as well. Specifically, for -some function `my_decorator`, this: - -```python {.good} -class C(object): - @my_decorator - def method(self): - # method body ... -``` - -is equivalent to: - -```python {.good} -class C(object): - def Methodmethod(self): - # method body ... - Methodmethod = MyDecoratormy_decorator(Methodmethod) -``` - - -#### 2.17.2 Pros - -Elegantly specifies some transformation on a method; the transformation might -eliminate some repetitive code, enforce invariants, etc. - - -#### 2.17.3 Cons - -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. - - -#### 2.17.4 Decision - -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. - -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 `pydoc` or other tools). A -decorator that is called with valid parameters should (as much as possible) be -guaranteed to succeed in all cases. - -Decorators are a special case of "top level code" - see [main](#s3.17-main) for -more discussion. - -Never use `@staticmethod` unless forced to in order to integrate with an API -defined in an existing library. Write a module level function instead. - -Use `@classmethod` only when writing a named constructor or a class-specific -routine that modifies necessary global state such as a process-wide cache. - - - -### 2.18 Threading - -Do not rely on the atomicity of built-in types. - -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 `__hash__` -or `__eq__` 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). - -Use the Queue module's `Queue` 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 -`threading.Condition` instead of using lower-level locks. - - - -### 2.19 Power Features - -Avoid these features. - - -#### 2.19.1 Definition - -Python is an extremely flexible language and gives you many fancy features such -as custom metaclasses, access to bytecode, on-the-fly compilation, dynamic -inheritance, object reparenting, import hacks, reflection, modification of -system internals, etc. - - -#### 2.19.2 Pros - -These are powerful language features. They can make your code more compact. - - -#### 2.19.3 Cons - -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. - - -#### 2.19.4 Decision - -Avoid these features in your code. - -Standard library modules and classes that internally use these features are okay -to use (for example, `abc.ABCMeta`, `collections.namedtuple`, and `enum`). - - - -### 2.20 Modern Python: Python 3 and from \_\_future\_\_ imports {#modern-python} - -Python 3 is here. While not every project is ready to use it yet, all code should be written with an eye towards the future. - - -#### 2.20.1 Definition - -Python 3 is a significant change in the Python language. While existing code is -often written with 2.7 in mind there are some simple things to do to make code -more explicit about its intentions and thus better prepared for use under Python -3 without modification. - - -#### 2.20.2 Pros - -Code written with Python 3 in mind is more explicit and easier to get running -under Python 3 once all of the dependencies of your project are ready. - - -#### 2.20.3 Cons - -Some people find the additional boilerplate to be ugly. Others say "but I don't -use that feature in this file" and want to clean-up. Please don't. It is better -to always have the future imports in all files so that they are not forgotten -during later edits when someone starts using such a feature. - - -#### 2.20.4 Decision - -##### from \_\_future\_\_ imports - -Use of `from __future__ import` statements is encouraged. All new code should -contain the following and existing code should be updated to be compatible when -possible: - -```python {.good} -from __future__ import absolute_import -from __future__ import division -from __future__ import print_function -``` - -If you are not already familiar with those, read up on each here: [absolute -imports](https://www.python.org/dev/peps/pep-0328/), [new `/` division -behavior](https://www.python.org/dev/peps/pep-0238/), and [the print -function](https://www.python.org/dev/peps/pep-3105/). - -There are other `from __future__` import statements. Use them as you see fit. We -do not include `unicode_literals` in our recommendations as it is not a clear -win due to implicit default codec conversion consequences it introduces in many -places within Python 2.7. Most code is better off with explicit use of `b''` and -`u''` bytes and unicode string literals as necessary. - -##### The six, future, or past libraries. - -When your project needs to actively support use under both Python 2 and 3, use -of these libraries is encouraged as you see fit. They exist to make your code -cleaner and life easier. - - - -### 2.21 Type Annotated Code - -You can annotate Python 3 code with type hints according to -[PEP-484](https://www.python.org/dev/peps/pep-0484/), and type-check the code at -build time with a type checking tool like -[pytype](https://github.com/google/pytype). - - -Type annotations can be in the source or in a [stub pyi -file](https://www.python.org/dev/peps/pep-0484/#stub-files). Whenever possible, -annotations should be in the source. Use pyi files for third-party or extension -modules. - - - -#### 2.21.1 Definition - -Type annotations (or "type hints") are for function or method arguments and -return values: - -```python {.good} -def func(a: int) -> List[int]: -``` - -You can also declare the type of a variable using a special comment: - -```python {.good} -a = SomeFunc() # type: SomeType -``` - - -#### 2.21.2 Pros - -Type annotations improve the readability and maintainability of your code. The -type checker will convert many runtime errors to build-time errors, and reduce -your ability to use [Power Features](#power-features). - - -#### 2.21.3 Cons - -You will have to keep the type declarations up to date. You might see type errors that you think are valid code. Use of a [type checker](https://github.com/google/pytype) -may reduce your ability to use [Power Features](#power-features). - - -#### 2.21.4 Decision - -This highly depends on the complexity of your project. Give it a try. - - - - -## 3 Python Style Rules - - - -### 3.1 Semicolons - -Do not terminate your lines with semi-colons and do not use semi-colons to put -two statements on the same line. - - - -### 3.2 Line length - -Maximum line length is *80 characters*. - -Exceptions: - -- Long import statements. -- URLs, pathnames, or long flags in comments. -- Long string module level constants not containing whitespace that would be - inconvenient to split across lines such as URLs or pathnames. -- Pylint disable comments. (e.g.: `# pylint: disable=invalid-name`) - -Do not use backslash line continuation except for `with` statements requiring -three or more context managers. - -Make use of Python's [implicit line joining inside parentheses, brackets and -braces](http://docs.python.org/reference/lexical_analysis.html#implicit-line-joining). -If necessary, you can add an extra pair of parentheses around an expression. - -```python {.good} -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'): -``` - -When a literal string won't fit on a single line, use parentheses for implicit -line joining. - -```python {.good} -x = ('This will build a very long long ' - 'long long long long long long string') -``` - -Within comments, put long URLs on their own line if necessary. - -```python {.good} -Yes: # See details at - # http://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html -``` - -```python {.bad} -No: # See details at - # http://www.example.com/us/developer/documentation/api/content/\ - # v2.0/csv_file_name_extension_full_specification.html -``` - -It is permissible to use backslash continuation when defining a `with` statement -whose expressions span three or more lines. For two lines of expressions, use a -nested `with` statement: - -```python {.good} -Yes: with very_long_first_expression_function() as spam, \ - very_long_second_expression_function() as beans, \ - third_thing() as eggs: - place_order(eggs, beans, spam, beans) -``` - -```python {.bad} -No: with VeryLongFirstExpressionFunction() as spam, \ - VeryLongSecondExpressionFunction() as beans: - PlaceOrder(eggs, beans, spam, beans) -``` - -```python {.good} -Yes: with very_long_first_expression_function() as spam: - with very_long_second_expression_function() as beans: - place_order(beans, spam) -``` - -Make note of the indentation of the elements in the line continuation examples -above; see the [indentation](#s3.4-indentation) section for explanation. - - - -### 3.3 Parentheses - -Use parentheses sparingly. - -It is fine, though not required, to use parentheses around tuples. Do not use -them in return statements or conditional statements unless using parentheses for -implied line continuation or to indicate a tuple. - -```python {.good} -Yes: if foo: - bar() - while x: - x = bar() - if x and y: - bar() - if not x: - bar() - # For a 1 item tuple the ()s are more visually obvious than the comma. - onesie = (foo,) - return foo - return spam, beans - return (spam, beans) - for (x, y) in dict.items(): ... -``` - -```python {.bad} -No: if (x): - bar() - if not(x): - bar() - return (foo) -``` - - - - -### 3.4 Indentation - -Indent your code blocks with *4 spaces*. - -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 -[line length](#s3.2-line-length) section; or using a hanging indent of 4 spaces, -in which case there should be nothing after the open parenthesis or bracket on -the first line. - -```python {.good} -Yes: # Aligned with opening delimiter - foo = long_function_name(var_one, var_two, - var_three, var_four) - meal = (spam, - beans) - - # 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) - meal = ( - spam, - beans) - - # 4-space hanging indent in a dictionary - foo = { - long_dictionary_key: - long_dictionary_value, - ... - } -``` - -```python {.bad} -No: # Stuff on first line forbidden - foo = long_function_name(var_one, var_two, - var_three, var_four) - meal = (spam, - beans) - - # 2-space hanging indent forbidden - foo = long_function_name( - var_one, var_two, var_three, - var_four) - - # No hanging indent in a dictionary - foo = { - long_dictionary_key: - long_dictionary_value, - ... - } -``` - - - -### 3.5 Blank Lines - -Two blank lines between top-level definitions, one blank line between method -definitions. - -Two blank lines between top-level definitions, be they function or class -definitions. One blank line between method definitions and between the `class` -line and the first method. Use single blank lines as you judge appropriate -within functions or methods. - - - -### 3.6 Whitespace - -Follow standard typographic rules for the use of spaces around punctuation. - -No whitespace inside parentheses, brackets or braces. - -```python {.good} -Yes: spam(ham[1], {eggs: 2}, []) -``` - -```python {.bad} -No: spam( ham[ 1 ], { eggs: 2 }, [ ] ) -``` - -No whitespace before a comma, semicolon, or colon. Do use whitespace after a -comma, semicolon, or colon except at the end of the line. - -```python {.good} -Yes: if x == 4: - print(x, y) - x, y = y, x -``` - -```python {.bad} -No: if x == 4 : - print(x , y) - x , y = y , x -``` - -No whitespace before the open paren/bracket that starts an argument list, -indexing or slicing. - -```python {.good} -Yes: spam(1) -``` - -```python {.bad} -No: spam (1) -``` - - -```python {.good} -Yes: dict['key'] = list[index] -``` - -```python {.bad} -No: dict ['key'] = list [index] -``` - -Surround binary operators with a single space on either side for assignment -(`=`), comparisons (`==, <, >, !=, <>, <=, >=, in, not in, is, is not`), and -Booleans (`and, or, not`). 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. - -```python {.good} -Yes: x == 1 -``` - -```python {.bad} -No: x<1 -``` - -Never use spaces around the '=' sign when passing keyword arguments. -Only use spaces around the '=' sign defining a default parameter value -[when a type annotation is present](#typing-default-values), -do not use spaces around '=' for default parameter values otherwise. - -```python {.good} -Yes: def complex(real, imag=0.0): return Magic(r=real, i=imag) -Yes: def complex(real, imag: float = 0.0): return Magic(r=real, i=imag) -``` - -```python {.bad} -No: def complex(real, imag = 0.0): return Magic(r = real, i = imag) -No: def complex(real, imag: float=0.0): return Magic(r = real, i = imag) -``` - -Don't use spaces to vertically align tokens on consecutive lines, since it -becomes a maintenance burden (applies to `:`, `#`, `=`, etc.): - -```python {.good} -Yes: - foo = 1000 # comment - long_name = 2 # comment that should not be aligned - - dictionary = { - 'foo': 1, - 'long_name': 2, - } -``` - -```python {.bad} -No: - foo = 1000 # comment - long_name = 2 # comment that should not be aligned - - dictionary = { - 'foo' : 1, - 'long_name': 2, - } -``` - - - - - -### 3.7 Shebang Line - -Most `.py` files do not need to start with a `#!` line. Start the main file of a -program with -`#!/usr/bin/python` with an optional single digit `2` or `3` suffix per -[PEP-394](https://www.google.com/url?sa=D&q=http://www.python.org/dev/peps/pep-0394/). - -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. - - - -### 3.8 Comments and Docstrings - -Be sure to use the right style for module, function, method docstrings and -in-line comments. - - - -#### 3.8.1 Docstrings - -Python uses docstrings for commenting code. 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 `__doc__` member of the object and are used -by `pydoc`. -(Try running `pydoc` on your module to see how it looks.) Always use the three -double-quote `"""` format for docstrings (per [PEP -257](https://www.google.com/url?sa=D&q=http://www.python.org/dev/peps/pep-0257/)). -A docstring 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 docstring starting at the same cursor position as -the first quote of the first line. There are more formatting guidelines for -docstrings below. - - - -#### 3.8.2 Modules - -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) - - - -#### 3.8.3 Functions and Methods - -As used in this section "function" applies to methods, functions, and -generators. - -A function must have a docstring, unless it meets all of the following criteria: - -- not externally visible -- very short -- obvious - -A docstring should give enough information to write a call to the function -without reading the function's code. The docstring should be descriptive -(`"""Fetches rows from a Bigtable."""`) rather than imperative -(`"""Fetch rows from a Bigtable."""`). 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. - -A method that overrides a method from a base class may have a simple docstring -sending the reader to its overridden method's docstring, such as -`"""See base class."""`. The rationale is that there is no need to repeat in -many places documentation that is already present in the base method's -docstring. However, if the overriding method's behavior is substantially -different than that of the overridden method or details need to be provided -about it (e.g., documenting additional side-effects), a docstring is required on -the overriding method, with at least those differences. - -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. - -*Args:* -: 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).
-: The description should include required type(s) if the code does not contain -: a corresponding type annotation.
-: If a function accepts `*foo` (variable length argument lists) and/or `**bar` -: (arbitrary keyword arguments), they should be listed as `*foo` and `**bar`. - -*Returns:* (or *Yields:* for generators) -: Describe the type and semantics of the return value. If the function only -: returns None, this section is not required. It may also be omitted if the -: docstring starts with Returns (or Yields) (e.g. -: `"""Returns row from Bigtable as a tuple of strings."""`) and the opening -: sentence is sufficient to describe return value. - -*Raises:* -: List all exceptions that are relevant to the interface. - -```python {.good} -def fetch_bigtable_rows(big_table, keys, other_silly_variable=None): - """Fetches rows from a Bigtable. - - Retrieves rows pertaining to the given keys from the Table instance - represented by big_table. Silly things may happen if - other_silly_variable is not None. - - Args: - big_table: An open Bigtable Table instance. - keys: A sequence of strings representing the key of each table row - to fetch. - other_silly_variable: Another optional variable, that has a much - longer name than the other args, and which does nothing. - - Returns: - A dict mapping keys to the corresponding table row data - fetched. Each row is represented as a tuple of strings. For - example: - - {'Serak': ('Rigel VII', 'Preparer'), - 'Zim': ('Irk', 'Invader'), - 'Lrrr': ('Omicron Persei 8', 'Emperor')} - - If a key from the keys argument is missing from the dictionary, - then that row was not found in the table. - - Raises: - IOError: An error occurred accessing the bigtable.Table object. - """ -``` - - - -#### 3.8.4 Classes - -Classes should have a docstring 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. - -```python {.good} -class SampleClass(object): - """Summary of class here. - - Longer class information.... - Longer class information.... - - Attributes: - likes_spam: A boolean indicating if we like SPAM or not. - eggs: An integer count of the eggs we have laid. - """ - - def __init__(self, likes_spam=False): - """Inits SampleClass with blah.""" - self.likes_spam = likes_spam - self.eggs = 0 - - def public_method(self): - """Performs operation blah.""" -``` - - - -#### 3.8.5 Block and Inline Comments - -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 [code -review](http://en.wikipedia.org/wiki/Code_review), 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. - -```python {.good} -# We use a weighted dictionary search to find out where i is in -# the array. We extrapolate position based on the largest num -# in the array and the array size and then do binary search to -# get the exact number. - -if i & (i-1) == 0: # True if i is 0 or a power of 2. -``` - -To improve legibility, these comments should be at least 2 spaces away from the -code. - -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. - -```python {.bad} -# BAD COMMENT: Now go through the b array and make sure whenever i occurs -# the next element is i+1 -``` - - - - -#### 3.8.6 Punctuation, Spelling and Grammar - -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 you should be consistent with your style. - -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. - - - -### 3.9 Classes - -If a class inherits from no other base classes, explicitly inherit from -`object`. This also applies to nested classes. - -```python {.good} -Yes: class SampleClass(object): - pass - - - class OuterClass(object): - - class InnerClass(object): - pass - - - class ChildClass(ParentClass): - """Explicitly inherits from another class already.""" - -``` - -```python {.bad} -No: class SampleClass: - pass - - - class OuterClass: - - class InnerClass: - pass -``` - -Inheriting from `object` is needed to make properties work properly in Python 2, -and can protect your code from some potential incompatibility with Python 3. It -also defines special methods that implement the default semantics of objects -including `__new__`, `__init__`, `__delattr__`, `__getattribute__`, -`__setattr__`, `__hash__`, `__repr__`, and `__str__`. - - - -### 3.10 Strings - -Use the `format` method or the `%` operator for formatting strings, even when -the parameters are all strings. Use your best judgement to decide between `+` -and `%` (or `format`) though. - -```python {.good} -Yes: x = a + b - x = '%s, %s!' % (imperative, expletive) - x = '{}, {}'.format(first, second) - x = 'name: %s; score: %d' % (name, n) - x = 'name: {}; score: {}'.format(name, n) - x = f'name: {name}; score: {n}' # Python 3.6+ -``` - -```python {.bad} -No: x = '%s%s' % (a, b) # use + in this case - x = '{}{}'.format(a, b) # use + in this case - x = first + ', ' + second - x = 'name: ' + name + '; score: ' + str(n) -``` - -Avoid using the `+` and `+=` 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 `''.join` the list after the loop terminates (or, write -each substring to a `io.BytesIO` buffer). - -```python {.good} -Yes: items = [''] - for last_name, first_name in employee_list: - items.append('' % (last_name, first_name)) - items.append('
%s, %s
') - employee_table = ''.join(items) -``` - -```python {.bad} -No: employee_table = '' - for last_name, first_name in employee_list: - employee_table += '' % (last_name, first_name) - employee_table += '
%s, %s
' -``` - -Be consistent with your choice of string quote character within a file. Pick `'` -or `"` and stick with it. It is okay to use the other quote character on a -string to avoid the need to `\\` escape within the string. `gpylint` enforces -this. - -```python {.good} -Yes: - Python('Why are you hiding your eyes?') - Gollum("I'm scared of lint errors.") - Narrator('"Good!" thought a happy Python reviewer.') -``` - -```python {.bad} -No: - Python("Why are you hiding your eyes?") - Gollum('The lint. It burns. It burns us.') - Gollum("Always the great lint. Watching. Watching.") -``` - -Prefer `"""` for multi-line strings rather than `'''`. Projects may choose to -use `'''` for all non-docstring multi-line strings if and only if they also use -`'` for regular strings. Docstrings must use `"""` 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: - -```python {.good} - Yes: - print("This is much nicer.\n" - "Do it this way.\n") -``` - -```python {.bad} - No: - print("""This is pretty ugly. -Don't do this. -""") -``` - - - -### 3.11 Files and Sockets - -Explicitly close files and sockets when done with them. - -Leaving files, sockets or other file-like objects open unnecessarily has many -downsides, including: - -- 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. -- Holding files open may prevent other actions being performed on them, such - as moves or deletion. -- Files and sockets that are shared throughout a program may inadvertently 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. - -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: - -- 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. -- Unexpected references to the file may keep it around longer than intended - (e.g. in tracebacks of exceptions, inside globals, etc). - -The preferred way to manage files is using the ["with" -statement](http://docs.python.org/reference/compound_stmts.html#the-with-statement): - -```python {.good} -with open("hello.txt") as hello_file: - for line in hello_file: - print(line) -``` - -For file-like objects that do not support the "with" statement, use -`contextlib.closing()`: - -```python {.good} -import contextlib - -with contextlib.closing(urllib.urlopen("http://www.python.org/")) as front_page: - for line in front_page: - print(line) -``` - - - -### 3.12 TODO Comments - -Use `TODO` comments for code that is temporary, a short-term solution, or -good-enough but not perfect. - -`TODO`s should include the string `TODO` in all caps, followed by the -name, e-mail address, or other identifier -of the person or issue with the best context about the problem referenced by the -`TODO`, in parentheses. A comment explaining what there is to do is required. -The main purpose is to have a consistent `TODO` format that can be searched to -find out how to get more details upon request. A `TODO` is not a commitment that -the person referenced will fix the problem. Thus when you create a `TODO`, it is almost always your name that is given. - -```python {.good} -# TODO(kl@gmail.com): Use a "*" here for string repetition. -# TODO(Zeke) Change this to use relations. -``` - -If your `TODO` 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."). - - - -### 3.13 Imports formatting - -Imports should be on separate lines. - -E.g.: - -```python {.good} -Yes: import os - import sys -``` - -```python {.bad} -No: import os, sys -``` - -Imports are always put at the top of the file, just after any module comments -and docstrings and before module globals and constants. Imports should be -grouped with the order being most generic to least generic: - -1. Python standard library imports. For example: - - ```python {.good} - import sys - ``` - -2. [third-party](https://pypi.python.org/pypi) - module or package imports. For example: - - - ```python {.good} - import tensorflow as tf - ``` - -3. Code repository - sub-package imports. For example: - - - ```python {.good} - from otherproject.ai import mind - ``` - -4. application-specific imports that are part of the same - top level - sub-package as this file. For example: - - - ```python {.good} - from myproject.backend.hgwells import time_machine - ``` - -Within each grouping, imports should be sorted lexicographically, ignoring case, -according to each module's full package path. Code may optionally place a blank -line between import sections. - -```python {.good} -import collections -import Queue -import sys - -import argcomplete -import BeautifulSoup -import cryptography -import tensorflow as tf - -from otherproject.ai import body -from otherproject.ai import mind -from otherproject.ai import soul - -from myproject.backend.hgwells import time_machine -from myproject.backend.state_machine import main_loop -``` - - - - -### 3.14 Statements - -Generally only one statement per line. - -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 -`try`/`except` since the `try` and `except` can't both fit on the same line, and -you can only do so with an `if` if there is no `else`. - -```python {.good} -Yes: - - if foo: bar(foo) -``` - -```python {.bad} -No: - - if foo: bar(foo) - else: baz(foo) - - try: bar(foo) - except ValueError: baz(foo) - - try: - bar(foo) - except ValueError: baz(foo) -``` - - - -### 3.15 Access Control - -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 `property` to keep the syntax -consistent. - -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 -[Naming](#s3.16-naming) guidelines) such as `get_foo()` and -`set_foo()`. 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. - - - -### 3.16 Naming - -`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`. - -Function names, variable names, and filenames should be descriptive; eschew -abbreviation. In particular, do not use abbreviations that are ambiguous or -unfamiliar to readers outside your project, and do not abbreviate by deleting -letters within a word. - -Always use a `.py` filename extension. Never use dashes. - - - -#### 3.16.1 Names to Avoid - -- single character names except for counters or iterators. You may use "e" as - an exception identifier in try/except statements. -- dashes (`-`) in any package/module name -- `__double_leading_and_trailing_underscore__` names (reserved by Python) - - - -#### 3.16.2 Naming Convention - -- "Internal" means internal to a module or protected or private within a - class. - -- Prepending a single underscore (`_`) has some support for protecting module - variables and functions (not included with `from module import *`). While - prepending a double underscore (`__` aka "dunder") to an instance variable - or method effectively makes the variable or method private to its class - (using name mangling) we discourage its use as it impacts readability and - testability and isn't *really* private. - -- 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. - -- Use CapWords for class names, but lower\_with\_under.py for module names. - Although there are some old 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 `import StringIO` or - `from StringIO import StringIO`?") - -- Underscores may appear in *unittest* method names starting with `test` to - separate logical components of the name, even if those components use - CapWords. One possible pattern is `test_`; for - example `testPop_EmptyStack` is okay. There is no One Correct Way to name - test methods. - - - -#### 3.16.3 File Naming {#s3.16.3-file-naming} - -Python filenames must have a `.py` extension and must not contain dashes (`-`). -This allows them to be imported and unittested. If you want an executable to be -accessible without the extension, use a symbolic link or a simple bash wrapper -containing `exec "$0.py" "$@"`. - - - -#### 3.16.4 Guidelines derived from Guido's Recommendations - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypePublicInternal
Packageslower_with_under
Moduleslower_with_under_lower_with_under
ClassesCapWords_CapWords
ExceptionsCapWords
Functionslower_with_under()_lower_with_under()
Global/Class ConstantsCAPS_WITH_UNDER_CAPS_WITH_UNDER
Global/Class Variableslower_with_under_lower_with_under
Instance Variableslower_with_under_lower_with_under (protected)
Method Nameslower_with_under()_lower_with_under() (protected)
Function/Method Parameterslower_with_under
Local Variableslower_with_under
- -While Python supports making things private by using a leading double underscore -`__` (aka. "dunder") prefix on a name their use is discouraged. Prefer the use -of a single underscore. They are much easier to type, read, and to access from -small unittests. Lint warnings take care of invalid access to protected members. - - - - -### 3.17 Main - -Even a file meant to be used as an executable should be importable and a mere -import should not have the side effect of executing the program's main -functionality. The main functionality should be in a `main()` function. - -In Python, `pydoc` as well as unit tests require modules to be importable. Your -code should always check `if __name__ == '__main__'` before executing your main -program so that the main program is not executed when the module is imported. - -```python {.good} -def main(): - ... - -if __name__ == '__main__': - main() -``` - -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 `pydoc`ed. - - - -### 3.18 Function length - -Prefer small and focused functions. - -We recognize that long functions are sometimes 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. - -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. - - - -### 3.19 Type Annotations - - - -#### 3.19.1 General Rules - -* Familiarize yourself with [PEP-484](https://www.python.org/dev/peps/pep-0484/). -* In methods, never annotate `self`, or `cls`. -* If any other variable or a returned type should not be expressed, use `Any`. -* You are not required to annotate all the functions in a module. - - At least annotate your public APIs. - - Use judgment to get to a good balance between safety and clarity on the - one hand, and flexibility on the other. - - Annotate code that is prone to type-related errors (previous bugs or - complexity). - - Annotate code that is hard to understand. - - Annotate code as it becomes stable from a types perspective. In many - cases, you can annotate all the functions in mature code without losing - too much flexibility. - - - - -#### 3.19.2 Line Breaking - -Try to follow the existing [indentation](#indentation) rules. Always prefer -breaking between variables. - -After annotating, many of the functions will become "one parameter per line". - -```python {.good} -def my_method(self, - first_var: int, - second_var: Foo, - third_var: Optional[Bar]) -> int: - ... -``` - -However, if everything fits on the same line, go for it. - -```python {.good} -def my_method(self, first_var: int) -> int: - ... -``` - -If the combination of the function name, the last parameter, and the return type -is too long, indent by 4 in a new line. - -```python {.good} -def my_method( - self, first_var: int) -> Tuple[MyLongType1, MyLongType1]: - ... -``` - -When the return type does not fit on the same line as the last parameter, the -preferred way is to indent the parameters by 4 on a new line and align the -closing parenthesis with the def. - -```python {.good} -Yes: -def my_method( - self, **kw_args: Optional[MyLongType] -) -> Dict[OtherLongType, MyLongType]: - ... -``` - -`pylint` allows you to move the closing parenthesis to a new line and align -with the opening one, but this is less readable. - -```python {.bad} -No: -def my_method(self, - **kw_args: Optional[MyLongType] - ) -> Dict[OtherLongType, MyLongType]: - ... -``` - -As in the examples above, prefer not to break types. However, sometimes they are -too long to be on a single line (try to keep sub-types unbroken). - -```python {.good} -def my_method( - self, - first_var: Tuple[List[MyLongType1], - List[MyLongType2]], - second_var: List[Dict[ - MyLongType3, MyLongType4]]) -> None: - ... -``` - -If a single name and type is too long, consider using an -[alias](#typing-aliases) for the type. The last resort is to break after the -colon and indent by 4. - -```python {.good} -Yes: -def my_function( - long_variable_name: - long_module_name.LongTypeName, -) -> None: - ... -``` - -```python {.bad} -No: -def my_function( - long_variable_name: long_module_name. - LongTypeName, -) -> None: - ... -``` - - - -#### 3.19.3 Forward Declarations - -If you need to use a class name from the same module that is not yet defined -- -for example, if you need the class inside the class declaration, or if you use a -class that is defined below -- use a string for the class name. - -```python {.good} -class MyClass(object): - - def __init__(self, - stack: List["MyClass"]) -> None: -``` - - - -#### 3.19.4 Default Values - -As per [PEP-008](https://www.python.org/dev/peps/pep-0008/#other-recommendations) -when combining an argument annotation with a default value, use spaces around -the = sign (but only for those arguments that have both an annotation and a -default). - -```python {.good} -Yes: -def func(a: int = 0) -> int: - ... -``` -```python {.bad} -No: -def func(a:int=0) -> int: - ... -``` - - - -#### 3.19.5 NoneType - -In the Python type system, `NoneType` is a "first class" type, and for typing -purposes, `None` is an alias for `NoneType`. If an argument can be `None`, it -has to be declared! You can use `Union`, but if there is only one other type, -`Optional` is a shortcut. - -```python {.good} -Yes: -def func(a: Optional[str]) -> str: - ... -``` - -```python {.bad} -No: -def func(a: Union[None, str]) -> str: - ... -``` - -If the default value of an argument is `None`, marking the variable `Optional` -is optional. - -```python {.good} -Yes: -def func(a: Optional[str] = None) -> str: - ... -def func(a: str = None) -> str: - ... -``` - - - -#### 3.19.6 Type Aliases - -You can declare aliases of complex types. The name of an alias should be -CapWorded; try to describe the composed type and end with "Type" (or "Types" for -returned tuples). If the alias is used only in this module, it should be -\_Private. - -For example, if the name of module together with the type is too long: - -```python {.good} -SomeType = module_with_long_name.TypeWithLongName -``` - -Other examples are complex nested types and multiple return variables from a -function (as a tuple). - - - -#### 3.19.7 Ignoring Types - -You can disable type checking on a line with the special comment -`# type: ignore`. - -`pytype` has a disable option for specific errors (similar to lint): - -```python {.good} -# pytype: disable=attribute-error -``` - - - -#### 3.19.8 Typing internal variables - -If an internal variable has a type that is hard or impossible to infer, you can -supply it as a special comment: - -```python {.good} -a = SomeUndecoratedFunction() # type: Foo -``` - - -#### 3.19.9 Tuples vs Lists - -Unlike Lists, which can only have a single type, Tuples can have either a single -repeated type or a set number of elements with different types. The latter is -commonly used as return type from a function. - -```python {.good} -a = [1, 2, 3] # type: List[int] -b = (1, 2, 3) # type: Tuple[int, ...] -c = (1, "2", 3.5) # type Tuple[int, str, float] -``` - - - -#### 3.19.10 TypeVar - -The Python type system has -[generics](https://www.python.org/dev/peps/pep-0484/#generics). The factory -function `TypeVar` is a common way to use them. - -Example: - -```python {.good} -from typing import List, TypeVar -T = TypeVar("T") -... -def next(l: List[T]) -> T: - return l.pop() -``` - -A TypeVar can be constrained: - -```python {.good} -AddableType = TypeVar("AddableType", int, float, str) -def add(a: AddableType, b: AddableType) -> AddableType: - return a + b -``` - -A common predefined type variable in the `typing` module is `AnyStr`. Use it for -arguments that can be `bytes` or `unicode`. - -```python {.good} -AnyStr = TypeVar("AnyStr", bytes, unicode) -``` - - -#### 3.19.11 Strings types - -When annotating functions that take or return strings, avoid using `str`, -because it means different things in Python 2 and Python 3. In Python 2, `str` -is `bytes`; in Python 3, it is `unicode`. Whenever possible, it is best to be -explicit: - -```python {.bad} -No: -def f(x: str) -> str: - ... -``` - -For code that deals with byte arrays, use `bytes`. - -```python {.good} -def f(x: bytes) -> bytes: - ... -``` - -For code that processes Unicode data, use `Text`. - -```python {.good} -from typing import Text -... -def f(x: Text) -> Text: - ... -``` - -If the type can be either bytes or unicode, use `Union`. - -```python {.good} -from typing import Text, Union -... -def f(x: Union[bytes, Text]) -> Union[bytes, Text]: - ... -``` - -If all the string types of a function are always the same, for example if the -return type is the same as the argument type in the code above, use -[AnyStr](#typing-type-var). - -Writing it like this will simplify the process of porting the code to Python 3. - - - -#### 3.19.12 Imports For Typing - -For classes from the `typing` module, always import the class itself. You are -explicitly allowed to import multiple specific classes on one line from the -`typing` module. Ex: - -```python {.good} -from typing import Any, Dict, Optional -``` - -Given that this way of importing from `typing` adds items to the local -namespace, any names in `typing` should be treated similarly to keywords, and -not be defined in your Python code, typed or not. If there is a collision -between a type and an existing name in a module, import it using -`import x as y`. - -```python {.good} -from typing import Any as AnyType -``` - -If the additional imports needed for type checking need to be avoided at -runtime, conditional imports may be used. This pattern is discouraged and -alternatives such as refactoring the code to allow top level imports should be -preferred. If this pattern is used at all, conditionally imported types need to -be referenced as strings `'sketch.Sketch'` rather than `sketch.Sketch`, to be -forward compatible with Python 3 where the annotation expressions are actually -evaluated. Imports that are needed only for type annotations can be placed -within an `if typing.TYPE_CHECKING:` block. - -- Only entities that are used solely for typing should be defined here; this - includes aliases. Otherwise it will be a runtime error, as the module will - not be imported at runtime. -- The block should be right after all the normal imports. -- There should be no empty lines in the typing imports list. -- Sort this list as if it were a regular imports list, but put the import from - the typing module at the end. -- The `google3` module also has a `TYPE_CHECKING` constant. You can use that - instead if you do you not want to import `typing` at runtime. - - -```python {.good} -import typing -... -if typing.TYPE_CHECKING: - import types - from MySQLdb import connections - from google3.path.to.my.project import my_proto_pb2 - from typing import Any, Dict, Optional -``` - - - -#### 3.19.13 Circular Dependencies - -Circular dependencies that are caused by typing are code smells. Such code is a -good candidate for refactoring. Although technically it is possible to keep -circular dependencies, the [build system](#typing-build-deps) will not let you -do so because each module has to depend on the other. - -Replace modules that create circular dependency imports with `Any`. Set an -[alias](#typing-aliases) with a meaningful name, and use the real type name from -this module (any attribute of Any is Any). Alias definitions should be separated -from the last import by one line. - -```python {.good} -from typing import Any - -some_mod = Any # some_mod.py imports this module. -... - -def my_method(self, var: some_mod.SomeType) -> None: - ... -``` - - -## 4 Parting Words - -*BE CONSISTENT*. - -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. - -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. - diff --git a/shell.xml b/shell.xml new file mode 100644 index 0000000..79f39f9 --- /dev/null +++ b/shell.xml @@ -0,0 +1,1152 @@ + + + + +

+ +Revision 1.26 +

+ + +
+ Paul Armstrong
+ Too many more to mention
+
+ + + + + + + + + + Bash is the only shell scripting language permitted for + executables. + + +

+ Executables must start with #!/bin/bash and a minimum + number of flags. Use set to set shell options so that + calling your script as bash <script_name> + does not break its functionality. +

+

+ Restricting all executable shell scripts to bash + gives us a consistent shell language that's installed on all our + machines. +

+

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

+ + + + + + Shell should only be used for small utilities or simple wrapper + scripts. + + +

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

+

+ Some guidelines: +

    +
  • + If you're mostly calling other utilities and are doing relatively + little data manipulation, shell is an acceptable choice for the + task. +
    • +
  • + If performance matters, use something other than shell. +
    • +
  • + If you find you need to use arrays for anything more than + assignment of ${PIPESTATUS}, you should use Python. +
    • +
  • + 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. +
    • +
+

+ + + + + + + + + + + Executables should have no extension (strongly preferred) or a + .sh extension. + Libraries must have a .sh extension and should not be + executable. + + +

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

+

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

+ + + + + + SUID and SGID are forbidden on shell scripts. + + +

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

+

+ Use sudo to provide elevated access if you need it. +

+ + + + + + + + + + All error messages should go to STDERR. + + +

+ This makes it easier + to separate normal status from actual issues. +

+

+ A function to print out error messages along with other status + information is recommended. + + 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 + +

+ + + + + + + + + + Start each file with a description of its contents. + + +

+ Every file must have a top-level comment including a brief overview of + its contents. + A + copyright notice + and author information are optional. +

+

+ Example: + + #!/bin/bash + # + # Perform hot backups of Oracle databases. + +

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

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

+

+ All function comments should contain: +

    +
  • + Description of the function +
    • +
  • + Global variables used and modified +
    • +
  • + Arguments taken +
    • +
  • + Returned values other than the default exit status of the last + command run +
    • +
+

+

+ Example: + + #!/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() { + ... + } + +

+ + + + + + Comment tricky, non-obvious, interesting or important parts of your code. + + +

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

+ + + + + + Use TODO comments for code that is temporary, a short-term solution, or + good-enough but not perfect. + + +

+ This matches the convention in the C++ + Guide. +

+

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

+

+ Examples: + + + # TODO(mrmonkey): Handle the unlikely edge cases (bug ####) + +

+ + + + + + +

+ While you should follow the style that's already there for files that + you're modifying, the following are required for any new code. +

+ + + + Indent 2 spaces. No tabs. + + +

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

+ + + + + + Maximum line length is 80 characters. + + +

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

+

+ + # 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." + +

+ + + + + + Pipelines should be split one per line if they don't all fit on one line. + + +

+ If a pipeline all fits on one line, it should be on one line. +

+

+ 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 '&&'. + + # All fits on one line + command1 | command2 + + # Long commands + command1 \ + | command2 \ + | command3 \ + | command4 + +

+ + + + + + Put ; do and ; then on the same line as the + while, for or if. + + +

+ Loops in shell are a bit different, but we follow the same principles + as with braces when declaring functions. That is: ; then + and ; do should be on the same line as the if/for/while. + else should be on its own line and closing statements + should be on their own line vertically aligned with the opening + statement. +

+

+ Example: + + 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 + +

+ + + + + +
    +
  • + Indent alternatives by 2 spaces. +
    • +
  • + A one-line alternative needs a space after the close parenthesis of + the pattern and before the ;;. +
    • +
  • + Long or multi-command alternatives should be split over multiple + lines with the pattern, actions, and ;; on separate + lines. +
    • +
+ + +

+ 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 + ;& and ;;& notations. +

+ + case "${expression}" in + a) + variable="..." + some_command "${variable}" "${other_expr}" ... + ;; + absolute) + actions="relative" + another_command "${actions}" "${other_expr}" ... + ;; + *) + error "Unexpected expression '${expression}'" + ;; + esac + +

+ Simple commands may be put on the same line as the pattern and + ;; 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 ;; 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 ;;. +

+ + 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 + + + + + + + In order of precedence: Stay consistent with what you find; + quote your variables; + prefer "${var}" over "$var", but see details. + + +

+ These are meant to be guidelines, as the topic seems too controversial for + a mandatory regulation. +
+ They are listed in order of precedence. +

+
    +
  1. + Stay consistent with what you find for existing code. +
    2. +
  2. + Quote variables, see Quoting section below. +
    3. +
  3. +

    + Don't brace-quote single character shell + specials / positional parameters, unless strictly necessary + or avoiding deep confusion. +
    + Prefer brace-quoting all other variables. + + # Section of recommended 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 discouraged 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" + +

    +
    4. +
+ + + + + +
    +
  • + Always quote strings containing variables, command substitutions, + spaces or shell meta characters, unless careful unquoted expansion + is required. +
    • +
  • + Prefer quoting strings that are "words" + (as opposed to command options or path names). +
    • +
  • + Never quote literal integers. +
    • +
  • + Be aware of the quoting rules for + pattern matches in [[. +
    • +
  • + Use "$@" unless you have a specific reason to use $*. +
    • +
+ + +

+ + # '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 "$#, $@") + +

+ + + + + + + + + + Use $(command) instead of backticks. + + +

+ Nested backticks require escaping the inner ones with \. + The $(command) format doesn't change when nested and is + easier to read. +

+

+ Example: + + # This is preferred: + var="$(command "$(command1)")" + + # This is not: + var="`command \`command1\``" + +

+ + + + + + [[ ... ]] is preferred over [, + test and /usr/bin/[. + + +

+ [[ ... ]] reduces errors as no pathname expansion or word + splitting takes place between [[ and ]] and + [[ ... ]] allows for regular expression matching where + [ ... ] does not. + + # 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 + +

+ + + + + + Use quotes rather than filler characters where possible. + + +

+ 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. + + # 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 + +

+

+ To avoid confusion about what you're testing for, explicitly use + -z or -n. + + # 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 + +

+ + + + + + Use an explicit path when doing wildcard expansion of filenames. + + +

+ As filenames can begin with a -, it's a lot safer to + expand wildcards with ./* instead of *. + + # 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' + +

+ + + + + + eval should be avoided. + + +

+ Eval munges the input when used for assignment to variables and can set + variables without making it possible to check what those variables + were. + + # 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)" + +

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

+ The implicit subshell in a pipe to while can make it difficult to track + down bugs. + + last_line='NULL' + your_command | while read line; do + last_line="${line}" + done + + # This will output 'NULL' + echo "${last_line}" + +

+

+ Use a for loop if you are confident that the input will not contain + spaces or special characters (usually, this means not user input). + + total=0 + # Only do this if there are no spaces in return values. + for value in $(command); do + total+="${value}" + done + +

+

+ 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. + + 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}" + +

+

+ 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. + + # 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 + +

+ + + + + + + + + + Lower-case, with underscores to separate words. Separate libraries + with ::. Parentheses are required after the function name. + The keyword function is optional, but must be used + consistently throughout a project. + + +

+ If you're writing single functions, use lowercase and separate words + with underscore. If you're writing a package, separate package names + with ::. 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. + + # Single function + my_func() { + ... + } + + # Part of a package + mypackage::my_func() { + ... + } + +

+

+ The function keyword is extraneous when "()" is present + after the function name, but enhances quick identification of + functions. +

+ + + + + + As for function names. + + +

+ Variables names for loops should be similarly named for any variable + you're looping through. + + for zone in ${zones}; do + something_with "${zone}" + done + +

+ + + + + + All caps, separated with underscores, declared at the top of the file. + + +

+ Constants and anything exported to the environment should be + capitalized. + + # Constant + readonly PATH_TO_FILES='/some/path' + + # Both constant and environment + declare -xr ORACLE_SID='PROD' + +

+

+ 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 declare doesn't operate on global variables + within functions, so readonly or export is + recommended instead. +

+ + VERBOSE='false' + while getopts 'v' flag; do + case "${flag}" in + v) VERBOSE='true' ;; + esac + done + readonly VERBOSE + + + + + + + Lowercase, with underscores to separate words if desired. + + +

+ This is for consistency with other code styles in Google: + maketemplate or make_template but not + make-template. +

+ + + + + + Use readonly or declare -r to ensure they're + read only. + + +

+ 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. + + zip_version="$(dpkg --status zip | grep Version: | cut -d ' ' -f 2)" + if [[ -z "${zip_version}" ]]; then + error_message + else + readonly zip_version + fi + +

+ + + + + + Declare function-specific variables with local. Declaration + and assignment should be on different lines. + + +

+ Ensure that local variables are only seen inside a function and its + children by using local when declaring them. This avoids + polluting the global name space and inadvertently setting variables + that may have significance outside the function. +

+

+ 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. + + 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 + + ... + } + +

+ + + + + + Put all functions together in the file just below constants. Don't hide + executable code between functions. + + +

+ If you've got functions, put them all together near the top of the + file. Only includes, set statements and setting constants + may be done before declaring functions. +

+

+ Don't hide executable code between functions. Doing so makes the code + difficult to follow and results in nasty surprises when debugging. +

+ + + + + + A function called main is required for scripts long enough + to contain at least one other function. + + +

+ In order to easily find the start of the program, put the main + program in a function called main 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 local + (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 main: + + main "$@" + +

+

+ Obviously, for short scripts where it's just a linear flow, + main is overkill and so is not required. +

+ + + + + + + + + + Always check return values and give informative return values. + + +

+ For unpiped commands, use $? or check directly via an + if statement to keep it simple. +

+

+ Example: + + 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 + + +

+

+ Bash also has the PIPESTATUS 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: + + 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 + +

+

+ However, as PIPESTATUS 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 + PIPESTATUS to another variable immediately after running + the command (don't forget that [ is a command and will + wipe out PIPESTATUS). + + 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 + +

+ + + + + + Given the choice between invoking a shell builtin and invoking a separate + process, choose the builtin. + + +

+ We prefer the use of builtins such as the Parameter Expansion + functions in bash(1) as it's more robust and portable + (especially when compared to things like sed). +

+

+ Example: + + # Prefer this: + addition=$((${X} + ${Y})) + substitution="${string/#foo/bar}" + + # Instead of this: + addition="$(expr ${X} + ${Y})" + substitution="$(echo "${string}" | sed -e 's/^foo/bar/')" + +

+ + + + + + +

+ Use common sense and BE CONSISTENT. +

+

+ Please take a few minutes to read the Parting Words section at the bottom + of the C++ Guide. +

+ + +

+Revision 1.26 +

+ + 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:value-of select="@title"/> + + + + + + + +

+ + + + + + + + + + + + + + + + +
+

+ Each style point has a summary for which additional information is available + by toggling the accompanying arrow button that looks this way: + + . + You may toggle all summaries with the big arrow button: +

+
+ + + + + + + Toggle all summaries +
+
+ + + + + + + +

Parting Words

+ + + + +
+ +

+ + + + + + + + +

+ +
+ + + +
+ + + + + + + + + + + + + + + + +

+ + + + + +

+ + + + + javascript:ShowHideByName(' + + ') + + + + ?showone=# + link + + + + + + + + + + + +
+ + + + +
+ + +
+ + + + +
+ +
+ + + + + display: inline + display: none + + + +
+
+ + + +

+ + Definition: + +

+ + + +

+ + Pros: + +

+ + + +

+ + Cons: + +

+ + + +

+ + Decision: + +

+ + + +

+ +

TODO: + +
+

+ + + +

+ + + +

+ + + +

+ + + +

+ + + +
+ + 

+           
+           
+           
+           
+             
+               
+               
+             
+           
+
+
+ + + +
+ + 

+           
+           
+           
+           
+             
+               
+               
+             
+           
+
+
+ + + +
+ + 

+             
+
+
+ + + +
+ + 

+                             
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
Table of Contents
+ + + + + + + +
+
+ + + # + + + + + + +
+ 		+
+ + + + + + # + + + + + + + + + +
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + _ + + + + + + + + + + + + + + + + diff --git a/vimscriptfull.xml b/vimscriptfull.xml new file mode 100644 index 0000000..fa7e343 --- /dev/null +++ b/vimscriptfull.xml @@ -0,0 +1,1534 @@ + + + +

+ + Revision 1.1 +

+ + +
+ Nate Soares
+ Joshua Hoak
+ David Barnett
+
+ + + +

+ This is the in-depth vimscript guide. If you're just a casual user + looking to write a plugin, the + abbreviated style guide is for you. +

+

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

+ +

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

+

+ Fair warning: Vimscript is a maddening abyss. When you gaze into it, it + gazes also into you. Proceed with caution. +

+ + + + +

+ 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: +

+
    +
  • + Always prefix regular expressions with one of \m, + \v, \M, or \V (prefer + tersity) +
      +
    • + Users can change the global "magic level" of regular expressions. + This changes how atoms are parsed in regular expressions, + including ., *, and {. +
      • +
    • + Even if your regular expression does not contain characters which + are affected by the magic 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. +
      • +
    • + If you have no opinion about what type of regular expression to + use, prefer the one which makes your regular expression most + concise. +
      • +
    +
    • +
  • + Avoid using :s[ubstitute] in scripts. +
      +
    • + :substitute moves the cursor. +
      • +
    • + :substitute outputs an error message when the match + does not exist. +
      • +
    • + The meaning of the g flag depends upon the + gdefault setting. If you do use + :substitute you must save gdefault, set + it to 0 or 1, perform the substitution, + and then restore it. +
      • +
    • + Script authors who want a safe way to replace text in the buffer + are encouraged to use maktaba#buffer#Replace. +
      • +
    +
    • +
  • + Always use case-explicit operators for strings (=~# and + =~?, never =~). +
      +
    • + This also applies to !~ == != > >= < and + <= +
      • +
    • + This only applies for strings. == and + >= are fine for numbers, but ==# and + >=# must be used for strings. +
      • +
    • + The behavior of =~ and friends is dependant upon the + ignorecase setting. +
      • +
    • + You may break this rule when you explicitly want to obey the + user's ignorecase setting. Be prepared to justify + your reasoning. +
      • +
    +
    • +
  • + When using regular expressions as arguments to functions, prepend them + with \c or \C. +
      +
    • + This forces case to be either explicitly matched or ignored. +
      • +
    • + This is recommended, but not required, when comparing regexes with + operators that specify case sensitivity (=~#, etc.). +
      • +
    • + This rule applies when your regexes are matching syntax, external + APIs, external messages, and most other cases. +
      • +
    • + It does not apply when matching text in the buffer. When matching + text in the buffer you should honor the ignorecase + setting. +
      • +
    • + You may also ignore this rule any time that you explicitly want to + honor the ignorecase setting. Be prepared to justify + your reasoning. +
      • +
    +
    • +
  • + Always use normal! instead of normal. +
      +
    • + If you forgo the ! the command will use the user's + key mappings and you have literally no idea what your macro will + do. +
      • +
    +
    • +
  • + Always use the noremap family of commands. +
      +
    • + Your plugins generally shouldn't introduce mappings, but if they + do, the map command respects the users existing + mappings and could do anything. +
      • +
    +
    • +
  • + When using catch, match the error code rather than the + error text. +
      +
    • + The error text may be locale-dependant. +
      • +
    • + See :help error-messages. +
      • +
    +
    • +
+

+ In general, guard all commands and functions against user settings. +

+ + + +
    + + +
  • + Line continuations: Yes +
      + +
    • + Plugins that support vi compatibility mode must save and restore + compatibility options as described in the + Errata section so line continuations work properly. +
      • +
    +
    • +
  • + Exceptions: Yes, with caution +
      +
    • + Always use an error code in thrown exception messages. +
      • +
    • + Prefer the maktaba#error codes found in + maktaba. +
      • +
    • + Fall back to the vim error codes. See + :help error-messages. +
      • +
    • + Generate custom error messages using + maktaba#error#Message. +
      • +
    +
    • +
  • + Global Variables: As configuration only +
      +
    • + See the plugin guide. +
      • +
    +
    • +
  • + Messaging: As little as possible. +
      +
    • + Loud scripts are annoying. +
      • +
    • + Message the user when an error has occured. +
      • +
    • + Message the user when an operation which takes a long time has + begun work. +
      • +
    • + Avoid messaging otherwise. +
      • +
    +
    • +
  • + Type checking: + Use strict and explicit checks where possible. +
      +
    • + Vimscript has unsafe, unintuitive behavior when dealing with some + types. For instance, 0 == 'foo' evaluates to true. +
      • +
    • + Use strict comparison operators where possible. When comparing + against a string literal, use the is# operator. + Otherwise, prefer maktaba#value#IsEqual or check + type() explicitly. +
      • +
    • + Check variable types explicitly before using them. Use functions + from maktaba#ensure, or check + maktaba#value or type() and throw your own + errors. +
      • +
    • + Use :unlet for variables that may change types, + particularly those assigned inside loops. +
      • +
    +
    • +
  • + FuncRefs: No in most cases. +
      +
    • + FuncRefs have inconsistently enforced naming restrictions. + (Functions can have names that FuncRefs can not.) +
      • +
    • + FuncRefs have inconsistent ability to be reassigned (in Vim + 7.2 and before you must unlet a FuncRef before assigning it). +
      • +
    • + 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. +
      • +
    • + Consider using maktaba#function instead to create and + manipulate handles to functions. +
      • +
    +
    • +
  • + Python: Sparingly +
      + +
    • + Hurts code reuse since python code embedded in python plugins is + awkward to share between plugins. +
      • +
    • + Using python introduces python language version dependencies, which + are likely to get stale. +
      • +
    • + Exception: It's reasonable to use python for plugin functionality + that needs to do work in the background, as vimscript can not do + this. +
      • +
    +
    • +
  • + Ruby: No +
      +
    • + We can not assume ruby interoperability. +
      • +
    • + You shouldn't depend upon the version of the ruby language that the + user has installed. +
      • +
    +
    • +
  • + Lua: No +
      +
    • + For the same reasons an Ruby. +
      • +
    +
    • +
  • + Dict Functions: Encouraged +
      +
    • + Vimscript can attach functions to dictionaries. Such functions + have access to the self parameter which access + the dict state. +
      • +
    • + Use these where you would use a class in python. +
      • +
    • + Do not over-use this feature; it is not necessary for helper + functions or API functions, only for encapsulated objects. +
      • +
    +
    • +
+

+ All other language features are fair game. +

+ + +
    +
  • + Provided functionality should be packed into modular plugins. +
      +
    • + Every function in your plugin should be specific to your + plugin. +
      • +
    • + General utility functions should be abstracted into library plugins. +
      • +
    • + Manage dependencies with maktaba. +
      • +
    +
    • +
  • + plugin-names-like-this +
      +
    • + Plugin names should be descriptive and concise. +
      • + + +
    +
    • +
  • + 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). +
    • +
  • + Plugin metadata should be declared in the addon-info.json format (see + the VAM documentation for details). +
    • +
  • + Functions should go in the autoload/ subdirectory of + your plugin. +
      +
    • + This allows them to be late-loaded, which speeds up startup + time. +
      • +
    • + This helps vim enforce namespacing conventions. +
      • +
    +
    • +
  • + Each file in the plugin/ or instant/ directory + should begin with the boilerplate + + let [s:plugin, s:enter] = maktaba#plugin#Enter(expand('<sfile>:p')) + if !s:enter + finish + endif + + (This prevents re-entry and allows users to selectively disable + functionality.) +
    • +
  • + User configuration should be via plugin flags defined in + instant/flags.vim. +
      +
    • + Define flags with + call s:plugin.Flag('FLAGNAME', DEFAULT_VALUE). +
      • +
    • + Users can configure these flags using the :Glaive + command (see glaive). +
      • +
    +
    • +
  • + Commands, autocommands, mappings, and settings changes should + occur either in the plugin/ or the + ftplugin/ subdirectories. +
      +
    • + All commands should be defined in plugin/commands.vim + or ftplugin/ files. +
      • +
    • + Autocommands should be defined in plugin/autocmds.vim, + inside an augroup. +
      • +
    • + Mappings should be defined in plugin/mappings.vim and + will be disabled unless explicitly enabled by users. +
      • +
    • + If the plugin configures any standard vim settings, those should be + configured in plugin/settings.vim or + instant/settings.vim. +
      • +
    +
    • +
  • + Avoid using the after/ subdirectory. +
      +
    • + after/ should be reserved for the user. +
      • +
    • + It is difficult for the user to add their own overrides when + plugins use after/. +
      • +
    +
    • +
+ + + + Separate library-providing plugins from command-providing plugins. + + +

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

+ + + + + + Don't clobber user settings. Provide as much configurability as + possible: that's what Vim's all about. + + +
    +
  • + Use maktaba flags for plugin configuration. Users can configure them + using the :Glaive command. + +
    • +
  • + Check if configuration variables exist before setting them. + + if !exists('g:myplugin_option') + let g:myplugin_option = 1 + endif + +
    • +
+ + + + +

+ Follow google-wide style conventions. Mimic google python style when + in doubt. +

+ + + + + + Use vimdoc. + + +

+ Provide help files generated by + vimdoc. 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 + VAM documentation). +

+ + + + + + Follow google-wide conventions. + + +
    +
  • + Use two spaces for indents. +
    • +
  • + Do not use tabs. +
    • +
  • + Use spaces around operators except for arguments to commands. +
      +
    • + 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. +
      • +
    • + + let s:variable = "concatenated " . "strings" + command -range=% MyCommand + + + let s:variable="concatenated "."strings" + command -range = % MyCommand + +
      • +
    +
    • +
  • + Do not introduce trailing whitespace. +
      +
    • + You need not go out of your way to remove it. +
      • +
    +
    • +
  • + Restrict lines to 80 columns wide. +
    • +
  • + Indent continued lines by two tabs (four spaces). +
    • +
  • + Do not waste whitespace aligning common segments of similar + commands. It is both difficult and expensive to maintain. +
      +
    • + + command -bang MyCommand call myplugin#foo() + command MyCommand2 call myplugin#bar() + + + command -bang MyCommand call myplugin#foo() + command MyCommand2 call myplugin#bar() + +
      • +
    +
    • +
+ +
    +
  • + Prefer line continuations on semantic boundaries. +
      +
    • + + command SomeLongCommand + \ call some#function() + + + command SomeLongCommand call + \ some#function() + +
      • +
    • + Use your best judgement. +
      • +
    +
    • +
  • + Place one space after the backslash denoting a line continuation. +
      +
    • + When continuing a multi-line command a pipe can be substituted + for this space as necessary, as follows: + + autocommand BufEnter <buffer> + \ if !empty(s:var) + \| call some#function() + \|else + \| call some#function(s:var) + \|endif + +
      • +
    +
    • +
  • + Do not continue multi-line commands when you can avoid it. Prefer + function calls. +
    • +
+ + +
    +
  • + Place a space after the " before the comment text. +
      +
    • + + " I am a line comment. + call call(s:my_function) + +
      • +
    +
    • +
  • + Do not use inline comments. +
      +
    • + 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. +
      • +
    • + Where you would use an inline comment, put a line comment on + the line above. +
      • +
    +
    • +
  • + When leaving blank lines in comments, include the quote in the + blank line. +
      +
    • + + " I am one continuous + " + " comment block + +
      • +
    +
    • +
+ + + + + + +

+ plugin-names-like-this, + FunctionNamesLikeThis, + CommandNamesLikeThis, + augroup_names_like_this, + variable_names_like_this. +

+

+ Prefix all variables with their scope. +

+ + +
    +
  • + variable_names_like_this +
      +
    • + FuncRef variables count as functions and should be named like + functions. +
      • +
    • + This (pathological) convention is enforced by vim itself. +
      • +
    +
    • +
  • + Prefix global variables with g: +
      +
    • + Vimscript allows you to create global variables without + prefixing them. +
      • +
    • + It is very bad practice to introduce non-prefixed global + variables into scope. +
      • +
    • + Global variables should only be used for plugin configuration. +
      • +
    • + This does not apply to functions defined in + autoload directories. +
      • +
    +
    • +
  • + Prefix script-local variables with s: +
      +
    • + This prevents namespace collisions between plugins. +
      • +
    • + This also applies to script-local functions. +
      • +
    +
    • +
  • + Prefix function arguments with a: +
      +
    • + This is enforced by vim itself. +
      • +
    +
    • +
  • + Prefix function-local variables with l: +
      +
    • + This is not enforced by vimscript but is good practice. +
      • +
    • + It helps you remember that all other variables must be + prefixed with scope. +
      • +
    • + l: disambiguates between function-local and + vim-predefined variables. For example, count + refers to + v:count, not l:count. +
      • +
    • + It future proofs your scripts against the introduction of new + vim-predefined variables. +
      • +
    +
    • +
  • + Prefix pre-defined vim variables with v: +
      +
    • + This is not enforced by vimscript but is good practice. +
      • +
    • + It provides context as to where the (undeclared) variable is + coming from. +
      • +
    • + It reminds you that the variable can not be assigned to. +
      • +
    +
    • +
  • + Prefix buffer-local variables with b: +
      +
    • + This is useful for plugins that keep per-buffer state. +
      • +
    +
    • +
+ + + + + + Prefer single quotes. + + +

+ Prefer single quoted strings. Specifically, in order of precedence: +

+
    +
  • + Always use single quotes for regular expressions. +
      +
    • + '\s*' is not the same as "\s*" +
      • +
    • + Single quotes will prevent the need for excessive backslashes. +
      • +
    • + Double single quotes escape to one single quote in single + quoted strings: 'example ('')' represents the + string + example (') +
      • +
    +
    • +
  • + If your string requires escape characters (\n, + \t, etc.) use double quotes. +
      +
    • + Escapes can not be expressed in single quoted strings. +
      • +
    • + Remember that '\n' 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. +
      • +
    +
    • +
  • + If your string contains no escapes nor single quotes, use single + quoted strings. +
      +
    • + Most strings in vimscript are regexes, so this provides maximum + consistency. +
      • +
    +
    • +
  • + If your non-regex string contains single quotes but no double + quotes, use double quotes. +
      +
    • + Don't bother escaping strings if you don't have to. +
      • +
    • + This is similar to the python string rules. +
      • +
    +
    • +
  • + If your string contains both single and double quotes, use whichever + quoting style requires less escaping. +
      +
    • + Break ties in favor of single quotes. +
      • +
    +
    • +
+ + + + + + Prefer long names. Set settings locally. + + +
    +
  • + Prefer long names of built in settings (i.e. tabstop + over + ts). +
    • +
  • + Set local settings unless you explicitly want to set global + settings. +
      +
    • + Use setlocal and &l: instead of + set and &. +
      • +
    +
    • +
+ + + + +

+ Vim plugins should provide any or all of the following: + Commands, Autocommands, + Functions, Statusline Flags, and + Mappings. +

+ + + +
    +
  • Define in plugin/commands.vim.
    • +
  • CommandNamesLikeThis.
    • +
  • Prefer semantic names to a unified prefix.
    • +
  • Do not use [!]
    • +
  • Extract logic into functions.
    • +
+ + +
    +
  • + CommandNamesLikeThis +
    • +
  • + Commands should be defined in one block with no whitespace between + them. +
      +
    • + Name commands semantically at the expense of a common prefix. +
      • +
    • + + command WhitespaceFixTrailing + command WhitespaceFixIndentation + + + command FixTrailingWhitespace + command FixIndentation + +
      • +
    +
    • +
  • + Use command without a bang. +
      +
    • + This notifies users to command name conflicts immediately at + startup. +
      • +
    • + Command name collisions are an error and should not fail + silently. +
      • +
    • + Plugins are guarded against re-entry, so a single vim session + should never attempt to re-define defined commands. +
      • +
    +
    • +
  • + Do not put logic in commands. +
      +
    • + Delegate to functions instead. +
      • +
    • + Pass non-argument command parameters (<bang>, + <register>, etc.) before argument parameters + (<f-args>, etc.). +
      • +
    • + Otherwise variable-length argument functions are difficult to + implement. +
      • +
    +
    • +
  • + Do not autoload commands. +
      +
    • + Autoloaded commands will not be available until after a function + in the same file is called. +
      • +
    • + Commands intended to be used in the .vimrc should be defined in + a instant/commands.vim file in plugins using + maktaba, or explicitly installed via an autoload function in + non-maktaba plugins. +
      • +
    +
    • +
+ +
    +
  • + Pass <bang> to functions with + '<bang>' == '!'. +
      +
    • + The function should receive a boolean parameter, not a string. +
      • +
    +
    • +
+ + + + + + +
    +
  • Define in plugin/autocmds.vim.
    • +
  • Use augroups.
    • +
  • augroup_names_like_this.
    • +
  • Clear the augroup first.
    • +
  • Extract logic into functions.
    • +
+ + +
    +
  • + All autocommands should be defined in the + plugin/autocmds.vim file. +
      +
    • + This allows users to disable your autocommands with + Glaive myplugin !plugin[autocmds]. +
      • +
    +
    • +
  • + Declare all autocommands in an augroup block. +
      +
    • + This allows your autocommands to be cleared with + autocmd!. +
      • +
    • + If your plugin only has one augroup, the + augroup name should be the same as your plugin + name, with underscores in place of any hyphens. +
      • +
    • + Otherwise augroup names should start with your + plugin name followed by an underscore. +
      • +
    +
    • +
  • + Do not put logic in autocommands. +
      +
    • + Delegate to functions instead. +
      • +
    +
    • +
  • + When creating a new augroup, clear it with + autocmd! +
      +
    • + This allows your plugins to be re-enterable. +
      • +
    +
    • +
+ + + + + +
    +
  • FunctionNamesLikeThis.
    • +
  • Autoload all functions.
    • +
  • Prefix script-local functions with s:
    • +
  • Use [!].
    • +
  • Use [abort].
    • +
+ + +
    +
  • + FunctionNamesLikeThis +
    • +
  • + Prefix all script-local functions with s: +
    • +
  • + Do not provide global functions. Use autoloaded functions instead. +
    • +
  • + Place two blank lines between top-level functions. +
    • +
  • + Declare all functions with abort. +
      +
    • + If you do not do this, the function's behavior depends upon + whether it is called within a try..endtry block + somewhere on the stack. +
      • +
    • + The abort keyword forces the function to act + consistently. +
      • +
    • + Without it, the function may (or may not) attempt to continue + execution after an error occurs. +
      • +
    +
    • +
  • + Use function! with a bang. +
      +
    • + This allows developers to re-source their scripts and have the + functions reloaded without complaint. +
      • +
    • + Function names should never collide because functions should + always be either script-local or defined in an + autoload directory. +
      • +
    • + 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). +
      • +
    +
    • +
  • + Use ... for optional arguments, not for lists of + arguments. +
      +
    • + Vimscript functions take at most 20 arguments. +
      • +
    • + Lists have no such length restriction. +
      • +
    • + Your function is likely to break when given too many arguments + if you use ... for a list of arguments. +
      • +
    +
    • +
  • + Throw exceptions rather than printing errors. +
      +
    • + Printed errors can not be caught. +
      • +
    • + Top-level functions expecting errors may catch them and print + error messages, but even those should throw their own errors + when they choke. +
      • +
    +
    • +
+ + + + + +
    +
  • + Provide opt-in key mappings in plugin/mappings.vim. +
    • +
  • + <Plug> mappings can be defined in + plugin/plugs.vim (unlike mappings.vim, plugs.vim is + opt-out). +
    • +
+ + +
    +
  • + Define key mappings in plugin/mappings.vim, using + maktaba#plugin#MapPrefix to get a prefix. +
      +
    • + Mappings defined in the special plugin/mappings.vim + file will be disabled by default (by the standard + maktaba#plugin#Enter() boilerplate). +
      • +
    • + Users can enable key mappings with + Glaive myplugin plugin[mappings]. +
      • +
    +
    • +
  • + Make all mappings with <unique>. +
      +
    • + This will inform the user when they have a mapping conflict + instead of silently clobbering their existing mappings. +
      • +
    +
    • +
  • + You may provide pseudo-mappings using <Plug> and + your plugin's name in plugin/plugs.vim (separate from + standard key mappings). +
      +
    • + <Plug> is a sequence which can not be typed. +
      • +
    • + You can do something like + noremap <Plug>namespace#MappingName + some_key_sequence + and then users can do + noremap <leader>x + <Plug>namespace#MappingName + to take advantage of your pseudo-mapping. +
      • +
    • + Pseudo-mappings should not be in + plugin/mappings.vim or they will be disabled by + default. +
      • +
    • + Such pseudo-mappings should be named <Plug> + followed by your plugin name, a pound sign, and a unique mapping + name (CamelCased like a function). +
      • +
    +
    • +
  • + Always use the noremap family of commands. Never use + the map family. +
      +
    • + map depends upon the user's existing mappings, and + could do anything. +
      • +
    +
    • +
  • + Only use noremap for commands that both make a motion + and take a range. +
      +
    • + noremap makes mappings in normal, visual, and + operator-pending modes. +
      • +
    • + If you don't want all these use nnoremap + onoremap or vnoremap explicitly. +
      • +
    +
    • +
  • + Always use <SID> in place of s: when + accessing script locals in mappings. +
      +
    • + Using s: will often fail as the mapping attempts to + type a literal s and colon. +
      • +
    +
    • +
+ + + + + + + Declare dependencies in addon-info.json and use maktaba. + + +

+ Declaring dependencies in addon-info.json allows conformant plugin + managers (like VAM) to ensure dependencies are installed. See the + VAM documentation for details. +

+

+ Calling maktaba#library#Require from dependent code at + runtime ensures that dependencies have been installed and that they + don't include unsafe non-library files. +

+ + + + + + Use <plugin-name>#status#Status() or its + finer-grained variants to provide statusline flags. + + +

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

+
    +
  • + Provide the + Info, + Alert, + Warning, and + Error functions under the + <plugin-name>#status namespace. +
    • +
  • + Info should provide information about the + state of the buffer. +
      +
    • + Example: The current git branch. +
      • +
    +
    • +
  • + Alert should provide a quiet reminder + that the buffer is non-standard. +
      +
    • + Example: The readonly setting is on. +
      • +
    +
    • +
  • + Warning should provide a warning about + the current state of the buffer. +
      +
    • + Example: The file has been edited elsewhere. +
      • +
    +
    • +
  • + Error should bring to attention a loud + issue with the buffer. +
      +
    • + Example: The file does not pass the syntax checker. +
      • +
    +
    • +
  • + By following these conventions, users can easily build up their own + statusline customizing the verbosity and colors to their tastes. +
    • +
  • + All functions should take no arguments and should return either + empty strings or strings enclosed by square brackets, e.g. + [Google]. For example: +
      +
    • + A trailing whitespace plugin might return [$] if + the file contains trailing whitespace +
      • +
    • + A prose writing plugin might return [write] if vim + is in writing mode. +
      • +
    +
    • +
  • + Consider providing the + <plugin-name>#status#Status function. +
      +
    • + It should return the first non-empty of Error, + Warning, Alert, or Info. +
      • +
    • + This is useful for users who want only the most relevant flag + and do not have a colored statusline. +
      • +
    +
    • +
+ + + + +

+ These are commands which can only be used by a limited number of + plugins, and should not in general be used by yours. +

+
    +
  • + Do not use :match :2match or :3match +
      +
    • + These are reserved for the user and for vim itself. +
      • +
    • + Use matchadd() to create a matchlevel unique to your + plugin. +
      • +
    +
    • +
  • + Do not use echoerr. +
      +
    • + echoerr does not print the red error message that you + might think it does. +
      • +
    • + echoerr prints an error message as well as context + about the code where echoerr was called. +
      • +
    • + echoerr is best suited for debugging. +
      • +
    • + Use echohl in tandem with echomsg if + you want the red error bar. +
      • +
    +
    • +
  • + Use echomsg instead of echo. +
      +
    • + echomsg messages can be reviewed with the + :messages command. +
      • +
    • + echo messages disappear permanently on redraw, which + can be very annoying to users who failed to read the message in + time. +
      • +
    +
    • +
+ + +

+ Lay out plugin/ files in the following sections, if + applicable, separated by two blank lines: +

+
    +
  • + Declaration of script constants +
    • +
  • + Declaration of configuration variables +
    • +
  • + Other declarations (commands in commands.vim file, + autocommands in autocmds.vim file, etc.) +
    • +
+

+ Lay out autoload/ files in the following sections, if + applicable, separated by two blank lines: +

+
    +
  • + maktaba#library#Require calls +
    • +
  • + Script-local variables +
    • +
  • + Script-local functions +
    • +
  • + Private autoloaded functions +
    • +
  • + Public autoloaded functions +
    • +
+

+ This is recommended convention and is not enforced. +

+ + + + +

+ Use the following shortcuts: +

+
    +
  • + catch over catch /.*/ +
    • +
  • + return over return 0 when the return value + has no semantic purpose. +
    • +
+ + + +

+ This section plumbs some of the darker corners of vimscript, explaining + the language pathologies that you wish you didn't have to know. + +

+ + + + If you don't support vi-compatibility mode, fail gracefully. + + +

+ When compatible is set, many vim features are not + available. The vim feature which most commonly affects vimscript + authors is line continuations. +

+

+ 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 :help use-cpo-save for details. +

+

+ Plugins that depend on maktaba generally don't need to worry about + compatible mode since maktaba currently just disables it, printing a + warning. +

+ + + + +

+ Revision 1.1 +

+ + +
+ Nate Soares
+ Joshua Hoak
+ David Barnett
+
+ diff --git a/vimscriptguide.xml b/vimscriptguide.xml new file mode 100644 index 0000000..2baf3fd --- /dev/null +++ b/vimscriptguide.xml @@ -0,0 +1,412 @@ + + + +

+ + Revision 1.1 +

+ + +
+ Nate Soares
+ Joshua Hoak
+ David Barnett
+
+ + + +

+ 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 + heavy guide. +

+ + + + +

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

+ + Prefer single quoted strings + +

+ Double quoted strings are semantically different in vimscript, and + you probably don't want them (they break regexes). +

+

+ Use double quoted strings when you need an escape sequence (such as + "\n") or if you know it doesn't matter and you need to + embed single quotes. +

+ + + + + Use the =~# or =~? operator families over the + =~ family. + + +

+ The matching behavior depends upon the user's ignorecase and smartcase + settings and on whether you compare them with the =~, + =~#, or =~? family of operators. Use the + =~# and =~? operator families explicitly + when comparing strings unless you explicitly need to honor the user's + case sensitivity settings. +

+ + + + Prefix all regexes with \m\C. + +

+ 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 \m\C. +

+

+ You are welcome to use other magic levels (\v) and case + sensitivities (\c) so long as they are intentional and + explicit. +

+ + + + Avoid commands with unintended side effects. + +

+ Avoid using :s[ubstitute] as it moves the cursor and + prints error messages. Prefer functions (such as + search()) better suited to scripts. +

+

+ For many vim commands, functions exist that do the same thing with + fewer side effects. See :help functions() for a list of + built-in functions. +

+ + + + Avoid commands that rely on user settings. + +

+ Always use normal! instead of normal. The + latter depends upon the user's key mappings and could do anything. +

+

+ Avoid :s[ubstitute], as its behavior depends upon a + number of local settings. +

+

+ The same applies to other commands not listed here. +

+ + + + Match error codes, not error text. + +

Error text may be locale dependant.

+ + + + + + + + + Message the user infrequently. + +

+ Loud scripts are annoying. Message the user only when: +

    +
  • A long-running process has kicked off.
    • +
  • An error has occurred.
    • +
+

+ + + + Use strict and explicit checks where possible. + +

+ Vimscript has unsafe, unintuitive behavior when dealing with some + types. For instance, 0 == 'foo' evaluates to true. +

+

+ Use strict comparison operators where possible. When comparing against + a string literal, use the is# operator. Otherwise, prefer + maktaba#value#IsEqual or check type() + explicitly. +

+

+ Check variable types explicitly before using them. Use functions from + maktaba#ensure, or check maktaba#value or + type() and throw your own errors. +

+

+ Use :unlet for variables that may change types, + particularly those assigned inside loops. +

+ + + + Use sparingly. + +

+ Use python only when it provides critical functionality, for example + when writing threaded code. +

+ + + + Use vimscript instead. + +

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

+ + + + + Use maktaba. + + +

+ maktaba removes boilerplate, including: +

    +
  • Plugin creation
    • +
  • Error handling
    • +
  • Dependency checking
    • +
+

+ + + + Organize functionality into modular plugins + +

+ 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 + VAM documentation for details). +

+ + + + + In the autoload/ directory, defined with [!] and + [abort]. + + +

+ Autoloading allows functions to be loaded on demand, which makes + startuptime faster and enforces function namespacing. +

+

+ Script-local functions are welcome, but should also live in autoload/ + and be called by autoloaded functions. +

+

+ Non-library plugins should expose commands instead of functions. + Command logic should be extracted into functions and autoloaded. +

+

+ [!] allows developers to reload their functions + without complaint. +

+

+ [abort] forces the function to halt when it encounters + an error. +

+ + + + + In the plugin/commands.vim or under the ftplugin/ directory, defined + without [!]. + + +

+ General commands go in plugin/commands.vim. + Filetype-specific commands go in ftplugin/. +

+

+ Excluding [!] prevents your plugin from silently + clobbering existing commands. Command conflicts should be resolved by + the user. +

+ + + + + Place them in plugin/autocmds.vim, within augroups. + + +

+ Place all autocommands in augroups. +

+

+ The augroup name should be unique. It should either be, or be prefixed + with, the plugin name. +

+

+ Clear the augroup with autocmd! before defining new + autocommands in the augroup. This makes your plugin re-entrable. +

+ + + + + Place them in plugin/mappings.vim, using + maktaba#plugin#MapPrefix to get a prefix. + + +

+ All key mappings should be defined in + plugin/mappings.vim. +

+

+ Partial mappings (see :help using-<Plug>.) should be defined in + plugin/plugs.vim. +

+ + + + Change settings locally + +

+ Use :setlocal and &l: instead of + :set and & unless you have explicit + reason to do otherwise. +

+ + + + + +

+ Follow google style conventions. When in doubt, treat vimscript style + like python style. +

+ + + + Similar to python. + +
+
+ + +
    +
  • Use two spaces for indents
    • +
  • Do not use tabs
    • +
  • Use spaces around operators +

    This does not apply to arguments to commands.

    + + let s:variable = "concatenated " . "strings" + command -range=% MyCommand + +
    • +
  • Do not introduce trailing whitespace +

    You need not go out of your way to remove it.

    +

    + Trailing whitespace is allowed in mappings which prep commands + for user input, such as + "noremap <leader>gf :grep -f ". +

    +
    • +
  • Restrict lines to 80 columns wide
    • +
  • Indent continued lines by four spaces
    • +
  • Do not align arguments of commands + + command -bang MyCommand call myplugin#foo() + command MyCommand2 call myplugin#bar() + + + command -bang MyCommand call myplugin#foo() + command MyCommand2 call myplugin#bar() + +
    • +
+ + + + + +

+ In general, use + plugin-names-like-this, + FunctionNamesLikeThis, + CommandNamesLikeThis, + augroup_names_like_this, + variable_names_like_this. +

+

Always prefix variables with their scope.

+ + + +

Keep them short and sweet.

+ + + +

Prefix script-local functions with s:

+

Autoloaded functions may not have a scope prefix.

+

+ Do not create global functions. Use autoloaded functions + instead. +

+ + +

Prefer succinct command names over common command prefixes.

+ + +

Augroup names count as variables for naming purposes.

+ + +
    +
  • Global variables with g:
    • +
  • Script-local variables with s:
    • +
  • Function arguments with a:
    • +
  • Function-local variables with l:
    • +
  • Vim-predefined variables with v:
    • +
  • Buffer-local variables with b:
    • +
+

+ g:, s:, and a: must always + be used. +

+

+ b: changes the variable semantics; use it when you + want buffer-local semantics. +

+

+ l: and v: 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. +

+ + + + + +

+ Revision 1.1 +

+ + +
+ Nate Soares
+ Joshua Hoak
+ David Barnett
+
+ diff --git a/xmlstyle.html b/xmlstyle.html new file mode 100644 index 0000000..7566f7e --- /dev/null +++ b/xmlstyle.html @@ -0,0 +1,681 @@ + + + + + +
+
+ +

+Google XML Document Format Style Guide

Version 1.0
Copyright Google 2008

Introduction

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.

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.

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 not applicable 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.

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.

The terms MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are used in this document in the sense of RFC 2119.
 

1. To design or not to design, that is the question

  1. 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 Tim Bray's warnings first.  Try to get wide review of your format, from outside your organization as well, if possible.  [Rationale: New document formats have a cost: they must be reviewed, documented, and learned by users.]

  2. If you are reusing or extending an existing format, make sensible + +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.  [Rationale:  Markup reuse is good, markup abuse is bad.]

  3. When extending formats, use the implicit style of the existing format, even if it contradicts this guide.  [Rationale: Consistency.]

2. Schemas

  1. Document formats SHOULD be expressed using a schema language.  [Rationale: Clarity and machine-checkability.]

  2. The schema language SHOULD be RELAX NG compact syntax.  Embedded Schematron rules MAY be added to the schema for additional fine control.  [Rationale: + +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.]

  3. Schemas SHOULD use the "Salami Slice" style (one rule per element).  Schemas MAY use the "Russian Doll" style (schema resembles document) if they are short and simple.  The "Venetian Blind" style (one rule per element type) is unsuited to RELAX NG and SHOULD NOT be used.

  4. Regular expressions SHOULD be provided to assist in validating complex values.

  5. DTDs and/or W3C XML Schemas MAY be provided for compatibility with existing products, tools, or users.  [Rationale: We can't change the world all at once.]

3. Namespaces

  1. 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.  [Rationale: Namespace-free +documents are obsolete; every set of names should be in some +namespace.  Using a default namespace improves readability.]

  2. 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.  [Rationale: Attribute names in a namespace must always have a prefix, which is annoying to type and hard to read.]

    +
  3. Namespace names are HTTP URIs.  Namespace names SHOULD take the form https://example.com/whatever/year, where whatever is a unique value based on the name of the document type, and year + +is the year the namespace was created.  There may be additional URI-path parts +before the year.  [Rationale: Existing convention.  Providing the year allows for the possible recycling of code names.]

  4. Namespaces MUST NOT be changed unless the semantics of particular elements or attributes has changed in drastically incompatible ways.  [Rationale: Changing the namespace requires changing all client code.]

  5. 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.  [Rationale: Ease of typing and absence of encoding compatibility problems.]

+ +

4. Names and enumerated values

Note: "Names" refers to the names of elements, attributes, and enumerated values.

  1. 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. [Rationale: 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.]

  2. Names MUST contain only ASCII letters and digits.  +[Rationale: Ease of typing and absence of encoding compatibility problems.]

  3. 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.  [Rationale: Longer names are awkward to use and require additional bandwidth.]

  4. 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. [Rationale:  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.]


+ +

+5. Elements

  1. All elements MUST contain either nothing, character content, or child elements.  Mixed content MUST NOT be used.  [Rationale: 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.]

  2. XML elements that merely wrap repeating child elements SHOULD NOT be used.  [Rationale: They are not used in Atom and add nothing.]
+ +


6. Attributes

  1. Document formats MUST NOT depend on the order of attributes in a start-tag.  [Rationale: Few XML parsers report the order, and it is not part of the XML Infoset.]

  2. 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.  [Rationale: This +approach maintains the built-in extensibility that XML provides with +elements, and is useful for providing forward compatibility as a +specification evolves.]

  3. Attributes MUST NOT be used to hold values in which line breaks are significant.  [Rationale: Such line breaks are converted to spaces by conformant XML parsers.]

  4. Document formats MUST allow either single or double quotation marks around attribute values.  [Rationale:  XML parsers don't report the difference.]
+ +


+

+

+7. Values

  1. 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 xsd:int, xsd:long, and xsd:double respectively.  If required in particular cases, xsd:integer (unlimited-precision integer) values MAY also be used.  [Rationale: There are far too many numeric types in XML Schema: these provide a reasonable subset.] 

  2. + +Boolean values SHOULD NOT be used (use enumerations instead).  If they must be used, they MUST be expressed as true or false, corresponding to a subset of the XML Schema type xsd:boolean.  The alternative xsd:boolean values 1 and 0 MUST NOT be used.  [Rationale: Boolean arguments are not extensible.  The additional flexibility of allowing numeric values is not abstracted away by any parser.]

  3. Dates should be represented using RFC 3339 format, a subset of both +ISO 8601 format and XML Schema xsd:dateTime format.  UTC times SHOULD be used rather than local times.  + +[Rationale: There are far too many date formats and time zones, although it is recognized that sometimes local time preserves important information.]

  4. 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.  [Rationale:  +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.]

  5. 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.
+ +


+

+

+

8. Key-value pairs

  1. +Simple key-value pairs SHOULD be represented with an empty element whose name represents the key, with the value attribute containing the value. Elements that have a value attribute MAY also have a unit attribute to specify the unit of a measured value.  For physical measurements, the SI system SHOULD be used.  [Rationale: + +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.]

  2. If the number of possible keys is very large or unbounded, key-value pairs MAY be represented by a single generic element with key, value, and optional unit and scheme +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.

9. Binary data

Note: 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.


  1. Binary data MUST NOT be included directly as-is in XML documents, but MUST be encoded using Base64 encoding.  [Rationale: XML does not allow arbitrary binary bytes.]

  2. + +The line breaks required by Base64 MAY be omitted.  [Rationale: The line breaks are meant to keep plain text lines short, but XML is not really plain text.]

  3. An attribute named xsi:type with value xs:base64Binary MAY be attached to this element to signal that the Base64 format is in use.  [Rationale: Opaque blobs should have decoding instructions attached.]

+

10. Processing instructions

  1. 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.  [Rationale: Processing instructions fit awkwardly into XML data models and can always be replaced by elements; they exist primarily to avoid breaking backward compatibility.]

 

+ +

+

 

11. Representation of XML document instances

Note:  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).  In no case should XML parsers rely on these guidelines being followed.  Use standard XML parsers, not hand-rolled hacks.


  1. The character encoding used SHOULD be UTF-8.  Exceptions should require extremely compelling circumstances.  [Rationale: UTF-8 is universal and in common use.]

  2. Namespaces SHOULD be declared in the root element of a document wherever possible.  [Rationale: Clarity and consistency.]

  3. The mapping of namespace URIs to prefixes SHOULD remain constant throughout the document, and SHOULD also be used in documentation of the design.  [Rationale: Clarity and consistency.]

  4. Well-known prefixes such as html: (for XHTML), dc: (for Dublin Core metadata), and xs: (for XML Schema) should be used for standard namespaces.  [Rationale: Human readability.]

  5. 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.  [Rationale: Consistency and conciseness.]

  6. 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.  [Rationale: They are not distinguished by XML parsers.]

  7. 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.  [Rationale: General compatibility with our style.  Wrapping character content affects its value.]

  8. Attribute values MAY be surrounded with either quotation marks or apostrophes. +Specifications MUST NOT require or forbid the use of either form.  &apos; and &quot; may be freely used to escape each type of quote.  [Rationale: No XML parsers report the distinction.]

    + +
  9. 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. [Rationale:  Comments are often discarded by parsers.]

  10. 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.  [Rationale:  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.]

  11. Comments SHOULD have whitespace following <!-- and preceding -->.  [Rationale: Readability.]

  12. CDATA sections MAY be used; they are equivalent to the use of &amp; and &lt;.  Specifications MUST NOT require or forbid the use of CDATA sections.  [Rationale: Few XML parsers report the distinction, and combinations of CDATA and text are often reported as single objects anyway.]

  13. Entity references other than the XML standard entity references &amp;, &lt;, &gt;, &quot;, and &apos; 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.
+ +

 

+

+

+



+12. Elements vs. Attributes +

+

+Note:  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. +

+

+12.1. General points:
+

+ +
    +
  1. +

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

    +

    +
    +

    +
    2. +
  2. +

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

    +

    +
    + +

    +
    3. +
  3. +

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

    +

    +
    +

    +
    4. +
  4. +

    +Both element content and attribute values need to be escaped appropriately, so escaping should not be a consideration in the design. +

    +

    +
    +

    + +
    5. +
  5. +

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

    +

    +
    +

    +
    6. +
  6. +

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

    +

    +
    +

    +
    7. +
  7. +

    +If you are extending an existing schema, do things by analogy to how things are done in that schema. +

    +

    +
    +

    +
    8. +
  8. +

    +Sensible schema languages, meaning RELAX NG and Schematron, treat elements and attributes symmetrically.  Older and cruder schema languages such as DTDs and XML Schema, tend to have better support for elements. + +

    +
    9. +
+

+

+

+12.2 Using elements
+

+
    +
  1. +

    +If something might appear more than once in a data model, use an element rather than introducing attributes with names like foo1, foo2, foo3 .... +

    + +

    +
    +

    +
    2. +
  2. +

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

    +

    +
    +

    +
    3. +
  3. +

    +Use elements when data incorporates strict typing or relationship rules. +

    +

    + +
    +

    +
    4. +
  4. +

    +If order matters between two pieces of data, use elements for them: attributes are inherently unordered. +

    +

    +
    +

    +
    5. +
  5. +

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

    + +

    +
    +

    +
    6. +
  6. +

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

    +

    +
    +

    +
    7. +
  7. +

    +If a piece of data extends across multiple lines, use an element: XML parsers will change newlines in attribute values into spaces. + +

  8. If a piece of data is very large, use an element so that its content can be streamed.

    9. +
  9. +

    +If a piece of data is in a natural language, put it in an element so you can use the xml:lang attribute to label the language being used.  Some kinds of natural-language text, like Japanese, often make use annotations that are conventionally represented using child elements; right-to-left languages like Hebrew and Arabic may similarly require child elements to manage bidirectionality properly. +

    + +

    +

    +
    10. +
+

+12.3 Using attributes
+

+
    +
  1. +

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

    +

    +
    + +

    +
    2. +
  2. +

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

    +

    +
    +

    +
    3. +
  3. +

    +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 xml:id for the attribute. + +

    +

    +
    +

    +
    4. +
  4. +

    +Hypertext references are conventionally put in href attributes. +

    +

    +
    +

    +
    5. +
  5. + +

    +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 xml:lang, xml:space, xml:base, and namespace declarations. +

    +

    +
    +

    +
    6. +
  6. +

    + +If terseness is really the most important thing, use attributes, but consider gzip compression instead -- it works very well on documents with highly repetitive structures.

    7. +

+

13. Parting words +

+

+

+Use common sense and BE CONSISTENT.   Design for extensibility.  You are gonna need it.  [Rationale: Long and painful experience.]


+ +

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

+
+Break ANY OR ALL 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. +

+

+
+Newbies always ask: +

+ +

+    "Elements or attributes? +

+

+Which will serve me best?" +

+

+    Those who know roar like lions; +

+

+    Wise hackers smile like tigers. +

+

+                    --a tanka, or extended haiku + +

+
+

+
+

+
[TODO: if a registry of schemas is set up, add a link to it]




+
+