![\"Creative](\"https://i.creativecommons.org/l/by/3.0/88x31.png\")
\n\n[cpp]: https://google.github.io/styleguide/cppguide.html\n[csharp]: https://google.github.io/styleguide/csharp-style.html\n[swift]: https://google.github.io/swift/\n[objc]: objcguide.md\n[gh-tracker]: https://github.com/google/styleguide/issues\n[go]: go/\n[java]: https://google.github.io/styleguide/javaguide.html\n[json]: https://google.github.io/styleguide/jsoncstyleguide.xml\n[kotlin]: https://developer.android.com/kotlin/style-guide\n[py]: https://google.github.io/styleguide/pyguide.html\n[r]: https://google.github.io/styleguide/Rguide.html\n[sh]: https://google.github.io/styleguide/shellguide.html\n[htmlcss]: https://google.github.io/styleguide/htmlcssguide.html\n[js]: https://google.github.io/styleguide/jsguide.html\n[markdown]: https://google.github.io/styleguide/docguide/style.html\n[ts]: https://google.github.io/styleguide/tsguide.html\n[angular]: https://google.github.io/styleguide/angularjs-google-style.html\n[cl]: https://google.github.io/styleguide/lispguide.xml\n[vim]: https://google.github.io/styleguide/vimscriptguide.xml\n[emacs]: https://raw.githubusercontent.com/google/styleguide/gh-pages/google-c-style.el\n[xml]: https://google.github.io/styleguide/xmlstyle.html\n[dart]: https://www.dartlang.org/guides/language/effective-dart\n[ccl]: https://creativecommons.org/licenses/by/3.0/\n[SCM]: https://en.wikipedia.org/wiki/Source_control_management\n[VCS]: https://en.wikipedia.org/wiki/Version_control_system\n"
},
{
"path": "Rguide.md",
"content": "# Google's R Style Guide\n\nR is a high-level programming language used primarily for statistical computing\nand graphics. The goal of the R Programming Style Guide is to make our R code\neasier to read, share, and verify.\n\nThe Google R Style Guide is a fork of the\n[Tidyverse Style Guide](https://style.tidyverse.org/) by Hadley Wickham\n[license](https://creativecommons.org/licenses/by-sa/2.0/). Google modifications\nwere developed in collaboration with the internal R user community. The rest of\nthis document explains Google's primary differences with the Tidyverse guide,\nand why these differences exist.\n\n## Syntax\n\n### Naming conventions\n\nGoogle prefers identifying functions with `BigCamelCase` to clearly distinguish\nthem from other objects.\n\n```\n# Good\nDoNothing <- function() {\n return(invisible(NULL))\n}\n```\n\nThe names of private functions should begin with a dot. This helps communicate\nboth the origin of the function and its intended use.\n\n```\n# Good\n.DoNothingPrivately <- function() {\n return(invisible(NULL))\n}\n```\n\nWe previously recommended naming objects with `dot.case`. We're moving away from\nthat, as it creates confusion with S3 methods.\n\n### Don't use attach()\n\nThe possibilities for creating errors when using `attach()` are numerous.\n\n## Pipes\n\n### Right-hand assignment\n\nWe do not support using right-hand assignment.\n\n```\n# Bad\niris %>%\n dplyr::summarize(max_petal = max(Petal.Width)) -> results\n```\n\nThis convention differs substantially from practices in other languages and\nmakes it harder to see in code where an object is defined. E.g. searching for\n`foo <-` is easier than searching for `foo <-` and `-> foo` (possibly split over\nlines).\n\n### Use explicit returns\n\nDo not rely on R's implicit return feature. It is better to be clear about your\nintent to `return()` an object.\n\n```\n# Good\nAddValues <- function(x, y) {\n return(x + y)\n}\n\n# Bad\nAddValues <- function(x, y) {\n x + y\n}\n```\n\n### Qualifying namespaces\n\nUsers should explicitly qualify namespaces for all external functions.\n\n```\n# Good\npurrr::map()\n```\n\nWe discourage using the `@import` Roxygen tag to bring in all functions into a\nNAMESPACE. Google has a very big R codebase, and importing all functions creates\ntoo much risk for name collisions.\n\nWhile there is a small performance penalty for using `::`, it makes it easier to\nunderstand dependencies in your code. There are some exceptions to this rule.\n\n* Infix functions (`%name%`) always need to be imported.\n* Certain `rlang` pronouns, notably `.data`, need to be imported.\n* Functions from default R packages, including `datasets`, `utils`,\n `grDevices`, `graphics`, `stats` and `methods`. If needed, you can `@import`\n the full package.\n\nWhen importing functions, place the `@importFrom` tag in the Roxygen header\nabove the function where the external dependency is used.\n\n## Documentation\n\n### Package-level documentation\n\nAll packages should have a package documentation file, in a\n`packagename-package.R` file.\n"
},
{
"path": "Rguide.xml",
"content": "\n\n \n \n \n \n \n The style guide has moved to Rguide.html\n
\n \n\n" }, { "path": "_includes/head-custom.html", "content": "\n" }, { "path": "angularjs-google-style.html", "content": "\n\n\n\n \n \n \n \n \n \nThis is the external version of a document that was primarily written for Google\n engineers. It describes a recommended style for AngularJS apps that use Closure, as used\n internally at Google. Members of the broader AngularJS community should feel free to apply\n (or not apply) these recommendations, as relevant to their own use cases.
\n\nThis document describes style for AngularJS apps in google3. This guide\n supplements and extends the \n Google JavaScript Style Guide.\n
\n\nStyle Note: Examples on the AngularJS external webpage, and many external apps, are\n written in a style that freely uses closures, favors functional inheritance, and does not often use\n \n JavaScript types. Google follows a more rigorous Javascript style to support JSCompiler\n optimizations and large code bases - see the javascript-style mailing list.\n This is not an Angular-specific issue, and is not discussed further in this style guide.\n (But if you want further reading:\n Martin Fowler on closures,\n much longer description, appendix A of the\n \n closure book has a good description of inheritance patterns and why it prefers\n pseudoclassical,\n \n Javascript, the Good Parts as a counter.)
\n\nChoose a namespace for your project, and use goog.provide and goog.require.
\n\ngoog.provide('hello.about.AboutCtrl');\ngoog.provide('hello.versions.Versions');\n\n\nWhy?\n Google BUILD rules integrate nicely with closure provide/require.
\n\nYour main application module should be in your root client directory. A module should never be\n altered other than the one where it is defined.
\n\nModules may either be defined in the same file as their components (this works well for a module\n that contains exactly one service) or in a separate file for wiring pieces together.
\n\nWhy?\n A module should be consistent for anyone that wants to include it as a reusable component.\n If a module can mean different things depending on which files are included, it is not consistent.\n
\n\nFor example:
\n\n\n// file submodulea.js:\n goog.provide('my.submoduleA');\n\n my.submoduleA = angular.module('my.submoduleA', []);\n // ...\n\n// file app.js\n goog.require('my.submoduleA');\n\n Yes: my.application.module = angular.module('hello', [my.submoduleA.name]);\n \n No: my.application.module = angular.module('hello', ['my.submoduleA']);\n \n\nWhy?\n Using a property of my.submoduleA prevents Closure presubmit failures complaining that the file is\n required but never used. Using the .name property avoids duplicating strings.
\n\nThis maximally allows the JS compiler to enforce type safety in the presence of externally\n provided types from Angular, and means you don't have to worry about Angular vars being obfuscated\n in a confusing way.
\n\nNote to readers outside Google: the current externs file is located in an internal-to-Google\n directory, but an example can be found on github \n here.
\n\nReminder: According to the JS style guide, customer facing code must be compiled.
\n\nRecommended: Use the JSCompiler (the closure compiler that works with js_binary by\n default) and ANGULAR_COMPILER_FLAGS_FULL from //javascript/angular/build_defs/build_defs for\n your base flags.\n
\n\nNote - if you are using @export for methods, you will need to add the compiler flag
\n\n\"--generate_exports\",\n\n\n
If you are using @export for properties, you will need to add the flags:
\n\n\"--generate_exports\",\n\"--remove_unused_prototype_props_in_externs=false\",\n\"--export_local_property_definitions\",\n\n\n
Controllers are classes. Methods should be defined on MyCtrl.prototype.
\n\nGoogle Angular applications should use the 'controller as' style to export the controller\n onto the scope. This is fully implemented in Angular 1.2 and can be mimicked in pre-Angular 1.2\n builds.\n
\n\nPre Angular 1.2, this looks like:
\n\n/**\n * Home controller.\n *\n * @param {!angular.Scope} $scope\n * @constructor\n * @ngInject\n * @export\n */\nhello.mainpage.HomeCtrl = function($scope) {\n /** @export */\n $scope.homeCtrl = this; // This is a bridge until Angular 1.2 controller-as\n\n /**\n * @type {string}\n * @export\n */\n this.myColor = 'blue';\n};\n\n\n/**\n * @param {number} a\n * @param {number} b\n * @export\n */\nhello.mainpage.HomeCtrl.prototype.add = function(a, b) {\n return a + b;\n};\n\n\nAnd the template:
\n\n\n<div ng-controller=\"hello.mainpage.HomeCtrl\"/>\n <span ng-class=\"homeCtrl.myColor\">I'm in a color!</span>\n <span>{{homeCtrl.add(5, 6)}}</span>\n</div>\n\n\nAfter Angular 1.2, this looks like:
\n\n\n/**\n * Home controller.\n *\n * @constructor\n * @ngInject\n * @export\n */\nhello.mainpage.HomeCtrl = function() {\n /**\n * @type {string}\n * @export\n */\n this.myColor = 'blue';\n};\n\n\n/**\n * @param {number} a\n * @param {number} b\n * @export\n */\nhello.mainpage.HomeCtrl.prototype.add = function(a, b) {\n return a + b;\n};\n\n\nIf you are compiling with property renaming, expose properties and methods using the @export\n annotation. Remember to @export the constructor as well.
\n\nAnd in the template:
\n\n\n<div ng-controller=\"hello.mainpage.HomeCtrl as homeCtrl\"/>\n <span ng-class=\"homeCtrl.myColor\">I'm in a color!</span>\n <span>{{homeCtrl.add(5, 6)}}</span>\n</div>\n\n\nWhy?\n Putting methods and properties directly onto the controller, instead of building up a scope\n object, fits better with the Google Closure class style. Additionally, using 'controller as'\n makes it obvious which controller you are accessing when multiple controllers apply to an element.\n Since there is always a '.' in the bindings, you don't have to worry about prototypal inheritance\n masking primitives.
\n\nAll DOM manipulation should be done inside directives. Directives should be kept small and use\n composition. Files defining directives should goog.provide a static function which returns the\n directive definition object.
\n\n\ngoog.provide('hello.pane.paneDirective');\n\n/**\n * Description and usage\n * @return {angular.Directive} Directive definition object.\n */\nhello.pane.paneDirective = function() {\n // ...\n};\n\n\nException: DOM manipulation may occur in services for DOM elements disconnected from the\n rest of the view, e.g. dialogs or keyboard shortcuts.
\n\nServices registered on the module with module.service are classes.\n Use module.service instead of module.provider or\n module.factory unless you need to do initialization beyond just creating a\n new instance of the class.
\n/**\n * @param {!angular.$http} $http The Angular http service.\n * @constructor\n */\nhello.request.Request = function($http) {\n /** @type {!angular.$http} */\n this.http_ = $http;\n};\n\nhello.request.Request.prototype.get = function() {/*...*/};\n\n\nIn the module:
\n\n\nmodule.service('request', hello.request.Request);\n\n\n\nDo not use $ to prepend your own object properties and service identifiers. Consider this style\n of naming reserved by AngularJS and jQuery.
\n\nYes:
\n\n $scope.myModel = { value: 'foo' }\n myModule.service('myService', function() { /*...*/ });\n var MyCtrl = function($http) {this.http_ = $http;};\n\n\nNo:
\n\n $scope.$myModel = { value: 'foo' } // BAD\n $scope.myModel = { $value: 'foo' } // BAD\n myModule.service('$myService', function() { ... }); // BAD\n var MyCtrl = function($http) {this.$http_ = $http;}; // BAD\n\n\nWhy?\n It's useful to distinguish between Angular / jQuery builtins and things you add yourself.\n In addition, $ is not an acceptable character for variables names in the JS style guide.\n
\n\nFor custom elements (e.g. <ng-include src=\"template\"></ng-include>), IE8\n requires special support (html5shiv-like hacks) to enable css styling. Be aware of this\n restriction in apps targeting old versions of IE.
These are not strict style guide rules, but are placed here as reference for folks getting\n started with Angular at Google.
\n\nAngular is designed for test-driven development.
\n\nThe recommended unit testing setup is Jasmine + Karma (though you could use closure tests\n or js_test)
\n\nAngular provides easy adapters to load modules and use the injector in Jasmine tests.\n
\n\n\n\n\n This directory structure doc describes how to structure your application with controllers in\n nested subdirectories and all components (e.g. services and directives) in a 'components' dir.\n
\n\n\nSee \n The Nuances of Scope Prototypal Inheritance
\n\nThis removes the need to add myCtrl['$inject'] = ... to prevent minification from\n messing up Angular's dependency injection.
Usage:
\n\n/**\n * My controller.\n * @param {!angular.$http} $http\n * @param {!my.app.myService} myService\n * @constructor\n * @export\n * @ngInject\n */\nmy.app.MyCtrl = function($http, myService) {\n //...\n};\n\n\nC++ is one of the main development languages used by\nmany of Google's open-source projects. As every C++\nprogrammer knows, the language has many powerful features, but\nthis power brings with it complexity, which in turn can make\ncode more bug-prone and harder to read and maintain.
\n\nThe goal of this guide is to manage this complexity by\ndescribing in detail the dos and don'ts of writing C++\ncode. These rules exist to\nkeep the codebase manageable while still allowing\ncoders to use C++ language features productively.
\n\nStyle, also known as readability, is what we call\nthe conventions that govern our C++ code. The term Style is a\nbit of a misnomer, since these conventions cover far more than\njust source file formatting.
\n\n\nMost open-source projects developed by\nGoogle conform to the requirements in this guide.\n
\n\n\n\nNote that this guide is not a C++ tutorial: we assume that\nthe reader is familiar with the language.
\n\nWhy do we have this document?
\n\nThere are a few core goals that we believe this guide should\nserve. These are the fundamental whys that\nunderlie all of the individual rules. By bringing these ideas to\nthe fore, we hope to ground discussions and make it clearer to our\nbroader community why the rules are in place and why particular\ndecisions have been made. If you understand what goals each rule is\nserving, it should be clearer to everyone when a rule may be waived\n(some can be), and what sort of argument or alternative would be\nnecessary to change a rule in the guide.
\n\nThe goals of the style guide as we currently see them are as follows:
\ngoto contravenes many\nof the following principles, but is already vanishingly rare, so the Style\nGuide doesn't discuss it.std::unique_ptr\ndemonstrates the ownership transfer unambiguously at the call\nsite). #includes only\nwork properly when your code is consistent with the expectations of\nthe tooling. In many cases, rules that are attributed to \"Be\nConsistent\" boil down to \"Just pick one and stop worrying about it\";\nthe potential value of allowing flexibility on these points is\noutweighed by the cost of having people argue over them. However,\nthere are limits to consistency; it is a good tie breaker when there\nis no clear technical argument, nor a long-term direction. It applies\nmore heavily locally (per file, or for a tightly-related set of\ninterfaces). Consistency should not generally be used as a\njustification to do things in an old style without considering the\nbenefits of the new style, or the tendency of the codebase to converge\non newer styles over time.The intent of this document is to provide maximal guidance with\nreasonable restriction. As always, common sense and good taste should\nprevail. By this we specifically refer to the established conventions\nof the entire Google C++ community, not just your personal preferences\nor those of your team. Be skeptical about and reluctant to use\nclever or unusual constructs: the absence of a prohibition is not the\nsame as a license to proceed. Use your judgment, and if you are\nunsure, please don't hesitate to ask your project leads to get additional\ninput.
\n\n\n\nCurrently, code should target C++20, i.e., should not use C++23\n features. The C++ version targeted by this guide will advance\n (aggressively) over time.
\n\n\n\nDo not use\n non-standard extensions.
\n\nConsider portability to other environments before using features\nfrom C++17 and C++20 in your project.
\nIn general, every .cc file should have an\nassociated .h file. There are some common\nexceptions, such as unit tests and small .cc files containing\njust a main() function.
Correct use of header files can make a huge difference to\nthe readability, size and performance of your code.
\n\nThe following rules will guide you through the various\npitfalls of using header files.
\n\n\nHeader files should be self-contained (compile on their own) and\nend in .h. Non-header files that are meant for inclusion\nshould end in .inc and be used sparingly.
All header files should be self-contained. Users and refactoring\ntools should not have to adhere to special conditions to include the\nheader. Specifically, a header should\nhave header guards and include all\nother headers it needs.
\n\nWhen a header declares inline functions or templates that clients of the\nheader will instantiate, the inline functions and templates must also have\ndefinitions in the header, either directly or in files it includes. Do not move\nthese definitions to separately included header (-inl.h) files;\nthis practice was common in the past, but is no longer allowed. When all\ninstantiations of a template occur in one .cc file, either because\nthey're \nexplicit or because the definition is accessible to only\nthe .cc file, the template definition can be kept in that file.
There are rare cases where a file designed to be included is not\nself-contained. These are typically intended to be included at unusual\nlocations, such as the middle of another file. They might not\nuse header guards, and might not include\ntheir prerequisites. Name such files with the .inc\nextension. Use sparingly, and prefer self-contained headers when\npossible.
All header files should have #define guards to\nprevent multiple inclusion. The format of the symbol name\nshould be\n\n<PROJECT>_<PATH>_<FILE>_H_.
To guarantee uniqueness, they should\nbe based on the full path in a project's source tree. For\nexample, the file foo/src/bar/baz.h in\nproject foo should have the following\nguard:
#ifndef FOO_BAR_BAZ_H_\n#define FOO_BAR_BAZ_H_\n\n...\n\n#endif // FOO_BAR_BAZ_H_\n\n\n\n\n
If a source or header file refers to a symbol defined elsewhere,\nthe file should directly include a header file which properly intends\nto provide a declaration or definition of that symbol. It should not\ninclude header files for any other reason.\n
\n\nDo not rely on transitive inclusions. This allows people to remove\nno-longer-needed #include statements from their headers without\nbreaking clients. This also applies to related headers\n- foo.cc should include bar.h if it uses a\nsymbol from it even if foo.h\nincludes bar.h.
Avoid using forward declarations where possible.\n Instead, include the headers you need.\n
\n\n\n\nA \"forward declaration\" is a declaration of an entity\n without an associated definition.
\n// In a C++ source file:\nclass B;\nvoid FuncInB();\nextern int variable_in_b;\nABSL_DECLARE_FLAG(flag_in_b);\n\n\n\n
#includes force the compiler to open\n more files and process more input.#includes can force\n your code to be recompiled more often, due to unrelated\n changes in the header.#include statement\n makes it difficult for automatic tooling to discover the module\n defining the symbol.std:: yields undefined behavior.#include is needed.\n Replacing an #include with a forward\n declaration can silently change the meaning of\n code:\n// b.h:\nstruct B {};\nstruct D : B {};\n\n// good_user.cc:\n#include \"b.h\"\nvoid f(B*);\nvoid f(void*);\nvoid test(D* x) { f(x); } // Calls f(B*)\n\n If the #include was replaced with forward\n decls for B and D,\n test() would call f(void*).\n #includeing the header.Try to avoid forward declarations of entities\ndefined in another project.
\n\n\nInclude the definition of a function at its point of declaration in a header file only\nwhen the definition is short. If the definition otherwise has a reason be in the header,\nput it in an internal part of the file. If necessary to make the definition ODR-safe, mark\nit with an inline specifier.
Functions defined in header files are sometimes referred to as \"inline functions\",\nwhich is a somewhat overloaded term that refers to several distinct but overlapping\nsituations:
\n\nWhile functions tend to be a more common source of confusion, these definitions apply to\nvariables as well, and so do the rules here.
\n\n\n\nconstexpr functions generally need to\nbe defined in the header file that declares them (but not necessarily the public part).Only define a function at its public declaration if it is short, say, 10 lines or fewer. Put\nlonger function bodies in the .cc file unless they must be in the header for\nperformance or technical reasons.
Even if a definition must be in the header, this is not a sufficient reason to put it within\nthe public part. Instead, the definition can be in an internal part of the header, such as the\nprivate section of a class, within a namespace that includes the word\ninternal, or below a comment like // Implementation details only\nbelow here.
Once a definition is in a header file, it must be ODR-safe by having the inline\nspecifier or being implicitly specified inline by being a function template or defined in a class\nbody when first declared.
template <typename T>\nclass Foo {\n public:\n int bar() { return bar_; }\n\n void MethodWithHugeBody();\n\n private:\n int bar_;\n};\n\n// Implementation details only below here\n\ntemplate <typename T>\nvoid Foo<T>::MethodWithHugeBody() {\n ...\n}\n\n\nInclude headers in the following order: Related header, C system headers,\nC++ standard library headers,\nother libraries' headers, your project's\nheaders.
\n\n\nAll of a project's header files should be\nlisted as descendants of the project's source\ndirectory without use of UNIX directory aliases\n. (the current directory) or ..\n(the parent directory). For example,\n\ngoogle-awesome-project/src/base/logging.h\nshould be included as:
#include \"base/logging.h\"\n\n\n
Headers should only be included using an angle-bracketed path if the library\nrequires you to do so. In particular, the following headers require angle\nbrackets:
\n\n<stdlib.h>\n and <string>).<unistd.h>\n and <windows.h>).<Python.h>).In dir/foo.cc or\ndir/foo_test.cc, whose main\npurpose is to implement or test the stuff in\ndir2/foo2.h, order your includes\nas follows:
dir2/foo2.h..h extension, e.g., <unistd.h>,\n <stdlib.h>, <Python.h>.<algorithm>, <cstddef>..h files..h\n files.Separate each non-empty group with one blank line.
\n\nWith the preferred ordering, if the related header\ndir2/foo2.h omits any necessary\nincludes, the build of dir/foo.cc\nor dir/foo_test.cc will break.\nThus, this rule ensures that build breaks show up first\nfor the people working on these files, not for innocent\npeople in other packages.
dir/foo.cc and\ndir2/foo2.h are usually in the same\ndirectory (e.g., base/basictypes_test.cc and\nbase/basictypes.h), but may sometimes be in different\ndirectories too.
Note that the C headers such as stddef.h\nare essentially interchangeable with their C++ counterparts\n(cstddef).\nEither style is acceptable, but prefer consistency with existing code.
Within each section the includes should be ordered\nalphabetically. Note that older code might not conform to\nthis rule and should be fixed when convenient.
\n\nFor example, the includes in\n\ngoogle-awesome-project/src/foo/internal/fooserver.cc\nmight look like this:
#include \"foo/server/fooserver.h\"\n\n#include <sys/types.h>\n#include <unistd.h>\n\n#include <string>\n#include <vector>\n\n#include \"base/basictypes.h\"\n#include \"foo/server/bar.h\"\n#include \"third_party/absl/flags/flag.h\"\n\n\n
Exception:
\n\nSometimes, system-specific code needs\nconditional includes. Such code can put conditional\nincludes after other includes. Of course, keep your\nsystem-specific code small and localized. Example:
\n\n#include \"foo/public/fooserver.h\"\n\n#ifdef _WIN32\n#include <windows.h>\n#endif // _WIN32\n\n\n
With few exceptions, place code in a namespace. Namespaces\nshould have unique names based on the project name, and possibly\nits path. Do not use using-directives (e.g.,\nusing namespace foo). Do not use\ninline namespaces. For unnamed namespaces, see\nInternal Linkage.\n\n
Namespaces subdivide the global scope\ninto distinct, named scopes, and so are useful for preventing\nname collisions in the global scope.
\n\n\n\nNamespaces provide a method for preventing name conflicts\nin large programs while allowing most code to use reasonably\nshort names.
\n\nFor example, if two different projects have a class\nFoo in the global scope, these symbols may\ncollide at compile time or at runtime. If each project\nplaces their code in a namespace, project1::Foo\nand project2::Foo are now distinct symbols that\ndo not collide, and code within each project's namespace\ncan continue to refer to Foo without the prefix.
Inline namespaces automatically place their names in\nthe enclosing scope. Consider the following snippet, for\nexample:
\n\nnamespace outer {\ninline namespace inner {\n void foo();\n} // namespace inner\n} // namespace outer\n\n\nThe expressions outer::inner::foo() and\nouter::foo() are interchangeable. Inline\nnamespaces are primarily intended for ABI compatibility\nacross versions.
Namespaces can be confusing, because they complicate\nthe mechanics of figuring out what definition a name refers\nto.
\n\nInline namespaces, in particular, can be confusing\nbecause names aren't actually restricted to the namespace\nwhere they are declared. They are only useful as part of\nsome larger versioning policy.
\n\nIn some contexts, it's necessary to repeatedly refer to\nsymbols by their fully-qualified names. For deeply-nested\nnamespaces, this can add a lot of clutter.
\n\n\n\nNamespaces should be used as follows:
\n\nNamespaces wrap the entire source file after\n includes,\n \n gflags definitions/declarations\n and forward declarations of classes from other namespaces.
\n\n// In the .h file\nnamespace mynamespace {\n\n// All declarations are within the namespace scope.\n// Notice the lack of indentation.\nclass MyClass {\n public:\n ...\n void Foo();\n};\n\n} // namespace mynamespace\n\n\n// In the .cc file\nnamespace mynamespace {\n\n// Definition of functions is within scope of the namespace.\nvoid MyClass::Foo() {\n ...\n}\n\n} // namespace mynamespace\n\n\n More complex .cc files might have additional details,\n like flags or using-declarations.
#include \"a.h\"\n\nABSL_FLAG(bool, someflag, false, \"a flag\");\n\nnamespace mynamespace {\n\nusing ::foo::Bar;\n\n...code for mynamespace... // Code goes against the left margin.\n\n} // namespace mynamespace\n\n package specifier in the\n .proto file. See\n\n\n \n Protocol Buffer Packages\n for details.std, including forward declarations of\n standard library classes. Declaring entities in\n namespace std is undefined behavior, i.e.,\n not portable. To declare entities from the standard\n library, include the appropriate header file.You may not use a using-directive\n to make all names from a namespace available.
\n\n// Forbidden -- This pollutes the namespace.\nusing namespace foo;\n\n
Do not use Namespace aliases at namespace scope\n in header files except in explicitly marked\n internal-only namespaces, because anything imported into a namespace\n in a header file becomes part of the public API exported by that file.\n Namespace aliases can be used when those conditions don't apply, but\n they must have appropriate names.
\n\n// In a .h file, an alias must not be a separate API, or must be hidden in an\n// implementation detail.\nnamespace librarian {\n\nnamespace internal { // Internal, not part of the API.\nnamespace sidetable = ::pipeline_diagnostics::sidetable;\n} // namespace internal\n\ninline void my_inline_function() {\n // Local to a function.\n namespace baz = ::foo::bar::baz;\n ...\n}\n\n} // namespace librarian\n\n\n// Remove uninteresting parts of some commonly used names in .cc files.\nnamespace sidetable = ::pipeline_diagnostics::sidetable;\n\n\n
Use namespaces with \"internal\" in the name to document parts of an API that\n should not be mentioned by users of the API.\n
\n\n// We shouldn't use this internal name in non-absl code.\nusing ::absl::container_internal::ImplementationDetail;\n\n\n
Note that there is still a risk of collision between libraries within a\n nested internal namespace, so give each library within a\n namespace a unique internal namespace by adding the library's\n filename. For example, gshoe/widget.h would use\n gshoe::internal_widget as opposed to just\n gshoe::internal.
Single-line nested namespace declarations\n\n are preferred in new code, but are not required.
\nnamespace my_project::my_component {\n\n ...\n\n} // namespace my_project::my_component\n\n When definitions in a .cc file do not need to be\nreferenced outside that file, give them internal linkage by placing\nthem in an unnamed namespace or declaring them static.\nDo not use either of these constructs in .h files.\n\n
All declarations can be given internal linkage by placing them in unnamed\nnamespaces. Functions and variables can also be given internal linkage by\ndeclaring them static. This means that anything you're declaring\ncan't be accessed from another file. If a different file declares something with\nthe same name, then the two entities are completely independent.
Use of internal linkage in .cc files is encouraged\nfor all code that does not need to be referenced elsewhere.\nDo not use internal linkage in .h files.
Format unnamed namespaces like named namespaces. In the\n terminating comment, leave the namespace name empty:
\n\nnamespace {\n...\n} // namespace\n\n\nPrefer placing nonmember functions in a namespace; use completely global\nfunctions rarely. Do not use a class simply to group static members. Static\nmethods of a class should generally be closely related to instances of the\nclass or the class's static data.
\n\n\n\nNonmember and static member functions can be useful in\nsome situations. Putting nonmember functions in a\nnamespace avoids polluting the global namespace.
\n\n\nNonmember and static member functions may make more sense\nas members of a new class, especially if they access\nexternal resources or have significant dependencies.
\n\n\nSometimes it is useful to define a\nfunction not bound to a class instance. Such a function\ncan be either a static member or a nonmember function.\nNonmember functions should not depend on external\nvariables, and should nearly always exist in a namespace.\nDo not create classes only to group static members;\nthis is no different than just giving the names a\ncommon prefix, and such grouping is usually unnecessary anyway.
\n\nIf you define a nonmember function and it is only\nneeded in its .cc file, use\ninternal linkage to limit\nits scope.
Place a function's variables in the narrowest scope\npossible, and initialize variables in the declaration.
\n\nC++ allows you to declare variables anywhere in a function.\nWe encourage you to declare them in a scope as local as\npossible, and as close to the first use as possible.\nThis makes it easier for the reader to find the\ndeclaration and see what type the variable is and what it\nwas initialized to. In particular, initialization should\nbe used instead of declaration and assignment, e.g.,:
\n\nint i;\ni = f(); // Bad -- initialization separate from declaration.\n\n\n
int i = f(); // Good -- declaration has initialization.\n\n\n\n
int jobs = NumJobs();\n// More code...\nf(jobs); // Bad -- declaration separate from use.\n\n\n
int jobs = NumJobs();\nf(jobs); // Good -- declaration immediately (or closely) followed by use.\n\n\n
std::vector<int> v;\nv.push_back(1); // Prefer initializing using brace initialization.\nv.push_back(2);\n\n\n
std::vector<int> v = {1, 2}; // Good -- v starts initialized.\n\n\nVariables needed for if, while\nand for statements should normally be declared\nwithin those statements, so that such variables are confined\nto those scopes. For example:
while (const char* p = strchr(str, '/')) str = p + 1;\n\n\n
There is one caveat: if the variable is an object, its\nconstructor is invoked every time it enters scope and is\ncreated, and its destructor is invoked every time it goes\nout of scope.
\n\n// Inefficient implementation:\nfor (int i = 0; i < 1000000; ++i) {\n Foo f; // My ctor and dtor get called 1000000 times each.\n f.DoSomething(i);\n}\n\n\nIt may be more efficient to declare such a variable\nused in a loop outside that loop:
\n\nFoo f; // My ctor and dtor get called once each.\nfor (int i = 0; i < 1000000; ++i) {\n f.DoSomething(i);\n}\n\n\nObjects with\n\nstatic storage duration are forbidden unless they are\ntrivially\ndestructible. Informally this means that the destructor does not do\nanything, even taking member and base destructors into account. More formally it\nmeans that the type has no user-defined or virtual destructor and that all bases\nand non-static members are trivially destructible.\nStatic function-local variables may use dynamic initialization.\nUse of dynamic initialization for static class member variables or variables at\nnamespace scope is discouraged, but allowed in limited circumstances; see below\nfor details.
\n\nAs a rule of thumb: a global variable satisfies these requirements if its\ndeclaration, considered in isolation, could be constexpr.
Every object has a storage duration, which correlates with its\nlifetime. Objects with static storage duration live from the point of their\ninitialization until the end of the program. Such objects appear as variables at\nnamespace scope (\"global variables\"), as static data members of classes, or as\nfunction-local variables that are declared with the static\nspecifier. Function-local static variables are initialized when control first\npasses through their declaration; all other objects with static storage duration\nare initialized as part of program start-up. All objects with static storage\nduration are destroyed at program exit (which happens before unjoined threads\nare terminated).
Initialization may be dynamic, which means that something\nnon-trivial happens during initialization. (For example, consider a constructor\nthat allocates memory, or a variable that is initialized with the current\nprocess ID.) The other kind of initialization is static\ninitialization. The two aren't quite opposites, though: static\ninitialization always happens to objects with static storage duration\n(initializing the object either to a given constant or to a representation\nconsisting of all bytes set to zero), whereas dynamic initialization happens\nafter that, if required.
\n\n\nGlobal and static variables are very useful for a large number of\napplications: named constants, auxiliary data structures internal to some\ntranslation unit, command-line flags, logging, registration mechanisms,\nbackground infrastructure, etc.
\n\n\nGlobal and static variables that use dynamic initialization or have\nnon-trivial destructors create complexity that can easily lead to hard-to-find\nbugs. Dynamic initialization is not ordered across translation units, and\nneither is destruction (except that destruction\nhappens in reverse order of initialization). When one initialization refers to\nanother variable with static storage duration, it is possible that this causes\nan object to be accessed before its lifetime has begun (or after its lifetime\nhas ended). Moreover, when a program starts threads that are not joined at exit,\nthose threads may attempt to access objects after their lifetime has ended if\ntheir destructor has already run.
\n\n\nWhen destructors are trivial, their execution is not subject to ordering at\nall (they are effectively not \"run\"); otherwise we are exposed to the risk of\naccessing objects after the end of their lifetime. Therefore, we only allow\nobjects with static storage duration if they are trivially destructible.\nFundamental types (like pointers and int) are trivially\ndestructible, as are arrays of trivially destructible types. Note that\nvariables marked with constexpr are trivially destructible.
const int kNum = 10; // Allowed\n\nstruct X { int n; };\nconst X kX[] = {{1}, {2}, {3}}; // Allowed\n\nvoid foo() {\n static const char* const kMessages[] = {\"hello\", \"world\"}; // Allowed\n}\n\n// Allowed: constexpr guarantees trivial destructor.\nconstexpr std::array<int, 3> kArray = {1, 2, 3};\n// bad: non-trivial destructor\nconst std::string kFoo = \"foo\";\n\n// Bad for the same reason, even though kBar is a reference (the\n// rule also applies to lifetime-extended temporary objects).\nconst std::string& kBar = StrCat(\"a\", \"b\", \"c\");\n\nvoid bar() {\n // Bad: non-trivial destructor.\n static std::map<int, int> kData = {{1, 0}, {2, 0}, {3, 0}};\n}\n\nNote that references are not objects, and thus they are not subject to the\nconstraints on destructibility. The constraint on dynamic initialization still\napplies, though. In particular, a function-local static reference of the form\nstatic T& t = *new T; is allowed.
Initialization is a more complex topic. This is because we must not only\nconsider whether class constructors execute, but we must also consider the\nevaluation of the initializer:
\nint n = 5; // Fine\nint m = f(); // ? (Depends on f)\nFoo x; // ? (Depends on Foo::Foo)\nBar y = g(); // ? (Depends on g and on Bar::Bar)\n\n\n
All but the first statement expose us to indeterminate initialization\nordering.
\n\nThe concept we are looking for is called constant initialization in\nthe formal language of the C++ standard. It means that the initializing\nexpression is a constant expression, and if the object is initialized by a\nconstructor call, then the constructor must be specified as\nconstexpr, too:
struct Foo { constexpr Foo(int) {} };\n\nint n = 5; // Fine, 5 is a constant expression.\nFoo x(2); // Fine, 2 is a constant expression and the chosen constructor is constexpr.\nFoo a[] = { Foo(1), Foo(2), Foo(3) }; // Fine\n\nConstant initialization is always allowed. Constant initialization of\nstatic storage duration variables should be marked with constexpr\nor constinit.\nAny non-local static storage\nduration variable that is not so marked should be presumed to have\ndynamic initialization, and reviewed very carefully.
By contrast, the following initializations are problematic:
\n\n// Some declarations used below.\ntime_t time(time_t*); // Not constexpr!\nint f(); // Not constexpr!\nstruct Bar { Bar() {} };\n\n// Problematic initializations.\ntime_t m = time(nullptr); // Initializing expression not a constant expression.\nFoo y(f()); // Ditto\nBar b; // Chosen constructor Bar::Bar() not constexpr.\n\nDynamic initialization of nonlocal variables is discouraged, and in general\nit is forbidden. However, we do permit it if no aspect of the program depends\non the sequencing of this initialization with respect to all other\ninitializations. Under those restrictions, the ordering of the initialization\ndoes not make an observable difference. For example:
\nint p = getpid(); // Allowed, as long as no other static variable\n // uses p in its own initialization.\n\n
Dynamic initialization of static local variables is allowed (and common).
\n\n\n\nconstexpr variable of\n string_view, character array, or character pointer, pointing\n to a string literal. String literals have static storage duration already\n and are usually sufficient.\n See TotW #140.int and const\n char*). For small collections, linear search is entirely sufficient\n (and efficient, due to memory locality); consider using the facilities from\n absl/algorithm/container.h\n for the standard operations. If necessary, keep the collection in sorted\n order and use a binary search algorithm.\n\n If you do really prefer a dynamic container from the standard library, consider using\n a function-local static pointer, as described below\n .std::unique_ptr, std::shared_ptr): smart\n pointers execute cleanup during destruction and are therefore forbidden.\n Consider whether your use case fits into one of the other patterns described\n in this section. One simple solution is to use a plain pointer to a\n dynamically allocated object and never delete it (see last item).constexpr constructor.static const auto& impl = *new T(args...);).thread_local variables that aren't declared inside a function\nmust be initialized with a true compile-time constant,\nand this must be enforced by using the\n\n constinit\nattribute. Prefer\nthread_local over other ways of defining thread-local data.
Variables can be declared with the\nthread_local specifier:
thread_local Foo foo = ...;\n\n
Such a variable is actually a collection of objects, so that when different\nthreads access it, they are actually accessing different objects.\nthread_local variables are much like\nstatic storage duration variables\nin many respects. For instance, they can be declared at namespace scope,\ninside functions, or as static class members, but not as ordinary class\nmembers.
thread_local variable instances are initialized much like\nstatic variables, except that they must be initialized separately for each\nthread, rather than once at program startup. This means that\nthread_local variables declared within a function are safe, but\nother thread_local variables are subject to the same\ninitialization-order issues as static variables (and more besides).
thread_local variables have a subtle destruction-order issue:\nduring thread shutdown, thread_local variables will be destroyed\nin the opposite order of their initialization (as is generally true in C++).\nIf code triggered by the destructor of any thread_local variable\nrefers to any already-destroyed thread_local on that thread, we will\nget a particularly hard to diagnose use-after-free.
thread_local useful for\n concurrent programming.thread_local is the only standard-supported way of creating\n thread-local data.thread_local variable may trigger execution of\n an unpredictable and uncontrollable amount of other code during thread-start or\n first use on a given thread.thread_local variables are effectively global variables,\n and have all the drawbacks of global variables other than lack of\n thread-safety.thread_local variable scales with\n the number of running threads (in the worst case), which can be quite large\n in a program.thread_local unless they are also\n static.thread_local variables\n have complex destructors. In particular, the destructor of any such variable must not\n call any code (transitively) that refers to any potentially-destroyed\n thread_local. This property is hard to enforce.thread_locals. Specifically, skipping destructors for globals and static\n variables is allowable because their lifetimes end at program shutdown. Thus, any \"leak\"\n is managed immediately by the OS cleaning up our memory and other resources. By\n contrast, skipping destructors for thread_local variables leads to resource\n leaks proportional to the total number of threads that terminate during the lifetime of\n the program.thread_local variables at class or namespace scope must be\n initialized with a true compile-time constant (i.e., they must have no\n dynamic initialization). To enforce this, thread_local variables\n at class or namespace scope must be annotated with\n \n constinit\n (or constexpr, but that should be rare):
constinit thread_local Foo foo = ...;\n\n\n
thread_local variables inside a function have no initialization\n concerns, but still risk use-after-free during thread exit. Note that you can use\n a function-scope thread_local to simulate a class- or\n namespace-scope thread_local by defining a function or\n static method that exposes it:
Foo& MyThreadLocalFoo() {\n thread_local Foo result = ComplicatedInitialization();\n return result;\n}\n\n\n Note that thread_local variables will be destroyed whenever a thread exits.\n If the destructor of any such variable refers to any other (potentially-destroyed)\n thread_local we will suffer from hard to diagnose use-after-free bugs.\n Prefer trivial types, or types that provably run no user-provided code at destruction to\n minimize the potential of accessing any other thread_local.\n
thread_local should be preferred over other mechanisms for\ndefining thread-local data.
Classes are the fundamental unit of code in C++. Naturally,\nwe use them extensively. This section lists the main dos and\ndon'ts you should follow when writing a class.
\n\nAvoid virtual method calls in constructors, and avoid\ninitialization that can fail if you can't signal an error.
\n\n\nIt is possible to perform arbitrary initialization in the body\nof the constructor.
\n\n\nconst and may also be easier to use with standard containers\n or algorithms.bool\n IsValid() state checking mechanism (or similar) which is easy\n to forget to call.Constructors should never call virtual functions. If appropriate\nfor your code ,\nterminating the program may be an appropriate error handling\nresponse. Otherwise, consider a factory function\nor Init() method as described in\nTotW #42\n.\nAvoid Init() methods on objects with\nno other states that affect which public methods may be called\n(semi-constructed objects of this form are particularly hard to work\nwith correctly).
Do not define implicit conversions. Use the explicit\nkeyword for conversion operators and single-argument\nconstructors.
Implicit conversions allow an\nobject of one type (called the source type) to\nbe used where a different type (called the destination\ntype) is expected, such as when passing an\nint argument to a function that takes a\ndouble parameter.
In addition to the implicit conversions defined by the language,\nusers can define their own, by adding appropriate members to the\nclass definition of the source or destination type. An implicit\nconversion in the source type is defined by a type conversion operator\nnamed after the destination type (e.g., operator\nbool()). An implicit conversion in the destination\ntype is defined by a constructor that can take the source type as\nits only argument (or only argument with no default value).
The explicit keyword can be applied to a constructor\nor a conversion operator, to ensure that it can only be\nused when the destination type is explicit at the point of use,\ne.g., with a cast. This applies not only to implicit conversions, but to\nlist initialization syntax:
class Foo {\n explicit Foo(int x, double y);\n ...\n};\n\nvoid Func(Foo f);\n\nFunc({42, 3.14}); // Error\n\nThis kind of code isn't technically an implicit conversion, but the\nlanguage treats it as one as far as explicit is concerned.
string_view parameter takes the\n place of separate overloads for std::string and\n const char*.explicit, there's no reliable way to tell whether\n it's intended to define an implicit conversion, or the author\n simply forgot to mark it.Type conversion operators, and constructors that are\ncallable with a single argument, must be marked\nexplicit in the class definition. As an\nexception, copy and move constructors should not be\nexplicit, since they do not perform type\nconversion.
Implicit conversions can sometimes be necessary and appropriate for\ntypes that are designed to be interchangeable, for example when objects\nof two types are just different representations of the same underlying\nvalue. In that case, contact\nyour project leads to request a waiver\nof this rule.\n
\n\nConstructors that cannot be called with a single argument\nmay omit explicit. Constructors that\ntake a single std::initializer_list parameter should\nalso omit explicit, in order to support copy-initialization\n(e.g., MyType m = {1, 2};).
A class's public API must make clear whether the class is copyable,\nmove-only, or neither copyable nor movable. Support copying and/or\nmoving if these operations are clear and meaningful for your type.
\n\n\nA movable type is one that can be initialized and assigned\nfrom temporaries.
\n\nA copyable type is one that can be initialized or assigned from\nany other object of the same type (so is also movable by definition), with the\nstipulation that the value of the source does not change.\nstd::unique_ptr<int> is an example of a movable but not\ncopyable type (since the value of the source\nstd::unique_ptr<int> must be modified during assignment to\nthe destination). int and std::string are examples of\nmovable types that are also copyable. (For int, the move and copy\noperations are the same; for std::string, there exists a move operation\nthat is less expensive than a copy.)
For user-defined types, the copy behavior is defined by the copy\nconstructor and the copy-assignment operator. Move behavior is defined by the\nmove constructor and the move-assignment operator, if they exist, or by the\ncopy constructor and the copy-assignment operator otherwise.
\n\nThe copy/move constructors can be implicitly invoked by the compiler\nin some situations, e.g., when passing objects by value.
\n\n\nObjects of copyable and movable types can be passed and returned by value,\nwhich makes APIs simpler, safer, and more general. Unlike when passing objects\nby pointer or reference, there's no risk of confusion over ownership,\nlifetime, mutability, and similar issues, and no need to specify them in the\ncontract. It also prevents non-local interactions between the client and the\nimplementation, which makes them easier to understand, maintain, and optimize by\nthe compiler. Further, such objects can be used with generic APIs that\nrequire pass-by-value, such as most containers, and they allow for additional\nflexibility in e.g., type composition.
\n\nCopy/move constructors and assignment operators are usually\neasier to define correctly than alternatives\nlike Clone(), CopyFrom() or Swap(),\nbecause they can be generated by the compiler, either implicitly or\nwith = default. They are concise, and ensure\nthat all data members are copied. Copy and move\nconstructors are also generally more efficient, because they don't\nrequire heap allocation or separate initialization and assignment\nsteps, and they're eligible for optimizations such as\n\n\ncopy elision.
Move operations allow the implicit and efficient transfer of\nresources out of rvalue objects. This allows a plainer coding style\nin some cases.
\n\n\nSome types do not need to be copyable, and providing copy\noperations for such types can be confusing, nonsensical, or outright\nincorrect. Types representing singleton objects (Registerer),\nobjects tied to a specific scope (Cleanup), or closely coupled to\nobject identity (Mutex) cannot be copied meaningfully.\nCopy operations for base class types that are to be used\npolymorphically are hazardous, because use of them can lead to\nobject slicing.\nDefaulted or carelessly-implemented copy operations can be incorrect, and the\nresulting bugs can be confusing and difficult to diagnose.
Copy constructors are invoked implicitly, which makes the\ninvocation easy to miss. This may cause confusion for programmers used to\nlanguages where pass-by-reference is conventional or mandatory. It may also\nencourage excessive copying, which can cause performance problems.
\n\n\n\nEvery class's public interface must make clear which copy and move\noperations the class supports. This should usually take the form of explicitly\ndeclaring and/or deleting the appropriate operations in the public\nsection of the declaration.
Specifically, a copyable class should explicitly declare the copy\noperations, a move-only class should explicitly declare the move operations, and\na non-copyable/movable class should explicitly delete the copy operations. A\ncopyable class may also declare move operations in order to support efficient\nmoves. Explicitly declaring or deleting all four copy/move operations is\npermitted, but not required. If you provide a copy or move assignment operator,\nyou must also provide the corresponding constructor.
\n\nclass Copyable {\n public:\n Copyable(const Copyable& other) = default;\n Copyable& operator=(const Copyable& other) = default;\n\n // The implicit move operations are suppressed by the declarations above.\n // You may explicitly declare move operations to support efficient moves.\n};\n\nclass MoveOnly {\n public:\n MoveOnly(MoveOnly&& other) = default;\n MoveOnly& operator=(MoveOnly&& other) = default;\n\n // The copy operations are implicitly deleted, but you can\n // spell that out explicitly if you want:\n MoveOnly(const MoveOnly&) = delete;\n MoveOnly& operator=(const MoveOnly&) = delete;\n};\n\nclass NotCopyableOrMovable {\n public:\n // Not copyable or movable\n NotCopyableOrMovable(const NotCopyableOrMovable&) = delete;\n NotCopyableOrMovable& operator=(const NotCopyableOrMovable&)\n = delete;\n\n // The move operations are implicitly disabled, but you can\n // spell that out explicitly if you want:\n NotCopyableOrMovable(NotCopyableOrMovable&&) = delete;\n NotCopyableOrMovable& operator=(NotCopyableOrMovable&&)\n = delete;\n};\n\n\nThese declarations/deletions can be omitted only if they are obvious:
\nprivate section, like a\n struct or an interface-only base class,\n then the copyability/movability can be determined by the\n copyability/movability of any public data members.\nA type should not be copyable/movable if the meaning of\ncopying/moving is unclear to a casual user, or if it incurs unexpected\ncosts. Move operations for copyable types are strictly a performance\noptimization and are a potential source of bugs and complexity, so\navoid defining them unless they are significantly more efficient than\nthe corresponding copy operations. If your type provides copy operations, it is\nrecommended that you design your class so that the default implementation of\nthose operations is correct. Remember to review the correctness of any\ndefaulted operations as you would any other code.
\n\nTo eliminate the risk of slicing, prefer to make base classes abstract,\nby making their constructors protected, by declaring their destructors protected,\nor by giving them one or more pure virtual member functions. Prefer to avoid\nderiving from concrete classes.
\n\nUse a struct only for passive objects that\n carry data; everything else is a class.
The struct and class\nkeywords behave almost identically in C++. We add our own\nsemantic meanings to each keyword, so you should use the\nappropriate keyword for the data-type you're\ndefining.
structs should be used for passive objects that carry\ndata, and may have associated constants. All fields must be public. The\nstruct type itself must not have invariants that imply relationships between\ndifferent fields, since direct user access to those fields may\nbreak those invariants, but users of a struct may have requirements and\nguarantees on particular uses of it. Constructors, destructors, and helper\nmethods may be present; however, these methods must not require or enforce\nany invariants.
If more functionality or invariants are required, or struct has wide visibility and expected to\nevolve, then a class is more appropriate. If in doubt, make it a class.\n
For consistency with STL, you can use\nstruct instead of class for\nstateless types, such as traits,\ntemplate metafunctions,\nand some functors.
Note that member variables in structs and classes have\ndifferent naming rules.
\n\nPrefer to use a struct instead of a pair or a\ntuple whenever the elements can have meaningful names.
\n While using pairs and tuples can avoid the need to define a custom type,\n potentially saving work when writing code, a meaningful field\n name will almost always be much clearer when reading code than\n .first, .second, or std::get<X>.\n While C++14's introduction of std::get<Type> to access a\n tuple element by type rather than index (when the type is unique) can\n sometimes partially mitigate this, a field name is usually substantially\n clearer and more informative than a type.\n
\n Pairs and tuples may be appropriate in generic code where there are not\n specific meanings for the elements of the pair or tuple. Their use may\n also be required in order to interoperate with existing code or APIs.\n
\n\n\nComposition is often more appropriate than inheritance.\nWhen using inheritance, make it public.
When a sub-class\ninherits from a base class, it includes the definitions\nof all the data and operations that the base class\ndefines. \"Interface inheritance\" is inheritance from a\npure abstract base class (one with no state or defined\nmethods); all other inheritance is \"implementation\ninheritance\".
\n\n\nImplementation inheritance reduces code size by re-using\nthe base class code as it specializes an existing type.\nBecause inheritance is a compile-time declaration, you\nand the compiler can understand the operation and detect\nerrors. Interface inheritance can be used to\nprogrammatically enforce that a class expose a particular\nAPI. Again, the compiler can detect errors, in this case,\nwhen a class does not define a necessary method of the\nAPI.
\n\n\nFor implementation inheritance, because the code\nimplementing a sub-class is spread between the base and\nthe sub-class, it can be more difficult to understand an\nimplementation. The sub-class cannot override functions\nthat are not virtual, so the sub-class cannot change\nimplementation.
\n\nMultiple inheritance is especially problematic, because\nit often imposes a higher performance overhead (in fact,\nthe performance drop from single inheritance to multiple\ninheritance can often be greater than the performance\ndrop from ordinary to virtual dispatch), and because\nit risks leading to \"diamond\" inheritance patterns,\nwhich are prone to ambiguity, confusion, and outright bugs.
\n\n\n\nAll inheritance should be public. If you\nwant to do private inheritance, you should be including\nan instance of the base class as a member instead. You may use\nfinal on classes when you don't intend to support using\nthem as base classes.
Do not overuse implementation inheritance. Composition\nis often more appropriate. Try to restrict use of\ninheritance to the \"is-a\" case: Bar\nsubclasses Foo if it can reasonably be said\nthat Bar \"is a kind of\"\nFoo.
Limit the use of protected to those\nmember functions that might need to be accessed from\nsubclasses. Note that data\nmembers should be private.
Explicitly annotate overrides of virtual functions or virtual\ndestructors with exactly one of an override or (less\nfrequently) final specifier. Do not\nuse virtual when declaring an override.\nRationale: A function or destructor marked\noverride or final that is\nnot an override of a base class virtual function will\nnot compile, and this helps catch common errors. The\nspecifiers serve as documentation; if no specifier is\npresent, the reader has to check all ancestors of the\nclass in question to determine if the function or\ndestructor is virtual or not.
Multiple inheritance is permitted, but multiple implementation\ninheritance is strongly discouraged.
\n\nOverload operators judiciously. Do not use user-defined literals.
\n\n\nC++ permits user code to\ndeclare\noverloaded versions of the built-in operators using the\noperator keyword, so long as one of the parameters\nis a user-defined type. The operator keyword also\npermits user code to define new kinds of literals using\noperator\"\", and to define type-conversion functions\nsuch as operator bool().
Operator overloading can make code more concise and\nintuitive by enabling user-defined types to behave the same\nas built-in types. Overloaded operators are the idiomatic names\nfor certain operations (e.g., ==, <,\n=, and <<), and adhering to\nthose conventions can make user-defined types more readable\nand enable them to interoperate with libraries that expect\nthose names.
User-defined literals are a very concise notation for\ncreating objects of user-defined types.
\n\n\nfoo < bar\n may do one thing, while &foo < &bar\n does something totally different.& can cause the same\n code to have different meanings depending on whether\n the overload declaration is visible. Overloads of\n &&, ||, and ,\n (comma) cannot match the evaluation-order semantics of the\n built-in operators.\"Hello World\"sv as a\n shorthand for std::string_view(\"Hello World\").\n Existing notations are clearer, though less terse.Define overloaded operators only if their meaning is\nobvious, unsurprising, and consistent with the corresponding\nbuilt-in operators. For example, use | as a\nbitwise- or logical-or, not as a shell-style pipe.
Define operators only on your own types. More precisely,\ndefine them in the same headers, .cc files, and namespaces\nas the types they operate on. That way, the operators are available\nwherever the type is, minimizing the risk of multiple\ndefinitions. If possible, avoid defining operators as templates,\nbecause they must satisfy this rule for any possible template\narguments. If you define an operator, also define\nany related operators that make sense, and make sure they\nare defined consistently.
Prefer to define non-modifying binary operators as\nnon-member functions. If a binary operator is defined as a\nclass member, implicit conversions will apply to the\nright-hand argument, but not the left-hand one. It will\nconfuse your users if a + b compiles but\nb + a doesn't.
For a type T whose values can be compared for\nequality, define a non-member operator== and document when\ntwo values of type T are considered equal.\nIf there is a single obvious notion of when a value t1\nof type T is less than another such value t2 then\nyou may also define operator<=>, which should be\nconsistent with operator==.\nPrefer not to overload the other comparison and ordering operators.
Don't go out of your way to avoid defining operator\noverloads. For example, prefer to define ==,\n=, and <<, rather than\nEquals(), CopyFrom(), and\nPrintTo(). Conversely, don't define\noperator overloads just because other libraries expect\nthem. For example, if your type doesn't have a natural\nordering, but you want to store it in a std::set,\nuse a custom comparator rather than overloading\n<.
Do not overload &&, ||,\n, (comma), or unary &. Do not overload\noperator\"\", i.e., do not introduce user-defined\nliterals. Do not use any such literals provided by others\n(including the standard library).
Type conversion operators are covered in the section on\nimplicit conversions.\nThe = operator is covered in the section on\ncopy constructors. Overloading\n<< for use with streams is covered in the\nsection on streams. See also the rules on\nfunction overloading, which\napply to operator overloading as well.
Make classes' data members private, unless they are\nconstants. This simplifies reasoning about invariants, at the cost\nof some easy boilerplate in the form of accessors (usually const) if necessary.
For technical\nreasons, we allow data members of a test fixture class defined in a .cc file to\nbe protected when using\n\n\nGoogle\nTest.\nIf a test fixture class is defined outside of the .cc file it is used in, for example\nin a .h file, make data members private.
Group similar declarations together, placing public parts\nearlier.
A class definition should usually start with a\npublic: section, followed by\nprotected:, then private:. Omit\nsections that would be empty.
Within each section, prefer grouping similar\nkinds of declarations together, and prefer the\nfollowing order:
\n\ntypedef, using,\n enum, nested structs and classes, and friend types)static data membersstatic and non-static member\n functions, and friend functions)\n Do not put large method definitions inline in the\nclass definition. Usually, only trivial or\nperformance-critical, and very short, methods may be\ndefined inline. See Defining\nFunctions in Header Files for more details.
\n\nThe output of a C++ function is naturally provided via\na return value and sometimes via output parameters (or in/out parameters).
\n\nPrefer using return values over output parameters:\nthey improve readability, and often provide the same or better performance.\nSee\nTotW #176.
\n\nPrefer to return by value or, failing that, return by reference.\nAvoid returning a raw pointer unless it can be null.
\n\nParameters are either inputs to the function, outputs from the\nfunction, or both. Non-optional input parameters should usually be values\nor const references, while non-optional output and\ninput/output parameters should usually be references (which cannot be null).\nGenerally, use std::optional to represent optional by-value\ninputs, and use a const pointer when the non-optional form would\nhave used a reference. Use non-const pointers to represent\noptional outputs and optional input/output parameters.
\nAvoid defining functions that require a reference parameter to outlive the call.\nIn some cases reference parameters can bind to temporaries, leading to lifetime\nbugs. Instead, find a way to eliminate the lifetime requirement\n(for example, by copying the parameter), or pass retained parameters by\npointer and document the lifetime and non-null requirements.\nSee TotW 116 for more.
\n\nWhen ordering function parameters, put all input-only\nparameters before any output parameters. In particular,\ndo not add new parameters to the end of the function just\nbecause they are new; place new input-only parameters before\nthe output parameters. This is not a hard-and-fast rule. Parameters that\nare both input and output muddy the waters, and, as always,\nconsistency with related functions may require you to bend the rule.\nVariadic functions may also require unusual parameter ordering.
\n\nPrefer small and focused functions.
\n\nWe recognize that long functions are sometimes\nappropriate, so no hard limit is placed on functions\nlength. If a function exceeds about 40 lines, think about\nwhether it can be broken up without harming the structure\nof the program.
\n\nEven if your long function works perfectly now,\nsomeone modifying it in a few months may add new\nbehavior. This could result in bugs that are hard to\nfind. Keeping your functions short and simple makes it\neasier for other people to read and modify your code.\nSmall functions are also easier to test.
\n\nYou could find long and complicated functions when\nworking with\nsome code. Do not be\nintimidated by modifying existing code: if working with\nsuch a function proves to be difficult, you find that\nerrors are hard to debug, or you want to use a piece of\nit in several different contexts, consider breaking up\nthe function into smaller and more manageable pieces.
\n\nUse overloaded functions (including constructors) only if a\nreader looking at a call site can get a good idea of what\nis happening without having to first figure out exactly\nwhich overload is being called.
\n\n\nYou may write a function that takes a const\nstd::string& and overload it with another that\ntakes const char*. However, in this case consider\nstd::string_view\n\ninstead.
class MyClass {\n public:\n void Analyze(const std::string& text);\n void Analyze(const char* text, size_t textlen);\n};\n\n\n\nOverloading can make code more intuitive by allowing an\nidentically-named function to take different arguments.\nIt may be necessary for templatized code, and it can be\nconvenient for Visitors.
\nOverloading based on const or ref qualification\nmay make utility code more usable, more efficient, or both.\nSee TotW #148 for more.
If a function is overloaded by the argument types alone,\na reader may have to understand C++'s complex matching\nrules in order to tell what's going on. Also many people\nare confused by the semantics of inheritance if a derived\nclass overrides only some of the variants of a\nfunction.
\n\n\nYou may overload a function when there are no semantic differences\nbetween variants. These overloads may vary in types, qualifiers, or\nargument count. However, a reader of such a call must not need to know\nwhich member of the overload set is chosen, only that something\nfrom the set is being called.
\n\nTo reflect this unified design, prefer a single, comprehensive \"umbrella\"\ncomment that documents the entire overload set and is placed before the first\ndeclaration.
\n\nWhere a reader might have difficulty connecting the umbrella\ncomment to a specific overload, it's okay to have a comment for specific overloads.
\n\nDefault arguments are allowed on non-virtual functions\nwhen the default is guaranteed to always have the same\nvalue. Follow the same restrictions as for function overloading, and\nprefer overloaded functions if the readability gained with\ndefault arguments doesn't outweigh the downsides below.
\n\n\nOften you have a function that uses default values, but\noccasionally you want to override the defaults. Default\nparameters allow an easy way to do this without having to\ndefine many functions for the rare exceptions. Compared\nto overloading the function, default arguments have a\ncleaner syntax, with less boilerplate and a clearer\ndistinction between 'required' and 'optional'\narguments.
\n\n\nDefaulted arguments are another way to achieve the\nsemantics of overloaded functions, so all the reasons not to overload\nfunctions apply.
\n\nThe defaults for arguments in a virtual function call are\ndetermined by the static type of the target object, and\nthere's no guarantee that all overrides of a given function\ndeclare the same defaults.
\n\nDefault parameters are re-evaluated at each call site,\nwhich can bloat the generated code. Readers may also expect\nthe default's value to be fixed at the declaration instead\nof varying at each call.
\n\nFunction pointers are confusing in the presence of\ndefault arguments, since the function signature often\ndoesn't match the call signature. Adding\nfunction overloads avoids these problems.
\n\n\nDefault arguments are banned on virtual functions, where\nthey don't work properly, and in cases where the specified\ndefault might not evaluate to the same value depending on\nwhen it was evaluated. (For example, don't write void\nf(int n = counter++);.)
In some other cases, default arguments can improve the\nreadability of their function declarations enough to\novercome the downsides above, so they are allowed. When in\ndoubt, use overloads.
\n\nUse trailing return types only where using the ordinary syntax (leading\n return types) is impractical or much less readable.
\n\n\nC++ allows two different forms of function declarations. In the older\n form, the return type appears before the function name. For example:
\nint Foo(int x);\n\n
The newer form uses the auto\n keyword before the function name and a trailing return type after\n the argument list. For example, the declaration above could\n equivalently be written:
auto Foo(int x) -> int;\n\n
The trailing return type is in the function's scope. This doesn't\n make a difference for a simple case like int but it matters\n for more complicated cases, like types declared in class scope or\n types written in terms of the function parameters.
Trailing return types are the only way to explicitly specify the\n return type of a lambda expression.\n In some cases the compiler is able to deduce a lambda's return type,\n but not in all cases. Even when the compiler can deduce it automatically,\n sometimes specifying it explicitly would be clearer for readers.\n
\nSometimes it's easier and more readable to specify a return type\n after the function's parameter list has already appeared. This is\n particularly true when the return type depends on template parameters.\n For example:
\ntemplate <typename T, typename U>\n auto Add(T t, U u) -> decltype(t + u);\n\n versus\n
template <typename T, typename U>\n decltype(declval<T&>() + declval<U&>()) Add(T t, U u);\n\n\n\n
Trailing return type syntax has no analogue in C++-like languages\n such as C and Java, so some readers may find it unfamiliar.
\nExisting codebases have an enormous number of function\n declarations that aren't going to get changed to use the new syntax,\n so the realistic choices are using the old syntax only or using a mixture\n of the two. Using a single version is better for uniformity of style.
\n\n\nIn most cases, continue to use the older style of function\n declaration where the return type goes before the function name.\n Use the new trailing-return-type form only in cases where it's\n required (such as lambdas) or where, by putting the type after the\n function's parameter list, it allows you to write the type in a much\n more readable way. The latter case should be rare; it's mostly an\n issue in fairly complicated template code, which is\n discouraged in most cases.
\n\n\nThere are various tricks and utilities that\nwe use to make C++ code more robust, and various ways we use\nC++ that may differ from what you see elsewhere.
\nPrefer to have single, fixed owners for dynamically\nallocated objects. Prefer to transfer ownership with smart\npointers.
\n\n\n\"Ownership\" is a bookkeeping technique for managing\ndynamically allocated memory (and other resources). The\nowner of a dynamically allocated object is an object or\nfunction that is responsible for ensuring that it is\ndeleted when no longer needed. Ownership can sometimes be\nshared, in which case the last owner is typically\nresponsible for deleting it. Even when ownership is not\nshared, it can be transferred from one piece of code to\nanother.
\n\n\"Smart\" pointers are classes that act like pointers,\ne.g., by overloading the * and\n-> operators. Some smart pointer types\ncan be used to automate ownership bookkeeping, to ensure\nthese responsibilities are met.\n\nstd::unique_ptr is a smart pointer type\nwhich expresses exclusive ownership\nof a dynamically allocated object; the object is deleted\nwhen the std::unique_ptr goes out of scope.\nIt cannot be copied, but can be moved to\nrepresent ownership transfer.\n\nstd::shared_ptr is a smart pointer type\nthat expresses shared ownership of\na dynamically allocated object. std::shared_ptrs\ncan be copied; ownership of the object is shared among\nall copies, and the object is deleted when the last\nstd::shared_ptr is destroyed.
const objects, shared ownership can be a simple\n and efficient alternative to deep copying.std::unique_ptr expresses ownership\n transfer using move semantics, which can be complex and\n may confuse some programmers.If dynamic allocation is necessary, prefer to keep\nownership with the code that allocated it. If other code\nneeds access to the object, consider passing it a copy,\nor passing a pointer or reference without transferring\nownership. Prefer to use std::unique_ptr to\nmake ownership transfer explicit. For example:
std::unique_ptr<Foo> FooFactory();\nvoid FooConsumer(std::unique_ptr<Foo> ptr);\n\n\n\n\n
Do not design your code to use shared ownership\nwithout a very good reason. One such reason is to avoid\nexpensive copy operations, but you should only do this if\nthe performance benefits are significant, and the\nunderlying object is immutable (i.e.,\nstd::shared_ptr<const Foo>). If you\ndo use shared ownership, prefer to use\nstd::shared_ptr.
Never use std::auto_ptr. Instead, use\nstd::unique_ptr.
Use cpplint.py to detect style errors.
cpplint.py\nis a tool that reads a source file and identifies many\nstyle errors. It is not perfect, and has both false\npositives and false negatives, but it is still a valuable\ntool.
Some projects have instructions on\nhow to run cpplint.py from their project\ntools. If the project you are contributing to does not,\nyou can download\n\ncpplint.py separately.
Use rvalue references only in certain special cases listed below.
\n\n\n Rvalue references\nare a type of reference that can only bind to temporary\nobjects. The syntax is similar to traditional reference\nsyntax. For example, void f(std::string&&\ns); declares a function whose argument is an\nrvalue reference to a std::string.
When the token '&&' is applied to\nan unqualified template argument in a function\nparameter, special template argument deduction\nrules apply. Such a reference is called a forwarding reference.
\n\n\nv1 is a std::vector<std::string>,\n for example, then auto v2(std::move(v1))\n will probably just result in some simple pointer\n manipulation instead of copying a large amount of data.\n In many cases this can result in a major performance\n improvement.std::move is necessary to make\n effective use of some standard-library types, such as\n std::unique_ptr.Do not use rvalue references (or apply the &&\nqualifier to methods), except as follows:
&&-qualified methods that\n logically \"consume\" *this, leaving it in an unusable\n or empty state. Note that this applies only to method qualifiers (which come\n after the closing parenthesis of the function signature); if you want to\n \"consume\" an ordinary function parameter, prefer to pass it by value.\n std::forward,\n to support perfect forwarding.Foo&& and the other taking const Foo&.\n Usually the preferred solution is just to pass by value, but an overloaded\n pair of functions sometimes yields better performance, for example if the\n functions sometimes don't consume the input. As always: if you're writing\n more complicated code for the sake of performance, make sure you have evidence\n that it actually helps.We allow use of friend classes and functions,\nwithin reason.
Friends should usually be defined in the same file so\nthat the reader does not have to look in another file to\nfind uses of the private members of a class. A common use\nof friend is to have a\nFooBuilder class be a friend of\nFoo so that it can construct the inner state\nof Foo correctly, without exposing this\nstate to the world. In some cases it may be useful to\nmake a unit test class a friend of the class it tests.
Friends extend, but do not break, the encapsulation\nboundary of a class. In some cases this is better than\nmaking a member public when you want to give only one\nother class access to it. However, most classes should\ninteract with other classes solely through their public\nmembers.
We do not use C++ exceptions.
\n\n\nInit() method, but these require heap\n allocation or a new \"invalid\" state, respectively.throw statement to an\n existing function, you must examine all of its\n transitive callers. Either they must make at least the\n basic exception safety guarantee, or they must never\n catch the exception and be happy with the program\n terminating as a result. For instance, if\n f() calls g() calls\n h(), and h throws an\n exception that f catches, g\n has to be careful or it may not clean up properly.On their face, the benefits of using exceptions\noutweigh the costs, especially in new projects. However,\nfor existing code, the introduction of exceptions has\nimplications on all dependent code. If exceptions can be\npropagated beyond a new project, it also becomes\nproblematic to integrate the new project into existing\nexception-free code. Because most existing C++ code at\nGoogle is not prepared to deal with exceptions, it is\ncomparatively difficult to adopt new code that generates\nexceptions.
\n\nGiven that Google's existing code is not\nexception-tolerant, the costs of using exceptions are\nsomewhat greater than the costs in a new project. The\nconversion process would be slow and error-prone. We\ndon't believe that the available alternatives to\nexceptions, such as error codes and assertions, introduce\na significant burden.
\n\nOur advice against using exceptions is not predicated\non philosophical or moral grounds, but practical ones.\n Because we'd like to use our open-source\nprojects at Google and it's difficult to do so if those\nprojects use exceptions, we need to advise against\nexceptions in Google open-source projects as well.\nThings would probably be different if we had to do it all\nover again from scratch.
\n\nThis prohibition also applies to exception handling related\nfeatures such as std::exception_ptr and\nstd::nested_exception.
There is an exception to\nthis rule (no pun intended) for Windows code.
\n\nnoexceptSpecify noexcept when it is useful and correct.
The noexcept specifier is used to specify whether\na function will throw exceptions or not. If an exception\nescapes from a function marked noexcept, the program\ncrashes via std::terminate.
The noexcept operator performs a compile-time\ncheck that returns true if an expression is declared to not\nthrow any exceptions.
noexcept\n improves performance in some cases, e.g.,\n std::vector<T>::resize() moves rather than\n copies the objects if T's move constructor is\n noexcept.noexcept on a function can\n trigger compiler optimizations in environments where\n exceptions are enabled, e.g., compiler does not have to\n generate extra code for stack-unwinding, if it knows\n that no exceptions can be thrown due to a\n noexcept specifier.noexcept\n specifiers are correct, and hard to define what\n correctness even means.noexcept\n because it eliminates a guarantee that callers may be relying\n on, in ways that are hard to detect.You may use noexcept when it is useful for\nperformance if it accurately reflects the intended semantics\nof your function, i.e., that if an exception is somehow thrown\nfrom within the function body then it represents a fatal error.\nYou can assume that noexcept on move constructors\nhas a meaningful performance benefit. If you think\nthere is significant performance benefit from specifying\nnoexcept on some other function, please discuss it\nwith\nyour project leads.
Prefer unconditional noexcept if exceptions are\ncompletely disabled (i.e., most Google C++ environments).\nOtherwise, use conditional noexcept specifiers\nwith simple conditions, in ways that evaluate false only in\nthe few cases where the function could potentially throw.\nThe tests might include type traits check on whether the\ninvolved operation might throw (e.g.,\nstd::is_nothrow_move_constructible for\nmove-constructing objects), or on whether allocation can throw\n(e.g., absl::default_allocator_is_nothrow for\nstandard default allocation). Note in many cases the only\npossible cause for an exception is allocation failure (we\nbelieve move constructors should not throw except due to\nallocation failure), and there are many applications where it's\nappropriate to treat memory exhaustion as a fatal error rather\nthan an exceptional condition that your program should attempt\nto recover from. Even for other\npotential failures you should prioritize interface simplicity\nover supporting all possible exception throwing scenarios:\ninstead of writing a complicated noexcept clause\nthat depends on whether a hash function can throw, for example,\nsimply document that your component doesn't support hash\nfunctions throwing and make it unconditionally\nnoexcept.
Avoid using run-time type information (RTTI).
\n\n\n RTTI allows a\nprogrammer to query the C++ class of an object at\nrun-time. This is done by use of typeid or\ndynamic_cast.
The standard alternatives to RTTI (described below)\nrequire modification or redesign of the class hierarchy\nin question. Sometimes such modifications are infeasible\nor undesirable, particularly in widely-used or mature\ncode.
\n\nRTTI can be useful in some unit tests. For example, it\nis useful in tests of factory classes where the test has\nto verify that a newly created object has the expected\ndynamic type. It is also useful in managing the\nrelationship between objects and their mocks.
\n\nRTTI is useful when considering multiple abstract\nobjects. Consider
\n\nbool Base::Equal(Base* other) = 0;\nbool Derived::Equal(Base* other) {\n Derived* that = dynamic_cast<Derived*>(other);\n if (that == nullptr)\n return false;\n ...\n}\n\n\n\nQuerying the type of an object at run-time frequently\nmeans a design problem. Needing to know the type of an\nobject at runtime is often an indication that the design\nof your class hierarchy is flawed.
\n\nUndisciplined use of RTTI makes code hard to maintain.\nIt can lead to type-based decision trees or switch\nstatements scattered throughout the code, all of which\nmust be examined when making further changes.
\n\n\nRTTI has legitimate uses but is prone to abuse, so you\nmust be careful when using it. You may use it freely in\nunit tests, but avoid it when possible in other code. In\nparticular, think twice before using RTTI in new code. If\nyou find yourself needing to write code that behaves\ndifferently based on the class of an object, consider one\nof the following alternatives to querying the type:
\n\nWhen the logic of a program guarantees that a given\ninstance of a base class is in fact an instance of a\nparticular derived class, then a\ndynamic_cast may be used freely on the\nobject. Usually one\ncan use a static_cast as an alternative in\nsuch situations.
Decision trees based on type are a strong indication\nthat your code is on the wrong track.
\n\nif (typeid(*data) == typeid(D1)) {\n ...\n} else if (typeid(*data) == typeid(D2)) {\n ...\n} else if (typeid(*data) == typeid(D3)) {\n...\n\n\nCode such as this usually breaks when additional\nsubclasses are added to the class hierarchy. Moreover,\nwhen properties of a subclass change, it is difficult to\nfind and modify all the affected code segments.
\n\nDo not hand-implement an RTTI-like workaround. The\narguments against RTTI apply just as much to workarounds\nlike class hierarchies with type tags. Moreover,\nworkarounds disguise your true intent.
\n\nUse C++-style casts\nlike static_cast<float>(double_value), or brace\ninitialization for conversion of arithmetic types like\nint64_t y = int64_t{1} << 42. Do not use\ncast formats like (int)x unless the cast is to\nvoid. You may use cast formats like T(x) only when\nT is a class type.
C++ introduced a\ndifferent cast system from C that distinguishes the types\nof cast operations.
\n\n\nThe problem with C casts is the ambiguity of the operation;\nsometimes you are doing a conversion\n(e.g., (int)3.5) and sometimes you are doing\na cast (e.g., (int)\"hello\"). Brace\ninitialization and C++ casts can often help avoid this\nambiguity. Additionally, C++ casts are more visible when searching for\nthem.
The C++-style cast syntax is verbose and cumbersome.
\n\n\nIn general, do not use C-style casts. Instead, use these C++-style\ncasts when explicit type conversion is necessary.\n
\n\nint64_t{x}). This is the safest approach because code\n will not compile if conversion can result in information loss. The\n syntax is also concise.std::string(some_cord) to\n static_cast<std::string>(some_cord).absl::implicit_cast\n to safely cast up a type hierarchy,\n e.g., casting a Foo* to a\n SuperclassOfFoo* or casting a\n Foo* to a const Foo*. C++\n usually does this automatically but some situations\n need an explicit up-cast, such as use of the\n ?: operator.static_cast as the equivalent of a C-style cast\n that does value conversion, when you need to\n explicitly up-cast a pointer from a class to its superclass, or when\n you need to explicitly cast a pointer from a superclass to a\n subclass. In this last case, you must be sure your object is\n actually an instance of the subclass.const_cast to remove the\n const qualifier (see const).reinterpret_cast to do unsafe conversions of\n pointer types to and from integer and other pointer\n types,\n including void*. Use this\n only if you know what you are doing and you understand the aliasing\n issues. Also, consider dereferencing the pointer (without a cast) and\n using std::bit_cast to cast the resulting value.std::bit_cast to interpret the raw bits of a\n value using a different type of the same size (a type pun), such as\n interpreting the bits of a double as\n int64_t.See the \nRTTI section for guidance on the use of\ndynamic_cast.
Use streams where appropriate, and stick to \"simple\"\nusages. Overload << for streaming only for types\nrepresenting values, and write only the user-visible value, not any\nimplementation details.
Streams are the standard I/O abstraction in C++, as\nexemplified by the standard header <iostream>.\nThey are widely used in Google code, mostly for debug logging\nand test diagnostics.
The << and >>\nstream operators provide an API for formatted I/O that\nis easily learned, portable, reusable, and extensible.\nprintf, by contrast, doesn't even support\nstd::string, to say nothing of user-defined types,\nand is very difficult to use portably.\nprintf also obliges you to choose among the\nnumerous slightly different versions of that function,\nand navigate the dozens of conversion specifiers.
Streams provide first-class support for console I/O\nvia std::cin, std::cout,\nstd::cerr, and std::clog.\nThe C APIs do as well, but are hampered by the need to\nmanually buffer the input.
<< operators interferes with\ninternationalization, because it bakes word order into the\ncode, and streams' support for localization is \nflawed.<< is\nextremely costly for the compiler. When used pervasively in a\nlarge codebase, it can consume as much as 20% of the parsing\nand semantic analysis time.Use streams only when they are the best tool for the job.\nThis is typically the case when the I/O is ad-hoc, local,\nhuman-readable, and targeted at other developers rather than\nend-users. Be consistent with the code around you, and with the\ncodebase as a whole; if there's an established tool for\nyour problem, use that tool instead.\nIn particular,\n\nlogging libraries are usually a better\nchoice than std::cerr or std::clog\nfor diagnostic output, and the libraries in\n\nabsl/strings\nor the equivalent are usually a\nbetter choice than std::stringstream.
Avoid using streams for I/O that faces external users or\nhandles untrusted data. Instead, find and use the appropriate\ntemplating libraries to handle issues like internationalization,\nlocalization, and security hardening.
\n\nIf you do use streams, avoid the stateful parts of the\nstreams API (other than error state), such as imbue(),\nxalloc(), and register_callback().\nUse explicit formatting functions (such as\nabsl::StreamFormat()) rather than\nstream manipulators or formatting flags to control formatting\ndetails such as number base, precision, or padding.
Overload << as a streaming operator\nfor your type only if your type represents a value, and\n<< writes out a human-readable string\nrepresentation of that value. Avoid exposing implementation\ndetails in the output of <<; if you need to print\nobject internals for debugging, use named functions instead\n(a method named DebugString() is the most common\nconvention).
Use the prefix form (++i) of the increment\nand decrement operators unless you need postfix semantics.
When a variable\nis incremented (++i or i++) or\ndecremented (--i or i--) and\nthe value of the expression is not used, one must decide\nwhether to preincrement (decrement) or postincrement\n(decrement).
A postfix increment/decrement expression evaluates to the value\nas it was before it was modified. This can result in code that is more\ncompact but harder to read. The prefix form is generally more readable, is\nnever less efficient, and can be more efficient because it doesn't need to\nmake a copy of the value as it was before the operation.\n
\n\n\nThe tradition developed, in C, of using post-increment, even\nwhen the expression value is not used, especially in\nfor loops.
Use prefix increment/decrement, unless the code explicitly\nneeds the result of the postfix increment/decrement expression.
\n\nIn APIs, use const whenever it makes sense.\nconstexpr is a better choice for some uses of\nconst.
Declared variables and parameters can be preceded\nby the keyword const to indicate the variables\nare not changed (e.g., const int foo). Class\nfunctions can have the const qualifier to\nindicate the function does not change the state of the\nclass member variables (e.g., class Foo { int\nBar(char c) const; };).
Easier for people to understand how variables are being\nused. Allows the compiler to do better type checking,\nand, conceivably, generate better code. Helps people\nconvince themselves of program correctness because they\nknow the functions they call are limited in how they can\nmodify your variables. Helps people know what functions\nare safe to use without locks in multi-threaded\nprograms.
\n\n\nconst is viral: if you pass a\nconst variable to a function, that function\nmust have const in its prototype (or the\nvariable will need a const_cast). This can\nbe a particular problem when calling library\nfunctions.
We strongly recommend using const\nin APIs (i.e., on function parameters, methods, and\nnon-local variables) wherever it is meaningful and accurate. This\nprovides consistent, mostly compiler-verified documentation\nof what objects an operation can mutate. Having\na consistent and reliable way to distinguish reads from writes\nis critical to writing thread-safe code, and is useful in\nmany other contexts as well. In particular:
const T&) or\n pointer-to-const (const T*), respectively.const has\n no effect on the caller, thus is not recommended in function\n declarations. See TotW #109.const unless they\n alter the logical state of the object (or enable the user to modify\n that state, e.g., by returning a non-const reference, but that's\n rare), or they can't safely be invoked concurrently.Using const on local variables is neither encouraged\nnor discouraged.
All of a class's const operations should be safe\nto invoke concurrently with each other. If that's not feasible, the class must\nbe clearly documented as \"thread-unsafe\".
Some people favor the form int const* foo\nto const int* foo. They argue that this is\nmore readable because it's more consistent: it keeps the\nrule that const always follows the object\nit's describing. However, this consistency argument\ndoesn't apply in codebases with few deeply-nested pointer\nexpressions since most const expressions\nhave only one const, and it applies to the\nunderlying value. In such cases, there's no consistency\nto maintain. Putting the const first is\narguably more readable, since it follows English in\nputting the \"adjective\" (const) before the\n\"noun\" (int).
That said, while we encourage putting\nconst first, we do not require it. But be\nconsistent with the code around you!
Use constexpr to define true\nconstants or to ensure constant initialization.\nUse constinit to ensure constant\ninitialization for non-constant variables.\n
Some variables can be declared constexpr\nto indicate the variables are true constants, i.e., fixed at\ncompilation/link time. Some functions and constructors\ncan be declared constexpr which enables them\nto be used in defining a constexpr\nvariable. Functions can be declared consteval\nto restrict their use to compile time.
Use of constexpr enables definition of\nconstants with floating-point expressions rather than\njust literals; definition of constants of user-defined\ntypes; and definition of constants with function\ncalls.
Prematurely marking something as constexpr may cause\nmigration problems if later on it has to be downgraded.\nCurrent restrictions on what is allowed in constexpr\nfunctions and constructors may invite obscure workarounds\nin these definitions.
constexpr definitions enable a more\nrobust specification of the constant parts of an\ninterface. Use constexpr to specify true\nconstants and the functions that support their\ndefinitions. consteval may be used for\ncode that must not be invoked at runtime.\nAvoid complexifying function definitions to\nenable their use with constexpr. Do not use\nconstexpr or consteval to force inlining.
Of the built-in C++ integer types, the only one used\n is\nint. If a program needs an integer type of a\ndifferent size, use an exact-width integer type from\n<stdint.h>, such as\nint16_t. If you have a\nvalue that could ever be greater than or equal to 2^31,\nuse a 64-bit type such as int64_t.\nKeep in mind that even if your value won't ever be too large\nfor an int, it may be used in intermediate\ncalculations which may require a larger type. When in doubt,\nchoose a larger type.
C++ does not specify exact sizes for the integer types\nlike int. Common sizes on contemporary architectures are\n16 bits for short, 32 bits for int, 32 or 64\nbits for long, and 64 bits for long long,\nbut different platforms make different choices, in particular\nfor long.
Uniformity of declaration.
\n\n\nThe sizes of integral types in C++ can vary based on\ncompiler and architecture.
\n\n\n\n\nThe standard library header <stdint.h> defines types\nlike int16_t, uint32_t,\nint64_t, etc. You should always use\nthose in preference to short, unsigned\nlong long, and the like, when you need a guarantee\non the size of an integer. Prefer to omit the std::\nprefix for these types, as the extra 5 characters do\nnot merit the added clutter. Of the built-in integer types, only\nint should be used. When appropriate, you\nare welcome to use standard type aliases like\nsize_t and ptrdiff_t.
We use int very often, for integers we\nknow are not going to be too big, e.g., loop counters.\nUse plain old int for such things. You\nshould assume that an int is\n\nat least 32 bits, but don't\nassume that it has more than 32 bits. If you need a 64-bit\ninteger type, use int64_t or uint64_t.\n\n
For integers we know can be \"big\",\n use\nint64_t.\n
You should not use the unsigned integer types such as\nuint32_t, unless there is a valid\nreason such as representing a bit pattern rather than a\nnumber, or you need defined overflow modulo 2^N. In\nparticular, do not use unsigned types to say a number\nwill never be negative. Instead, use\n\nassertions for this.
If your code is a container that returns a size, be\nsure to use a type that will accommodate any possible\nusage of your container. When in doubt, use a larger type\nrather than a smaller type.
\n\nUse care when converting integer types. Integer conversions and\npromotions can cause undefined behavior, leading to security bugs and\nother problems.
\n\nUnsigned integers are good for representing bitfields and modular\narithmetic. Because of historical accident, the C++ standard also uses\nunsigned integers to represent the size of containers - many members\nof the standards body believe this to be a mistake, but it is\neffectively impossible to fix at this point. The fact that unsigned\narithmetic doesn't model the behavior of a simple integer, but is\ninstead defined by the standard to model modular arithmetic (wrapping\naround on overflow/underflow), means that a significant class of bugs\ncannot be diagnosed by the compiler. In other cases, the defined\nbehavior impedes optimization.
\n\nThat said, mixing signedness of integer types is responsible for an\nequally large class of problems. The best advice we can provide: try\nto use iterators and containers rather than pointers and sizes, try\nnot to mix signedness, and try to avoid unsigned types (except for\nrepresenting bitfields or modular arithmetic). Do not use an unsigned\ntype merely to assert that a variable is non-negative.
\n\nOf the built-in C++ floating-point types, the only ones used\n are float and\ndouble. You may assume that these types represent IEEE-754 binary32\nand binary64, respectively.
Do not use long double, as it gives non-portable\nresults.
Write architecture-portable code. Do not rely on CPU features specific to a\nsingle processor.
\n\nabsl::StrCat,\n absl::Substitute,\n absl::StrFormat,\n or std::ostream instead of the\n printf family of functions.uintptr_ts rather than uint32_ts or\n uint64_ts.int64_t my_value{0x123456789};\nuint64_t my_mask{uint64_t{3} << 48};\n\n long double.short, long, and long long.Avoid defining macros, especially in headers; prefer\ninline functions, enums, and const variables.\nName macros with a project-specific prefix. Do not use\nmacros to define pieces of a C++ API.
Macros mean that the code you see is not the same as\nthe code the compiler sees. This can introduce unexpected\nbehavior, especially since macros have global scope.
\n\nThe problems introduced by macros are especially severe\nwhen they are used to define pieces of a C++ API,\nand still more so for public APIs. Every error message from\nthe compiler when developers incorrectly use that interface\nnow must explain how the macros formed the interface.\nRefactoring and analysis tools have a dramatically harder\ntime updating the interface. As a consequence, we\nspecifically disallow using macros in this way.\nFor example, avoid patterns like:
\n\nclass WOMBAT_TYPE(Foo) {\n // ...\n\n public:\n EXPAND_PUBLIC_WOMBAT_API(Foo)\n\n EXPAND_WOMBAT_COMPARISONS(Foo, ==, <)\n};\n\n\nLuckily, macros are not nearly as necessary in C++ as\nthey are in C. Instead of using a macro to inline\nperformance-critical code, use an inline function.\nInstead of using a macro to store a constant, use a\nconst variable. Instead of using a macro to\n\"abbreviate\" a long variable name, use a reference.\nInstead of using a macro to conditionally compile code\n... well, don't do that at all (except, of course, for\nthe #define guards to prevent double\ninclusion of header files). It makes testing much more\ndifficult.
Macros can do things these other techniques cannot,\nand you do see them in the codebase, especially in the\nlower-level libraries. And some of their special features\n(like stringifying, concatenation, and so forth) are not\navailable through the language proper. But before using a\nmacro, consider carefully whether there's a non-macro way\nto achieve the same result. If you need to use a macro to\ndefine an interface, contact\nyour project leads to request\na waiver of this rule.
\n\nThe following usage pattern will avoid many problems\nwith macros; if you use macros, follow it whenever\npossible:
\n\n.h file.#define macros right before you use\n them, and #undef them right after.#undef an existing macro\n before replacing it with your own; instead, pick a name\n that's likely to be unique.## to generate\n function/class/variable names.Exporting macros from headers (i.e., defining them in a header\nwithout #undefing them before the end of the header)\nis extremely strongly discouraged. If you do export a macro from a\nheader, it must have a globally unique name. To achieve this, it\nmust be named with a prefix consisting of your project's namespace\nname (but upper case).
Use nullptr for pointers, and '\\0' for chars (and\nnot the 0 literal).
For pointers (address values), use nullptr, as this\nprovides type-safety.
Use '\\0' for the null character. Using the correct type makes\nthe code more readable.
Prefer sizeof(varname) to\nsizeof(type).
Use sizeof(varname) when you\ntake the size of a particular variable.\nsizeof(varname) will update\nappropriately if someone changes the variable type either\nnow or later. You may use\nsizeof(type) for code unrelated\nto any particular variable, such as code that manages an\nexternal or internal data format where a variable of an\nappropriate C++ type is not convenient.
MyStruct data;\nmemset(&data, 0, sizeof(data));\n\n\n
memset(&data, 0, sizeof(MyStruct));\n\n\n
if (raw_size < sizeof(int)) {\n LOG(ERROR) << \"compressed record not big enough for count: \" << raw_size;\n return false;\n}\n\n\n\nUse type deduction only if it makes the code clearer to readers who aren't\n familiar with the project, or if it makes the code safer. Do not use it\n merely to avoid the inconvenience of writing an explicit type.
\n\n\n\nThere are several contexts in which C++ allows (or even requires) types to\nbe deduced by the compiler, rather than spelled out explicitly in the code:
\ntemplate <typename T>\nvoid f(T t);\n\nf(0); // Invokes f<int>(0)\n
auto variable declarationsauto keyword in place\n of the type. The compiler deduces the type from the variable's\n initializer, following the same rules as function template argument\n deduction with the same initializer (so long as you don't use curly braces\n instead of parentheses).\n auto a = 42; // a is an int\nauto& b = a; // b is an int&\nauto c = b; // c is an int\nauto d{42}; // d is an int, not a std::initializer_list<int>\n\n auto can be qualified with const, and can be\n used as part of a pointer or reference type, and (since C++17) as a\n non-type template argument. A rare variant of this syntax uses\n decltype(auto) instead of auto, in which case\n the deduced type is the result of applying\n decltype\n to the initializer.\n auto (and decltype(auto)) can also be used in\n place of a function return type. The compiler deduces the return type from\n the return statements in the function body, following the same\n rules as for variable declarations:\n auto f() { return 0; } // The return type of f is int\n Lambda expression return types can be\n deduced in the same way, but this is triggered by omitting the return type,\n rather than by an explicit auto. Confusingly,\n trailing return type syntax for functions\n also uses auto in the return-type position, but that doesn't\n rely on type deduction; it's just an alternative syntax for an explicit\n return type.\n auto keyword in place of\n one or more of its parameter types. This causes the lambda's call operator\n to be a function template instead of an ordinary function, with a separate\n template parameter for each auto function parameter:\n // Sort `vec` in decreasing order\nstd::sort(vec.begin(), vec.end(), [](auto lhs, auto rhs) { return lhs > rhs; });\n [x = 42, y = \"foo\"] { ... } // x is an int, and y is a const char*\n This syntax doesn't allow the type to be specified; instead, it's deduced\n using the rules for auto variables.\n auto, you can\n specify names for the individual elements instead of a name for the whole\n object; these names are called \"structured bindings\", and the whole\n declaration is called a \"structured binding declaration\". This syntax\n provides no way of specifying the type of either the enclosing object\n or the individual names:\n auto [iter, success] = my_map.insert({key, value});\nif (!success) {\n iter->second = value;\n}\n The auto can also be qualified with const,\n &, and &&, but note that these qualifiers\n technically apply to the anonymous tuple/struct/array, rather than the\n individual bindings. The rules that determine the types of the bindings\n are quite complex; the results tend to be unsurprising, except that\n the binding types typically won't be references even if the declaration\n declares a reference (but they will usually behave like references anyway).\n (These summaries omit many details and caveats; see the links for further\n information.)
\n\n\n\nC++ code is usually clearer when types are explicit,\n especially when type deduction would depend on information from\n distant parts of the code. In expressions like:
\n\nauto foo = x.add_foo();\nauto i = y.Find(key);\n\n\n
it may not be obvious what the resulting types are if the type\n of y isn't very well known, or if y was\n declared many lines earlier.
Programmers have to understand when type deduction will or won't\n produce a reference type, or they'll get copies when they didn't\n mean to.
\n\nIf a deduced type is used as part of an interface, then a\n programmer might change its type while only intending to\n change its value, leading to a more radical API change\n than intended.
\n\n\n\nThe fundamental rule is: use type deduction only to make the code\n clearer or safer, and do not use it merely to avoid the\n inconvenience of writing an explicit type. When judging whether the\n code is clearer, keep in mind that your readers are not necessarily\n on your team, or familiar with your project, so types that you and\n your reviewer experience as unnecessary clutter will very often\n provide useful information to others. For example, you can assume that\n the return type of make_unique<Foo>() is obvious,\n but the return type of MyWidgetFactory() probably isn't.
These principles apply to all forms of type deduction, but the\n details vary, as described in the following sections.
\n\nFunction template argument deduction is almost always OK. Type deduction\n is the expected default way of interacting with function templates,\n because it allows function templates to act like infinite sets of ordinary\n function overloads. Consequently, function templates are almost always\n designed so that template argument deduction is clear and safe, or\n doesn't compile.
\n\nFor local variables, you can use type deduction to make the code clearer\n by eliminating type information that is obvious or irrelevant, so that\n the reader can focus on the meaningful parts of the code:
\nstd::unique_ptr<WidgetWithBellsAndWhistles> widget =\n std::make_unique<WidgetWithBellsAndWhistles>(arg1, arg2);\nabsl::flat_hash_map<std::string,\n std::unique_ptr<WidgetWithBellsAndWhistles>>::const_iterator\n it = my_map_.find(key);\nstd::array<int, 6> numbers = {4, 8, 15, 16, 23, 42};\n\n auto widget = std::make_unique<WidgetWithBellsAndWhistles>(arg1, arg2);\nauto it = my_map_.find(key);\nstd::array numbers = {4, 8, 15, 16, 23, 42};\n\nTypes sometimes contain a mixture of useful information and boilerplate,\n such as it in the example above: it's obvious that the\n type is an iterator, and in many contexts the container type and even the\n key type aren't relevant, but the type of the values is probably useful.\n In such situations, it's often possible to define local variables with\n explicit types that convey the relevant information:
if (auto it = my_map_.find(key); it != my_map_.end()) {\n WidgetWithBellsAndWhistles& widget = *it->second;\n // Do stuff with `widget`\n}\nIf the type is a template instance, and the parameters are\n boilerplate but the template itself is informative, you can use\n class template argument deduction to suppress the boilerplate. However,\n cases where this actually provides a meaningful benefit are quite rare.\n Note that class template argument deduction is also subject to a\n separate style rule.
\n\nDo not use decltype(auto) if a simpler option will work;\n because it's a fairly obscure feature, it has a high cost in code\n clarity.
Use return type deduction (for both functions and lambdas) only if the\n function body has a very small number of return statements,\n and very little other code, because otherwise the reader may not be able\n to tell at a glance what the return type is. Furthermore, use it only\n if the function or lambda has a very narrow scope, because functions with\n deduced return types don't define abstraction boundaries: the implementation\n is the interface. In particular, public functions in header files\n should almost never have deduced return types.
auto parameter types for lambdas should be used with caution,\n because the actual type is determined by the code that calls the lambda,\n rather than by the definition of the lambda. Consequently, an explicit\n type will almost always be clearer unless the lambda is explicitly called\n very close to where it's defined (so that the reader can easily see both),\n or the lambda is passed to an interface so well-known that it's\n obvious what arguments it will eventually be called with (e.g.,\n the std::sort example above).
Init captures are covered by a more specific\n style rule, which largely supersedes the general rules for\n type deduction.
\n\nUnlike other forms of type deduction, structured bindings can actually\n give the reader additional information, by giving meaningful names to the\n elements of a larger object. This means that a structured binding declaration\n may provide a net readability improvement over an explicit type, even in cases\n where auto would not. Structured bindings are especially\n beneficial when the object is a pair or tuple (as in the insert\n example above), because they don't have meaningful field names to begin with,\n but note that you generally shouldn't use\n pairs or tuples unless a pre-existing API like insert\n forces you to.
If the object being bound is a struct, it may sometimes be helpful to\n provide names that are more specific to your usage, but keep in mind that\n this may also mean the names are less recognizable to your reader than the\n field names. We recommend using a comment to indicate the name of the\n underlying field, if it doesn't match the name of the binding, using the\n same syntax as for function parameter comments:
\nauto [/*field_name1=*/bound_name1, /*field_name2=*/bound_name2] = ...\n
As with function parameter comments, this can enable tools to detect if\n you get the order of the fields wrong.
\n\nUse class template argument deduction only with templates that have\n explicitly opted into supporting it.
\n\n\nClass\n template argument deduction (often abbreviated \"CTAD\") occurs when\n a variable is declared with a type that names a template, and the template\n argument list is not provided (not even empty angle brackets):
\nstd::array a = {1, 2, 3}; // `a` is a std::array<int, 3>\nThe compiler deduces the arguments from the initializer using the\n template's \"deduction guides\", which can be explicit or implicit.
\n\nExplicit deduction guides look like function declarations with trailing\n return types, except that there's no leading auto, and the\n function name is the name of the template. For example, the above example\n relies on this deduction guide for std::array:
namespace std {\ntemplate <class T, class... U>\narray(T, U...) -> std::array<T, 1 + sizeof...(U)>;\n}\nConstructors in a primary template (as opposed to a template specialization)\n also implicitly define deduction guides.
\n\nWhen you declare a variable that relies on CTAD, the compiler selects\n a deduction guide using the rules of constructor overload resolution,\n and that guide's return type becomes the type of the variable.
\n\n\nCTAD can sometimes allow you to omit boilerplate from your code.
\n\n\nThe implicit deduction guides that are generated from constructors\n may have undesirable behavior, or be outright incorrect. This is\n particularly problematic for constructors written before CTAD was\n introduced in C++17, because the authors of those constructors had no\n way of knowing about (much less fixing) any problems that their\n constructors would cause for CTAD. Furthermore, adding explicit deduction\n guides to fix those problems might break any existing code that relies on\n the implicit deduction guides.
\n\nCTAD also suffers from many of the same drawbacks as auto,\n because they are both mechanisms for deducing all or part of a variable's\n type from its initializer. CTAD does give the reader more information\n than auto, but it also doesn't give the reader an obvious\n cue that information has been omitted.
Do not use CTAD with a given template unless the template's maintainers\n have opted into supporting use of CTAD by providing at least one explicit\n deduction guide (all templates in the std namespace are\n also presumed to have opted in). This should be enforced with a compiler\n warning if available.
Uses of CTAD must also follow the general rules on\n Type deduction.
\n\nUse designated initializers only in their C++20-compliant form.
\n\n\n\n Designated initializers are a syntax that allows for initializing an\n aggregate (\"plain old struct\") by naming its fields explicitly:
\n struct Point {\n float x = 0.0;\n float y = 0.0;\n float z = 0.0;\n };\n\n Point p = {\n .x = 1.0,\n .y = 2.0,\n // z will be 0.0\n };\nThe explicitly listed fields will be initialized as specified, and others\n will be initialized in the same way they would be in a traditional aggregate\n initialization expression like Point{1.0, 2.0}.
Designated initializers can make for convenient and highly readable\naggregate expressions, especially for structs with less straightforward\nordering of fields than the Point example above.
While designated initializers have long been part of the C standard and\nsupported by C++ compilers as an extension, they were not supported by\nC++ prior to C++20.
\n\nThe rules in the C++ standard are stricter than in C and compiler extensions,\nrequiring that the designated initializers appear in the same order as the\nfields appear in the struct definition. So in the example above, it is legal\naccording to C++20 to initialize x and then z, but not\ny and then x.
Use designated initializers only in the form that is compatible with the\nC++20 standard: with initializers in the same order as the corresponding fields\nappear in the struct definition.
\n\n\n\nUse lambda expressions where appropriate. Prefer explicit captures\nwhen the lambda will escape the current scope.
\n\n\nLambda expressions are a concise way of creating anonymous\nfunction objects. They're often useful when passing\nfunctions as arguments. For example:
\n\nstd::sort(v.begin(), v.end(), [](int x, int y) {\n return Weight(x) < Weight(y);\n});\n\n\nThey further allow capturing variables from the enclosing scope either\nexplicitly by name, or implicitly using a default capture. Explicit captures\nrequire each variable to be listed, as\neither a value or reference capture:
\n\nint weight = 3;\nint sum = 0;\n// Captures `weight` by value and `sum` by reference.\nstd::for_each(v.begin(), v.end(), [weight, &sum](int x) {\n sum += weight * x;\n});\n\n\n\nDefault captures implicitly capture any variable referenced in the\nlambda body, including this if any members are used:
const std::vector<int> lookup_table = ...;\nstd::vector<int> indices = ...;\n// Captures `lookup_table` by reference, sorts `indices` by the value\n// of the associated element in `lookup_table`.\nstd::sort(indices.begin(), indices.end(), [&](int a, int b) {\n return lookup_table[a] < lookup_table[b];\n});\n\n\nA variable capture can also have an explicit initializer, which can\n be used for capturing move-only variables by value, or for other situations\n not handled by ordinary reference or value captures:
\nstd::unique_ptr<Foo> foo = ...;\n[foo = std::move(foo)] () {\n ...\n}\nSuch captures (often called \"init captures\" or \"generalized lambda captures\")\n need not actually \"capture\" anything from the enclosing scope, or even have\n a name from the enclosing scope; this syntax is a fully general way to define\n members of a lambda object:
\n[foo = std::vector<int>({1, 2, 3})] () {\n ...\n}\nThe type of a capture with an initializer is deduced using the same rules\n as auto.
std::function, and\n std::bind can be used in combination as a\n general purpose callback mechanism; they make it easy\n to write functions that take bound functions as\n arguments.this by value,\n since the use of this is often implicit.auto placeholder (although init captures can\n indicate it indirectly, e.g., with a cast). This can make it difficult to\n even recognize them as declarations.auto, with the additional problem that the syntax doesn't\n even cue the reader that deduction is taking place.{\n Foo foo;\n ...\n executor->Schedule([&] { Frobnicate(foo); })\n ...\n}\n// BAD! The fact that the lambda makes use of a reference to `foo` and\n// possibly `this` (if `Frobnicate` is a member function) may not be\n// apparent on a cursory inspection. If the lambda is invoked after\n// the function returns, that would be bad, because both `foo`\n// and the enclosing object could have been destroyed.\n\nprefer to write:\n{\n Foo foo;\n ...\n executor->Schedule([&foo] { Frobnicate(foo); })\n ...\n}\n// BETTER - The compile will fail if `Frobnicate` is a member\n// function, and it's clearer that `foo` is dangerously captured by\n// reference.\n\n[&]) only when\nthe lifetime of the lambda is obviously shorter than any potential\ncaptures.\n[=]) only as a means of\nbinding a few variables for a short lambda, where the set of captured\nvariables is obvious at a glance, and which does not result in\ncapturing this implicitly. (That means that a lambda that\nappears in a non-static class member function and refers to non-static\nclass members in its body must capture this explicitly or\nvia [&].) Prefer not to write long or complex lambdas\nwith default capture by value.\nAvoid complicated template programming.
\n\n\nTemplate metaprogramming refers to a family of techniques that\nexploit the fact that the C++ template instantiation mechanism is\nTuring complete and can be used to perform arbitrary compile-time\ncomputation in the type domain.
\n\n\nTemplate metaprogramming allows extremely flexible interfaces that\nare type safe and high performance. Facilities like\n\nGoogleTest,\nstd::tuple, std::function, and\nBoost.Spirit would be impossible without it.
The techniques used in template metaprogramming are often obscure\nto anyone but language experts. Code that uses templates in\ncomplicated ways is often unreadable, and is hard to debug or\nmaintain.
\n\nTemplate metaprogramming often leads to extremely poor compile\ntime error messages: even if an interface is simple, the complicated\nimplementation details become visible when the user does something\nwrong.
\n\nTemplate metaprogramming interferes with large scale refactoring by\nmaking the job of refactoring tools harder. First, the template code\nis expanded in multiple contexts, and it's hard to verify that the\ntransformation makes sense in all of them. Second, some refactoring\ntools work with an AST that only represents the structure of the code\nafter template expansion. It can be difficult to automatically work\nback to the original source construct that needs to be\nrewritten.
\n\n\nTemplate metaprogramming sometimes allows cleaner and easier-to-use\ninterfaces than would be possible without it, but it's also often a\ntemptation to be overly clever. It's best used in a small number of\nlow level components where the extra maintenance burden is spread out\nover a large number of uses.
\n\nThink twice before using template metaprogramming or other\ncomplicated template techniques; think about whether the average\nmember of your team will be able to understand your code well enough\nto maintain it after you switch to another project, or whether a\nnon-C++ programmer or someone casually browsing the codebase will be\nable to understand the error messages or trace the flow of a function\nthey want to call. If you're using recursive template instantiations\nor type lists or metafunctions or expression templates, or relying on\nSFINAE or on the sizeof trick for detecting function\noverload resolution, then there's a good chance you've gone too\nfar.
If you use template metaprogramming, you should expect to put\nconsiderable effort into minimizing and isolating the complexity. You\nshould hide metaprogramming as an implementation detail whenever\npossible, so that user-facing headers are readable, and you should\nmake sure that tricky code is especially well commented. You should\ncarefully document how the code is used, and you should say something\nabout what the \"generated\" code looks like. Pay extra attention to the\nerror messages that the compiler emits when users make mistakes. The\nerror messages are part of your user interface, and your code should\nbe tweaked as necessary so that the error messages are understandable\nand actionable from a user point of view.
\n\nUse concepts sparingly.\nIn general, concepts and constraints should only be used in cases\nwhere templates would have been used prior to C++20.\nAvoid introducing new concepts in headers,\nunless the headers are marked as internal to the library.\nDo not define concepts that are not enforced by the compiler.\nPrefer constraints over template metaprogramming, and\navoid the template<Concept T> syntax;\ninstead, use the requires(Concept<T>)\nsyntax.
The concept keyword is a new mechanism for defining\nrequirements (such as type traits or interface specifications)\nfor a template parameter.\nThe requires keyword provides mechanisms for placing\nanonymous constraints on templates and verifying that constraints\nare satisfied at compile time.\nConcepts and constraints are often used together, but can be\nalso used independently.
Predefined concepts in the standard library should be\npreferred to type traits, when equivalent ones exist.\n(e.g., if std::is_integral_v would have been used\nbefore C++20, then std::integral should be used in\nC++20 code.)\nSimilarly, prefer modern constraint syntax\n(via requires(Condition)).\nAvoid legacy template metaprogramming constructs\n(such as std::enable_if<Condition>)\nas well as the template<Concept T>\nsyntax.
Do not manually re-implement any existing concepts or traits.\nFor example, use\nrequires(std::default_initializable<T>)\ninstead of\nrequires(requires { T v; })\nor the like.\n\n
New concept declarations should be rare, and only\ndefined internally within a library, such that they are not\nexposed at API boundaries.\nMore generally, do not use concepts or constraints in cases where\nyou wouldn't use their legacy template equivalents in C++17.\n
Do not define concepts that duplicate the function body,\nor impose requirements that would be insignificant or obvious\nfrom reading the body of the code or the resulting error messages.\nFor example, avoid the following:\n
template <typename T> // Bad - redundant with negligible benefit\nconcept Addable = std::copyable<T> && requires(T a, T b) { a + b; };\ntemplate <Addable T>\nT Add(T x, T y, T z) { return x + y + z; }\n\nInstead, prefer to leave code as an ordinary template unless\nyou can demonstrate that concepts result in significant\nimprovement for that particular case, such as in the resulting\nerror messages for a deeply nested or non-obvious\nrequirement.\n\nConcepts should be statically verifiable by the compiler.\nDo not use any concept whose primary benefits would come from a\nsemantic (or otherwise unenforced) constraint.\nRequirements that are unenforced at compile time should instead\nbe imposed via other mechanisms such as comments, assertions,\nor tests.
\n\nDo not use C++20 Modules.
\n\nC++20 introduces \"modules\", a new language feature designed as an\nalternative to textual inclusion of header files. It introduces three\nnew keywords to support\nthis: module, export,\nand import.\n\n
Modules are a big shift in how C++ is written and compiled, and we\nare still assessing how they may fit into Google's C++ ecosystem in\nthe future. Furthermore, they are not currently well-supported by our\nbuild systems, compilers, and other tooling, and need further\nexploration as to the best practices when writing and using them.
\n\n\n\nOnly use C++20 coroutines via libraries that have been\n approved by your project leads.
\n\n\nC++20 introduced\ncoroutines:\nfunctions that can suspend and resume\nexecuting later. They are especially convenient for asynchronous\nprogramming, where they can provide substantial improvements over\ntraditional callback-based frameworks.
\n\nUnlike most other programming languages (Kotlin, Rust, TypeScript, etc.),\nC++ does not provide a concrete implementation of coroutines.\nInstead, it requires users to implement their own awaitable type (using a\n\n promise type) which determines coroutine parameter types, how coroutines\nare executed, and allows running user-defined code during different stages\nof their execution.
\n\n\nIn summary, designing a high-quality and interoperable coroutine library\nrequires a large amount of difficult work, careful thought, and extensive\ndocumentation.
\n\n\n\n\n\nUse only coroutine libraries that have been approved for\n project-wide use by your project leads. Do not roll your own promise or\n awaitable types.
\n\nUse only approved libraries from the Boost library\ncollection.
\n\n\nThe\n\nBoost library collection is a popular collection of\npeer-reviewed, free, open-source C++ libraries.
\n\n\nBoost code is generally very high-quality, is widely\nportable, and fills many important gaps in the C++\nstandard library, such as type traits and better binders.
\n\n\nSome Boost libraries encourage coding practices which can\nhamper readability, such as metaprogramming and other\nadvanced template techniques, and an excessively\n\"functional\" style of programming.
\n\n\n\n\n\nIn order to maintain a high level of readability for\nall contributors who might read and maintain code, we\nonly allow an approved subset of Boost features.\nCurrently, the following libraries are permitted:
\n\nboost/call_traits.hppboost/compressed_pair.hppboost/graph,\n except serialization (adj_list_serialize.hpp) and\n parallel/distributed algorithms and data structures\n (boost/graph/parallel/* and\n boost/graph/distributed/*).boost/property_map, except\n parallel/distributed property maps (boost/property_map/parallel/*).boost/iteratorboost/polygon/voronoi_builder.hpp,\n boost/polygon/voronoi_diagram.hpp, and\n boost/polygon/voronoi_geometry_type.hppboost/bimapboost/math/distributionsboost/math/special_functionsboost/math/toolsboost/multi_indexboost/heapboost/container/flat_map, and\n boost/container/flat_setboost/intrusive.boost/sort library.boost/preprocessor.We are actively considering adding other Boost\nfeatures to the list, so this list may be expanded in\nthe future.
\nAs with Boost, some modern C++\nlibrary functionality encourages coding practices that hamper\nreadability — for example by removing\nchecked redundancy (such as type names) that may be\nhelpful to readers, or by encouraging template\nmetaprogramming. Other extensions duplicate functionality\navailable through existing mechanisms, which may lead to confusion\nand conversion costs.
\n\n\nThe following C++ standard library features may not be used:
\n\n<ratio>), because of concerns that\n it's tied to a more template-heavy interface\n style.<cfenv> and\n <fenv.h> headers, because many\n compilers do not support those features reliably.<filesystem> header, which\n\n does not have sufficient support for testing, and suffers\n from inherent security vulnerabilities.Nonstandard extensions to C++ may not be used unless otherwise specified.
\n\n\nCompilers support various extensions that are not part of standard C++. Such\n extensions include GCC's __attribute__, intrinsic functions such\n as __builtin_prefetch or SIMD, #pragma, inline\n assembly, __COUNTER__, __PRETTY_FUNCTION__,\n compound statement expressions (e.g., foo = ({ int x; Bar(&x); x\n }), variable-length arrays and alloca(), and the\n \"Elvis\n Operator\" a?:b.
Do not use nonstandard extensions. You may use portability wrappers that\n are implemented using nonstandard extensions, so long as those wrappers\n\n are provided by a designated project-wide portability\n header.
\n\nPublic aliases are for the benefit of an API's user, and should be clearly documented.
\n\n\nThere are several ways to create names that are aliases of other entities:
\nusing Bar = Foo;\ntypedef Foo Bar; // But prefer `using` in C++ code.\nusing ::other_namespace::Foo;\nusing enum MyEnumType; // Creates aliases for all enumerators in MyEnumType.\n\n\n
In new code, using is preferable to typedef,\n because it provides a more consistent syntax with the rest of C++ and works\n with templates.
Like other declarations, aliases declared in a header file are part of that\n header's public API unless they're in a function definition, in the private portion of a class,\n or in an explicitly-marked internal namespace. Aliases in such areas or in .cc files\n are implementation details (because client code can't refer to them), and are not restricted by\n this rule.
Don't put an alias in your public API just to save typing in the implementation;\n do so only if you intend it to be used by your clients.
\nWhen defining a public alias, document the intent of\nthe new name, including whether it is guaranteed to always be the same as the type\nit's currently aliased to, or whether a more limited compatibility is\nintended. This lets the user know whether they can treat the types as\nsubstitutable or whether more specific rules must be followed, and can help the\nimplementation retain some degree of freedom to change the alias.
\nDon't put namespace aliases in your public API. (See also Namespaces.)\n
\n\nFor example, these aliases document how they are intended to be used in client code:
\nnamespace mynamespace {\n// Used to store field measurements. DataPoint may change from Bar* to some internal type.\n// Client code should treat it as an opaque pointer.\nusing DataPoint = ::foo::Bar*;\n\n// A set of measurements. Just an alias for user convenience.\nusing TimeSeries = std::unordered_set<DataPoint, std::hash<DataPoint>, DataPointComparator>;\n} // namespace mynamespace\n\n\nThese aliases don't document intended use, and half of them aren't meant for client use:
\n\nnamespace mynamespace {\n// Bad: none of these say how they should be used.\nusing DataPoint = ::foo::Bar*;\nusing ::std::unordered_set; // Bad: just for local convenience\nusing ::std::hash; // Bad: just for local convenience\ntypedef unordered_set<DataPoint, hash<DataPoint>, DataPointComparator> TimeSeries;\n} // namespace mynamespace\n\n\nHowever, local convenience aliases are fine in function definitions, private\n sections of classes, explicitly-marked internal namespaces, and in .cc files:
// In a .cc file\nusing ::foo::Bar;\n\n\n
If not conditional on an enumerated value, switch statements should always\nhave a default case (in the case of an enumerated value, the\ncompiler will warn you if any values are not handled). If the default case\nshould never execute, treat this as an error. For example:\n\n
switch (var) {\n case 0: {\n ...\n break;\n }\n case 1: {\n ...\n break;\n }\n default: {\n LOG(FATAL) << \"Invalid value in switch statement: \" << var;\n }\n}\n\n\nFall-through from one case label to another must be annotated using the\n[[fallthrough]]; attribute. [[fallthrough]]; should\nbe placed at a point of execution where a fall-through to the next case label\noccurs. A common exception is consecutive case labels without intervening code,\nin which case no annotation is needed.
switch (x) {\n case 41: // No annotation needed here.\n case 43:\n if (dont_be_picky) {\n // Use this instead of or along with annotations in comments.\n [[fallthrough]];\n } else {\n CloseButNoCigar();\n break;\n }\n case 42:\n DoSomethingSpecial();\n [[fallthrough]];\n default:\n DoSomethingGeneric();\n break;\n}\n\n\nIn all code, including naming and comments, use inclusive language\nand avoid terms that other programmers might find disrespectful or offensive\n(such as \"master\" and \"slave\", \"blacklist\" and \"whitelist\", or \"redline\"),\neven if the terms also have an ostensibly neutral meaning.\nSimilarly, use gender-neutral language unless you're referring\nto a specific person (and using their pronouns). For example,\nuse \"they\"/\"them\"/\"their\" for people of unspecified gender\n(even\nwhen singular), and \"it\"/\"its\" for software, computers, and other\nthings that aren't people.
\n\n\n\nThe most important consistency rules are those that govern\nnaming. The style of a name immediately informs us what sort of\nthing the named entity is: a type, a variable, a function, a\nconstant, a macro, etc., without requiring us to search for the\ndeclaration of that entity. The pattern-matching engine in our\nbrains relies a great deal on these naming rules.\n
\n\nStyle rules about naming are pretty arbitrary, but\n we feel that\nconsistency is more important than individual preferences in this\narea, so regardless of whether you find them sensible or not,\nthe rules are the rules.
\n\nFor the purposes of the naming rules below, a \"word\" is anything that you\nwould write in English without internal spaces. Either words are all lowercase,\nwith underscores between words\n(\"snake_case\"), or words\nare mixed case with the first letter of each word capitalized\n(\"camelCase\" or\n\"PascalCase\").\n\n
Give things names that make their purpose or intent understandable to a new\nreader, even someone on a different team than the owners. Do not worry about\nsaving horizontal space as it is far more important to make your code\nimmediately understandable by a new reader.
\n\nConsider the context in which the name will be used. A name should be\ndescriptive even if it is used far from the code that makes it available for\nuse. However, a name should not distract the reader by repeating information\nthat's present in the immediate context. Generally, this means that\ndescriptiveness should be proportional to the name's scope of visibility. A free\nfunction declared in a header should probably mention the header's library,\nwhile a local variable probably shouldn't explain what function it's within.
\n\nMinimize the use of abbreviations that would likely be unknown to someone\noutside your project (especially acronyms and initialisms). Do not abbreviate by\ndeleting letters within a word. When an abbreviation is used, prefer to\ncapitalize it as a single \"word\", e.g., StartRpc() rather than\nStartRPC(). As a rule of thumb, an abbreviation is probably OK\nif it's listed in\n\nWikipedia. Note that certain universally-known abbreviations are OK, such as\ni for a loop index and T for a template\nparameter.
The names you see most frequently are not like most names; a small number of\n\"vocabulary\" names are reused so widely that they are always in context. These\nnames tend to be short or even abbreviated and their full meaning comes from\nexplicit long-form documentation rather than from just comments on their\ndefinition and the words within the names. For example, absl::Status\nhas a dedicated\n\npage\nin a devguide,\ndocumenting its proper use. You probably won't define new vocabulary names very\noften, but if you do, get\nadditional design review to make sure the chosen names work well when\nused widely.
class MyClass {\n public:\n int CountFooErrors(const std::vector<Foo>& foos) {\n int n = 0; // Clear meaning given limited scope and context\n for (const auto& foo : foos) {\n ...\n ++n;\n }\n return n;\n }\n // Function comment doesn't need to explain that this returns non-OK on\n // failure as that is implied by the `absl::Status` return type, but it\n // might document behavior for some specific codes.\n absl::Status DoSomethingImportant() {\n std::string fqdn = ...; // Well-known abbreviation for Fully Qualified Domain Name\n return absl::OkStatus();\n }\n private:\n const int kMaxAllowedConnections = ...; // Clear meaning within context\n};\n\n\nclass MyClass {\n public:\n int CountFooErrors(const std::vector<Foo>& foos) {\n int total_number_of_foo_errors = 0; // Overly verbose given limited scope and context\n for (int foo_index = 0; foo_index < foos.size(); ++foo_index) { // Use idiomatic `i`\n ...\n ++total_number_of_foo_errors;\n }\n return total_number_of_foo_errors;\n }\n // A return type with a generic name is unclear without widespread education.\n Result DoSomethingImportant() {\n int cstmr_id = ...; // Deletes internal letters\n }\n private:\n const int kNum = ...; // Unclear meaning within broad scope\n};\n\n\nFilenames should be all lowercase and can include\nunderscores (_) or dashes (-).\nFollow the convention that your\n\nproject uses. If there is no consistent\nlocal pattern to follow, prefer \"_\".
Examples of acceptable file names:
\n\nmy_useful_class.ccmy-useful-class.ccmyusefulclass.ccmyusefulclass_test.cc // _unittest and _regtest are deprecated.C++ files should have a .cc filename extension, and header files\nshould have a .h extension. Files that rely on being textually included at specific points\nshould end in .inc (see also the section on\nself-contained headers).
Do not use filenames that already exist in\n/usr/include, such as db.h.
In general, make your filenames very specific. For\nexample, use http_server_logs.h rather than\nlogs.h. A very common case is to have a pair\nof files called, e.g., foo_bar.h and\nfoo_bar.cc, defining a class called\nFooBar.
Type names start with a capital letter and have a capital\nletter for each new word, with no underscores:\nMyExcitingClass, MyExcitingEnum.
The names of all types — classes, structs, type aliases,\nenums, and type template parameters — have the same naming convention.\nType names should start with a capital letter and have a capital letter\nfor each new word. No underscores. For example:
\n\n// classes and structs\nclass UrlTable { ...\nclass UrlTableTester { ...\nstruct UrlTableProperties { ...\n\n// typedefs\ntypedef hash_map<UrlTableProperties*, std::string> PropertiesMap;\n\n// using aliases\nusing PropertiesMap = hash_map<UrlTableProperties*, std::string>;\n\n// enums\nenum class UrlTableError { ...\n\n\nThe names of variables (including function parameters) and data members are\nsnake_case (all lowercase, with underscores between words). Data members of classes\n(but not structs) additionally have trailing underscores. For instance:\na_local_variable, a_struct_data_member,\na_class_data_member_.
For example:
\n\nstd::string table_name; // OK - snake_case.\n\n\n
std::string tableName; // Bad - mixed case.\n\n\n
Data members of classes, both static and non-static, are\nnamed like ordinary nonmember variables, but with a\ntrailing underscore. The exception to this is static constant\nclass members, which should follow the rules for\nnaming constants.
\n\nclass TableInfo {\n public:\n ...\n static const int kTableVersion = 3; // OK - constant naming.\n ...\n\n private:\n std::string table_name_; // OK - underscore at end.\n static Pool<TableInfo>* pool_; // OK.\n};\n\n\nData members of structs, both static and non-static,\nare named like ordinary nonmember variables. They do not have\nthe trailing underscores that data members in classes have.
\n\nstruct UrlTableProperties {\n std::string name;\n int num_entries;\n static Pool<UrlTableProperties>* pool;\n};\n\n\n\nSee Structs vs.\nClasses for a discussion of when to use a struct\nversus a class.
\n\nVariables declared constexpr or const, and whose value is fixed for\nthe duration of the program, are named with a leading \"k\" followed\nby mixed case. Underscores can be used as separators in the rare cases\nwhere capitalization cannot be used for separation. For example:
const int kDaysInAWeek = 7;\nconst int kAndroid8_0_0 = 24; // Android 8.0.0\n\n\n
All such variables with static storage duration (i.e., statics and globals,\nsee \nStorage Duration for details) should be named this way, including those that are static constant\nclass data members and those in templates where different instantiations of the template\nmay have different values. This convention is optional for variables of other storage classes,\ne.g., automatic variables; otherwise the usual variable naming rules apply. For example:
\n\nvoid ComputeFoo(absl::string_view suffix) {\n // Either of these is acceptable.\n const absl::string_view kPrefix = \"prefix\";\n const absl::string_view prefix = \"prefix\";\n ...\n}\n\n\nvoid ComputeFoo(absl::string_view suffix) {\n // Bad - different invocations of ComputeFoo give kCombined different values.\n const std::string kCombined = absl::StrCat(kPrefix, suffix);\n ...\n}\n\n\nOrdinarily, functions follow PascalCase:\nstart with a capital letter and have a capital letter for each new word.
\n\nAddTableEntry()\nDeleteUrl()\nOpenFileOrDie()\n\n\n
The same naming rule applies to class- and namespace-scope\nconstants that are exposed as part of an API and that are intended to look\nlike functions, because the fact that they're objects rather than functions\nis an unimportant implementation detail.
\n\nAccessors and mutators (get and set functions) may be named like variables,\nin snake_case. These often correspond to actual member variables,\nbut this is not required. For example, int count() and\nvoid set_count(int count).
Namespace names are snake_case (all lowercase, with underscores\nbetween words).
When choosing names for namespaces, note\nthat names must be fully qualified when used in a header outside the namespace,\nbecause unqualified Aliases are generally banned.
\n\nTop-level namespaces must be globally unique and recognizable, so each one\nshould be owned by a single project or team, with a name based on the name of\nthat project or team. Usually, all code in the namespace should be under one or\nmore directories with the same name as the namespace.
\n\nNested namespaces should avoid the names of well-known top-level namespaces,\nespecially std and absl, because in C++, nested\nnamespaces do not protect from collisions with names in other namespaces\n(see TotW #130).
Enumerators (for both scoped and unscoped enums) should be named like\nconstants, not like\nmacros. That is, use kEnumName not\nENUM_NAME.
enum class UrlTableError {\n kOk = 0,\n kOutOfMemory,\n kMalformedInput,\n};\n\nenum class AlternateUrlTableError {\n OK = 0,\n OUT_OF_MEMORY = 1,\n MALFORMED_INPUT = 2,\n};\n\n\nUntil January 2009, the style was to name enum values\nlike macros. This caused\nproblems with name collisions between enum values and\nmacros. Hence, the change to prefer constant-style naming\nwas put in place. New code should use constant-style\nnaming.
\n\n\n\nTemplate parameters should follow the naming style for their\ncategory: type template parameters should follow the rules for naming\ntypes, and non-type template\nparameters should follow the rules for naming \nvariables or constants.\n\n
You're not really going to \ndefine a macro, are you? If you do, they're like this:\nMY_MACRO_THAT_SCARES_SMALL_CHILDREN_AND_ADULTS_ALIKE.\n
Please see the description\nof macros; in general macros should not be used.\nHowever, if they are absolutely needed, then they should be\nnamed with all capitals and underscores, and with a project-specific prefix.
\n\n#define MYPROJECT_ROUND(x) ...\n\n\n
The name for an alias follows the same principles as\nany other new name, applied in the context where the alias is defined rather\nthan where the original name appears.
\n\nIf you are naming something that is analogous to an existing C or C++\nentity (or a Rust entity via interop), then you can follow the existing\nnaming convention scheme.
\n\nbigopen()open()uinttypedefbigposstruct or class, follows\n form of possparse_hash_mapLONGLONG_MAXINT_MAXComments are absolutely vital to keeping our code readable. The following rules describe what you\nshould comment and where. But remember: while comments are very important, the best code is\nself-documenting. Giving sensible names to types and variables is much better than using obscure\nnames that you must then explain through comments.
\n\nWhen writing your comments, write for your audience: the\nnext\ncontributor who will need to\nunderstand your code. Be generous — the next\none may be you!
\n\nUse either the // or /* */\nsyntax, as long as you are consistent.
While either syntax is acceptable, // is\nmuch more common. Be consistent with how you\ncomment and what style you use where.
Start each file with license boilerplate.
\nIf a source file (such as a .h file) declares multiple user-facing abstractions\n(common functions, related classes, etc.), include a comment describing the collection of those\nabstractions. Include enough detail for future authors to know what does not fit there. However,\nthe detailed documentation about individual abstractions belongs with those abstractions, not at the\nfile level.
For instance, if you write a file comment for frobber.h, you do not need\nto include a file comment in frobber.cc or\nfrobber_test.cc. On the other hand, if you write a collection of classes in\nregistered_objects.cc that has no associated header file, you must include a file\ncomment in registered_objects.cc.\n\n
Every file should contain license\nboilerplate. Choose the appropriate boilerplate for the\nlicense used by the project (for example, Apache 2.0,\nBSD, LGPL, GPL).
\nIf you make significant changes to a file with an\nauthor line, consider deleting the author line.\nNew files should usually not contain copyright notice or\nauthor line.
\n\nEvery non-obvious class or struct declaration should have an\naccompanying comment that describes what it is for and how it should\nbe used.
\n\n// Iterates over the contents of a GargantuanTable.\n// Example:\n// std::unique_ptr<GargantuanTableIterator> iter = table->NewIterator();\n// for (iter->Seek(\"foo\"); !iter->done(); iter->Next()) {\n// process(iter->key(), iter->value());\n// }\nclass GargantuanTableIterator {\n ...\n};\n\n\nThe class comment should provide the reader with enough information to know\nhow and when to use the class, as well as any additional considerations\nnecessary to correctly use the class. Document the synchronization assumptions\nthe class makes, if any. If an instance of the class can be accessed by\nmultiple threads, take extra care to document the rules and invariants\nsurrounding multithreaded use.
\n\nThe class comment is often a good place for a small example code snippet\ndemonstrating a simple and focused usage of the class.
\n\nWhen sufficiently separated (e.g., .h and .cc\nfiles), comments describing the use of the class should go together with its\ninterface definition; comments about the class operation and implementation\nshould accompany the implementation of the class's methods.
Declaration comments describe use of the function (when it is\nnon-obvious); comments at the definition of a function describe\noperation.
\n\nAlmost every function declaration should have comments immediately\npreceding it that describe what the function does and how to use\nit. These comments may be omitted only if the function is simple and\nobvious (e.g., simple accessors for obvious properties of the class).\nPrivate methods and functions declared in .cc files are not exempt.\nFunction comments should be written with an implied subject of\nThis function and should start with the verb phrase; for example,\n\"Opens the file\", rather than \"Open the file\". In general, these comments do not\ndescribe how the function performs its task. Instead, that should be\nleft to comments in the function definition.
Types of things to mention in comments at the function\ndeclaration:
\n\nHere is an example:
\n\n// Returns an iterator for this table, positioned at the first entry\n// lexically greater than or equal to `start_word`. If there is no\n// such entry, returns a null pointer. The client must not use the\n// iterator after the underlying GargantuanTable has been destroyed.\n//\n// This method is equivalent to:\n// std::unique_ptr<Iterator> iter = table->NewIterator();\n// iter->Seek(start_word);\n// return iter;\nstd::unique_ptr<Iterator> GetIterator(absl::string_view start_word) const;\n\n\n
However, do not be unnecessarily verbose or state the\ncompletely obvious.
\n\nWhen documenting function overrides, focus on the\nspecifics of the override itself, rather than repeating\nthe comment from the overridden function. In many of these\ncases, the override needs no additional documentation and\nthus no comment is required.
\n\nWhen commenting constructors and destructors, remember\nthat the person reading your code knows what constructors\nand destructors are for, so comments that just say\nsomething like \"destroys this object\" are not useful.\nDocument what constructors do with their arguments (for\nexample, if they take ownership of pointers), and what\ncleanup the destructor does. If this is trivial, just\nskip the comment. It is quite common for destructors not\nto have a header comment.
\n\nIf there is anything tricky about how a function does\nits job, the function definition should have an\nexplanatory comment. For example, in the definition\ncomment you might describe any coding tricks you use,\ngive an overview of the steps you go through, or explain\nwhy you chose to implement the function in the way you\ndid rather than using a viable alternative. For instance,\nyou might mention why it must acquire a lock for the\nfirst half of the function but why it is not needed for\nthe second half.
\n\nNote you should not just repeat the comments\ngiven with the function declaration, in the\n.h file or wherever. It's okay to\nrecapitulate briefly what the function does, but the\nfocus of the comments should be on how it does it.
In general the actual name of the variable should be\ndescriptive enough to give a good idea of what the variable\nis used for. In certain cases, more comments are required.
\n\nThe purpose of each class data member (also called an instance\nvariable or member variable) must be clear. If there are any\ninvariants (special values, relationships between members, lifetime\nrequirements) not clearly expressed by the type and name, they must be\ncommented. However, if the type and name suffice (int\nnum_events_;), no comment is needed.
In particular, add comments to describe the existence and meaning\nof sentinel values, such as nullptr or -1, when they are not\nobvious. For example:
\n\nprivate:\n // Used to bounds-check table accesses. -1 means\n // that we don't yet know how many entries the table has.\n int num_total_entries_;\n\n\n
All global variables should have a comment describing what they\nare, what they are used for, and (if unclear) why they need to be\nglobal. For example:
\n\n// The total number of test cases that we run through in this regression test.\nconst int kNumTestCases = 6;\n\n\n
In your implementation you should have comments in tricky,\nnon-obvious, interesting, or important parts of your code.
\n\nTricky or complicated code blocks should have comments\nbefore them.
\n\nWhen the meaning of a function argument is nonobvious, consider\none of the following remedies:
\n\nbool\n argument with an enum argument. This will make the argument\n values self-describing.// What are these arguments?\nconst DecimalNumber product = CalculateProduct(values, 7, false, nullptr);\n\n\n
versus:
\n\nProductOptions options;\noptions.set_precision_decimals(7);\noptions.set_use_cache(ProductOptions::kDontUseCache);\nconst DecimalNumber product =\n CalculateProduct(values, options, /*completion_callback=*/nullptr);\n\n\n
Do not state the obvious. In particular, don't literally describe what\ncode does, unless the behavior is nonobvious to a reader who understands\nC++ well. Instead, provide higher-level comments that describe why\nthe code does what it does, or make the code self-describing.
\n\nCompare this:\n\n// Find the element in the vector. <-- Bad: obvious!\nif (std::find(v.begin(), v.end(), element) != v.end()) {\n Process(element);\n}\n\n\nTo this:\n\n// Process \"element\" unless it was already processed.\nif (std::find(v.begin(), v.end(), element) != v.end()) {\n Process(element);\n}\n\n\nSelf-describing code doesn't need a comment. The comment from\nthe example above would be obvious:
\n\nif (!IsAlreadyProcessed(element)) {\n Process(element);\n}\n\n\n\nPay attention to punctuation, spelling, and grammar; it is\neasier to read well-written comments than badly written\nones.
\n\nComments should be as readable as narrative text, with\nproper capitalization and punctuation. In many cases,\ncomplete sentences are more readable than sentence\nfragments. Shorter comments, such as comments at the end\nof a line of code, can sometimes be less formal, but you\nshould be consistent with your style.
\n\nAlthough it can be frustrating to have a code reviewer\npoint out that you are using a comma when you should be\nusing a semicolon, it is very important that source code\nmaintain a high level of clarity and readability. Proper\npunctuation, spelling, and grammar help with that\ngoal.
\n\nUse TODO comments for code that is temporary,\na short-term solution, or good-enough but not perfect.
TODOs should include the string\nTODO in all caps, followed by the bug ID, name, e-mail address, or other identifier\nof the person or issue with the best context\nabout the problem referenced by the TODO.
Recommended styles are (in order of preference):
\n\n// TODO: bug 12345678 - Remove this after the 2047q4 compatibility window expires.\n// TODO: example.com/my-design-doc - Manually fix up this code the next time it's touched.\n// TODO(bug 12345678): Update this list after the Foo service is turned down.\n// TODO(John): Use a \"\\*\" here for concatenation operator.\n\n\n
If your TODO is of the form \"At a future\ndate do something\" make sure that you either include a\nvery specific date (\"Fix by November 2005\") or a very\nspecific event (\"Remove this code when all clients can\nhandle XML responses.\").
Coding style and formatting are pretty arbitrary, but a\n\nproject is much easier to follow\nif everyone uses the same style. Individuals may not agree with every\naspect of the formatting rules, and some of the rules may take\nsome getting used to, but it is important that all\n\nproject contributors follow the\nstyle rules so that\nthey can all read and understand\neveryone's code easily.
\n\n\n\nTo help you format code correctly, we've created a\n\nsettings file for emacs.
\nEach line of text in your code should be at most 80\ncharacters long.
\n\n\n\nWe recognize that this rule is\ncontroversial, but so much existing code already adheres\nto it, and we feel that consistency is important.
\nThose who favor this rule\nargue that it is rude to force them to resize\ntheir windows and there is no need for anything longer.\nSome folks are used to having several code windows\nside-by-side, and thus don't have room to widen their\nwindows in any case. People set up their work environment\nassuming a particular maximum window width, and 80\ncolumns has been the traditional standard. Why change\nit?
\n\n\nProponents of change argue that a wider line can make\ncode more readable. The 80-column limit is an hidebound\nthrowback to 1960s mainframes; modern equipment has wide screens that\ncan easily show longer lines.
\n\n\n80 characters is the maximum.
\n\nA line may exceed 80 characters if it is
\n\nNon-ASCII characters should be rare, and must use UTF-8\nformatting.
\n\nYou shouldn't hard-code user-facing text in source,\neven English, so use of non-ASCII characters should be\nrare. However, in certain cases it is appropriate to\ninclude such words in your code. For example, if your\ncode parses data files from foreign sources, it may be\nappropriate to hard-code the non-ASCII string(s) used in\nthose data files as delimiters. More commonly, unit test\ncode (which does not need to be localized) might\ncontain non-ASCII strings. In such cases, you should use\nUTF-8, since that is an encoding\nunderstood by most tools able to handle more than just\nASCII.
\n\nHex encoding is also OK, and encouraged where it\nenhances readability — for example,\n\"\\xEF\\xBB\\xBF\", or, even more simply,\n\"\\uFEFF\", is the Unicode zero-width\nno-break space character, which would be invisible\nif included in the source as straight UTF-8.
When possible, avoid the u8 prefix.\nIt has significantly different semantics starting in C++20\nthan in C++17, producing arrays of char8_t\nrather than char, and will change again in C++23.\n\n\n
You shouldn't use char16_t and\nchar32_t character types, since they're for\nnon-UTF-8 text. For similar reasons you also shouldn't\nuse wchar_t (unless you're writing code that\ninteracts with the Windows API, which uses\nwchar_t extensively).
Use only spaces, and indent 2 spaces at a time.
\n\nWe use spaces for indentation. Do not use tabs in your\ncode. You should set your editor to emit spaces when you\nhit the tab key.
\n\nReturn type on the same line as function name, parameters\non the same line if they fit. Wrap parameter lists which do\nnot fit on a single line as you would wrap arguments in a\nfunction call.
\n\nFunctions look like this:
\n\n\nReturnType ClassName::FunctionName(Type par_name1, Type par_name2) {\n DoSomething();\n ...\n}\n\n\nIf you have too much text to fit on one line:
\n\nReturnType ClassName::ReallyLongFunctionName(Type par_name1, Type par_name2,\n Type par_name3) {\n DoSomething();\n ...\n}\n\n\nor if you cannot fit even the first parameter:
\n\nReturnType LongClassName::ReallyReallyReallyLongFunctionName(\n Type par_name1, // 4 space indent\n Type par_name2,\n Type par_name3) {\n DoSomething(); // 2 space indent\n ...\n}\n\n\nSome points to note:
\n\nUnused parameters that are obvious from context may omit the name:
\n\nclass Foo {\n public:\n Foo(const Foo&) = delete;\n Foo& operator=(const Foo&) = delete;\n};\n\n\nUnused parameters that might not be obvious should comment out the variable\nname in the function definition:
\n\nclass Shape {\n public:\n virtual void Rotate(double radians) = 0;\n};\n\nclass Circle : public Shape {\n public:\n void Rotate(double radians) override;\n};\n\nvoid Circle::Rotate(double /*radians*/) {}\n\n\n// Bad - if someone wants to implement later, it's not clear what the\n// variable means.\nvoid Circle::Rotate(double) {}\n\n\nAttributes, and macros that expand to attributes, appear at the very\nbeginning of the function declaration or definition, before the\nreturn type:
\nABSL_ATTRIBUTE_NOINLINE void ExpensiveFunction();\n [[nodiscard]] bool IsOk();\n\n\n
Format parameters and bodies as for any other function, and capture\nlists like other comma-separated lists.
\n\nFor by-reference captures, do not leave a space between the\nampersand (&) and the variable name.
int x = 0;\nauto x_plus_n = [&x](int n) -> int { return x + n; }\n\nShort lambdas may be written inline as function arguments.
\nabsl::flat_hash_set<int> to_remove = {7, 8, 9};\nstd::vector<int> digits = {3, 9, 1, 8, 4, 7, 1};\ndigits.erase(std::remove_if(digits.begin(), digits.end(), [&to_remove](int i) {\n return to_remove.contains(i);\n }),\n digits.end());\n\n\nFloating-point literals should always have a radix point, with digits on both\nsides, even if they use exponential notation. Readability is improved if all\nfloating-point literals take this familiar form, as this helps ensure that they\nare not mistaken for integer literals, and that the\nE/e of the exponential notation is not mistaken for a\nhexadecimal digit. It is fine to initialize a floating-point variable with an\ninteger literal (assuming the variable type can exactly represent that integer),\nbut note that a number in exponential notation is never an integer literal.\n
float f = 1.f;\nlong double ld = -.5L;\ndouble d = 1248e6;\n\n\n
float f = 1.0f;\nfloat f2 = 1.0; // Also OK\nfloat f3 = 1; // Also OK\nlong double ld = -0.5L;\ndouble d = 1248.0e6;\n\n\n\n
Either write the call all on a single line, wrap the\narguments at the parenthesis, or start the arguments on a new\nline indented by four spaces and continue at that 4 space\nindent. In the absence of other considerations, use the\nminimum number of lines, including placing multiple arguments\non each line where appropriate.
\n\nFunction calls have the following format:
\nbool result = DoSomething(argument1, argument2, argument3);\n\n\n
If the arguments do not all fit on one line, they\nshould be broken up onto multiple lines, with each\nsubsequent line aligned with the first argument. Do not\nadd spaces after the open paren or before the close\nparen:
\nbool result = DoSomething(averyveryveryverylongargument1,\n argument2, argument3);\n\n\n
Arguments may optionally all be placed on subsequent\nlines with a four space indent:
\nif (...) {\n ...\n ...\n if (...) {\n bool result = DoSomething(\n argument1, argument2, // 4 space indent\n argument3, argument4);\n ...\n }\n\n\nPut multiple arguments on a single line to reduce the\nnumber of lines necessary for calling a function unless\nthere is a specific readability problem. Some find that\nformatting with strictly one argument on each line is\nmore readable and simplifies editing of the arguments.\nHowever, we prioritize for the reader over the ease of\nediting arguments, and most readability problems are\nbetter addressed with the following techniques.
\n\nIf having multiple arguments in a single line decreases\nreadability due to the complexity or confusing nature of the\nexpressions that make up some arguments, try creating\nvariables that capture those arguments in a descriptive name:
\nint my_heuristic = scores[x] * y + bases[x];\nbool result = DoSomething(my_heuristic, x, y, z);\n\n\n
Or put the confusing argument on its own line with\nan explanatory comment:
\nbool result = DoSomething(scores[x] * y + bases[x], // Score heuristic.\n x, y, z);\n\n\n
If there is still a case where one argument is\nsignificantly more readable on its own line, then put it on\nits own line. The decision should be specific to the argument\nwhich is made more readable rather than a general policy.
\n\nSometimes arguments form a structure that is important\nfor readability. In those cases, feel free to format the\narguments according to that structure:
\n// Transform the widget by a 3x3 matrix.\nmy_widget.Transform(x1, x2, x3,\n y1, y2, y3,\n z1, z2, z3);\n\n\n
Format a braced initializer list exactly like you would format a function\ncall in its place.
\n\nIf the braced list follows a name (e.g., a type or\nvariable name), format as if the {} were the\nparentheses of a function call with that name. If there\nis no name, assume a zero-length name.
// Examples of braced init list on a single line.\nreturn {foo, bar};\nfunctioncall({foo, bar});\nstd::pair<int, int> p{foo, bar};\n\n// When you have to wrap.\nSomeFunction(\n {\"assume a zero-length name before {\"},\n some_other_function_parameter);\nSomeType variable{\n some, other, values,\n {\"assume a zero-length name before {\"},\n SomeOtherType{\n \"Very long string requiring the surrounding breaks.\",\n some, other, values},\n SomeOtherType{\"Slightly shorter string\",\n some, other, values}};\nSomeType variable{\n \"This is too long to fit all in one line\"};\nMyType m = { // Here, you could also break before {.\n superlongvariablename1,\n superlongvariablename2,\n {short, interior, list},\n {interiorwrappinglist,\n interiorwrappinglist2}};\n\n\n\nAt a high level, looping or branching statements consist of the following\ncomponents:\n
if,\n else, switch, while, do,\n or for).if (condition) { // Good - no spaces inside parentheses, space before brace.\n DoOneThing(); // Good - two-space indent.\n DoAnotherThing();\n} else if (int a = f(); a != 3) { // Good - closing brace on new line, else on same line.\n DoAThirdThing(a);\n} else {\n DoNothing();\n}\n\n// Good - the same rules apply to loops.\nwhile (condition) {\n RepeatAThing();\n}\n\n// Good - the same rules apply to loops.\ndo {\n RepeatAThing();\n} while (condition);\n\n// Good - the same rules apply to loops.\nfor (int i = 0; i < 10; ++i) {\n RepeatAThing();\n}\n\n\nif(condition) {} // Bad - space missing after `if`.\nelse if ( condition ) {} // Bad - space between the parentheses and the condition.\nelse if (condition){} // Bad - space missing before `{`.\nelse if(condition){} // Bad - multiple spaces missing.\n\nfor (int a = f();a == 10) {} // Bad - space missing after the semicolon.\n\n// Bad - `if ... else` statement does not have braces everywhere.\nif (condition)\n foo;\nelse {\n bar;\n}\n\n// Bad - `if` statement too long to omit braces.\nif (condition)\n // Comment\n DoSomething();\n\n// Bad - `if` statement too long to omit braces.\nif (condition1 &&\n condition2)\n DoSomething();\n\n\nFor historical reasons, we allow one exception to the above rules: the curly\nbraces for the controlled statement or the line breaks inside the curly braces\nmay be omitted if as a result the entire statement appears on either a single\nline (in which case there is a space between the closing parenthesis and the\ncontrolled statement) or on two lines (in which case there is a line break\nafter the closing parenthesis and there are no braces).
\n\n// OK - fits on one line.\nif (x == kFoo) { return new Foo(); }\n\n// OK - braces are optional in this case.\nif (x == kFoo) return new Foo();\n\n// OK - condition fits on one line, body fits on another.\nif (x == kBar)\n Bar(arg1, arg2, arg3);\n\n\nThis exception does not apply to multi-keyword statements like\nif ... else or do ... while.
// Bad - `if ... else` statement is missing braces.\nif (x) DoThis();\nelse DoThat();\n\n// Bad - `do ... while` statement is missing braces.\ndo DoThis();\nwhile (x);\n\n\n
Use this style only when the statement is brief, and consider that loops and\nbranching statements with complex conditions or controlled statements may be\nmore readable with curly braces. Some\nprojects require curly braces always.
\n\ncase blocks in switch statements can have curly\nbraces or not, depending on your preference. If you do include curly braces,\nthey should be placed as shown below.
switch (var) {\n case 0: { // 2 space indent\n Foo(); // 4 space indent\n break;\n }\n default: {\n Bar();\n }\n}\n\n\nEmpty loop bodies should use either an empty pair of braces or\ncontinue with no braces, rather than a single semicolon.
while (condition) {} // Good - `{}` indicates no logic.\nwhile (condition) {\n // Comments are okay, too\n}\nwhile (condition) continue; // Good - `continue` indicates no logic.\n\n\nwhile (condition); // Bad - looks like part of `do-while` loop.\n\n\n
No spaces around period or arrow. Pointer operators do not\nhave trailing spaces.
\n\nThe following are examples of correctly-formatted\npointer and reference expressions:
\n\nx = *p;\np = &x;\nx = r.y;\nx = r->y;\n\n\n
Note that:
\n\n* or &.When referring to a pointer or reference (variable declarations or definitions, arguments, return\ntypes, template parameters, etc.), you must not place a space before the asterisk/ampersand. Use a\nspace to separate the type from the declared name (if present).
\n\n// These are fine.\nchar* c;\nconst std::string& str;\nint* GetPointer();\nstd::vector<char*> // Note no space between '*' and '>'\n\n\n
It is allowed (if unusual) to declare multiple variables in the same\ndeclaration, but it is disallowed if any of those have pointer or\nreference decorations. Such declarations are easily misread.
\n// Fine if helpful for readability.\nint x, y;\n\n
int x, *y; // Disallowed - no & or * in multiple declaration\nint *x, *y; // Disallowed - no & or * in multiple declaration\nint *x; // Disallowed - & or * must be left of the space\nchar * c; // Bad - spaces on both sides of *\nconst std::string & str; // Bad - spaces on both sides of &\n\n\n
When you have a boolean expression that is longer than the\nstandard line length, be\nconsistent in how you break up the lines.
\n\nIn this example, the logical AND operator is always at\nthe end of the lines:
\n\nif (this_one_thing > this_other_thing &&\n a_third_thing == a_fourth_thing &&\n yet_another && last_one) {\n ...\n}\n\n\nNote that when the code wraps in this example, both of\nthe && logical AND operators are at\nthe end of the line. This is more common in Google code,\nthough wrapping all operators at the beginning of the\nline is also allowed. Feel free to insert extra\nparentheses judiciously because they can be very helpful\nin increasing readability when used\nappropriately, but be careful about overuse. Also note that you\nshould always use the punctuation operators, such as\n&& and ~, rather than\nthe word operators, such as and and\ncompl.
Do not needlessly surround the return\nexpression with parentheses.
Use parentheses in return expr; only\nwhere you would use them in x = expr;.
return result; // No parentheses in the simple case.\n// Parentheses OK to make a complex expression more readable.\nreturn (some_long_condition &&\n another_condition);\n\n\n
return (value); // You wouldn't write var = (value);\nreturn(result); // return is not a function!\n\n\n\n\n
You may choose between =,\n(), and {}; the following are\nall correct:
int x = 3;\nint x(3);\nint x{3};\nstd::string name = \"Some Name\";\nstd::string name(\"Some Name\");\nstd::string name{\"Some Name\"};\n\n\nBe careful when using a braced initialization list {...}\non a type with an std::initializer_list constructor.\nA nonempty braced-init-list prefers the\nstd::initializer_list constructor whenever\npossible. Note that empty braces {} are special, and\nwill call a default constructor if available. To force the\nnon-std::initializer_list constructor, use parentheses\ninstead of braces.
std::vector<int> v(100, 1); // A vector containing 100 items: All 1s.\nstd::vector<int> v{100, 1}; // A vector containing 2 items: 100 and 1.\n\n\nAlso, the brace form prevents narrowing of integral\ntypes. This can prevent some types of programming\nerrors.
\n\nint pi(3.14); // OK -- pi == 3.\nint pi{3.14}; // Compile error: narrowing conversion.\n\n\nThe hash mark that starts a preprocessor directive should\nalways be at the beginning of the line.
\n\nEven when preprocessor directives are within the body\nof indented code, the directives should start at the\nbeginning of the line.
\n\n// Good - directives at beginning of line\n if (lopsided_score) {\n#if DISASTER_PENDING // Correct -- Starts at beginning of line\n DropEverything();\n# if NOTIFY // OK but not required -- Spaces after #\n NotifyClient();\n# endif\n#endif\n BackToNormal();\n }\n\n\n// Bad - indented directives\n if (lopsided_score) {\n #if DISASTER_PENDING // Wrong! The \"#if\" should be at beginning of line\n DropEverything();\n #endif // Wrong! Do not indent \"#endif\"\n BackToNormal();\n }\n\n\nSections in public, protected, and\nprivate order, each indented one space.
The basic format for a class definition (lacking the\ncomments, see Class\nComments for a discussion of what comments are\nneeded) is:
\n\nclass MyClass : public OtherClass {\n public: // Note the 1 space indent!\n MyClass(); // Regular 2 space indent.\n explicit MyClass(int var);\n ~MyClass() {}\n\n void SomeFunction();\n void SomeFunctionThatDoesNothing() {\n }\n\n void set_some_var(int var) { some_var_ = var; }\n int some_var() const { return some_var_; }\n\n private:\n bool SomeInternalFunction();\n\n int some_var_;\n int some_other_var_;\n};\n\n\nThings to note:
\n\npublic:, protected:,\n and private: keywords should be indented\n one space.public section should be first,\n followed by the protected and finally the\n private section.Constructor initializer lists can be all on one line or\nwith subsequent lines indented four spaces.
\n\nThe acceptable formats for initializer lists are:
\n\n// When everything fits on one line:\nMyClass::MyClass(int var) : some_var_(var) {\n DoSomething();\n}\n\n// If the signature and initializer list are not all on one line,\n// you must wrap before the colon and indent 4 spaces:\nMyClass::MyClass(int var)\n : some_var_(var), some_other_var_(var + 1) {\n DoSomething();\n}\n\n// When the list spans multiple lines, put each member on its own line\n// and align them:\nMyClass::MyClass(int var)\n : some_var_(var), // 4 space indent\n some_other_var_(var + 1) { // lined up\n DoSomething();\n}\n\n// As with any other code block, the close curly can be on the same\n// line as the open curly, if it fits.\nMyClass::MyClass(int var)\n : some_var_(var) {}\n\n\nThe contents of namespaces are not indented.
\n\nNamespaces do not add an\nextra level of indentation. For example, use:
\n\nnamespace {\n\nvoid foo() { // Correct. No extra indentation within namespace.\n ...\n}\n\n} // namespace\n\n\nDo not indent within a namespace:
\n\nnamespace {\n\n // Wrong! Indented when it should not be.\n void foo() {\n ...\n }\n\n} // namespace\n\n\nUse of horizontal whitespace depends on location. Never put\ntrailing whitespace at the end of a line.
\n\nint i = 0; // Two spaces before end-of-line comments.\n\nvoid f(bool b) { // Open braces should always have a space before them.\n ...\nint i = 0; // Semicolons usually have no space before them.\n// Spaces inside braces for braced-init-list are optional. If you use them,\n// put them on both sides!\nint x[] = { 0 };\nint x[] = {0};\n\n// Spaces around the colon in inheritance and initializer lists.\nclass Foo : public Bar {\n public:\n // For inline function implementations, put spaces between the braces\n // and the implementation itself.\n Foo(int b) : Bar(), baz_(b) {} // No spaces inside empty braces.\n void Reset() { baz_ = 0; } // Spaces separating braces from implementation.\n ...\n\n\nAdding trailing whitespace can cause extra work for\nothers editing the same file when they merge, as can\nremoving existing trailing whitespace. So, don't\nintroduce trailing whitespace. Remove it if you're\nalready changing that line, or do it in a separate\nclean-up\noperation (preferably when no one\nelse is working on the file).
\n\nif (b) { // Space after the keyword in conditions and loops.\n} else { // Spaces around else.\n}\nwhile (test) {} // There is usually no space inside parentheses.\nswitch (i) {\nfor (int i = 0; i < 5; ++i) {\n// Loops and conditions may have spaces inside parentheses, but this\n// is rare. Be consistent.\nswitch ( i ) {\nif ( test ) {\nfor ( int i = 0; i < 5; ++i ) {\n// For loops always have a space after the semicolon. They may have a space\n// before the semicolon, but this is rare.\nfor ( ; i < 5 ; ++i) {\n ...\n\n// Range-based for loops always have a space before and after the colon.\nfor (auto x : counts) {\n ...\n}\nswitch (i) {\n case 1: // No space before colon in a switch case.\n ...\n case 2: break; // Use a space after a colon if there's code after it.\n\n\n// Assignment operators always have spaces around them.\nx = 0;\n\n// Other binary operators usually have spaces around them, but it's\n// OK to remove spaces around factors. Parentheses should have no\n// internal padding.\nv = w * x + y / z;\nv = w*x + y/z;\nv = w * (x + z);\n\n// No spaces separating unary operators and their arguments.\nx = -5;\n++x;\nif (x && !y)\n ...\n\n\n
// No spaces inside the angle brackets (< and >), before\n// <, or between >( in a cast\nstd::vector<std::string> x;\ny = static_cast<char*>(x);\n\n// No spaces between type and pointer.\nstd::vector<char*> x;\n\n\n
Use vertical whitespace sparingly; unnecessary blank lines make it harder to\nsee overall code structure. Use blank lines only where they aid the reader in\nunderstanding the structure.
\n\nDo not add blank lines where indentation already provides clear delineation,\nsuch as at the start or end of a code block. Do use blank lines to separate code\ninto closely related chunks, analogous to paragraph breaks in prose. Within a\nstatement or declaration, usually only insert line breaks to stay within\nthe line length limit, or to attach a comment to only\npart of the contents.
\n\nThe coding conventions described above are mandatory.\nHowever, like all good rules, these sometimes have exceptions,\nwhich we discuss here.
\n\n\n\nYou may diverge from the rules when dealing with code that\ndoes not conform to this style guide.
\n\nIf you find yourself modifying code that was written\nto specifications other than those presented by this\nguide, you may have to diverge from these rules in order\nto stay consistent with the local conventions in that\ncode. If you are in doubt about how to do this, ask the\noriginal author or the person currently responsible for\nthe code. Remember that consistency includes\nlocal consistency, too.
\n\nWindows\nprogrammers have developed their own set of coding\nconventions, mainly derived from the conventions in Windows\nheaders and other Microsoft code. We want to make it easy\nfor anyone to understand your code, so we have a single set\nof guidelines for everyone writing C++ on any platform.
\n\nIt is worth reiterating a few of the guidelines that\nyou might forget if you are used to the prevalent Windows\nstyle:
\n\niNum). Use the Google naming\n conventions, including the .cc extension\n for source files.DWORD,\n HANDLE, etc. It is perfectly acceptable,\n and encouraged, that you use these types when calling\n Windows API functions. Even so, keep as close as you\n can to the underlying C++ types. For example, use\n const TCHAR* instead of\n LPCTSTR.#pragma once; instead use\n the standard Google include guards. The path in the\n include guards should be relative to the top of your\n project tree.#pragma and __declspec,\n unless you absolutely must. Using\n __declspec(dllimport) and\n __declspec(dllexport) is allowed; however,\n you must use them through macros such as\n DLLIMPORT and DLLEXPORT, so\n that someone can easily disable the extensions if they\n share the code.However, there are just a few rules that we\noccasionally need to break on Windows:
\n\n_ATL_NO_EXCEPTIONS to disable exceptions.\n You should investigate whether you can also disable\n exceptions in your STL, but if not, it is OK to turn on\n exceptions in the compiler. (Note that this is only to\n get the STL to compile. You should still not write\n exception handling code yourself.)StdAfx.h\n or precompile.h. To make your code easier\n to share with other projects, avoid including this file\n explicitly (except in precompile.cc), and\n use the /FI compiler option to include the\n file automatically.resource.h and contain only macros, do not\n need to conform to these style guidelines.This document defines formatting and style rules for HTML and CSS. It aims at\nimproving collaboration, code quality, and enabling supporting infrastructure.\nIt applies to raw, working files that use HTML and CSS, including Sass and GSS\nfiles. Tools are free to obfuscate, minify, and compile as long as the general\ncode quality is maintained.
\n\nUse HTTPS for embedded resources where possible.
\n\nAlways use HTTPS (https:) for images and other media files, style sheets, and\nscripts, unless the respective files are not available over HTTPS.
<!-- Not recommended: omits the protocol -->\n<script src=\"//ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js\"></script>\n\n<!-- Not recommended: uses HTTP -->\n<script src=\"http://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js\"></script>\n<!-- Recommended -->\n<script src=\"https://ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js\"></script>\n/* Not recommended: omits the protocol */\n@import '//fonts.googleapis.com/css?family=Open+Sans';\n\n/* Not recommended: uses HTTP */\n@import 'http://fonts.googleapis.com/css?family=Open+Sans';\n/* Recommended */\n@import 'https://fonts.googleapis.com/css?family=Open+Sans';\nIndent by 2 spaces at a time.
\n\nDon’t use tabs or mix tabs and spaces for indentation.
\n\n<ul>\n <li>Fantastic\n <li>Great\n</ul>\n.example {\n color: blue;\n}\nUse only lowercase.
\n\nAll code has to be lowercase: This applies to HTML element names, attributes,\nattribute values (unless text/CDATA), CSS selectors, properties, and property\nvalues (with the exception of strings).
<!-- Not recommended -->\n<A HREF=\"/\">Home</A>\n<!-- Recommended -->\n<img src=\"google.png\" alt=\"Google\">\n/* Not recommended */\ncolor: #E5E5E5;\n/* Recommended */\ncolor: #e5e5e5;\nRemove trailing white spaces.
\n\nTrailing white spaces are unnecessary and can complicate diffs.
\n\n<!-- Not recommended -->\n<p>What?_\n<!-- Recommended -->\n<p>Yes please.\nUse UTF-8 (no BOM).
\n\nMake sure your editor uses UTF-8 as character encoding, without a byte order\nmark.
\n\nSpecify the encoding in HTML templates and documents via <meta\ncharset=\"utf-8\">. Do not specify the encoding of style sheets as these assume\nUTF-8.
(More on encodings and when and how to specify them can be found in\nHandling character encodings in HTML and CSS.)
\n\nExplain code as needed, where possible.
\n\nUse comments to explain code: What does it cover, what purpose does it serve,\nwhy is respective solution used or preferred?
\n\n(This item is optional as it is not deemed a realistic expectation to always\ndemand fully documented code. Mileage may vary heavily for HTML and CSS code and\ndepends on the project’s complexity.)
\n\nMark todos and action items with TODO.
Highlight todos by using the keyword TODO only, not other common formats like\n@@.
Append action items after a colon as in TODO: action\nitem.
{# TODO: Revisit centering. #}\n<center>Test</center>\n<!-- TODO: Remove optional tags. -->\n<ul>\n <li>Apples</li>\n <li>Oranges</li>\n</ul>\nUse <!doctype html>.
Always put your HTML in\nno-quirks mode\nby including <!doctype html> at the beginning of the document.
A document without a doctype is rendered in “quirks mode”, and one with a\ndifferent doctype may be rendered in “limited-quirks mode”. These modes don’t\nfollow the widely-understood, widely-documented behavior for various core HTML\nand CSS constructs, and are likely to cause subtle failures and\nincompatibilities especially when re-using code that expects no-quirks mode.
\n\nUse valid HTML where possible.
\n\nUse valid HTML code unless that is not possible due to otherwise unattainable\nperformance goals regarding file size.
\n\nUse tools such as the\nW3C HTML validator\nto test.
\n\nUsing valid HTML is a measurable baseline quality attribute that contributes to\nlearning about technical requirements and constraints, and that ensures proper\nHTML usage.
\n\n<!-- Not recommended -->\n<title>Test</title>\n<article>This is only a test.\n<!-- Recommended -->\n<!doctype html>\n<meta charset=\"utf-8\">\n<title>Test</title>\n<article>This is only a test.</article>\nUse HTML according to its purpose.
\n\nUse elements (sometimes incorrectly called “tags”) for what they have been\ncreated for. For example, use heading elements for headings, p elements for\nparagraphs, a elements for anchors, etc.
Using HTML according to its purpose is important for accessibility, reuse, and\ncode efficiency reasons.
\n\n<!-- Not recommended -->\n<div onclick=\"goToRecommendations();\">All recommendations</div>\n<!-- Recommended -->\n<a href=\"recommendations/\">All recommendations</a>\nProvide alternative contents for multimedia.
\n\nFor multimedia, such as images, videos, animated objects via canvas, make sure\nto offer alternative access. For images that means use of meaningful alternative\ntext (alt) and for video and audio transcripts and captions, if available.
Providing alternative contents is important for accessibility reasons: A blind\nuser has few cues to tell what an image is about without @alt, and other users\nmay have no way of understanding what video or audio contents are about either.
(For images whose alt attributes would introduce redundancy, and for images\nwhose purpose is purely decorative which you cannot immediately use CSS for, use\nno alternative text, as in alt=\"\".)
<!-- Not recommended -->\n<img src=\"spreadsheet.png\">\n<!-- Recommended -->\n<img src=\"spreadsheet.png\" alt=\"Spreadsheet screenshot.\">\nSeparate structure from presentation from behavior.
\n\nStrictly keep structure (markup), presentation (styling), and behavior\n(scripting) apart, and try to keep the interaction between the three to an\nabsolute minimum.
\n\nThat is, make sure documents and templates contain only HTML and HTML that is\nsolely serving structural purposes. Move everything presentational into style\nsheets, and everything behavioral into scripts.
\n\nIn addition, keep the contact area as small as possible by linking as few style\nsheets and scripts as possible from documents and templates.
\n\nSeparating structure from presentation from behavior is important for\nmaintenance reasons. It is always more expensive to change HTML documents and\ntemplates than it is to update style sheets and scripts.
\n\n<!-- Not recommended -->\n<!doctype html>\n<title>HTML sucks</title>\n<link rel=\"stylesheet\" href=\"base.css\" media=\"screen\">\n<link rel=\"stylesheet\" href=\"grid.css\" media=\"screen\">\n<link rel=\"stylesheet\" href=\"print.css\" media=\"print\">\n<h1 style=\"font-size: 1em;\">HTML sucks</h1>\n<p>I’ve read about this on a few sites but now I’m sure:\n <u>HTML is stupid!!1</u>\n<center>I can’t believe there’s no way to control the styling of\n my website without doing everything all over again!</center>\n<!-- Recommended -->\n<!doctype html>\n<title>My first CSS-only redesign</title>\n<link rel=\"stylesheet\" href=\"default.css\">\n<h1>My first CSS-only redesign</h1>\n<p>I’ve read about this on a few sites but today I’m actually\n doing it: separating concerns and avoiding anything in the HTML of\n my website that is presentational.\n<p>It’s awesome!\nDo not use entity references.
\n\nThere is no need to use entity references like —, ”, or\n☺, assuming the same encoding (UTF-8) is used for files and editors as\nwell as among teams.
The only exceptions apply to characters with special meaning in HTML (like <\nand &) as well as control or “invisible” characters (like no-break spaces).
<!-- Not recommended -->\nThe currency symbol for the Euro is “&eur;”.\n<!-- Recommended -->\nThe currency symbol for the Euro is “€”.\nOmit optional tags (optional).
\n\nFor file size optimization and scannability purposes, consider omitting optional\ntags. The\nHTML5 specification\ndefines what tags can be omitted.
\n\n(This approach may require a grace period to be established as a wider guideline\nas it’s significantly different from what web developers are typically taught.\nFor consistency and simplicity reasons it’s best served omitting all optional\ntags, not just a selection.)
\n\n<!-- Not recommended -->\n<!doctype html>\n<html>\n <head>\n <title>Spending money, spending bytes</title>\n </head>\n <body>\n <p>Sic.</p>\n </body>\n</html>\n<!-- Recommended -->\n<!doctype html>\n<title>Saving money, saving bytes</title>\n<p>Qed.\ntype AttributesOmit type attributes for style sheets and scripts.
Do not use type attributes for style sheets (unless not using CSS) and scripts\n(unless not using JavaScript).
Specifying type attributes in these contexts is not necessary as HTML5 implies\ntext/css\nand\ntext/javascript\nas defaults. This can be safely done even for older browsers.
<!-- Not recommended -->\n<link rel=\"stylesheet\" href=\"https://www.google.com/css/maia.css\"\n type=\"text/css\">\n<!-- Recommended -->\n<link rel=\"stylesheet\" href=\"https://www.google.com/css/maia.css\">\n<!-- Not recommended -->\n<script src=\"https://www.google.com/js/gweb/analytics/autotrack.js\"\n type=\"text/javascript\"></script>\n<!-- Recommended -->\n<script src=\"https://www.google.com/js/gweb/analytics/autotrack.js\"></script>\nid AttributesAvoid unnecessary id attributes.
Prefer class attributes for styling and data attributes for scripting.
Where id attributes are strictly required, always include a hyphen in the\nvalue to ensure it does not match the JavaScript identifier syntax, e.g. use\nuser-profile rather than just profile or userProfile.
When an element has an id attribute, browsers will make that available as a\nnamed property on the global window prototype,\nwhich may cause unexpected behavior. While id attribute values containing a\nhyphen are still available as property names, these cannot be referenced as\nglobal JavaScript variables.
<!-- Not recommended: `window.userProfile` will resolve to reference the <div> node -->\n<div id=\"userProfile\"></div>\n<!-- Recommended: `id` attribute is required and its value includes a hyphen -->\n<div aria-describedby=\"user-profile\">\n …\n <div id=\"user-profile\"></div>\n …\n</div>\nUse a new line for every block, list, or table element, and indent every such\nchild element.
\n\nIndependent of the styling of an element (as CSS allows elements to assume a\ndifferent role per display property), put every block, list, or table element\non a new line.
Also, indent them if they are child elements of a block, list, or table element.
\n\n(If you run into issues around whitespace between list items it’s acceptable to\nput all li elements in one line. A linter is encouraged to throw a warning\ninstead of an error.)
<blockquote>\n <p><em>Space</em>, the final frontier.</p>\n</blockquote>\n<ul>\n <li>Moe\n <li>Larry\n <li>Curly\n</ul>\n<table>\n <thead>\n <tr>\n <th scope=\"col\">Income\n <th scope=\"col\">Taxes\n <tbody>\n <tr>\n <td>$ 5.00\n <td>$ 4.50\n</table>\nBreak long lines (optional).
\n\nWhile there is no column limit recommendation for HTML, you may consider\nwrapping long lines if it significantly improves readability.
\n\nWhen line-wrapping, each continuation line should be indented to distinguish\nwrapped attributes from child elements. Lines should be wrapped consistently\nwithin a project, ideally enforced by automated code formatting tools.
\n\n<button\n mat-icon-button\n color=\"primary\"\n class=\"menu-button\"\n (click)=\"openMenu()\"\n>\n <mat-icon>menu</mat-icon>\n</button>\n<button mat-icon-button color=\"primary\" class=\"menu-button\"\n (click)=\"openMenu()\">\n <mat-icon>menu</mat-icon>\n</button>\n<button\n mat-icon-button\n color=\"primary\"\n class=\"menu-button\"\n (click)=\"openMenu()\">\n <mat-icon>menu</mat-icon>\n</button>\n<button mat-icon-button\n color=\"primary\"\n class=\"menu-button\"\n (click)=\"openMenu()\">\n <mat-icon>menu</mat-icon>\n</button>\nWhen quoting attributes values, use double quotation marks.
\n\nUse double (\"\") rather than single quotation marks ('') around attribute\nvalues.
<!-- Not recommended -->\n<a class='maia-button maia-button-secondary'>Sign in</a>\n<!-- Recommended -->\n<a class=\"maia-button maia-button-secondary\">Sign in</a>\nUse valid CSS where possible.
\n\nUnless dealing with CSS validator bugs or requiring proprietary syntax, use\nvalid CSS code.
\n\nUse tools such as the\nW3C CSS validator\nto test.
\n\nUsing valid CSS is a measurable baseline quality attribute that allows to spot\nCSS code that may not have any effect and can be removed, and that ensures\nproper CSS usage.
\n\nUse meaningful or generic class names.
\n\nInstead of presentational or cryptic names, always use class names that reflect\nthe purpose of the element in question, or that are otherwise generic.
\n\nNames that are specific and reflect the purpose of the element should be\npreferred as these are most understandable and the least likely to change.
\n\nGeneric names are simply a fallback for elements that have no particular or no\nmeaning different from their siblings. They are typically needed as “helpers.”
\n\nUsing functional or generic names reduces the probability of unnecessary\ndocument or template changes.
\n\n/* Not recommended: meaningless */\n.yee-1901 {}\n\n/* Not recommended: presentational */\n.button-green {}\n.clear {}\n/* Recommended: specific */\n.gallery {}\n.login {}\n.video {}\n\n/* Recommended: generic */\n.aux {}\n.alt {}\nUse class names that are as short as possible but as long as necessary.
\n\nTry to convey what a class is about while being as brief as possible.
\n\nUsing class names this way contributes to acceptable levels of understandability\nand code efficiency.
\n\n/* Not recommended */\n.navigation {}\n.atr {}\n/* Recommended */\n.nav {}\n.author {}\nSeparate words in class names by a hyphen.
\n\nDo not concatenate words and abbreviations in selectors by any characters\n(including none at all) other than hyphens, in order to improve understanding\nand scannability.
\n\n/* Not recommended: does not separate the words “demo” and “image” */\n.demoimage {}\n\n/* Not recommended: uses underscore instead of hyphen */\n.error_status {}\n/* Recommended */\n.video-id {}\n.ads-sample {}\nPrefix selectors with an application-specific prefix (optional).
\n\nIn large projects as well as for code that gets embedded in other projects or on\nexternal sites use prefixes (as namespaces) for class names. Use short, unique\nidentifiers followed by a dash.
\n\nUsing namespaces helps preventing naming conflicts and can make maintenance\neasier, for example in search and replace operations.
\n\n.adw-help {} /* AdWords */\n.maia-note {} /* Maia */\nAvoid qualifying class names with type selectors.
\n\nUnless necessary (for example with helper classes), do not use element names in\nconjunction with classes.
\n\nAvoiding unnecessary ancestor selectors is useful for\nperformance reasons.
\n\n/* Not recommended */\nul.example {}\ndiv.error {}\n/* Recommended */\n.example {}\n.error {}\nAvoid ID selectors.
\n\nID attributes are expected to be unique across an entire page, which is\ndifficult to guarantee when a page contains many components worked on by many\ndifferent engineers. Class selectors should be preferred in all situations.
\n\n/* Not recommended */\n#example {}\n/* Recommended */\n.example {}\nUse shorthand properties where possible.
\n\nCSS offers a variety of\nshorthand\nproperties (like font) that should be used whenever possible, even in cases\nwhere only one value is explicitly set.
Using shorthand properties is useful for code efficiency and understandability.
\n\n/* Not recommended */\nborder-top-style: none;\nfont-family: palatino, georgia, serif;\nfont-size: 100%;\nline-height: 1.6;\npadding-bottom: 2em;\npadding-left: 1em;\npadding-right: 1em;\npadding-top: 0;\n/* Recommended */\nborder-top: 0;\nfont: 100%/1.6 palatino, georgia, serif;\npadding: 0 1em 2em;\nOmit unit specification after “0” values, unless required.
\n\nDo not use units after 0 values unless they are required.
flex: 0px; /* This flex-basis component requires a unit. */\nflex: 1 1 0px; /* Not ambiguous without the unit, but needed in IE11. */\nmargin: 0;\npadding: 0;\nAlways include leading “0”s in values.
\n\nPut 0s in front of values or lengths between -1 and 1.
font-size: 0.8em;\nUse 3 character hexadecimal notation where possible.
\n\nFor color values that permit it, 3 character hexadecimal notation is shorter and\nmore succinct.
\n\n/* Not recommended */\ncolor: #eebbcc;\n/* Recommended */\ncolor: #ebc;\nAvoid using !important declarations.
These declarations break the natural cascade of CSS and make it difficult to\nreason about and compose styles. Use\nselector specificity\nto override properties instead.
\n\n/* Not recommended */\n.example {\n font-weight: bold !important;\n}\n/* Recommended */\n.example {\n font-weight: bold;\n}\nAvoid user agent detection as well as CSS “hacks”—try a different approach\nfirst.
\n\nIt’s tempting to address styling differences over user agent detection or\nspecial CSS filters, workarounds, and hacks. Both approaches should be\nconsidered last resort in order to achieve and maintain an efficient and\nmanageable code base. Put another way, giving detection and hacks a free pass\nwill hurt projects in the long run as projects tend to take the way of least\nresistance. That is, allowing and making it easy to use detection and hacks\nmeans using detection and hacks more frequently—and more frequently is too\nfrequently.
\n\nAlphabetize declarations (optional).
\n\nSort declarations consistently within a project. In the absence of tooling to\nautomate and enforce a consistent sort order, consider putting declarations in\nalphabetical order in order to achieve consistent code in a way that is easy to\nlearn, remember, and manually maintain.
\n\nIgnore vendor-specific prefixes for sorting purposes. However, multiple\nvendor-specific prefixes for a certain CSS property should be kept sorted (e.g.\n-moz prefix comes before -webkit).
\n\nbackground: fuchsia;\nborder: 1px solid;\n-moz-border-radius: 4px;\n-webkit-border-radius: 4px;\nborder-radius: 4px;\ncolor: black;\ntext-align: center;\ntext-indent: 2em;\nIndent all block content.
\n\nIndent all\nblock content,\nthat is rules within rules as well as declarations, so to reflect hierarchy and\nimprove understanding.
\n\n@media screen, projection {\n\n html {\n background: #fff;\n color: #444;\n }\n\n}\nUse a semicolon after every declaration.
\n\nEnd every declaration with a semicolon for consistency and extensibility\nreasons.
\n\n/* Not recommended */\n.test {\n display: block;\n height: 100px\n}\n/* Recommended */\n.test {\n display: block;\n height: 100px;\n}\nUse a space after a property name’s colon.
\n\nAlways use a single space between property and value (but no space between\nproperty and colon) for consistency reasons.
\n\n/* Not recommended */\nh3 {\n font-weight:bold;\n}\n/* Recommended */\nh3 {\n font-weight: bold;\n}\nUse a space between the last selector and the declaration block.
\n\nAlways use a single space between the last selector and the opening brace that\nbegins the\ndeclaration block.
\n\nThe opening brace should be on the same line as the last selector in a given\nrule.
\n\n/* Not recommended: missing space */\n.video{\n margin-top: 1em;\n}\n\n/* Not recommended: unnecessary line break */\n.video\n{\n margin-top: 1em;\n}\n/* Recommended */\n.video {\n margin-top: 1em;\n}\nSeparate selectors and declarations by new lines.
\n\nAlways start a new line for each selector and declaration.
\n\n/* Not recommended */\na:focus, a:active {\n position: relative; top: 1px;\n}\n/* Recommended */\nh1,\nh2,\nh3 {\n font-weight: normal;\n line-height: 1.2;\n}\nSeparate rules by new lines.
\n\nAlways put a blank line (two line breaks) between rules.
\n\nhtml {\n background: #fff;\n}\n\nbody {\n margin: auto;\n width: 50%;\n}\nUse single ('') rather than double (\"\") quotation marks for attribute\nselectors 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\nmarks—single quotation marks are not permitted.
/* Not recommended */\n@import url(\"https://www.google.com/css/maia.css\");\n\nhtml {\n font-family: \"open sans\", arial, sans-serif;\n}\n/* Recommended */\n@import url(https://www.google.com/css/maia.css);\n\nhtml {\n font-family: 'open sans', arial, sans-serif;\n}\nGroup sections by a section comment (optional).
\n\nIf possible, group style sheet sections together by using comments. Separate\nsections with new lines.
\n\n/* Header */\n\n.adw-header {}\n\n/* Footer */\n\n.adw-footer {}\n\n/* Gallery */\n\n.adw-gallery {}\nBe consistent.
\n\nIf you’re editing code, take a few minutes to look at the code around you and\ndetermine its style. If they use spaces around all their arithmetic operators,\nyou should too. If their comments have little boxes of hash marks around them,\nmake your comments have little boxes of hash marks around them too.
\n\nThe point of having style guidelines is to have a common vocabulary of coding so\npeople can concentrate on what you’re saying rather than on how you’re saying\nit. We present global style rules here so people know the vocabulary, but local\nstyle is also important. If code you add to a file looks drastically different\nfrom the existing code around it, it throws readers out of their rhythm when\nthey go to read it. Avoid this.
\n\n The style guide has moved to\n htmlcssguide.html\n
\nThis document serves as the complete definition of Google's coding standards for\nsource code in the Java™ Programming Language. A Java source file is described as being in\nGoogle Style if and only if it adheres to the rules herein.
\n\n\n\nLike other programming style guides, the issues covered span not only aesthetic issues of\nformatting, but other types of conventions or coding standards as well. However, this document\nfocuses primarily on the hard-and-fast rules that we follow universally, and\navoids giving advice that isn't clearly enforceable (whether by human or tool).\n
\n\n\n\n\n\nIn this document, unless otherwise clarified:
\n\n@interface).Other \"terminology notes\" will appear occasionally throughout the document.
\n\nExample code in this document is non-normative. That is, while the examples\nare in Google Style, they may not illustrate the only stylish way to represent the\ncode. Optional formatting choices made in examples should not be enforced as rules.
\n\n\nFor a source file containing classes, the file name consists of the case-sensitive name of the\ntop-level class (of which there is exactly one), plus the\n.java extension.
Source files are encoded in UTF-8.
\n\nAside from the line terminator sequence, the ASCII horizontal space\ncharacter (0x20) is the only whitespace character that appears\nanywhere in a source file. This implies that:
\n\nchar and string literals and in\n text blocks.For any character that has a\n\n special escape sequence\n(\\b,\n\\t,\n\\n,\n\\f,\n\\r,\n\\s,\n\\\",\n\\' and\n\\\\), that sequence\nis used rather than the corresponding octal\n(e.g. \\012) or Unicode\n(e.g. \\u000a) escape.
For the remaining non-ASCII characters, either the actual Unicode character\n(e.g. ∞) or the equivalent Unicode escape\n(e.g. \\u221e) is used. The choice depends only on\nwhich makes the code easier to read and understand, although Unicode escapes\noutside string literals and comments are strongly discouraged.
Tip: In the Unicode escape case, and occasionally even when actual\nUnicode characters are used, an explanatory comment can be very helpful.
\n\nExamples:
\n\n| Example | \nDiscussion | \n
|---|---|
String unitAbbrev = \"μs\"; | \n Best: perfectly clear even without a comment. | \n
String unitAbbrev = \"\\u03bcs\"; // \"μs\" | \n Allowed, but there's no reason to do this. | \n
String unitAbbrev = \"\\u03bcs\";\n // Greek letter mu, \"s\" | \n Allowed, but awkward and prone to mistakes. | \n
String unitAbbrev = \"\\u03bcs\"; | \n Poor: the reader has no idea what this is. | \n
return '\\ufeff' + content;\n // byte order mark | \n Good: use escapes for non-printable characters, and comment if necessary. | \n
Tip: Never make your code less readable simply out of fear that\nsome programs might not handle non-ASCII characters properly. If that should happen, those\nprograms are broken and they must be fixed.
\n\n\n\nAn ordinary source file consists of these sections, in order:
\n\nExactly one blank line separates each section that is present.
\n\nA package-info.java file is the same, but without the class declaration.
A module-info.java file does not contain a package declaration and replaces the\nclass declaration with a module declaration, but otherwise follows the same structure.
If license or copyright information belongs in a file, it belongs here.
\n\n\n\n\nThe package declaration is not line-wrapped. The column limit (Section 4.4,\nColumn limit: 100) does not apply to package declarations.
\n\n\nWildcard (\"on-demand\") imports, static or otherwise, are not\n used.
\n\nImports are not line-wrapped. The column limit (Section 4.4,\nColumn limit: 100) does not apply to imports.
\n\nImports are ordered as follows:
\n\nIf there are both static and non-static imports, a single blank line separates the two\ngroups. There are no other blank lines between imports.
\n\nWithin each group the imported names appear in ASCII sort order. (Note:\nthis is not the same as the import lines being in ASCII sort order, since '.'\nsorts before ';'.)
\n\n\n\nStatic import is not used for static nested classes. They are imported with\nnormal imports.
\n\nEach top-level class resides in a source file of its own.
\n\n\nThe order you choose for the members and initializers of your class can have a great effect on\nlearnability. However, there's no single correct recipe for how to do it; different classes may\norder their contents in different ways.
\n\nWhat is important is that each class uses some logical order, which its\nmaintainer could explain if asked. For example, new methods are not just habitually added to the end\nof the class, as that would yield \"chronological by date added\" ordering, which is not a logical\nordering.
\n\n\n\n\nMethods of a class that share the same name appear in a single contiguous group with no other\n members in between. The same applies to multiple constructors. This rule applies even when\n modifiers such as static or\n private differ between the methods or constructors.
Module directives are ordered as follows:
\n\nrequires directives in a single block.exports directives in a single block.opens directives in a single block.uses directives in a single block.provides directives in a single block.A single blank line separates each block that is present.
\n\nTerminology Note: block-like construct refers to\nthe body of a class, method, constructor, or switch. Note that, by Section 4.8.3.1 on\narray initializers, any array initializer\nmay optionally be treated as if it were a block-like construct.
\n\n\nBraces are used with\nif,\nelse,\nfor,\ndo and\nwhile statements, even when the\nbody is empty or contains only a single statement.
Other optional braces, such as those in a lambda expression, remain optional.
\n\nBraces follow the Kernighan and Ritchie style for nonempty blocks and block-like\n constructs:
\n\nelse or a comma.Exception: In places where these rules allow a single statement ending with a semicolon\n(;), a block of statements can appear, and the opening\nbrace of this block is preceded by a line break. Blocks like these are typically introduced to\nlimit the scope of local variables.
Examples:
\n\nreturn () -> {\n while (condition()) {\n method();\n }\n};\n\nreturn new MyClass() {\n @Override public void method() {\n if (condition()) {\n try {\n something();\n } catch (ProblemException e) {\n recover();\n }\n } else if (otherCondition()) {\n somethingElse();\n } else {\n lastThing();\n }\n {\n int x = foo();\n frob(x);\n }\n }\n};\n\n\nA few exceptions for enum classes are given in Section 4.8.1,\nEnum classes.
\n\n\nAn empty block or block-like construct may be in K & R style (as described in\nSection 4.1.2). Alternatively, it may be closed immediately\nafter it is opened, with no characters or line break in between\n({}), unless it is part of a\nmulti-block statement (one that directly contains multiple blocks:\nif/else or\ntry/catch/finally).
Examples:
\n\n // This is acceptable\n void doNothing() {}\n\n // This is equally acceptable\n void doNothingElse() {\n }\n\n // This is not acceptable: No concise empty blocks in a multi-block statement\n try {\n doSomething();\n } catch (Exception e) {}\n\n\nEach time a new block or block-like construct is opened, the indent increases by two\nspaces. When the block ends, the indent returns to the previous indent level. The indent level\napplies to both code and comments throughout the block. (See the example in Section 4.1.2,\nNonempty blocks: K & R Style.)
\n\nEach statement is followed by a line break.
\n\n\nJava code has a column limit of 100 characters. A \"character\" means any Unicode code point.\nExcept as noted below, any line that would exceed this limit must be line-wrapped, as explained in\nSection 4.5, Line-wrapping.\n
\n\nEach Unicode code point counts as one character, even if its display width is\ngreater or less. For example, if using\nfullwidth characters,\nyou may choose to wrap the line earlier than where this rule strictly requires.
\n\nExceptions:
\n\npackage declarations and\n imports (see Sections 3.2 Package declarations and\n 3.3 Imports).Terminology Note: When code that might otherwise\noccupy a single line is divided into multiple lines, this activity is called\nline-wrapping.
\n\nThere is no comprehensive, deterministic formula showing exactly how to line-wrap in\nevery situation. Very often there are several valid ways to line-wrap the same piece of code.
\n\nNote: While the typical reason for line-wrapping is to avoid\noverflowing the column limit, even code that would in fact fit within the column limit may\nbe line-wrapped at the author's discretion.
\n\nTip: Extracting a method or local variable may solve the problem\nwithout the need to line-wrap.
\n\nThe prime directive of line-wrapping is: prefer to break at a\nhigher syntactic level. Also:
\n\n.)::)<T extends Foo & Bar>)catch (FooException | BarException e)).for (\"foreach\") statement.() that follows it.,) stays attached to the token that\n precedes it.MyLambda<String, Long, Object> lambda =\n (String label, Long value, Object obj) -> {\n ...\n };\n\nPredicate<String> predicate = str ->\n longExpressionInvolving(str);\n\nswitch (x) {\n case ColorPoint(Color color, Point(int x, int y)) ->\n handleColorPoint(color, x, y);\n ...\n}\n\n Note: The primary goal for line wrapping is to have clear\ncode, not necessarily code that fits in the smallest number of lines.
\n\n\nWhen line-wrapping, each line after the first (each continuation line) is indented\nat least +4 from the original line.
\n\nWhen there are multiple continuation lines, indentation may be varied beyond +4 as\ndesired. In general, two continuation lines use the same indentation level if and only if they\nbegin with syntactically parallel elements.
\n\nSection 4.6.3 on Horizontal alignment addresses\nthe discouraged practice of using a variable number of spaces to align certain tokens with\nprevious lines.
\n\nA single blank line always appears:
\n\nA single blank line may also appear anywhere it improves readability, for example between\nstatements to organize the code into logical subsections. A blank line before the first member or\ninitializer, or after the last member or initializer of the class, is neither encouraged nor\ndiscouraged.\n\n
Multiple consecutive blank lines are permitted, but never required (or encouraged).
\n\nBeyond where required by the language or other style rules, and apart from within literals,\ncomments and Javadoc, a single ASCII space also appears in the following places\nonly.
\n\nif,\n for or\n catch, from an open parenthesis\n (()\n that follows it on that lineelse or\n catch, from a closing curly brace\n (}) that precedes it on that line{), with two exceptions:\n @SomeAnnotation({a, b}) (no space is used)String[][] x = {{\"foo\"}}; (no space is required\n between {{, by item 10 below)<T extends Foo & Bar>catch (FooException | BarException e):) in an enhanced\n for (\"foreach\") statement(String str) -> str.length()case \"FOO\" -> bar();::) of a method reference, which\n is written like Object::toString.), which is written like\n object.toString(),:; or the closing parenthesis\n ()) of a cast//) which\n begins a comment. Multiple spaces are allowed.//) which begins a comment\n and the comment's text. Multiple spaces are allowed.List<String> listnew int[] {5, 6} and\n new int[] { 5, 6 } are both valid[] or\n ....This rule is never interpreted as requiring or forbidding additional space at the start or\nend of a line; it addresses only interior space.
\n\nTerminology Note: Horizontal alignment is the\npractice of adding a variable number of additional spaces in your code with the goal of making\ncertain tokens appear directly below certain other tokens on previous lines.
\n\nThis practice is permitted, but is never required by Google Style. It is not\neven required to maintain horizontal alignment in places where it was already used.
\n\nHere is an example without alignment, then using alignment:
\n\nprivate int x; // this is fine\nprivate Color color; // this too\n\nprivate int x; // permitted, but future edits\nprivate Color color; // may leave it unaligned\n\n\n
Tip: Alignment can aid readability, but attempting to preserve\nalignment for its own sake creates future problems. For example, consider a change that touches only\none line. If that change disrupts the previous alignment, it's important **not** to introduce\nadditional changes on nearby lines simply to realign them. Introducing formatting changes on\notherwise unaffected lines corrupts version history, slows down reviewers, and exacerbates merge\nconflicts. These practical concerns take priority over alignment.
\n\n\nOptional grouping parentheses are omitted only when author and reviewer agree that there is no\nreasonable chance the code will be misinterpreted without them, nor would they have made the code\neasier to read. It is not reasonable to assume that every reader has the entire Java\noperator precedence table memorized.
\n\nAfter the comma that follows an enum constant, a line break is optional. Additional blank\nlines (usually just one) are also allowed. This is one possibility:\n\n
private enum Answer {\n YES {\n @Override public String toString() {\n return \"yes\";\n }\n },\n\n NO,\n MAYBE\n}\n\n\nAn enum class with no methods and no documentation on its constants may optionally be formatted\nas if it were an array initializer (see Section 4.8.3.1 on\narray initializers).
\n\nprivate enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }\n\n\nSince enum classes are classes, all other rules for formatting classes apply.
\n\n\nEvery variable declaration (field or local) declares only one variable: declarations such as\nint a, b; are not used.
Exception: Multiple variable declarations are acceptable in the header of a\nfor loop.
Local variables are not habitually declared at the start of their containing\nblock or block-like construct. Instead, local variables are declared close to the point they are\nfirst used (within reason), to minimize their scope. Local variable declarations typically have\ninitializers, or are initialized immediately after declaration.
\n\nAny array initializer may optionally be formatted as if it were a \"block-like\nconstruct.\" For example, the following are all valid (not an exhaustive\nlist):
\n\nnew int[] { new int[] {\n 0, 1, 2, 3 0,\n} 1,\n 2,\nnew int[] { 3,\n 0, 1, }\n 2, 3\n} new int[]\n {0, 1, 2, 3}\n\n\nThe square brackets form a part of the type, not the variable:\nString[] args, not\nString args[].
For historical reasons, the Java language has two distinct syntaxes for switch, which we can call old-style and\nnew-style. New-style switches use an arrow\n(->) after the switch labels, while old-style switches\nuse a colon (:).\n\n
Terminology Note: Inside the braces of a\nswitch block are either one or more switch rules (new-style);\nor one or more statement groups (old-style). A switch\nrule consists of a switch label (case ...\nor default) followed by -> and an expression, block, or throw. A statement group consists of one or more switch labels each followed by\na colon, then one or more statements, or, for the last statement group, zero or\nmore statements. (These definitions match the Java Language Specification,\n§14.11.)
As with any other block, the contents of a switch block are indented +2. Each switch label\nstarts with this +2 indentation.
\n\nIn a new-style switch, a switch rule can be written on a single line if it otherwise follows\nGoogle style. (It must not exceed the column limit, and if it contains a non-empty block then\nthere must be a line break after {.) The line-wrapping\nrules of Section 4.5 apply, including the +4 indent for\ncontinuation lines. For a switch rule with a non-empty block after the arrow, the same rules apply\nas for blocks elsewhere: lines between { and\n} are indented a further +2 relative to the line with the\nswitch label.\n\n
switch (number) {\n case 0, 1 -> handleZeroOrOne();\n case 2 ->\n handleTwoWithAnExtremelyLongMethodCallThatWouldNotFitOnTheSameLine();\n default -> {\n logger.atInfo().log(\"Surprising number %s\", number);\n handleSurprisingNumber(number);\n }\n}\n\n\nIn an old-style switch, the colon of each switch label is followed by a line break. The\nstatements within a statement group are indented a further +2.
\n\n\nWithin an old-style switch block, each statement group either terminates abruptly (with a\nbreak,\ncontinue,\nreturn or thrown exception), or is marked with a comment\nto indicate that execution will or might continue into the next statement group. Any\ncomment that communicates the idea of fall-through is sufficient (typically\n// fall through). This special comment is not required in\nthe last statement group of the switch block. Example:
switch (input) {\n case 1:\n case 2:\n prepareOneOrTwo();\n // fall through\n case 3:\n handleOneTwoOrThree();\n break;\n default:\n handleLargeNumber(input);\n}\n\n\nNotice that no comment is needed after case 1:, only\nat the end of the statement group.
There is no fall-through in new-style switches.
\n\ndefault labelThe Java language requires switch expressions and many kinds of switch statements to be\nexhaustive. That effectively means that every possible value that could be switched on will\nbe matched by one of the switch labels. A switch is exhaustive if it has a default label, but also for example if the value being switched\non is an enum and every value of the enum is matched by a switch label. Google Style requires\nevery switch to be exhaustive, even those where the language itself does not require it.\nThis may require adding a default label, even if it\ncontains no code.
Switch expressions must be new-style switches:
\n\n return switch (list.size()) {\n case 0 -> \"\";\n case 1 -> list.getFirst();\n default -> String.join(\", \", list);\n };\n\n\n\nType-use annotations appear immediately before the annotated type. An annotation is a type-use\nannotation if it is meta-annotated with\n@Target(ElementType.TYPE_USE). Example:
final @Nullable String name;\n\npublic @Nullable Person getPersonByName(String name);\n\n\n
Annotations applying to a class, package, or module declaration appear immediately after the\ndocumentation block, and each annotation is listed on a line of its own (that is, one annotation\nper line). These line breaks do not constitute line-wrapping (Section\n4.5, Line-wrapping), so the indentation level is not\nincreased. Examples:
\n\n/** This is a class. */\n@Deprecated\n@CheckReturnValue\npublic final class Frozzler { ... }\n\n/** This is a package. */\n@Deprecated\n@CheckReturnValue\npackage com.example.frozzler;\n\n
/** This is a module. */\n@Deprecated\n@SuppressWarnings(\"CheckReturnValue\")\nmodule com.example.frozzler { ... }\n\n\nThe rules for annotations on method and constructor declarations are the same as the\nprevious section. Example:
\n\n@Deprecated\n@Override\npublic String getNameIfPresent() { ... }\n\n\nException: A single parameterless annotation\nmay instead appear together with the first line of the signature, for example:
\n\n@Override public int hashCode() { ... }\n\n\nAnnotations applying to a field also appear immediately after the documentation block, but in\nthis case, multiple annotations (possibly parameterized) may be listed on the same line;\nfor example:
\n\n@Partial @Mock DataLoader loader;\n\n\n
There are no specific rules for formatting annotations on parameters or local variables (except,\nof course, when the annotation is a type-use annotation).
\n\n\nThis section addresses implementation comments. Javadoc is addressed separately in\nSection 7, Javadoc.
\n\nAny line break may be preceded by arbitrary whitespace followed by an implementation comment.\nSuch a comment renders the line non-blank.
\n\nBlock comments are indented at the same level as the surrounding code. They may be in\n/* ... */ style or\n// ... style. For multi-line\n/* ... */ comments, subsequent lines must start with\n* aligned with the * on the previous line.
/*\n * This is // And so /* Or you can\n * okay. // is this. * even do this. */\n */\n\n\n\n
Comments are not enclosed in boxes drawn with asterisks or other characters.
\n\nTip: When writing multi-line comments, use the\n/* ... */ style if you want automatic code formatters to\nre-wrap the lines when necessary (paragraph-style). Most formatters don't re-wrap lines in\n// ... style comment blocks.
Use TODO comments for code that is temporary, a short-term solution, or good-enough\n but not perfect.
A TODO comment begins with the word TODO in all caps, a following\n colon, and a link to a resource that contains the context, ideally a bug reference. A bug\n reference is preferable because bugs are tracked and have follow-up comments. Follow this piece of\n context with an explanatory string introduced with a hyphen -.
The purpose is to have a consistent TODO format that can be searched to find out how\n to get more details.
// TODO: crbug.com/12345678 - Remove this after the 2047q4 compatibility window expires.\n\n\n
Avoid adding TODOs that refer to an individual or team as the context:
\n\n// TODO: @yourusername - File an issue and use a '*' for repetition.\n\n\n
If your TODO is of the form \"At a future date do something\" make sure that you\n either include a very specific date (\"Fix by November 2005\") or a very specific event (\"Remove\n this code when all clients can handle XML responses.\").
Class and member modifiers, when present, appear in the order\nrecommended by the Java Language Specification:\n
\n\npublic protected private abstract default static final sealed non-sealed\n transient volatile synchronized native strictfp\n\n\n
Modifiers on requires module directives, when present, appear in the following\norder:
transitive static\n\n
long-valued integer literals use an uppercase L suffix, never\nlowercase (to avoid confusion with the digit 1). For example, 3000000000L\nrather than 3000000000l.
The opening \"\"\" of a text block is always on a new line. That line may\n either follow the same indentation rules as other constructs, or it may have no indentation at all\n (so it starts at the left margin). The closing \"\"\" is on a new line\n with the same indentation as the opening \"\"\", and may be followed on the\n same line by further code. Each line of text in the text block is indented at least as much as the\n opening and closing \"\"\". (If a line is indented further, then the string\n literal defined by the text block will have space at the start of that line.)\n\n
The contents of a text block may exceed the column limit.\n\n\n
Identifiers use only ASCII letters and digits, and, in a small number of cases noted below,\nunderscores. Thus each valid identifier name is matched by the regular expression\n\\w+ .
In Google Style, special prefixes or suffixes are not used. For example, these\nnames are not Google Style: name_, mName,\ns_name and kName.
Package and module names use only lowercase letters and digits (no underscores). Consecutive\nwords are simply concatenated together. For example, com.example.deepspace, not\ncom.example.deepSpace or\ncom.example.deep_space.
Class names are written in UpperCamelCase.
\n\nClass names are typically nouns or noun phrases. For example,\nCharacter or\nImmutableList. Interface names may also be nouns or\nnoun phrases (for example, List), but may sometimes be\nadjectives or adjective phrases instead (for example,\nReadable).
There are no specific rules or even well-established conventions for naming annotation types.
\n\nA test class has a name that ends with Test,\nfor example, HashIntegrationTest.\nIf it covers a single class, its name is the name of that class\nplus Test, for example HashImplTest.
Method names are written in lowerCamelCase.
\n\nMethod names are typically verbs or verb phrases. For example,\nsendMessage or\nstop.
Underscores may appear in JUnit test method names to separate logical components of the\nname, with each component written in lowerCamelCase, for\nexample transferMoney_deductsFromSource. There is no One\nCorrect Way to name test methods.
Constant names use UPPER_SNAKE_CASE: all uppercase\nletters, with each word separated from the next by a single underscore. But what is a\nconstant, exactly?
Constants are static final fields whose contents are deeply immutable and whose methods have no\ndetectable side effects. Examples include primitives, strings, immutable value classes, and anything\nset to null. If any of the instance's observable state can change, it is not a\nconstant. Merely intending to never mutate the object is not enough. Examples:
// Constants\nstatic final int NUMBER = 5;\nstatic final ImmutableList<String> NAMES = ImmutableList.of(\"Ed\", \"Ann\");\nstatic final Map<String, Integer> AGES = ImmutableMap.of(\"Ed\", 35, \"Ann\", 32);\nstatic final Joiner COMMA_JOINER = Joiner.on(','); // because Joiner is immutable\nstatic final SomeMutableType[] EMPTY_ARRAY = {};\n\n// Not constants\nstatic String nonFinal = \"non-final\";\nfinal String nonStatic = \"non-static\";\nstatic final Set<String> mutableCollection = new HashSet<String>();\nstatic final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable);\nstatic final ImmutableMap<String, SomeMutableType> mutableValues =\n ImmutableMap.of(\"Ed\", mutableInstance, \"Ann\", mutableInstance2);\nstatic final Logger logger = Logger.getLogger(MyClass.getName());\nstatic final String[] nonEmptyArray = {\"these\", \"can\", \"change\"};\n\n\nThese names are typically nouns or noun phrases.
\n\nNon-constant field names (static or otherwise) are written\nin lowerCamelCase.
\n\nThese names are typically nouns or noun phrases. For example,\ncomputedValues or\nindex.
Parameter names are written in lowerCamelCase.
\n\nOne-character parameter names in public methods should be avoided.
\n\nLocal variable names are written in lowerCamelCase.
\n\nEven when final and immutable, local variables are not considered to be constants, and should not\nbe styled as constants.
\n\nEach type variable is named in one of two styles:
\n\nE, T,\n X, T2)\n T (examples:\n RequestT,\n FooBarT).Sometimes there is more than one reasonable way to convert an English phrase into camel case,\nsuch as when acronyms or unusual constructs like \"IPv6\" or \"iOS\" are present. To improve\npredictability, Google Style specifies the following (nearly) deterministic scheme.
\n\nBeginning with the prose form of the name:
\n\nIn very rare circumstances (for example, multipart version numbers), you may need to use\nunderscores to separate adjacent numbers, since numbers do not have upper and lower case variants.\n
\n\nExamples:
\n\n| Prose form | \nCorrect | \nIncorrect | \n
|---|---|---|
| \"XML HTTP request\" | \nXmlHttpRequest | \n XMLHTTPRequest | \n
| \"new customer ID\" | \nnewCustomerId | \n newCustomerID | \n
| \"inner stopwatch\" | \ninnerStopwatch | \n innerStopWatch | \n
| \"supports IPv6 on iOS?\" | \nsupportsIpv6OnIos | \n supportsIPv6OnIOS | \n
| \"YouTube importer\" | \nYouTubeImporter\n YoutubeImporter* | \n \n |
| \"Turn on 2SV\" | \nturnOn2sv | \n turnOn2Sv | \n
| \"Guava 33.4.6\" | \nguava33_4_6 | \n guava3346 | \n
*Acceptable, but not recommended.
\n\nNote: Some words are ambiguously hyphenated in the English\nlanguage: for example \"nonempty\" and \"non-empty\" are both correct, so the method names\ncheckNonempty and\ncheckNonEmpty are likewise both correct.
@Override: always usedA method is marked with the @Override annotation\nwhenever it is legal. This includes a class method overriding a superclass method, a class method\nimplementing an interface method, an interface method respecifying a superinterface method, and an\nexplicitly declared accessor method for a record component.
Exception:\n@Override may be omitted when the parent method is\n@Deprecated.
It is very rarely correct to do nothing in response to a caught\nexception. (Typical responses are to log it, or if it is considered \"impossible\", rethrow it as an\nAssertionError.)
When it truly is appropriate to take no action whatsoever in a catch block, the reason this is\njustified is explained in a comment.
\n\ntry {\n int i = Integer.parseInt(response);\n return handleNumericResponse(i);\n} catch (NumberFormatException ok) {\n // it's not numeric; that's fine, just continue\n}\nreturn handleTextResponse(response);\n\n\nWhen a reference to a static class member must be qualified, it is qualified with that class's\nname, not with a reference or expression of that class's type.
\n\nFoo aFoo = ...;\nFoo.aStaticMethod(); // good\naFoo.aStaticMethod(); // bad\nsomethingThatYieldsAFoo().aStaticMethod(); // very bad\n\n\n\n
Do not override Object.finalize. Finalization support\nis scheduled for removal.
The basic formatting of Javadoc blocks is as seen in this example:
\n\n/**\n * Multiple lines of Javadoc text are written here,\n * wrapped normally...\n */\npublic int method(String p1) { ... }\n\n\n... or in this single-line example:
\n\n/** An especially short bit of Javadoc. */\n\n\n
The basic form is always acceptable. The single-line form may be substituted when the entirety\nof the Javadoc block (including comment markers) can fit on a single line. Note that this only\napplies when there are no block tags such as @param.
One blank line—that is, a line containing only the aligned leading asterisk\n(*)—appears between paragraphs, and before the group of block tags if present.\nEach paragraph except the first has <p> immediately before the first word, with\nno space after it. HTML tags for other block-level elements, such as <ul> or\n<table>, are not preceded with <p>.
Any of the standard \"block tags\" that are used appear in the order @param,\n@return, @throws, @deprecated, and these four types never\nappear with an empty description. When a block tag doesn't fit on a single line, continuation lines\nare indented four (or more) spaces from the position of the @.\n
Each Javadoc block begins with a brief summary fragment. This\nfragment is very important: it is the only part of the text that appears in certain contexts such as\nclass and method indexes.
\n\nThis is a fragment—a noun phrase or verb phrase, not a complete sentence. It does\nnot begin with A {@code Foo} is a..., or\nThis method returns..., nor does it form a complete imperative sentence\nlike Save the record.. However, the fragment is capitalized and\npunctuated as if it were a complete sentence.
Tip: A common mistake is to write simple Javadoc in the form\n/** @return the customer ID */. This is\nincorrect, and should be changed to\n/** Returns the customer ID. */ or\n/** {@return the customer ID} */.
At the minimum, Javadoc is present for every visible class, member, or record\ncomponent, with a few exceptions noted below. A top-level class is visible if it is public; a member is visible if it is public or protected and its containing\nclass is visible; and a record component is visible if its containing record is visible.\n\n
Additional Javadoc content may also be present, as explained in Section 7.3.4,\nNon-required Javadoc.
\n\nJavadoc is optional for \"simple, obvious\" members and record components, such as a\ngetFoo() method, if there really and\ntruly is nothing else worthwhile to say but \"the foo\".
Important: it is not appropriate to cite this exception to justify\nomitting relevant information that a typical reader might need to know. For example, for a record\ncomponent named canonicalName, don't omit its\ndocumentation (with the rationale that it would say only\n@param canonicalName the canonical name) if a typical reader may have\nno idea what the term \"canonical name\" means!
Javadoc is not always present on a method that overrides a supertype method.\n\n
\n\n\n\nOther classes, members, and record components have Javadoc as needed or desired.\n\n
Whenever an implementation comment would be used to define the overall purpose or behavior of a\nclass or member, that comment is written as Javadoc instead (using /**).
Non-required Javadoc is not strictly required to follow the formatting rules of Sections\n7.1.1, 7.1.2, 7.1.3, and 7.2, though it is of course recommended.
\n\n\n\n\n Please note: This guide is old and is not being updated. It is retained\n as a reference as it was written for pre-ECMAScript 6th Edition features.\n Please use the newer guide instead.\n
\n\n Revision 2.93\n
\n\n \n Aaron Whyte\n Hooray! Now you know you can expand points to get more\n details. Alternatively, there's a \"toggle all\" at the\n top of this document.\n
\n \n\n JavaScript is the main client-side scripting language used\n\n by many of Google's open-source\n projects.\n This style guide is a list of dos and don'ts for\n JavaScript programs.\n
\n\n\n\n\n\nvar: Always\n var,\n the variable gets placed in the global context, potentially clobbering\n existing values. Also, if there's no declaration, it's hard to tell in\n what scope a variable lives (e.g., it could be in the Document or\n Window just as easily as in the local scope). So always declare with\n var.\n NAMES_LIKE_THIS for constant values.@const to indicate a constant (non-overwritable)\n pointer (a variable or property).const keyword\n as it's not supported in Internet Explorer.If a value is intended to be constant\n and immutable, it should be given a name\n in CONSTANT_VALUE_CASE.\n ALL_CAPS additionally implies @const\n (that the value is not overwritable).\n
Primitive types (number, string,\n boolean) are constant values.
Objects'\n immutability is more subjective — objects should be\n considered immutable only if they do not demonstrate observable\n state change. This is not enforced by the compiler.
The @const annotation on a variable or property\n implies that it is not overwritable. This is enforced by the\n compiler at build time. This behavior is consistent with the\n \n const keyword (which we do not use due to the\n lack of support in Internet Explorer).
A @const annotation on a method additionally\n implies that the method cannot not be overridden in subclasses.\n
A @const annotation on a constructor implies the\n class cannot be subclassed (akin to final in Java).\n
Note that @const does not necessarily imply\n CONSTANT_VALUES_CASE.\n\n However, CONSTANT_VALUES_CASE\n does imply @const.\n
The number of seconds in a minute never changes. It is a\n constant value. ALL_CAPS\n also implies @const, so the constant cannot be\n overwritten.\n
The open source compiler will allow the symbol to be\n overwritten because the constant is\n not marked as @const.
In this case, the pointer can never be overwritten, but\n value is highly mutable and not constant (and thus in\n camelCase, not ALL_CAPS).
Relying on implicit insertion can cause subtle, hard to debug\n problems. Don't do it. You're better than that.
\nThere are a couple places where missing semicolons are particularly\n dangerous:
\nx[ffVersion, ieVersion][isIE]().die is always called since the array minus 1 is\n NaN which is never equal to anything (not even if\n resultOfOperation() returns NaN) and\n THINGS_TO_EAT gets assigned the result of\n die().JavaScript requires statements to end with a semicolon, except when\n it thinks it can safely infer their existence. In each of these\n examples, a function declaration or object or array literal is used\n inside a statement. The closing brackets are not enough to signal\n the end of the statement. Javascript never ends a statement if the\n next token is an infix or bracket operator.
\nThis has really surprised people, so make sure your assignments end\n with semicolons.
\nSemicolons should be included at the end of function expressions,\n but not at the end of function declarations. The distinction is\n best illustrated with an example:
\nNested functions can be very useful, for example in the creation of\n continuations and for the task of hiding helper functions. Feel free\n to use them.
\n \nDo not do this:
\nWhile most script engines support Function Declarations within blocks\n it is not part of ECMAScript (see\n ECMA-262,\n clause 13 and 14). Worse implementations are inconsistent with each\n other and with future EcmaScript proposals. ECMAScript only allows for\n Function Declarations in the root statement list of a script or\n function. Instead use a variable initialized with a Function\n Expression to define a function within a block:
\nYou basically can't avoid exceptions if you're doing something\n non-trivial (using an application development framework, etc.).\n Go for it.
\n \nWithout custom exceptions, returning error information from a\n function that also returns a value can be tricky, not to mention\n inelegant. Bad solutions include passing in a reference type to hold\n error information or always returning Objects with a potential\n error member. These basically amount to a primitive exception\n handling hack. Feel free to use custom exceptions when\n appropriate.
\n \nFor maximum portability and compatibility, always prefer standards\n features over non-standards features (e.g.,\n string.charAt(3) over string[3] and element\n access with DOM functions instead of using an application-specific\n shorthand).
There's no reason to use wrapper objects for primitive types, plus\n they're dangerous:
\nDon't do it!
\nHowever type casting is fine.
\nThis is very useful for casting things to\n number, string and boolean.
Multi-level prototype hierarchies are how JavaScript implements\n inheritance. You have a multi-level hierarchy if you have a\n user-defined class D with another user-defined class B as its\n prototype. These hierarchies are much harder to get right than they\n first appear!
\n\nFor that reason, it is best to use goog.inherits() from\n \n the Closure Library\n \n or a similar library function.\n
/** @constructor */\n function SomeConstructor() {\n this.someProperty = 1;\n }\n Foo.prototype.someMethod = function() { ... };While there are several ways to attach methods and properties to an\n object created via \"new\", the preferred style for methods\n is:
\nThe preferred style for other properties is to initialize the field\n in the constructor:
\nCurrent JavaScript engines optimize based on the \"shape\"\n of an object, \n adding a property to an object (including overriding\n a value set on the prototype) changes the shape and can degrade\n performance.
\nthis.foo = null.Instead of:
\nIn modern JavaScript engines, changing the number of properties on an\n object is much slower than reassigning the values. The delete keyword\n should be avoided except when it is necessary to remove a property\n from an object's iterated list of keys, or to change the result of\n if (key in obj).
The ability to create closures is perhaps the most useful and often\n overlooked feature of JS. Here is\n \n a good description of how closures work.
\nOne thing to keep in mind, however, is that a closure keeps a pointer\n to its enclosing scope. As a result, attaching a closure to a DOM\n element can create a circular reference and thus, a memory leak. For\n example, in the following code:
\nthe function closure keeps a reference to element,\n a, and b even if it never uses\n element. Since element also keeps a\n reference to the closure, we have a cycle that won't be cleaned up by\n garbage collection. In these situations, the code can be structured\n as follows:
eval() makes for confusing semantics and is dangerous\n to use if the string being eval()'d contains user input.\n There's usually a better, clearer, and safer way to write your code,\n so its use is generally not permitted.
For RPC you can always use JSON and read the result using\n JSON.parse() instead of eval().
Let's assume we have a server that returns something like this:
\n\nIf the feed was modified to include malicious JavaScript code, then\n if we use eval then that code will be executed.
With JSON.parse, invalid JSON (including all executable\n JavaScript) will cause an exception to be thrown.
Using with clouds the semantics of your program.\n Because the object of the with can have properties that\n collide with local variables, it can drastically change the meaning\n of your program. For example, what does this do?
Answer: anything. The local variable x could be\n clobbered by a property of foo and perhaps it even has\n a setter, in which case assigning 3 could cause lots of\n other code to execute. Don't use with.
The semantics of this can be tricky. At times it refers\n to the global object (in most places), the scope of the caller (in\n eval), a node in the DOM tree (when attached using an\n event handler HTML attribute), a newly created object (in a\n constructor), or some other object (if function was\n call()ed or apply()ed).
Because this is so easy to get wrong, limit its use to those places\n where it is required:
\nfor-in loops are often incorrectly used to loop over\n the elements in an Array. This is however very error\n prone because it does not loop from 0 to\n length - 1 but over all the present keys in the object\n and its prototype chain. Here are a few cases where it fails:
Always use normal for loops when using arrays.
\nArray as a map/hash/associative array\n Associative Arrays are not allowed... or more precisely\n you are not allowed to use non number indexes for arrays. If you need\n a map/hash use Object instead of Array in\n these cases because the features that you want are actually features\n of Object and not of Array.\n Array just happens to extend Object (like\n any other object in JS and therefore you might as well have used\n Date, RegExp or String).
Do not do this:
\nThe whitespace at the beginning of each line can't be safely stripped\n at compile time; whitespace after the slash will result in tricky\n errors.
\nUse string concatenation instead:
\nUse Array and Object literals instead of\n Array and Object constructors.
Array constructors are error-prone due to their arguments.
\nBecause of this, if someone changes the code to pass 1 argument\n instead of 2 arguments, the array might not have the expected\n length.
\nTo avoid these kinds of weird cases, always use the more readable\n array literal.
\nObject constructors don't have the same problems, but for readability\n and consistency object literals should be used.
\nShould be written as:
\nModifying builtins like Object.prototype and\n Array.prototype are strictly forbidden. Modifying other\n builtins like Function.prototype is less dangerous but\n still leads to hard to debug issues in production and should be\n avoided.
Don't do this:
\nConditional Comments hinder automated tools as they can vary the\n JavaScript syntax tree at runtime.
\n \nIn general, use\n functionNamesLikeThis,\n variableNamesLikeThis,\n ClassNamesLikeThis,\n EnumNamesLikeThis,\n methodNamesLikeThis,\n CONSTANT_VALUES_LIKE_THIS,\n foo.namespaceNamesLikeThis.bar, and\n filenameslikethis.js.\n
For more information on private and protected,\n read the section on\n \n visibility.\n
\n\n\n\n\nOptional function arguments start with opt_.
Functions that take a variable number of arguments should have the\n last argument named var_args. You may not refer to\n var_args in the code; use the arguments\n array.
Optional and variable arguments can also be specified in\n @param annotations. Although either convention is\n acceptable to the compiler, using both together is preferred.
EcmaScript 5 getters and setters for properties are discouraged.\n However, if they are used, then getters must not change observable\n state.
\nGetters and setters methods for properties are not required.\n However, if they are used, then getters must be named\n getFoo() and setters must be named\n setFoo(value). (For boolean getters,\n isFoo() is also acceptable, and often sounds more\n natural.)
JavaScript has no inherent packaging or namespacing support.
\nGlobal name conflicts are difficult to debug, and can cause\n intractable problems when two projects try to integrate. In order\n to make it possible to share common JavaScript code, we've adopted\n conventions to prevent collisions.
\nALWAYS prefix identifiers in the global scope with a\n unique pseudo namespace related to the project or library. If you\n are working on \"Project Sloth\", a reasonable pseudo namespace\n would be sloth.*.
Many JavaScript libraries, including\n \n the Closure Library\n \n and\n \n Dojo toolkit\n \n give you high-level functions for declaring your namespaces.\n Be consistent about how you declare your namespaces.
\nWhen choosing a child-namespace, make sure that the owners of the\n parent namespace know what you are doing. If you start a project\n that creates hats for sloths, make sure that the Sloth team knows\n that you're using sloth.hats.
\"External code\" is code that comes from outside your codebase,\n and is compiled independently. Internal and external names should\n be kept strictly separate. If you're using an external library\n that makes things available in foo.hats.*, your\n internal code should not define all its symbols in\n foo.hats.*, because it will break if the other\n team defines new symbols.
If you need to define new APIs on an external namespace, then you\n should explicitly export the public API functions, and only those\n functions. Your internal code should call the internal APIs by\n their internal names, for consistency and so that the compiler\n can optimize them better.
\nUse local aliases for fully-qualified types if doing so improves\n readability. The name of a local alias should match the last part\n of the type.
\nDo not create local aliases of namespaces. Namespaces should only\n be aliased using goog.scope.
\nAvoid accessing properties of an aliased type, unless it is an\n enum.
\nNever create aliases in the global scope. Use them only in\n function blocks.
\nFilenames should be all lowercase in order to avoid confusion on\n case-sensitive platforms. Filenames should end in .js,\n and should contain no punctuation except for - or\n _ (prefer - to _).
You can control how your objects string-ify themselves by defining a\n custom toString() method. This is fine, but you need\n to ensure that your method (1) always succeeds and (2) does not have\n side-effects. If your method doesn't meet these criteria, it's very\n easy to run into serious problems. For example, if\n toString() calls a method that does an\n assert, assert might try to output the name\n of the object in which it failed, which of course requires calling\n toString().
It isn't always possible to initialize variables at the point of\n declaration, so deferred initialization is fine.
\n \nAlways use explicit scope - doing so increases portability and\n clarity. For example, don't rely on window being in the\n scope chain. You might want to use your function in another\n application for which window is not the content\n window.
We follow the C++ formatting\n rules in spirit, with the following additional clarifications.
\nBecause of implicit semicolon insertion, always start your curly\n braces on the same line as whatever they're opening. For\n example:
\nSingle-line array and object initializers are allowed when they\n fit on a line:
\nMultiline array initializers and object initializers are indented\n 2 spaces, with the braces on their own line, just like blocks.
\nLong identifiers or values present problems for aligned\n initialization lists, so always prefer non-aligned initialization.\n For example:
\nNot like this:
\nWhen possible, all function arguments should be listed on the same\n line. If doing so would exceed the 80-column limit, the arguments\n must be line-wrapped in a readable way. To save space, you may wrap\n as close to 80 as possible, or put each argument on its own line to\n enhance readability. The indentation may be either four spaces, or\n aligned to the parenthesis. Below are the most common patterns for\n argument wrapping:
\nWhen the function call is itself indented, you're free to start the\n 4-space indent relative to the beginning of the original statement\n or relative to the beginning of the current function call.\n The following are all acceptable indentation styles.
\nWhen declaring an anonymous function in the list of arguments for\n a function call, the body of the function is indented two spaces\n from the left edge of the statement, or two spaces from the left\n edge of the function keyword. This is to make the body of the\n anonymous function easier to read (i.e. not be all squished up into\n the right half of the screen).
\n\n goog.scope\n may be used to shorten references to\n namespaced symbols in programs using\n the Closure\n Library.
Only one goog.scope invocation may be added per\n file. Always place it in the global scope.
The opening goog.scope(function() { invocation\n must be preceded by exactly one blank line and follow any\n goog.provide statements, goog.require\n statements, or top-level comments. The invocation must be closed on\n the last line in the file. Append // goog.scope to the\n closing statement of the scope. Separate the comment from the\n semicolon by two spaces.
Similar to C++ namespaces, do not indent under goog.scope\n declarations. Instead, continue from the 0 column.
\nOnly alias names that will not be re-assigned to another object\n (e.g., most constructors, enums, and namespaces). Do not do\n this (see below for how to alias a constructor):
\n\nNames must be the same as the last property of the global that they\n are aliasing.
\n\nExcept for array literals,\n object literals, and anonymous functions, all wrapped lines\n should be indented either left-aligned to a sibling expression\n above, or four spaces (not two spaces) deeper than a parent\n expression (where \"sibling\" and \"parent\" refer to parenthesis\n nesting level).\n
\n\nUse newlines to group logically related pieces of code.\n For example:
\nAlways put the operator on the preceding line. Otherwise,\n line breaks and indentation follow the same rules as in other\n Google style guides. This operator placement was initially agreed\n upon out of concerns about automatic semicolon insertion. In fact,\n semicolon insertion cannot happen before a binary operator, but new\n code should stick to this style for consistency.
\nThis includes the dot operator.
\nUse sparingly and in general only where required by the syntax\n and semantics.
\nNever use parentheses for unary operators such as\n delete, typeof and void or\n after keywords such as return, throw as\n well as others (case, in or\n new).
For consistency single-quotes (') are preferred to double-quotes (\").\n This is helpful when creating strings that include HTML:
\n@private and\n @protectedWe recommend the use of the JSDoc annotations @private and\n @protected to indicate visibility levels for classes,\n functions, and properties.
The --jscomp_warning=visibility compiler flag turns on compiler\n warnings for visibility violations. See\n \n Closure Compiler\n Warnings.\n
\n@private global variables and functions are only\n accessible to code in the same file.
Constructors marked @private may only be instantiated by\n code in the same file and by their static and instance members.\n @private constructors may also be accessed anywhere in the\n same file for their public static properties and by the\n instanceof operator.
Global variables, functions, and constructors should never be\n annotated @protected.
@private properties are accessible to all code in the\n same file, plus all static methods and instance methods of that class\n that \"owns\" the property, if the property belongs to a class. They\n cannot be accessed or overridden from a subclass in a different file.
@protected properties are accessible to all code in the\n same file, plus any static methods and instance methods of any subclass\n of a class that \"owns\" the property.
Note that these semantics differ from those of C++ and Java, in that\n they grant private and protected access to all code in the same file,\n not just in the same class or class hierarchy. Also, unlike in C++,\n private properties cannot be overridden by a subclass.\n
\nNotice that in JavaScript, there is no distinction between a type\n (like AA_PrivateClass_) and the constructor for that\n type. There is no way to express both that a type is public and its\n constructor is private (because the constructor could easily be aliased\n in a way that would defeat the privacy check).
When documenting a type in JSDoc, be as specific and accurate as\n possible. The types we support are based on the\n \n EcmaScript 4 spec.
\nThe ES4 proposal contained a language for specifying JavaScript\n types. We use this language in JsDoc to express the types of\n function parameters and return values.
\n\nAs the ES4 proposal has evolved, this language has changed. The\n compiler still supports old syntaxes for types, but those syntaxes\n are deprecated.
\n\n \n| Syntax Name | \nSyntax | \nDescription | \nDeprecated Syntaxes | \n
|---|---|---|---|
| Primitive Type | \n\n There are 5 primitive types in JavaScript:\n {null},\n {undefined},\n {boolean},\n {number}, and\n {string}.\n | \n Simply the name of a type. | \n\n |
| Instance Type | \n\n {Object}\n An instance of Object or null.\n {Function}\n An instance of Function or null.\n {EventTarget}\n An instance of a constructor that implements the EventTarget\n interface, or null.\n | \n An instance of a constructor or interface function.\n\n Constructor functions are functions defined with the\n @constructor JSDoc tag.\n Interface functions are functions defined with the\n @interface JSDoc tag.\n\n By default, instance types will accept null. This is the only\n\t\ttype syntax that makes the type nullable. Other type syntaxes\n\t\tin this table will not accept null.\n | \n \n |
| Enum Type | \n\n {goog.events.EventType}\n One of the properties of the object literal initializer\n of goog.events.EventType.\n | \n An enum must be initialized as an object literal, or as\n an alias of another enum, annotated with the @enum\n JSDoc tag. The properties of this literal are the instances\n of the enum. The syntax of the enum is defined\n below.\n\n Note that this is one of the few things in our type system\n that were not in the ES4 spec.\n | \n \n |
| Type Application | \n\n {Array.<string>}An array of strings.\n {Object.<string, number>}\n An object in which the keys are strings and the values\n are numbers.\n | \n Parameterizes a type, by applying a set of type arguments\n to that type. The idea is analogous to generics in Java.\n | \n\n |
| Type Union | \n\n {(number|boolean)}A number or a boolean.\n | \n Indicates that a value might have type A OR type B.\n\n The parentheses may be omitted at the top-level\n expression, but the parentheses should be included in\n sub-expressions to avoid ambiguity. \n {number|boolean}\n {function(): (number|boolean)}\n | \n \n {(number,boolean)},\n {(number||boolean)}\n | \n
| Nullable type | \n\n {?number}A number or null.\n | \n Shorthand for the union of the null type with any\n other type. This is just syntactic sugar.\n | \n\n {number?}\n | \n
| Non-nullable type | \n\n {!Object}An Object, but never the\n null value.\n | \n Filters null out of nullable types. Most often used\n with instance types, which are nullable by default.\n | \n\n {Object!}\n | \n
| Record Type | \n\n {{myNum: number, myObject}}\n An anonymous type with the given type members.\n | \n \n Indicates that the value has the specified members with the\n specified types. In this case, Notice that the braces are part of the type syntax. For\n example, to denote an | \n \n |
| Function Type | \n\n {function(string, boolean)}\n A function that takes two arguments (a string and a boolean),\n and has an unknown return value. \n | \n Specifies a function. | \n\n |
| Function Return Type | \n\n {function(): number}\n A function that takes no arguments and returns a number. \n | \n Specifies a function return type. | \n\n |
Function this Type | \n \n {function(this:goog.ui.Menu, string)}\n A function that takes one argument (a string), and executes\n in the context of a goog.ui.Menu.\n | \n Specifies the context type of a function type. | \n\n |
Function new Type | \n \n {function(new:goog.ui.Menu, string)}\n A constructor that takes one argument (a string), and\n creates a new instance of goog.ui.Menu when called\n with the 'new' keyword.\n | \n Specifies the constructed type of a constructor. | \n\n |
| Variable arguments | \n\n {function(string, ...[number]): number}\n A function that takes one argument (a string), and then a\n variable number of arguments that must be numbers.\n | \n Specifies variable arguments to a function. | \n\n |
\n \n Variable arguments (in @param annotations)\n | \n \n @param {...number} var_args\n A variable number of arguments to an annotated function.\n | \n \n Specifies that the annotated function accepts a variable\n number of arguments.\n | \n\n |
| Function optional arguments | \n\n {function(?string=, number=)}\n A function that takes one optional, nullable string and one\n optional number as arguments. The = syntax is\n only for function type declarations.\n | \n Specifies optional arguments to a function. | \n\n |
\n \n Function optional arguments\n (in @param annotations)\n | \n \n @param {number=} opt_argument\n An optional parameter of type number.\n | \n Specifies that the annotated function accepts an optional\n argument. | \n\n |
| The ALL type | \n{*} | \n Indicates that the variable can take on any type. | \n\n |
| The UNKNOWN type | \n{?} | \n Indicates that the variable can take on any type,\n and the compiler should not type-check any uses of it. | \n\n |
| Type Example | \nValue Examples | \nDescription | \n
|---|---|---|
| number | \n\n | \n \n |
| Number | \n\n | \n \n \n Number object\n \n | \n
| string | \n\n | \n \n String value\n | \n
| String | \n\n | \n \n \n String object\n \n | \n
| boolean | \n\n | \n \n Boolean value\n | \n
| Boolean | \n\n | \n \n \n Boolean object\n \n | \n
| RegExp | \n\n | \n | \n
| Date | \n\n | \n \n |
| \n\n null\n\n | \n\n | \n \n |
| \n\n undefined\n\n | \n\n | \n \n |
| void | \n\n | \n No return value | \n
| Array | \n\n | \n Untyped Array | \n
| Array.<number> | \n\n | \n \n An Array of numbers\n | \n
| Array.<Array.<string>> | \n\n | \n Array of Arrays of strings | \n
| Object | \n\n | \n \n |
| Object.<string> | \n\n | \n \n An Object in which the values are strings.\n | \n
| Object.<number, string> | \n\n | \n \n An Object in which the keys are numbers and the values are\n strings. Note that in JavaScript, the keys are always\n implicitly converted to strings, so\n obj['1'] == obj[1].\n So the key will always be a string in for...in loops. But the\n compiler will verify the type of the key when indexing into\n the object.\n | \n
| Function | \n\n | \n \n \n Function object\n \n | \n
| function(number, number): number | \n\n | \n function value | \n
| SomeClass | \n\n | \n \n |
| SomeInterface | \n\n | \n \n |
| project.MyClass | \n\n | \n \n |
| project.MyEnum | \n\n | \n Enumeration\n JSDoc comments on enum values are optional.\n | \n
| Element | \n\n | \n Elements in the DOM. | \n
| Node | \n\n | \n Nodes in the DOM. | \n
| HTMLInputElement | \n\n | \n A specific type of DOM element. | \n
In cases where type-checking doesn't accurately infer the type of\n an expression, it is possible to add a type cast comment by adding a\n type annotation comment and enclosing the expression in\n parentheses. The parentheses are required.
\n\nBecause JavaScript is a loosely-typed language, it is very\n important to understand the subtle differences between optional,\n nullable, and undefined function parameters and class\n properties.
\n\nInstances of classes and interfaces are nullable by default.\n For example, the following declaration
\n\ntells the compiler that the myValue_ property holds\n either an Object or null. If myValue_ must never be\n null, it should be declared like this:
This way, if the compiler can determine that somewhere in the code\n MyClass is initialized with a null value, it will issue\n a warning.
Optional parameters to functions may be undefined at runtime, so if\n they are assigned to class properties, those properties must be\n declared accordingly:
\n\nThis tells the compiler that myValue_ may hold an\n Object, null, or remain undefined.
Note that the optional parameter opt_value is declared\n to be of type {Object=}, not\n {Object|undefined}. This is because optional\n parameters may, by definition, be undefined. While there is no harm\n in explicitly declaring an optional parameter as possibly undefined,\n it is both unnecessary and makes the code harder to read.
Finally, note that being nullable and being optional are orthogonal\n properties. The following four declarations are all different:
\n\nSometimes types can get complicated. A function that accepts\n content for an Element might look like:
\n\nYou can define commonly used type expressions with a\n @typedef tag. For example,
The compiler has limited support for template types. It can only\n infer the type of this inside an anonymous function\n literal from the type of the this argument and whether the\n this argument is missing.
\n We follow the\n \n C++ style for comments in spirit.\n
\n\nAll files, classes, methods and properties should be documented with\n JSDoc\n comments with the appropriate tags\n and types. Textual descriptions for properties,\n methods, method parameters and method return values should be included\n unless obvious from the property, method, or parameter name.\n
\n\nInline comments should be of the // variety.
Complete sentences are recommended but not required.\n Complete sentences should use appropriate capitalization\n and punctuation.
\n\nThe JSDoc syntax is based on\n \n JavaDoc. Many tools extract metadata from JSDoc comments to\n perform code validation and optimizations. These comments must be\n well-formed.
\n\nIf you have to line break a block tag, you should treat this as\n breaking a code statement and indent it four spaces.
\n\nYou should not indent the @fileoverview command. You do not have to\n indent the @desc command.
Even though it is not preferred, it is also acceptable to line up\n the description.
\n\nLike JavaDoc, JSDoc supports many HTML tags, like <code>,\n <pre>, <tt>, <strong>, <ul>, <ol>,\n <li>, <a>, and others.
\n\nThis means that plaintext formatting is not respected. So, don't\n rely on whitespace to format JSDoc:
\n\nIt'll come out like this:
\n\nInstead, do this:
\n\n\n\n A copyright notice and author information are optional.\n File overviews are generally recommended whenever a file consists of\n more than a single class definition. The top level comment is\n designed to orient readers unfamiliar with the code to what is in\n this file. If present, it should provide a description of the\n file's contents and any dependencies or compatibility information.\n As an example:\n
\n\nClasses must be documented with a description and a\n type tag that\n identifies the constructor.\n
\n\nParameter and return types should be documented. The method\n description may be omitted if it is obvious from the parameter\n or return type descriptions. Method descriptions should start\n with a sentence written in the third person declarative voice.
\n| Tag | \nTemplate & Examples | \nDescription | \n
|---|---|---|
| \n @author\n\n | \n\n @author username@google.com (first last)\n For example: \n | \n \n Document the author of a file or the owner of a test,\n generally only used in the @fileoverview comment.\n\n | \n
| @code | \n\n {@code ...}\n For example: \n | \n \n Indicates that a term in a JSDoc description is code so it may\n be correctly formatted in generated documentation.\n | \n
| @const | \n\n @const\n @const {type}\n For example: \n | \n \n Marks a variable (or property) as read-only and suitable\n for inlining. \n\nA The type declaration of a constant value can be omitted\n if it can be clearly inferred. An additional comment about\n the variable is optional. \n\nWhen For more on | \n
| @constructor | \n\n @constructor\n For example: \n | \n \n Used in a class's documentation to indicate the constructor.\n | \n
| @define | \n\n @define {Type} description\n For example: \n | \n \n Indicates a constant that can be overridden by the compiler at\n compile-time. In the example, the compiler flag\n --define='goog.userAgent.ASSUME_IE=true'\n could be specified in the BUILD file to indicate that the\n constant goog.userAgent.ASSUME_IE should be replaced\n with true.\n | \n
| @deprecated | \n\n @deprecated Description\n For example: \n | \n \n Used to tell that a function, method or property should not be\n used any more. Always provide instructions on what callers\n should use instead.\n | \n
| @dict | \n\n @dict Description\n For example: \n | \n \n When a constructor (Foo in the example) is\n annotated with @dict, you can only use the\n bracket notation to access the properties of Foo\n objects.\n The annotation can also be used directly on object literals.\n | \n
| @enum | \n\n @enum {Type}\n For example: \n | \n |
| @export | \n\n @export\n For example: \n | \n \n Given the code on the left, when the compiler is run with\n the which will export the symbols to uncompiled code.\n Code that uses the
| \n
| @expose | \n\n @expose\n For example: \n | \n \n \n Declares an exposed property. Exposed properties\n will not be removed, or renamed, or collapsed,\n or optimized in any way by the compiler. No properties\n with the same name will be able to be optimized either.\n \n\n\n | \n
| @extends | \n\n \n @extends Type\n For example: \n | \n \n Used with @constructor to indicate that a class\n inherits from another class. Curly braces around the type are\n optional.\n | \n
| @externs | \n\n @externs\n For example: \n | \n \n \n Declares an\n\n externs file.\n \n\n\n | \n
| @fileoverview | \n\n @fileoverview Description\n For example: \n | \n Makes the comment block provide file level information. | \n
| @implements | \n\n \n @implements Type\n For example: \n | \n \n Used with @constructor to indicate that a class\n implements an interface. Curly braces around the type are\n optional.\n | \n
| @inheritDoc | \n\n @inheritDoc\n For example: \n | \n \n Deprecated. Use\n @inheritDoc implies @override\n | \n
| @interface | \n\n @interface\n For example: \n | \n \n Used to indicate that the function defines an interface.\n | \n
| @lends | \n\n @lends objectName\n @lends {objectName}\n For example: \n | \n \n Indicates that the keys of an object literal should\n be treated as properties of some other object. This annotation\n should only appear on object literals.\n\n Notice that the name in braces is not a type name like\n in other annotations. It's an object name. It names\n the object on which the properties are \"lent\".\n For example, @type {Foo} means \"an instance of Foo\",\n but @lends {Foo} means \"the constructor Foo\".\n\n The \n JSDoc Toolkit docs have more information on this\n annotation.\n | \n
| @license or\n @preserve | \n\n @license Description\n For example: \n | \n \n Anything marked by @license or\n @preserve will be retained by the compiler and\n output at the top of the compiled code for that file. This\n annotation allows important notices (such as legal licenses or\n copyright text) to survive compilation unchanged. Line breaks\n are preserved.\n | \n
| @noalias | \n\n @noalias\n For example: \n | \n \n Used in an externs file to indicate to the compiler that the\n variable or function should not be aliased as part of the\n alias externals pass of the compiler.\n | \n
| @nocompile | \n\n @nocompile\n For example: \n | \n \n Used at the top of a file to tell the compiler to parse this\n file but not compile it.\n Code that is not meant for compilation and should be omitted\n from compilation tests (such as bootstrap code) uses this\n annotation.\n Use sparingly.\n | \n
| @nosideeffects | \n\n @nosideeffects\n For example: \n | \n \n This annotation can be used as part of function and\n constructor declarations to indicate that calls to the\n declared function have no side-effects. This annotation\n allows the compiler to remove calls to these functions if the\n return value is not used.\n | \n
| @override | \n\n @override\n For example: \n | \n \n Indicates that a method or property of a subclass\n intentionally hides a method or property of the superclass. If\n no other documentation is included, the method or property\n also inherits documentation from its superclass.\n | \n
| @param | \n\n @param {Type} varname Description\n For example: \n | \n \n Used with method, function and constructor calls to document\n the arguments of a function.\n\n Type\n names must be enclosed in curly braces. If the type\n is omitted, the compiler will not type-check the parameter.\n | \n
| @private | \n\n @private\n @private {type}\n For example: \n | \n \n Used in conjunction with a trailing underscore on the method\n or property name to indicate that the member is\n private and final.\n | \n
| @protected | \n\n @protected\n @protected {type}\n For example: \n | \n \n Used to indicate that the member or property is\n protected.\n Should be used in conjunction with names with no trailing\n underscore.\n | \n
| @public | \n\n @public\n @public {type}\n For example: \n | \n \n Used to indicate that the member or property is public. Variables and\n properties are public by default, so this annotation is rarely necessary.\n Should only be used in legacy code that cannot be easily changed to\n override the visibility of members that were named as private variables.\n | \n
| @return | \n\n @return {Type} Description\n For example: \n | \n \n Used with method and function calls to document the return\n type. When writing descriptions for boolean parameters,\n prefer \"Whether the component is visible\" to \"True if the\n component is visible, false otherwise\". If there is no return\n value, do not use an @return tag.\n\n Type\n names must be enclosed in curly braces. If the type\n is omitted, the compiler will not type-check the return value.\n | \n
| @see | \n\n @see Link\n For example: \n | \n Reference a lookup to another class function or method. | \n
| @struct | \n\n @struct Description\n For example: \n | \n \n When a constructor (Foo in the example) is\n annotated with @struct, you can only use the dot\n notation to access the properties of Foo objects.\n Also, you cannot add new properties to Foo\n objects after they have been created.\n The annotation can also be used directly on object literals.\n | \n
| @supported | \n\n @supported Description\n For example: \n | \n \n Used in a fileoverview to indicate what browsers are supported\n by the file.\n | \n
| @suppress | \n\n \n @suppress {warning1|warning2}\n \n \n @suppress {warning1,warning2}\n \n For example: \n | \n \n Suppresses warnings from tools. Warning categories are\n separated by | or ,.\n\n | \n
| @template | \n\n @template\n For example: \n | \n \n This annotation can be used to declare a\n template typename.\n | \n
| @this | \n\n \n @this Type\n For example: \n | \n \n The type of the object in whose context a particular method is\n called. Required when the this keyword is referenced\n from a function that is not a prototype method.\n | \n
| @type | \n\n \n @type Type\n For example: \n | \n \n Identifies the type of a variable,\n property, or expression. Curly braces are not required around\n most types, but some projects mandate them for all types, for\n consistency.\n | \n
| @typedef | \n\n @typedef\n For example: \n | \n \n This annotation can be used to declare an alias of a more\n complex type.\n | \n
\n You may also see other types of JSDoc annotations in third-party\n code. These annotations appear in the\n \n JSDoc Toolkit Tag Reference\n \n but are currently discouraged in Google code. You should consider\n them \"reserved\" names for future use. These include:\n
\n All members defined on a class should be in the same file. So, only\n top-level classes should be provided in a file that contains multiple\n members defined on the same class (e.g. enums, inner classes, etc).\n
\nDo this:
\nNot this:
\n\n Members on namespaces may also be provided:\n
\nUse of JS compilers such as the\n Closure Compiler\n is required for all customer-facing code.
\n\n\n\n\n \nThe following are all false in boolean expressions:
\nnullundefined'' the empty string0 the numberBut be careful, because these are all true:
\n'0' the string[] the empty array{} the empty objectThis means that instead of this:
\nyou can write this shorter code (as long as you don't expect x to\n be 0, or the empty string, or false):
\nAnd if you want to check a string to see if it is null or empty,\n you could do this:
\nBut this is shorter and nicer:
\nCaution: There are many unintuitive things about\n boolean expressions. Here are some of them:
\n\n Boolean('0') == true
\n '0' != true\n 0 != null
\n 0 == []
\n 0 == false\n Boolean(null) == false
\n null != true
\n null != false\n Boolean(undefined) == false
\n undefined != true
\n undefined != false\n Boolean([]) == true
\n [] != true
\n [] == false\n Boolean({}) == true
\n {} != true
\n {} != falseInstead of this:
\nyou can write this:
\nThe ternary conditional is also useful when generating HTML:
\nThese binary boolean operators are short-circuited, and evaluate\n to the last evaluated term.
\n\n\"||\" has been called the 'default' operator, because instead of\n writing this:
\nyou can write this:
\n\"&&\" is also useful for shortening code. For instance,\n instead of this:
\nyou could do this:
\nor this:
\nHowever, this is going a little too far:
\nNode lists are often implemented as node iterators with a filter.\n This means that getting a property like length is O(n), and\n iterating over the list by re-checking the length will be\n O(n^2).
\nIt is better to do this instead:
\nThis works well for all collections and arrays as long as the array\n does not contain things that are treated as boolean false.
\n\nIn cases where you are iterating over the childNodes you can also\n use the firstChild and nextSibling properties.
\n\n BE CONSISTENT.\n
\n\n\n If you're editing code, take a few minutes to look at the code\n around you and determine its style. If they use spaces around\n all their arithmetic operators, you should too. If their\n comments have little boxes of hash marks around them, make your\n comments have little boxes of hash marks around them too.\n
\n\n\n The point of having style guidelines is to have a common vocabulary\n of coding so people can concentrate on what you're saying rather\n than on how you're saying it. We present global style rules here so\n people know the vocabulary, but local style is also important. If\n code you add to a file looks drastically different from the existing\n code around it, it throws readers out of their rhythm when they go to\n read it. Avoid this.\n
\n\n\n Revision 2.93\n
\n\n\n \n Aaron Whyte\nPlease note: This guide is no longer being updated. Google recommends migrating\nto TypeScript, and following the TypeScript guide.\n
\n\nThis document serves as the complete definition of Google’s coding standards\nfor source code in the JavaScript programming language. A JavaScript source file\nis described as being in Google Style if and only if it adheres to the rules\nherein.
\n\nLike other programming style guides, the issues covered span not only aesthetic\nissues of formatting, but other types of conventions or coding standards as\nwell. However, this document focuses primarily on the hard-and-fast rules that\nwe follow universally, and avoids giving advice that isn't clearly enforceable\n(whether by human or tool).
\n\nIn this document, unless otherwise clarified:
\n\nThe term comment always refers to implementation comments. We do not use\nthe phrase documentation comments
, instead using the common term “JSDoc”\nfor both human-readable text and machine-readable annotations within /** …\n*/.
This Style Guide uses RFC 2119 terminology when using the phrases must,\nmust not, should, should not, and may. The terms prefer and\navoid correspond to should and should not, respectively. Imperative\nand declarative statements are prescriptive and correspond to must.
Other terminology notes
will appear occasionally throughout the document.
Example code in this document is non-normative. That is, while the examples\nare in Google Style, they may not illustrate the only stylish way to represent\nthe code. Optional formatting choices made in examples must not be enforced as\nrules.
\n\nFile names must be all lowercase and may include underscores (_) or dashes\n(-), but no additional punctuation. Follow the convention that your project\nuses. Filenames’ extension must be .js.
Source files are encoded in UTF-8.
\n\nAside from the line terminator sequence, the ASCII horizontal space character\n(0x20) is the only whitespace character that appears anywhere in a source file.\nThis implies that
\n\nAll other whitespace characters in string literals are escaped, and
Tab characters are not used for indentation.
For any character that has a special escape sequence (\\', \\\", \\\\, \\b,\n\\f, \\n, \\r, \\t, \\v), that sequence is used rather than the\ncorresponding numeric escape (e.g \\x0a, \\u000a, or \\u{a}). Legacy octal\nescapes are never used.
For the remaining non-ASCII characters, either the actual Unicode character\n(e.g. ∞) or the equivalent hex or Unicode escape (e.g. \\u221e) is used,\ndepending only on which makes the code easier to read and understand.
Tip: In the Unicode escape case, and occasionally even when actual Unicode\ncharacters are used, an explanatory comment can be very helpful.
\n\n/* Best: perfectly clear even without a comment. */\nconst units = 'μs';\n\n/* Allowed: but unnecessary as μ is a printable character. */\nconst units = '\\u03bcs'; // 'μs'\n\n/* Good: use escapes for non-printable characters with a comment for clarity. */\nreturn '\\ufeff' + content; // Prepend a byte order mark.\n/* Poor: the reader has no idea what character this is. */\nconst units = '\\u03bcs';\nTip: Never make your code less readable simply out of fear that some programs\nmight not handle non-ASCII characters properly. If that happens, those programs\nare broken and they must be fixed.
\n\nAll new source files should either be a goog.module\nfile (a file containing a goog.module call) or an ECMAScript (ES) module (uses\nimport and export statements).
Files consist of the following, in order:
\n\n@fileoverview JSDoc, if presentgoog.module statement, if a goog.module fileimport statements, if an ES modulegoog.require and goog.requireType statementsExactly one blank line separates each section that is present, except the\nfile's implementation, which may be preceded by 1 or 2 blank lines.
\n\nIf license or copyright information belongs in a file, it belongs here.
\n\n@fileoverview JSDoc, if presentSee ?? for formatting rules.
\n\ngoog.module statementAll goog.module files must declare exactly one goog.module name on a single\nline: lines containing a goog.module declaration must not be wrapped, and are\ntherefore an exception to the 80-column limit.
The entire argument to goog.module is what defines a namespace. It is the\npackage name (an identifier that reflects the fragment of the directory\nstructure where the code lives) plus, optionally, the main class/enum/interface\nthat it defines concatenated to the end in lowerCamelCase.
Example:
\n\ngoog.module('search.urlHistory.urlHistoryService');\nModule namespaces may never be named as a direct child of another module's\nnamespace.
\n\nDisallowed:
\n\ngoog.module('foo.bar'); // 'foo.bar.qux' would be fine, though\ngoog.module('foo.bar.baz');\nThe directory hierarchy reflects the namespace hierarchy, so that deeper-nested\nchildren are subdirectories of higher-level parent directories. Note that this\nimplies that owners of “parent” namespace groups are necessarily aware of all\nchild namespaces, since they exist in the same directory.
\n\ngoog.module.declareLegacyNamespaceThe single goog.module statement may optionally be followed by a call to\ngoog.module.declareLegacyNamespace();. Avoid\ngoog.module.declareLegacyNamespace() when possible.
Example:
\n\ngoog.module('my.test.helpers');\ngoog.module.declareLegacyNamespace();\ngoog.setTestOnly();\ngoog.module.declareLegacyNamespace exists to ease the transition from\ntraditional object hierarchy-based namespaces but comes with some naming\nrestrictions. As the child module name must be created after the parent\nnamespace, this name must not be a child or parent of any other\ngoog.module (for example, goog.module('parent'); and\ngoog.module('parent.child'); cannot both exist safely, nor can\ngoog.module('parent'); and goog.module('parent.child.grandchild');).
goog.module ExportsClasses, enums, functions, constants, and other symbols are exported using the\nexports object. Exported symbols may be defined directly on the exports\nobject, or else declared locally and exported separately. Symbols are only\nexported if they are meant to be used outside the module. Non-exported\nmodule-local symbols are not declared @private. There is no prescribed\nordering for exported and module-local symbols.
Examples:
\n\nconst /** !Array<number> */ exportedArray = [1, 2, 3];\n\nconst /** !Array<number> */ moduleLocalArray = [4, 5, 6];\n\n/** @return {number} */\nfunction moduleLocalFunction() {\n return moduleLocalArray.length;\n}\n\n/** @return {number} */\nfunction exportedFunction() {\n return moduleLocalFunction() * 2;\n}\n\nexports = {exportedArray, exportedFunction};\n/** @const {number} */\nexports.CONSTANT_ONE = 1;\n\n/** @const {string} */\nexports.CONSTANT_TWO = 'Another constant';\nDo not annotate the exports object as @const as it is already treated as a\nconstant by the compiler.
/** @const */\nexports = {exportedFunction};\nDo not use default exports as they don't translate easily to ES module\nsemantics.
\n\nexports = FancyClass;\n\n\n
ES modules are files that use the import and export keywords.
\n\n
Import statements must not be line wrapped and are therefore an exception to the\n80-column limit.
\n\n\n\n
ES module files must use the import statement to import other ES module\nfiles. Do not goog.require another ES module.
import './sideeffects.js';\n\nimport * as goog from '../closure/goog/goog.js';\nimport * as parent from '../parent.js';\n\nimport {name} from './sibling.js';\n\n\n
The .js file extension is not optional in import paths and must always be\nincluded.
import '../directory/file';\nimport '../directory/file.js';\nDo not import the same file multiple times. This can make it hard to determine\nthe aggregate imports of a file.
\n\n// Imports have the same path, but since it doesn't align it can be hard to see.\nimport {short} from './long/path/to/a/file.js';\nimport {aLongNameThatBreaksAlignment} from './long/path/to/a/file.js';\n\n\n
Module import names (import * as name) are lowerCamelCase names that are\nderived from the imported file name.
import * as fileOne from '../file-one.js';\nimport * as fileTwo from '../file_two.js';\nimport * as fileThree from '../filethree.js';\nimport * as libString from './lib/string.js';\nimport * as math from './math/math.js';\nimport * as vectorMath from './vector/math.js';\nSome libraries might commonly use a namespace import prefix that violates this\nnaming scheme, but overbearingly common open source use makes the violating\nstyle more readable. The only library that currently falls under this exception\nis threejs, using the THREE prefix.
Default import names are derived from the imported file name and follow the\nrules in ??.
\n\nimport MyClass from '../my-class.js';\nimport myFunction from '../my_function.js';\nimport SOME_CONSTANT from '../someconstant.js';\nNote: In general this should not happen as default exports are banned by this\nstyle guide, see ??. Default imports are only used\nto import modules that do not conform to this style guide.
\n\nIn general symbols imported via the named import (import {name}) should keep\nthe same name. Avoid aliasing imports (import {SomeThing as SomeOtherThing}).\nPrefer fixing name collisions by using a module import (import *) or renaming\nthe exports themselves.
import * as bigAnimals from './biganimals.js';\nimport * as domesticatedAnimals from './domesticatedanimals.js';\n\nnew bigAnimals.Cat();\nnew domesticatedAnimals.Cat();\nIf renaming a named import is needed then use components of the imported\nmodule's file name or path in the resulting alias.
\n\nimport {Cat as BigCat} from './biganimals.js';\nimport {Cat as DomesticatedCat} from './domesticatedanimals.js';\n\nnew BigCat();\nnew DomesticatedCat();\n\n\n
Symbols are only exported if they are meant to be used outside the module.\nNon-exported module-local symbols are not declared @private. There is no\nprescribed ordering for exported and module-local symbols.
Use named exports in all code. You can apply the export keyword to a\ndeclaration, or use the export {name}; syntax.
Do not use default exports. Importing modules must give a name to these values,\nwhich can lead to inconsistencies in naming across modules.
\n\n// Do not use default exports:\nexport default class Foo { ... } // BAD!\n// Use named exports:\nexport class Foo { ... }\n// Alternate style named exports:\nclass Foo { ... }\n\nexport {Foo};\n\n\n
Exported variables must not be mutated outside of module initialization.
\n\nThere are alternatives if mutation is needed, including exporting a constant\nreference to an object that has mutable fields or exporting accessor functions for\nmutable data.
\n\n// Bad: both foo and mutateFoo are exported and mutated.\nexport let /** number */ foo = 0;\n\n/**\n * Mutates foo.\n */\nexport function mutateFoo() {\n ++foo;\n}\n\n/**\n * @param {function(number): number} newMutateFoo\n */\nexport function setMutateFoo(newMutateFoo) {\n // Exported classes and functions can be mutated!\n mutateFoo = () => {\n foo = newMutateFoo(foo);\n };\n}\n// Good: Rather than export the mutable variables foo and mutateFoo directly,\n// instead make them module scoped and export a getter for foo and a wrapper for\n// mutateFooFunc.\nlet /** number */ foo = 0;\nlet /** function(number): number */ mutateFooFunc = (foo) => foo + 1;\n\n/** @return {number} */\nexport function getFoo() {\n return foo;\n}\n\nexport function mutateFoo() {\n foo = mutateFooFunc(foo);\n}\n\n/** @param {function(number): number} mutateFoo */\nexport function setMutateFoo(mutateFoo) {\n mutateFooFunc = mutateFoo;\n}\n\n\n
export from statements must not be line wrapped and are therefore an\nexception to the 80-column limit. This applies to both export from flavors.
export {specificName} from './other.js';\nexport * from './another.js';\nDo not create cycles between ES modules, even though the ECMAScript\nspecification allows this. Note that it is possible to create cycles with both\nthe import and export statements.
// a.js\nimport './b.js';\n// b.js\nimport './a.js';\n\n// `export from` can cause circular dependencies too!\nexport {x} from './c.js';\n// c.js\nimport './b.js';\n\nexport let x;\n\n\n
\n\n
To reference the Closure goog namespace, import Closure's goog.js.
import * as goog from '../closure/goog/goog.js';\n\nconst {compute} = goog.require('a.name');\n\nexport const CONSTANT = compute();\ngoog.js exports only a subset of properties from the global goog that can be\nused in ES modules.
\n\n
goog.require in ES modules works as it does in goog.module files. You can\nrequire any Closure namespace symbol (i.e., symbols created by goog.provide or\ngoog.module) and goog.require will return the value.
import * as goog from '../closure/goog/goog.js';\nimport * as anEsModule from './anEsModule.js';\n\nconst GoogPromise = goog.require('goog.Promise');\nconst myNamespace = goog.require('my.namespace');\n\n\n
goog.declareModuleId can be used within ES modules to declare a\ngoog.module-like module ID. This means that this module ID can be\ngoog.required, goog.module.getd etc. as if it were\na goog.module that did not call goog.module.declareLegacyNamespace. It does\nnot create the module ID as a globally available JavaScript symbol.
A goog.require (or goog.module.get) for a module ID from\ngoog.declareModuleId will always return the module object (as if it was\nimport *'d). As a result, the argument to goog.declareModuleId should always\nend with a lowerCamelCaseName.
Note: It is an error to call goog.module.declareLegacyNamespace in an ES\nmodule, it can only be called from goog.module files. There is no direct way\nto associate a legacy
namespace with an ES module.
goog.declareModuleId should only be used to upgrade Closure files to ES\nmodules in place, where named exports are used.
import * as goog from '../closure/goog.js';\n\ngoog.declareModuleId('my.esm');\n\nexport class Class {};\ngoog.setTestOnlyIn a goog.module file the goog.module statement and, if present,\ngoog.module.declareLegacyNamespace() statement may optionally be followed by a\ncall to goog.setTestOnly().
In an ES module the import statements may optionally be\nfollowed by a call to goog.setTestOnly().
goog.require and goog.requireType statementsImports are done with goog.require and goog.requireType statements. The\nnames imported by a goog.require statement may be used both in code and in\ntype annotations, while those imported by a goog.requireType may be used in\ntype annotations only.
The goog.require and goog.requireType statements form a contiguous block\nwith no empty lines. This block follows the goog.module declaration separated\nby a single empty line. The entire argument to\ngoog.require or goog.requireType is a namespace defined by a goog.module\nin a separate file. goog.require and goog.requireType statements may not\nappear anywhere else in the file.
Each goog.require or goog.requireType is assigned to a single constant\nalias, or else destructured into several constant aliases. These aliases are the\nonly acceptable way to refer to dependencies in type annotations or code. Fully\nqualified namespaces must not be used anywhere, except as an argument to\ngoog.require or goog.requireType.
Exception: Types, variables, and functions declared in externs files have to\nuse their fully qualified name in type annotations and code.
\n\nWhen goog.require is assigned to a single constant alias, it must match the\nfinal dot-separated component of the imported module's namespace.
Exception: In certain cases, additional components of the namespace can be\nused to form a longer alias. The resulting alias must retain the original\nidentifier's casing such that it still correctly identifies its type. Longer\naliases may be used to disambiguate otherwise identical aliases, or if it\nsignificantly improves readability. In addition, a longer alias must be used to\nprevent masking native types such as Element, Event, Error, Map, and\nPromise (for a more complete list, see Standard Built-in Objects and\nWeb APIs at MDN).
A file should not contain both a goog.require and a goog.requireType\nstatement for the same namespace. If the imported name is used both in code and\nin type annotations, it should be imported by a single goog.require statement.
If a module is imported only for its side effects, the call must be a\ngoog.require (not a goog.requireType) and assignment may be omitted. A\ncomment is required to explain why this is needed and suppress a compiler\nwarning.
The lines are sorted according to the following rules: All requires with a name\non the left hand side come first, sorted alphabetically by those names. Then\ndestructuring requires, again sorted by the names on the left hand side.\nFinally, any require calls that are standalone (generally these are for modules\nimported just for their side effects).
\n\nTip: There’s no need to memorize this order and enforce it manually. You can\nrely on your IDE to report requires\nthat are not sorted correctly.
\n\nIf a long alias or module name would cause a line to exceed the 80-column limit,\nit must not be wrapped: require lines are an exception to the 80-column\nlimit.
\n\nExample:
\n\n// Standard alias style.\nconst asserts = goog.require('goog.asserts');\n// Namespace-based alias used to disambiguate.\nconst testingAsserts = goog.require('goog.testing.asserts');\n// Standard destructuring into aliases.\nconst {MyClass} = goog.require('some.package');\nconst {MyType} = goog.requireType('other.package');\nconst {clear, clone} = goog.require('goog.array');\nconst {Rgb} = goog.require('goog.color');\n// Namespace-based destructuring into aliases used to disambiguate.\nconst {MyClass: NsMyClass} = goog.require('other.ns');\nconst {SomeType: FooSomeType} = goog.requireType('foo.types');\nconst {clear: objectClear, clone: objectClone} = goog.require('goog.object');\n// Namespace-based destructuring into aliases used to prevent masking native type.\nconst {Element: RendererElement} = goog.require('web.renderer');\n// Out of sequence namespace-based aliases used to improve readability.\n// Also, require lines longer than 80 columns must not be wrapped.\nconst {SomeDataStructure: SomeDataStructureModel} = goog.requireType('identical.package.identifiers.models');\nconst {SomeDataStructure: SomeDataStructureProto} = goog.require('proto.identical.package.identifiers');\n// goog.require without an alias in order to trigger side effects.\n/** @suppress {extraRequire} Initializes MyFramework. */\ngoog.require('my.framework.initialization');\nDiscouraged:
\n\n// Some legacy code uses a \"default export\" style to export a single class, enum,\n// record type, etc. Do not use this pattern in new JS.\n// When using a \"default export\", prefer destructuring into aliases.\nconst MyClass = goog.require('some.package.MyClass');\nconst MyType = goog.requireType('some.package.MyType');\n// If necessary to disambiguate, prefer PackageClass over SomeClass as it is\n// closer to the format of the module name.\nconst SomeClass = goog.require('some.package.Class');\nDisallowed:
\n\n// Extra terms must come from the namespace.\nconst MyClassForBizzing = goog.require('some.package.MyClass');\n// Alias must include the entire final namespace component.\nconst MyClass = goog.require('some.package.MyClassForBizzing');\n// Alias must not mask native type (should be `const JspbMap` here).\nconst Map = goog.require('jspb.Map');\n// Don't break goog.require lines over 80 columns.\nconst SomeDataStructure =\n goog.require('proto.identical.package.identifiers.SomeDataStructure');\n// Alias must be based on the namespace.\nconst randomName = goog.require('something.else');\n// Missing a space after the colon.\nconst {Foo:FooProto} = goog.require('some.package.proto.Foo');\n// goog.requireType without an alias.\ngoog.requireType('some.package.with.a.Type');\n\n\n/**\n * @param {!some.unimported.Dependency} param All external types used in JSDoc\n * annotations must be goog.require'd, unless declared in externs.\n */\nfunction someFunction(param) {\n // goog.require lines must be at the top level before any other code.\n const alias = goog.require('my.long.name.alias');\n // ...\n}\nThe actual implementation follows after all dependency information is declared\n(separated by at least one blank line).
\n\nThis may consist of any module-local declarations (constants, variables,\nclasses, functions, etc), as well as any exported symbols.
\n\nTerminology Note: block-like construct refers to the body of a class,\nfunction, method, or brace-delimited block of code. Note that, by\n?? and ??, any array or\nobject literal may optionally be treated as if it were a block-like construct.
\n\nTip: Use clang-format. The JavaScript community has invested effort to make\nsure clang-format does the right thing
on JavaScript files. clang-format has\nintegration with several popular editors.
Braces are required for all control structures (i.e. if, else, for, do,\nwhile, as well as any others), even if the body contains only a single\nstatement. The first statement of a non-empty block must begin on its own line.
Disallowed:
\n\nif (someVeryLongCondition())\n doSomething();\n\nfor (let i = 0; i < foo.length; i++) bar(foo[i]);\nException: A simple if statement that can fit entirely on a single line with\nno wrapping (and that doesn’t have an else) may be kept on a single line with no\nbraces when it improves readability. This is the only case in which a control\nstructure may omit braces and newlines.
\n\nif (shortCondition()) foo();\nBraces follow the Kernighan and Ritchie style (Egyptian brackets
) for\nnonempty blocks and block-like constructs:
else,\ncatch, while, or a comma, semicolon, or right-parenthesis.Example:
\n\nclass InnerClass {\n constructor() {}\n\n /** @param {number} foo */\n method(foo) {\n if (condition(foo)) {\n try {\n // Note: this might fail.\n something();\n } catch (err) {\n recover();\n }\n }\n }\n}\nAn empty block or block-like construct may be closed immediately after it is\nopened, with no characters, space, or line break in between (i.e. {}),\nunless it is a part of a multi-block statement (one that directly contains\nmultiple blocks: if/else or try/catch/finally).
Example:
\n\nfunction doNothing() {}\nDisallowed:
\n\nif (condition) {\n // …\n} else if (otherCondition) {} else {\n // …\n}\n\ntry {\n // …\n} catch (e) {}\nEach time a new block or block-like construct is opened, the indent increases by\ntwo spaces. When the block ends, the indent returns to the previous indent\nlevel. The indent level applies to both code and comments throughout the block.\n(See the example in ??).
\n\nblock-like
Any array literal may optionally be formatted as if it were a “block-like\nconstruct.” For example, the following are all valid (not an exhaustive\nlist):
\n\nconst a = [\n 0,\n 1,\n 2,\n];\n\nconst b =\n [0, 1, 2];\n\nconst c = [0, 1, 2];\n\nsomeMethod(foo, [\n 0, 1, 2,\n], bar);\nOther combinations are allowed, particularly when emphasizing semantic groupings\nbetween elements, but should not be used only to reduce the vertical size of\nlarger arrays.
\n\nblock-like
Any object literal may optionally be formatted as if it were a “block-like\nconstruct.” The same examples apply as ??. For\nexample, the following are all valid (not an exhaustive list):
\n\nconst a = {\n a: 0,\n b: 1,\n};\n\nconst b =\n {a: 0, b: 1};\nconst c = {a: 0, b: 1};\n\nsomeMethod(foo, {\n a: 0, b: 1,\n}, bar);\nClass literals (whether declarations or expressions) are indented as blocks. Do\nnot add semicolons after methods, or after the closing brace of a class\ndeclaration (statements—such as assignments—that contain class expressions\nare still terminated with a semicolon). For inheritance, the extends keyword\nis sufficient unless the superclass is templatized. Subclasses of templatized\ntypes must explicitly specify the template type in an @extends JSDoc\nannotation, even if it is just passing along the same template name.
Example:
\n\n/** @template T */\nclass Foo {\n /** @param {T} x */\n constructor(x) {\n /** @type {T} */\n this.x = x;\n }\n}\n\n/** @extends {Foo<number>} */\nclass Bar extends Foo {\n constructor() {\n super(42);\n }\n}\n\nexports.Baz = class extends Bar {\n /** @return {number} */\n method() {\n return this.x;\n }\n};\n/** @extends {Bar} */ // <-- unnecessary @extends\nexports.Baz = class extends Bar {\n /** @return {number} */\n method() {\n return this.x;\n }\n};\nWhen declaring an anonymous function in the list of arguments for a function\ncall, the body of the function is indented two spaces more than the preceding\nindentation depth.
\n\nExample:
\n\nprefix.something.reallyLongFunctionName('whatever', (a1, a2) => {\n // Indent the function body +2 relative to indentation depth\n // of the 'prefix' statement one line above.\n if (a1.equals(a2)) {\n someOtherLongFunctionName(a1);\n } else {\n andNowForSomethingCompletelyDifferent(a2.parrot);\n }\n});\n\nsome.reallyLongFunctionCall(arg1, arg2, arg3)\n .thatsWrapped()\n .then((result) => {\n // Indent the function body +2 relative to the indentation depth\n // of the '.then()' call.\n if (result) {\n result.use();\n }\n });\nAs with any other block, the contents of a switch block are indented +2.
\n\n\n\nAfter a switch label, a newline appears, and the indentation level is increased\n+2, exactly as if a block were being opened. An explicit block may be used if\nrequired by lexical scoping. The following switch label returns to the previous\nindentation level, as if a block had been closed.
\n\nA blank line is optional between a break and the following case.
Example:
\n\nswitch (animal) {\n case Animal.BANDERSNATCH:\n handleBandersnatch();\n break;\n\n case Animal.JABBERWOCK:\n handleJabberwock();\n break;\n\n default:\n throw new Error('Unknown animal');\n}\nEach statement is followed by a line-break.
\n\nEvery statement must be terminated with a semicolon. Relying on automatic\nsemicolon insertion is forbidden.
\n\nJavaScript code has a column limit of 80 characters. Except as noted below, any\nline that would exceed this limit must be line-wrapped, as explained in\n??.
\n\nExceptions:
\n\ngoog.module, goog.require and goog.requireType statements (see\n?? and ??).import and export from statements (see\n?? and ??).Terminology Note: Line wrapping is breaking a chunk of code into multiple\nlines to obey column limit, where the chunk could otherwise legally fit in a\nsingle line.
\n\nThere is no comprehensive, deterministic formula showing exactly how to\nline-wrap in every situation. Very often there are several valid ways to\nline-wrap the same piece of code.
\n\nNote: While the typical reason for line-wrapping is to avoid overflowing the\ncolumn limit, even code that would in fact fit within the column limit may be\nline-wrapped at the author's discretion.
\n\nTip: Extracting a method or local variable may solve the problem without the\nneed to line-wrap.
\n\nThe prime directive of line-wrapping is: prefer to break at a higher syntactic\nlevel.
\n\nPreferred:
\n\ncurrentEstimate =\n calc(currentEstimate + x * currentEstimate) /\n 2.0;\nDiscouraged:
\n\ncurrentEstimate = calc(currentEstimate + x *\n currentEstimate) / 2.0;\nIn the preceding example, the syntactic levels from highest to lowest are as\nfollows: assignment, division, function call, parameters, number constant.
\n\nOperators are wrapped as follows:
\n\ndot(
.), which is not actually an\noperator.()\nthat follows it.,) stays attached to the token that precedes it.{. This is necessary as\nannotations with optional types (@const, @private, @param, etc) do not scan\nthe next line.
\n\n\nNote: The primary goal for line wrapping is to have clear code, not\nnecessarily code that fits in the smallest number of lines.
\n
When line-wrapping, each line after the first (each continuation line) is\nindented at least +4 from the original line, unless it falls under the rules of\nblock indentation.
\n\nWhen there are multiple continuation lines, indentation may be varied beyond +4\nas appropriate. In general, continuation lines at a deeper syntactic level are\nindented by larger multiples of 4, and two lines use the same indentation level\nif and only if they begin with syntactically parallel elements.
\n\n?? addresses the discouraged practice of\nusing a variable number of spaces to align certain tokens with previous lines.
\n\nA single blank line appears:
\n\nMultiple consecutive blank lines are permitted, but never required (nor\nencouraged).
\n\nUse of horizontal whitespace depends on location, and falls into three broad\ncategories: leading (at the start of a line), trailing (at the end of a\nline), and internal. Leading whitespace (i.e., indentation) is addressed\nelsewhere. Trailing whitespace is forbidden.
\n\nBeyond where required by the language or other style rules, and apart from\nliterals, comments, and JSDoc, a single internal ASCII space also appears in the\nfollowing places only.
\n\nif, for, or catch) except for\nfunction and super, from an open parenthesis (() that follows it on\nthat line.else or catch) from a closing\ncurly brace (}) that precedes it on that line.{), with two exceptions:\nfoo({a: [{c: d}]})).`ab${1 + 2}cd`, invalid: `xy$ {3}z`).,) or semicolon (;). Note that spaces are never allowed\nbefore these characters.:) in an object literal.//) that begins an end-of-line comment.\nHere, multiple spaces are allowed, but not required.this.foo = /** @type {number} */ (bar); or function(/** string */ foo)\n{; or baz(/* buzz= */ true)).Terminology Note: Horizontal alignment is the practice of adding a\nvariable number of additional spaces in your code with the goal of making\ncertain tokens appear directly below certain other tokens on previous lines.
\n\nThis practice is permitted, but it is generally discouraged by Google Style.\nIt is not even required to maintain horizontal alignment in places where it\nwas already used.
\n\nHere is an example without alignment, followed by one with alignment. Both are\nallowed, but the latter is discouraged:
\n\n{\n tiny: 42, // this is great\n longer: 435, // this too\n};\n\n{\n tiny: 42, // permitted, but future edits\n longer: 435, // may leave it unaligned\n};\nTip: Alignment can aid readability, but it creates problems for future\nmaintenance. Consider a future change that needs to touch just one line. This\nchange may leave the formerly-pleasing formatting mangled, and that is allowed.\nMore often it prompts the coder (perhaps you) to adjust whitespace on nearby\nlines as well, possibly triggering a cascading series of reformattings. That\none-line change now has a blast radius.
This can at worst result in pointless\nbusywork, but at best it still corrupts version history information, slows down\nreviewers and exacerbates merge conflicts.
Prefer to put all function arguments on the same line as the function name. If\ndoing so would exceed the 80-column limit, the arguments must be line-wrapped in\na readable way. To save space, you may wrap as close to 80 as possible, or put\neach argument on its own line to enhance readability. Indentation should be four\nspaces. Aligning to the parenthesis is allowed, but discouraged. Below are the\nmost common patterns for argument wrapping:
\n\n// Arguments start on a new line, indented four spaces. Preferred when the\n// arguments don't fit on the same line with the function name (or the keyword\n// \"function\") but fit entirely on the second line. Works with very long\n// function names, survives renaming without reindenting, low on space.\ndoSomething(\n descriptiveArgumentOne, descriptiveArgumentTwo, descriptiveArgumentThree) {\n // …\n}\n\n// If the argument list is longer, wrap at 80. Uses less vertical space,\n// but violates the rectangle rule and is thus not recommended.\ndoSomething(veryDescriptiveArgumentNumberOne, veryDescriptiveArgumentTwo,\n tableModelEventHandlerProxy, artichokeDescriptorAdapterIterator) {\n // …\n}\n\n// Four-space, one argument per line. Works with long function names,\n// survives renaming, and emphasizes each argument.\ndoSomething(\n veryDescriptiveArgumentNumberOne,\n veryDescriptiveArgumentTwo,\n tableModelEventHandlerProxy,\n artichokeDescriptorAdapterIterator) {\n // …\n}\nOptional grouping parentheses are omitted only when the author and reviewer\nagree that there is no reasonable chance that the code will be misinterpreted\nwithout them, nor would they have made the code easier to read. It is not\nreasonable to assume that every reader has the entire operator precedence table\nmemorized.
\n\nDo not use unnecessary parentheses around the entire expression following\ndelete, typeof, void, return, throw, case, in, of, or yield.
Parentheses are required for type casts: /** @type {!Foo} */ (foo).
This section addresses implementation comments. JSDoc is addressed separately\nin ??.
\n\nBlock comments are indented at the same level as the surrounding code. They may\nbe in /* … */ or //-style. For multi-line /* … */ comments, subsequent\nlines must start with * aligned with the * on the previous line, to make\ncomments obvious with no extra context.
/*\n * This is\n * okay.\n */\n\n// And so\n// is this.\n\n/* This is fine, too. */\nComments are not enclosed in boxes drawn with asterisks or other characters.
\n\nDo not use JSDoc (/** … */) for implementation comments.
“Parameter name” comments should be used whenever the value and method name do\nnot sufficiently convey the meaning, and refactoring the method to be clearer is\ninfeasible .\nTheir preferred format is before the value with =
:
someFunction(obviousParam, /* shouldRender= */ true, /* name= */ 'hello');\nFor consistency with surrounding code you may put them after the value without\n=
:
someFunction(obviousParam, true /* shouldRender */, 'hello' /* name */);\nJavaScript includes many dubious (and even dangerous) features. This section\ndelineates which features may or may not be used, and any additional constraints\non their use.
\n\nLanguage features which are not discussed in this style guide may be used with\nno recommendations of their usage.
\n\nconst and letDeclare all local variables with either const or let. Use const by\ndefault, unless a variable needs to be reassigned. The var keyword\nmust not be used.
Every local variable declaration declares only one variable: declarations such\nas let a = 1, b = 2; are not used.
Local variables are not habitually declared at the start of their containing\nblock or block-like construct. Instead, local variables are declared close to\nthe point they are first used (within reason), to minimize their scope, and\ninitialized as soon as possible.
\n\nJSDoc type annotations may be added either on the line above the declaration, or\nelse inline before the variable name if no other JSDoc is present.
\n\nExample:
\n\nconst /** !Array<number> */ data = [];\n\n/**\n * Some description.\n * @type {!Array<number>}\n */\nconst data = [];\nMixing inline and JSDoc styles is not allowed: the compiler will only process\nthe first JsDoc and the inline annotations will be lost.
\n\n/** Some description. */\nconst /** !Array<number> */ data = [];\nTip: There are many cases where the compiler can infer a templatized type but\nnot its parameters. This is particularly the case when the initializing literal\nor constructor call does not include any values of the template parameter type\n(e.g., empty arrays, objects, Maps, or Sets), or if the variable is modified\nin a closure. Local variable type annotations are particularly helpful in these\ncases since otherwise the compiler will infer the template parameter as unknown.
Include a trailing comma whenever there is a line break between the final\nelement and the closing bracket.
\n\nExample:
\n\nconst values = [\n 'first value',\n 'second value',\n];\nArray constructorThe constructor is error-prone if arguments are added or removed. Use a literal\ninstead.
\n\nDisallowed:
\n\nconst a1 = new Array(x1, x2, x3);\nconst a2 = new Array(x1, x2);\nconst a3 = new Array(x1);\nconst a4 = new Array();\nThis works as expected except for the third case: if x1 is a whole number then\na3 is an array of size x1 where all elements are undefined. If x1 is any\nother number, then an exception will be thrown, and if it is anything else then\nit will be a single-element array.
Instead, write
\n\nconst a1 = [x1, x2, x3];\nconst a2 = [x1, x2];\nconst a3 = [x1];\nconst a4 = [];\nExplicitly allocating an array of a given length using new Array(length) is\nallowed when appropriate.
Do not define or use non-numeric properties on an array (other than length).\nUse a Map (or Object) instead.
Array literals may be used on the left-hand side of an assignment to perform\ndestructuring (such as when unpacking multiple values from a single array or\niterable). A final rest
element may be included (with no space between the\n... and the variable name). Elements should be omitted if they are unused.
const [a, b, c, ...rest] = generateResults();\nlet [, b,, d] = someArray;\nDestructuring may also be used for function parameters (note that a parameter\nname is required but ignored). Always specify [] as the default value if a\ndestructured array parameter is optional, and provide default values on the left\nhand side:
/** @param {!Array<number>=} param1 */\nfunction optionalDestructuring([a = 4, b = 2] = []) { … };\nDisallowed:
\n\nfunction badDestructuring([a, b] = [4, 2]) { … };\nTip: For (un)packing multiple values into a function’s parameter or return,\nprefer object destructuring to array destructuring when possible, as it allows\nnaming the individual elements and specifying a different type for each.
\n\nArray literals may include the spread operator (...) to flatten elements out\nof one or more other iterables. The spread operator should be used instead of\nmore awkward constructs with Array.prototype. There is no space after the\n....
Example:
\n\n[...foo] // preferred over Array.prototype.slice.call(foo)\n[...foo, ...bar] // preferred over foo.concat(bar)\nInclude a trailing comma whenever there is a line break between the final\nproperty and the closing brace.
\n\nObject constructorWhile Object does not have the same problems as Array, it is still\ndisallowed for consistency. Use an object literal ({} or {a: 0, b: 1, c: 2})\ninstead.
Object literals may represent either structs (with unquoted keys and/or\nsymbols) or dicts (with quoted and/or computed keys). Do not mix these key\ntypes in a single object literal.
\n\nDisallowed:
\n\n{\n width: 42, // struct-style unquoted key\n 'maxWidth': 43, // dict-style quoted key\n}\nThis also extends to passing the property name to functions, like\nhasOwnProperty. In particular, doing so will break in compiled code because\nthe compiler cannot rename/obfuscate the string literal.
Disallowed:
\n\n/** @type {{width: number, maxWidth: (number|undefined)}} */\nconst o = {width: 42};\nif (o.hasOwnProperty('maxWidth')) {\n ...\n}\nThis is best implemented as:
\n\n/** @type {{width: number, maxWidth: (number|undefined)}} */\nconst o = {width: 42};\nif (o.maxWidth != null) {\n ...\n}\nComputed property names (e.g., {['key' + foo()]: 42}) are allowed, and are\nconsidered dict-style (quoted) keys (i.e., must not be mixed with non-quoted\nkeys) unless the computed property is a\nsymbol\n(e.g., [Symbol.iterator]). Enum values may also be used for computed keys, but\nshould not be mixed with non-enum keys in the same literal.
Methods can be defined on object literals using the method shorthand ({method()\n{… }}) in place of a colon immediately followed by a function or arrow\nfunction literal.
Example:
\n\nreturn {\n stuff: 'candy',\n method() {\n return this.stuff; // Returns 'candy'\n },\n};\nNote that this in a method shorthand or function refers to the object\nliteral itself whereas this in an arrow function refers to the scope outside\nthe object literal.
Example:
\n\nclass {\n getObjectLiteral() {\n this.stuff = 'fruit';\n return {\n stuff: 'candy',\n method: () => this.stuff, // Returns 'fruit'\n };\n }\n}\nShorthand properties are allowed on object literals.
\n\nExample:
\n\nconst foo = 1;\nconst bar = 2;\nconst obj = {\n foo,\n bar,\n method() { return this.foo + this.bar; },\n};\nassertEquals(3, obj.method());\nObject destructuring patterns may be used on the left-hand side of an assignment\nto perform destructuring and unpack multiple values from a single object.
\n\nDestructured objects may also be used as function parameters, but should be kept\nas simple as possible: a single level of unquoted shorthand properties. Deeper\nlevels of nesting and computed properties may not be used in parameter\ndestructuring. Specify any default values in the left-hand-side of the\ndestructured parameter ({str = 'some default'} = {}, rather than\n{str} = {str: 'some default'}), and if a\ndestructured object is itself optional, it must default to {}. The JSDoc for\nthe destructured parameter may be given any name (the name is unused but is\nrequired by the compiler).
Example:
\n\n/**\n * @param {string} ordinary\n * @param {{num: (number|undefined), str: (string|undefined)}=} param1\n * num: The number of times to do something.\n * str: A string to do stuff to.\n */\nfunction destructured(ordinary, {num, str = 'some default'} = {}) {}\nDisallowed:
\n\n/** @param {{x: {num: (number|undefined), str: (string|undefined)}}} param1 */\nfunction nestedTooDeeply({x: {num, str}}) {};\n/** @param {{num: (number|undefined), str: (string|undefined)}=} param1 */\nfunction nonShorthandProperty({num: a, str: b} = {}) {};\n/** @param {{a: number, b: number}} param1 */\nfunction computedKey({a, b, [a + b]: c}) {};\n/** @param {{a: number, b: string}=} param1 */\nfunction nontrivialDefault({a, b} = {a: 2, b: 4}) {};\nDestructuring may also be used for goog.require statements, and in this case\nmust not be wrapped: the entire statement occupies one line, regardless of how\nlong it is (see ??).
Enumerations are defined by adding the @enum annotation to an object literal.\nEnums must be module-local or assigned directly on exports, not nested under a\ntype or object.
Additional properties may not be added to an enum after it is defined. Enums\nmust be constant. All enum values must be either a string literal or a number.
\n\n/**\n * Supported temperature scales.\n * @enum {string}\n */\nconst TemperatureScale = {\n CELSIUS: 'celsius',\n FAHRENHEIT: 'fahrenheit',\n};\n\n/**\n * An enum with two values.\n * @enum {number}\n */\nconst Value = {\n /** The value used shall have been the first. */\n FIRST_VALUE: 1,\n /** The second among two values. */\n SECOND_VALUE: 2,\n};\nFor string enums, all values must be statically initialized and not computed\nusing arithmetic operators, template literal substitution, function calls or\neven a variable reference.
\n\nconst ABSOLUTE_ZERO = '-273°F';\n\n/**\n * Not supported computed values in string enum.\n * @enum {string}\n */\nconst TemperatureInFahrenheit = {\n MIN_POSSIBLE: ABSOLUTE_ZERO,\n ZERO_FAHRENHEIT: 0 + '°F',\n ONE_FAHRENHEIT: `${Values.FIRST_VALUE}°F`,\n TWO_FAHRENHEIT: Values.SECOND_VALUE + '°F',\n SOME_FAHRENHEIT: getTemperatureInFahrenheit() + '°F',\n};\nNote: Although TypeScript supports a few more patterns for enum values (e.g A:\n'a'+'b', etc), the restriction of only allowing string literals and numbers for\nenum values is to aid migration to TypeScript. For complex values consider using\na const object without @enum.
Constructors are optional. Subclass constructors must call super() before\nsetting any fields or otherwise accessing this. Interfaces should declare\nnon-method properties in the constructor.
Define all of a concrete object’s fields (i.e. all properties other than\nmethods) in the constructor. Annotate fields that are never reassigned with\n@const (these need not be deeply immutable). Annotate non-public fields with\nthe proper visibility annotation (@private, @protected, @package).\n@private fields' names may optionally end with an underscore. Fields must not\nbe defined within a nested scope in the constructor nor on a concrete class's\nprototype.
Example:
\n\nclass Foo {\n constructor() {\n /** @private @const {!Bar} */\n this.bar_ = computeBar();\n\n /** @protected @const {!Baz} */\n this.baz = computeBaz();\n }\n}\nTip: Properties should never be added to or removed from an instance after the\nconstructor is finished, since it significantly hinders VMs’ ability to\noptimize. If necessary, fields that are initialized later should be explicitly\nset to undefined in the constructor to prevent later shape changes. Adding\n@struct to an object will check that undeclared properties are not\nadded/accessed. Classes have this added by default.
Computed properties may only be used in classes when the property is a symbol.\nDict-style properties (that is, quoted or computed non-symbol keys, as defined\nin ??) are not allowed. A [Symbol.iterator]\nmethod should be defined for any classes that are logically iterable. Beyond\nthis, Symbol should be used sparingly.
Tip: be careful of using any other built-in symbols (e.g.,\nSymbol.isConcatSpreadable) as they are not polyfilled by the compiler and will\ntherefore not work in older browsers.
Where it does not interfere with readability, prefer module-local functions over\nprivate static methods.
\n\nCode should not rely on dynamic dispatch of static methods, because it\ninterferes with Closure Compiler optimizations. Static methods should only be\ncalled on the base class itself. Static methods should not be called on\nvariables containing a dynamic instance that may be either the constructor or a\nsubclass constructor (and must be defined with @nocollapse if this is done),\nand must not be called directly on a subclass that doesn’t define the method\nitself. Do not access this in static methods.
Disallowed:
\n\n// Context for the examples below; by itself this code is allowed.\nclass Base {\n /** @nocollapse */ static foo() {}\n}\nclass Sub extends Base {}\n\n// discouraged: don't call static methods dynamically\nfunction callFoo(cls) { cls.foo(); }\n\n// Disallowed: don't call static methods on subclasses that don't define it themselves\nSub.foo();\n\n// Disallowed: don't access this in static methods.\nclass Clazz {\n static foo() {\n return this.staticField;\n }\n}\nClass.staticField = 1;\nWhile ES6 classes are preferred, there are cases where ES6 classes may not be\nfeasible. For example:
\n\nIf there exist or will exist subclasses, including frameworks that create\nsubclasses, that cannot be immediately changed to use ES6 class syntax. If\nsuch a class were to use ES6 syntax, all downstream subclasses not using ES6\nclass syntax would need to be modified.
Frameworks that require a known this value before calling the superclass\nconstructor, since constructors with ES6 super classes do not have access to\nthe instance this value until the call to super returns.
In all other ways the style guide still applies to this code: let, const,\ndefault parameters, rest, and arrow functions should all be used when\nappropriate.
goog.defineClass allows for a class-like definition similar to ES6 class\nsyntax:
let C = goog.defineClass(S, {\n /**\n * @param {string} value\n */\n constructor(value) {\n S.call(this, 2);\n /** @const */\n this.prop = value;\n },\n\n /**\n * @param {string} param\n * @return {number}\n */\n method(param) {\n return 0;\n },\n});\nAlternatively, while goog.defineClass should be preferred for all new code,\nmore traditional syntax is also allowed.
/**\n * @constructor @extends {S}\n * @param {string} value\n */\nfunction C(value) {\n S.call(this, 2);\n /** @const */\n this.prop = value;\n}\ngoog.inherits(C, S);\n\n/**\n * @param {string} param\n * @return {number}\n */\nC.prototype.method = function(param) {\n return 0;\n};\nPer-instance properties should be defined in the constructor after the call to\nthe super class constructor, if there is a super class. Methods should be\ndefined on the prototype of the constructor.
\n\nDefining constructor prototype hierarchies correctly is harder than it first\nappears! For that reason, it is best to use goog.inherits from\nthe Closure Library .
prototypes directlyThe class keyword allows clearer and more readable class definitions than\ndefining prototype properties. Ordinary implementation code has no business\nmanipulating these objects, though they are still useful for defining classes as\ndefined in ??. Mixins and modifying the\nprototypes of builtin objects are explicitly forbidden.
Exception: Framework code (such as Polymer, or Angular) may need to use prototypes, and should not resort\nto even-worse workarounds to avoid doing so.
Do not use JavaScript getter and setter properties. They are potentially\nsurprising and difficult to reason about, and have limited support in the\ncompiler. Provide ordinary methods instead.
\n\nException: there are situations where defining a getter or setter is\nunavoidable (e.g. data binding frameworks such as Angular and Polymer, or for\ncompatibility with external APIs that cannot be adjusted). In these cases only,\ngetters and setters may be used with caution, provided they are defined with\nthe get and set shorthand method keywords or Object.defineProperties (not\nObject.defineProperty, which interferes with property renaming). Getters\nmust not change observable state.
Disallowed:
\n\nclass Foo {\n get next() { return this.nextId++; }\n}\nThe toString method may be overridden, but must always succeed and never have\nvisible side effects.
Tip: Beware, in particular, of calling other methods from toString, since\nexceptional conditions could lead to infinite loops.
\n\nInterfaces may be declared with @interface or @record. Interfaces declared\nwith @record can be explicitly (i.e. via @implements) or implicitly\nimplemented by a class or object literal.
All methods on an interface must be non-static and method bodies must be empty\nblocks. Fields must be declared as uninitialized members in the class\nconstructor.
\n\nExample:
\n\n/**\n * Something that can frobnicate.\n * @record\n */\nclass Frobnicator {\n constructor() {\n /** @type {number} The number of attempts before giving up. */\n this.attempts;\n }\n\n /**\n * Performs the frobnication according to the given strategy.\n * @param {!FrobnicationStrategy} strategy\n */\n frobnicate(strategy) {}\n}\n\nUse abstract classes when appropriate. Abstract classes and methods must be\nannotated with @abstract. Do not use goog.abstractMethod. See\nabstract classes and methods.
Do not use container classes with only static methods or properties for the sake\nof namespacing.
\n\n// container.js\n// Bad: Container is an exported class that has only static methods and fields.\nclass Container {\n /** @return {number} */\n static bar() {\n return 1;\n }\n}\n\n/** @const {number} */\nContainer.FOO = 1;\n\nexports = {Container};\nInstead, export individual constants and functions:
\n\n/** @return {number} */\nexports.bar = () => {\n return 1;\n}\n\n/** @const {number} */\nexports.FOO = 1;\nDo not define a nested type (e.g. class, typedef, enum, interface) on another\nmodule-local name.
\n\n// foo.js\ngoog.module('my.namespace');\n\nclass Foo {...}\n\nFoo.Bar = class {...};\n\n/** @enum {number} */\nFoo.Baz = {...};\n\n/** @typedef {{value: number}} */\nFoo.Qux;\n\n/** @interface */\nFoo.Quuz = class {...}\n\nexports.Foo = Foo;\nThese values should be top-level exports. Choose clear names for these values\n(e.g. FooConverter for a Converter that could have been nested on Foo). However,\nwhen the module name is redundant with part of the class name, consider omitting\nthe redundancy: foo.Foo and foo.Converter rather than foo.Foo and\nfoo.FooConverter. Importers can add the prefix when necessary for clarity\n(e.g. import {Converter as FooConverter} from './foo';) but cannot easily\nremove the redundancy when importing the entire module as a namespace.
// foo.js\ngoog.module('my.namespace');\n\nclass Foo {...}\n\nclass FooBar {...}\n\n/** @enum {string} */\nlet FooBaz = {...};\n\n/** @typedef {{value: number}} */\nlet FooQux;\n\n/** @interface */\nclass FooQuuz {...};\n\nexport = {\n Foo,\n FooBar,\n FooBaz,\n FooQux,\n FooQuuz,\n};\nTop-level functions may be defined directly on the exports object, or else\ndeclared locally and optionally exported. See ??\nfor more on exports.
Examples:
\n\n/** @param {string} str */\nexports.processString = (str) => {\n // Process the string.\n};\n/** @param {string} str */\nconst processString = (str) => {\n // Process the string.\n};\n\nexports = {processString};\nFunctions may contain nested function definitions. If it is useful to give the\nfunction a name, it should be assigned to a local const.
Arrow functions provide a concise function syntax and simplify scoping this\nfor nested functions. Prefer arrow functions over the function keyword for\nnested functions (but see ??).
Prefer arrow functions over other this scoping approaches such as\nf.bind(this), goog.bind(f, this), and const self = this. Arrow functions\nare particularly useful for calling into callbacks as they permit explicitly\nspecifying which parameters to pass to the callback whereas binding will blindly\npass along all parameters.
The left-hand side of the arrow contains zero or more parameters. Parentheses\naround the parameters are optional if there is only a single non-destructured\nparameter. When parentheses are used, inline parameter types may be specified\n(see ??).
\n\nTip: Always using parentheses even for single-parameter arrow functions can\navoid situations where adding parameters, but forgetting to add parentheses, may\nresult in parseable code which no longer works as intended.
\n\nThe right-hand side of the arrow contains the body of the function. By default\nthe body is a block statement (zero or more statements surrounded by curly\nbraces). The body may also be an implicitly returned single expression if\neither: the program logic requires returning a value, or the void operator\nprecedes a single function or method call (using void ensures undefined is\nreturned, prevents leaking values, and communicates intent). The single\nexpression form is preferred if it improves readability (e.g., for short or\nsimple expressions).
Examples:
\n\n/**\n * Arrow functions can be documented just like normal functions.\n * @param {number} numParam A number to add.\n * @param {string} strParam Another number to add that happens to be a string.\n * @return {number} The sum of the two parameters.\n */\nconst moduleLocalFunc = (numParam, strParam) => numParam + Number(strParam);\n\n// Uses the single expression syntax with `void` because the program logic does\n// not require returning a value.\ngetValue((result) => void alert(`Got ${result}`));\n\nclass CallbackExample {\n constructor() {\n /** @private {number} */\n this.cachedValue_ = 0;\n\n // For inline callbacks, you can use inline typing for parameters.\n // Uses a block statement because the value of the single expression should\n // not be returned and the expression is not a single function call.\n getNullableValue((/** ?number */ result) => {\n this.cachedValue_ = result == null ? 0 : result;\n });\n }\n}\nDisallowed:
\n\n/**\n * A function with no params and no returned value.\n * This single expression body usage is illegal because the program logic does\n * not require returning a value and we're missing the `void` operator.\n */\nconst moduleLocalFunc = () => anotherFunction();\nGenerators enable a number of useful abstractions and may be used as needed.
\n\nWhen defining generator functions, attach the * to the function keyword when\npresent, and separate it with a space from the name of the function. When using\ndelegating yields, attach the * to the yield keyword.
Example:
\n\n/** @return {!Iterator<number>} */\nfunction* gen1() {\n yield 42;\n}\n\n/** @return {!Iterator<number>} */\nconst gen2 = function*() {\n yield* gen1();\n}\n\nclass SomeClass {\n /** @return {!Iterator<number>} */\n * gen() {\n yield 42;\n }\n}\nFunction parameters and return types should usually be documented with JSDoc\nannotations. See ?? for more information.
\n\nOptional parameters are permitted using the equals operator in the parameter\nlist. Optional parameters must include spaces on both sides of the equals\noperator, be named exactly like required parameters (i.e., not prefixed with\nopt_), use the = suffix in their JSDoc type, come after required parameters,\nand not use initializers that produce observable side effects. All optional\nparameters for concrete functions must have default values, even if that value\nis undefined. In contrast to concrete functions, abstract and interface\nmethods must omit default parameter values.
Example:
\n\n/**\n * @param {string} required This parameter is always needed.\n * @param {string=} optional This parameter can be omitted.\n * @param {!Node=} node Another optional parameter.\n */\nfunction maybeDoSomething(required, optional = '', node = undefined) {}\n\n/** @interface */\nclass MyInterface {\n /**\n * Interface and abstract methods must omit default parameter values.\n * @param {string=} optional\n */\n someMethod(optional) {}\n}\nUse default parameters sparingly. Prefer destructuring (as in\n??) to create readable APIs when there are\nmore than a small handful of optional parameters that do not have a natural\norder.
\n\nNote: Unlike Python's default parameters, it is okay to use initializers that\nreturn new mutable objects (such as {} or []) because the initializer is\nevaluated each time the default value is used, so a single object won't be\nshared across invocations.
Tip: While arbitrary expressions including function calls may be used as\ninitializers, these should be kept as simple as possible. Avoid initializers\nthat expose shared mutable state, as that can easily introduce unintended\ncoupling between function calls.
\n\nUse a rest parameter instead of accessing arguments. Rest parameters are\ntyped with a ... prefix in their JSDoc. The rest parameter must be the last\nparameter in the list. There is no space between the ... and the parameter\nname. Do not name the rest parameter var_args. Never name a local variable or\nparameter arguments, which confusingly shadows the built-in name.
Example:
\n\n/**\n * @param {!Array<string>} array This is an ordinary parameter.\n * @param {...number} numbers The remainder of arguments are all numbers.\n */\nfunction variadic(array, ...numbers) {}\nDeclare generic functions and methods when necessary with @template TYPE in\nthe JSDoc above the function or method definition.
Function calls may use the spread operator (...). Prefer the spread operator\nto Function.prototype.apply when an array or iterable is unpacked into\nmultiple parameters of a variadic function. There is no space after the ....
Example:
\n\nfunction myFunction(...elements) {}\nmyFunction(...array, ...iterable, ...generator());\nOrdinary string literals are delimited with single quotes ('), rather than\ndouble quotes (\").
Tip: if a string contains a single quote character, consider using a template\nstring to avoid having to escape the quote.
\n\nOrdinary string literals may not span multiple lines.
\n\nUse template literals (delimited with `) over complex string\nconcatenation, particularly if multiple string literals are involved. Template\nliterals may span multiple lines.
If a template literal spans multiple lines, it does not need to follow the\nindentation of the enclosing block, though it may if the added whitespace does\nnot matter.
\n\nExample:
\n\nfunction arithmetic(a, b) {\n return `Here is a table of arithmetic operations:\n${a} + ${b} = ${a + b}\n${a} - ${b} = ${a - b}\n${a} * ${b} = ${a * b}\n${a} / ${b} = ${a / b}`;\n}\nDo not use line continuations (that is, ending a line inside a string literal\nwith a backslash) in either ordinary or template string literals. Even though\nES5 allows this, it can lead to tricky errors if any trailing whitespace comes\nafter the slash, and is less obvious to readers.
\n\nDisallowed:
\n\nconst longString = 'This is a very long string that far exceeds the 80 \\\n column limit. It unfortunately contains long stretches of spaces due \\\n to how the continued lines are indented.';\nInstead, write
\n\nconst longString = 'This is a very long string that far exceeds the 80 ' +\n 'column limit. It does not contain long stretches of spaces since ' +\n 'the concatenated strings are cleaner.';\nNumbers may be specified in decimal, hex, octal, or binary. Use exactly 0x,\n0o, and 0b prefixes, with lowercase letters, for hex, octal, and binary,\nrespectively. Never include a leading zero unless it is immediately followed by\nx, o, or b.
With ES6, the language now has three different kinds of for loops. All may be\nused, though for-of loops should be preferred when possible.
for-in loops may only be used on dict-style objects (see\n??), and should not be used to iterate over an\narray. Object.prototype.hasOwnProperty should be used in for-in loops to\nexclude unwanted prototype properties. Prefer for-of and Object.keys over\nfor-in when possible.
Exceptions are an important part of the language and should be used whenever\nexceptional cases occur. Always throw Errors or subclasses of Error: never\nthrow string literals or other objects. Always use new when constructing an\nError.
This treatment extends to Promise rejection values as Promise.reject(obj) is\nequivalent to throw obj; in async functions.
Custom exceptions provide a great way to convey additional error information\nfrom functions. They should be defined and used wherever the native Error type\nis insufficient.
Prefer throwing exceptions over ad-hoc error-handling approaches (such as\npassing an error container reference type, or returning an object with an error\nproperty).
\n\nIt is very rarely correct to do nothing in response to a caught exception. When\nit truly is appropriate to take no action whatsoever in a catch block, the\nreason this is justified is explained in a comment.
\n\ntry {\n return handleNumericResponse(response);\n} catch (ok) {\n // it's not numeric; that's fine, just continue\n}\nreturn handleTextResponse(response);\nDisallowed:
\n\n try {\n shouldFail();\n fail('expected an error');\n } catch (expected) {\n }\nTip: Unlike in some other languages, patterns like the above simply don’t work\nsince this will catch the error thrown by fail. Use assertThrows() instead.
Terminology Note: Inside the braces of a switch block are one or more statement\ngroups. Each statement group consists of one or more switch labels (either case\nFOO: or default:), followed by one or more statements.
Within a switch block, each statement group either terminates abruptly (with a\nbreak, return or thrown exception), or is marked with a comment to\nindicate that execution will or might continue into the next statement group.\nAny comment that communicates the idea of fall-through is sufficient (typically\n// fall through). This special comment is not required in the last statement\ngroup of the switch block.
Example:
\n\nswitch (input) {\n case 1:\n case 2:\n prepareOneOrTwo();\n // fall through\n case 3:\n handleOneTwoOrThree();\n break;\n default:\n handleLargeNumber(input);\n}\ndefault case is presentEach switch statement includes a default statement group, even if it contains\nno code. The default statement group must be last.
Only use this in class constructors and methods, in arrow functions defined\nwithin class constructors and methods, or in functions that have an explicit\n@this declared in the immediately-enclosing function’s JSDoc.
Never use this to refer to the global object, the context of an eval, the\ntarget of an event, or unnecessarily call()ed or apply()ed functions.
Use identity operators (===/!==) except in the cases documented below.
Catching both null and undefined values:
if (someObjectOrPrimitive == null) {\n // Checking for null catches both null and undefined for objects and\n // primitives, but does not catch other falsy values like 0 or the empty\n // string.\n}\nDo not use the with keyword. It makes your code harder to understand and has\nbeen banned in strict mode since ES5.
Do not use eval or the Function(...string) constructor (except for code\nloaders). These features are potentially dangerous and simply do not work in CSP\nenvironments.
Always terminate statements with semicolons (except function and class\ndeclarations, as noted above).
\n\nDo not use non-standard features. This includes old features that have been\nremoved (e.g., WeakMap.clear), new features that are not yet standardized\n(e.g., the current TC39 working draft, proposals at any stage, or proposed but\nnot-yet-complete web standards), or proprietary features that are only\nimplemented in some browsers. Use only features defined in the current ECMA-262\nor WHATWG standards. (Note that projects writing against specific APIs, such as\nChrome extensions or Node.js, can obviously use those APIs). Non-standard\nlanguage “extensions” (such as those provided by some external transpilers) are\nforbidden.
Never use new on the primitive object wrappers (Boolean, Number, String,\nSymbol), nor include them in type annotations.
Disallowed:
\n\nconst /** Boolean */ x = new Boolean(false);\nif (x) alert(typeof x); // alerts 'object' - WAT?\nThe wrappers may be called as functions for coercing (which is preferred over\nusing + or concatenating the empty string) or creating symbols.
Example:
\n\nconst /** boolean */ x = Boolean(0);\nif (!x) alert(typeof x); // alerts 'boolean', as expected\nNever modify builtin types, either by adding methods to their constructors or to\ntheir prototypes. Avoid depending on libraries that do this. Note that the\nJSCompiler’s runtime library will provide standards-compliant polyfills where\npossible; nothing else may modify builtin objects.
\n\nDo not add symbols to the global object unless absolutely necessary (e.g.\nrequired by a third-party API).
\n\n() when invoking a constructorNever invoke a constructor in a new statement without using parentheses ().
Disallowed:
\n\nnew Foo;\nUse instead:
\n\nnew Foo();\nOmitting parentheses can lead to subtle mistakes. These two lines are not\nequivalent:
\n\nnew Foo().Bar();\nnew Foo.Bar();\nIdentifiers use only ASCII letters and digits, and, in a small number of cases\nnoted below, underscores and very rarely (when required by frameworks like\nAngular) dollar signs.
\n\nGive as descriptive a name as possible, within reason. Do not worry about saving\nhorizontal space as it is far more important to make your code immediately\nunderstandable by a new reader. Do not use abbreviations that are ambiguous or\nunfamiliar to readers outside your project, and do not abbreviate by deleting\nletters within a word.
\n\nerrorCount // No abbreviation.\ndnsConnectionIndex // Most people know what \"DNS\" stands for.\nreferrerUrl // Ditto for \"URL\".\ncustomerId // \"Id\" is both ubiquitous and unlikely to be misunderstood.\nDisallowed:
\n\nn // Meaningless.\nnErr // Ambiguous abbreviation.\nnCompConns // Ambiguous abbreviation.\nwgcConnections // Only your group knows what this stands for.\npcReader // Lots of things can be abbreviated \"pc\".\ncstmrId // Deletes internal letters.\nkSecondsPerDay // Do not use Hungarian notation.\nException: Variables that are in scope for 10 lines or fewer, including\narguments that are not part of an exported API, may use short (e.g. single\nletter) variable names.
\n\nPackage names are all lowerCamelCase. For example, my.exampleCode.deepSpace,\nbut not my.examplecode.deepspace or\nmy.example_code.deep_space.
Exception: The package name may conform to TypeScript's path-based pattern. This is\ntypically all lower case with underscores where present in filenames.
\n\nClass, interface, record, and typedef names are written in UpperCamelCase.\nUnexported classes are simply locals: they are not marked @private.
Type names are typically nouns or noun phrases. For example, Request,\nImmutableView, or VisibilityMode. Additionally, interface names may\nsometimes be adjectives or adjective phrases instead (for example, Readable).
Method names are written in lowerCamelCase. Names for @private methods may\noptionally end with a trailing underscore.
Method names are typically verbs or verb phrases. For example, sendMessage or\nstop_. Getter and setter methods for properties are never required, but if\nthey are used they should be named getFoo (or optionally isFoo or hasFoo\nfor booleans), or setFoo(value) for setters.
Underscores may also appear in JsUnit test method names to separate logical\ncomponents of the name. One typical pattern is\ntest<MethodUnderTest>_<state>_<expectedOutcome>, for example\ntestPop_emptyStack_throws. There is no One Correct Way to name test methods.
Enum names are written in UpperCamelCase, similar to classes, and should\ngenerally be singular nouns. Individual items within the enum are named in\nCONSTANT_CASE.
Constant names use CONSTANT_CASE: all uppercase letters, with words separated\nby underscores. There is no reason for a constant to be named with a trailing\nunderscore, since private static properties can be replaced by (implicitly\nprivate) module locals.
Every constant is a @const static property or a module-local const\ndeclaration, but not all @const static properties and module-local consts\nare constants. Before choosing constant case, consider whether the field really\nfeels like a deeply immutable constant. For example, if any of that instance's\nobservable state can change, it is almost certainly not a constant. Merely\nintending to never mutate the object is generally not enough.
Examples:
\n\n// Constants\nconst NUMBER = 5;\n/** @const */ exports.NAMES = goog.debug.freeze(['Ed', 'Ann']);\n/** @enum */ exports.SomeEnum = { ENUM_CONSTANT: 'value' };\n\n// Not constants\nlet letVariable = 'non-const';\n\nclass MyClass {\n constructor() { /** @const {string} */ this.nonStatic = 'non-static'; }\n};\n/** @type {string} */\nMyClass.staticButMutable = 'not @const, can be reassigned';\n\nconst /** Set<string> */ mutableCollection = new Set();\n\nconst /** MyImmutableContainer<SomeMutableType> */ stillMutable =\n new MyImmutableContainer(mutableInner);\n\nconst {Foo} = goog.require('my.foo'); // mirrors imported name\n\nconst logger = log.getLogger('loggers.are.not.immutable');\nConstants’ names are typically nouns or noun phrases.
\n\nLocal aliases should be used whenever they improve readability over\nfully-qualified names. Follow the same rules as goog.requires\n(??), maintaining the last part of the aliased name.\nAliases may also be used within functions. Aliases must be const.
Examples:
\n\nconst staticHelper = importedNamespace.staticHelper;\nconst CONSTANT_NAME = ImportedClass.CONSTANT_NAME;\nconst {assert, assertInstanceof} = asserts;\nNon-constant field names (static or otherwise) are written in lowerCamelCase,\nwith an optional trailing underscore for private fields.
These names are typically nouns or noun phrases. For example, computedValues\nor index_.
Parameter names are written in lowerCamelCase. Note that this applies even if\nthe parameter expects a constructor.
One-character parameter names should not be used in public methods.
\n\nException: When required by a third-party framework, parameter names may\nbegin with a $. This exception does not apply to any other identifiers (e.g.\nlocal variables or properties).
Local variable names are written in lowerCamelCase, except for module-local\n(top-level) constants, as described above. Constants in function scopes are\nstill named in lowerCamelCase. Note that lowerCamelCase is used\neven if the variable holds a constructor.
Template parameter names should be concise, single-word or single-letter\nidentifiers, and must be all-caps, such as TYPE or THIS.
Module-local names that are not exported are implicitly private. They are not\nmarked @private. This applies to classes, functions, variables, constants,\nenums, and other module-local identifiers.
Sometimes there is more than one reasonable way to convert an English phrase\ninto camel case, such as when acronyms or unusual constructs like IPv6
or\niOS
are present. To improve predictability, Google Style specifies the\nfollowing (nearly) deterministic scheme.
Beginning with the prose form of the name:
\n\nMüller's algorithmmight become
Muellers algorithm.
AdWordsbecomes
ad words). Note that a word such as
iOSis not\nreally in camel case per se; it defies any convention, so this\nrecommendation does not apply.
UpperCamelCase, orlowerCamelCaseNote that the casing of the original words is almost entirely disregarded.
\n\nExamples of lowerCamelCase:
| Prose form | \nCorrect | \nIncorrect | \n
|---|---|---|
XML HTTP request | \nxmlHttpRequest | \nXMLHTTPRequest | \n
new customer ID | \nnewCustomerId | \nnewCustomerID | \n
inner stopwatch | \ninnerStopwatch | \ninnerStopWatch | \n
supports IPv6 on iOS? | \nsupportsIpv6OnIos | \nsupportsIPv6OnIOS | \n
YouTube importer | \nyouTubeImporter | \nyoutubeImporter* | \n
*Acceptable, but not recommended.
\n\nFor examples of UpperCamelCase, uppercase the first letter of each correct\nlowerCamelCase example.
Note: Some words are ambiguously hyphenated in the English language: for example\nnonempty
and non-empty
are both correct, so the method names checkNonempty\nand checkNonEmpty are likewise both correct.
JSDoc is used on all classes, fields, and methods.
\n\nThe basic formatting of JSDoc blocks is as seen in this example:
\n\n/**\n * Multiple lines of JSDoc text are written here,\n * wrapped normally.\n * @param {number} arg A number to do something to.\n */\nfunction doSomething(arg) { … }\nor in this single-line example:
\n\n/** @const @private {!Foo} A short bit of JSDoc. */\nthis.foo_ = foo;\nIf a single-line comment overflows into multiple lines, it must use the\nmulti-line style with /** and */ on their own lines.
Many tools extract metadata from JSDoc comments to perform code validation and\noptimization. As such, these comments must be well-formed.
\n\nJSDoc is written in Markdown, though it may include HTML when necessary.
\n\nNote that tools that automatically extract JSDoc (e.g. JsDossier) will often\nignore plain text formatting, so if you did this:
\n\n/**\n * Computes weight based on three factors:\n * items sent\n * items received\n * last timestamp\n */\nit would come out like this:
\n\nComputes weight based on three factors: items sent items received last timestamp\nInstead, write a Markdown list:
\n\n/**\n * Computes weight based on three factors:\n *\n * - items sent\n * - items received\n * - last timestamp\n */\nGoogle style allows a subset of JSDoc tags. See\n?? for the complete list. Most tags must\noccupy their own line, with the tag at the beginning of the line.
\n\nDisallowed:
\n\n/**\n * The \"param\" tag must occupy its own line and may not be combined.\n * @param {number} left @param {number} right\n */\nfunction add(left, right) { ... }\nSimple tags that do not require any additional data (such as @private,\n@const, @final, @export) may be combined onto the same line, along with an\noptional type when appropriate.
/**\n * Place more complex annotations (like \"implements\" and \"template\")\n * on their own lines. Multiple simple tags (like \"export\" and \"final\")\n * may be combined in one line.\n * @export @final\n * @implements {Iterable<TYPE>}\n * @template TYPE\n */\nclass MyClass {\n /**\n * @param {!ObjType} obj Some object.\n * @param {number=} num An optional number.\n */\n constructor(obj, num = 42) {\n /** @private @const {!Array<!ObjType|number>} */\n this.data_ = [obj, num];\n }\n}\nThere is no hard rule for when to combine tags, or in which order, but be\nconsistent.
\n\nFor general information about annotating types in JavaScript see\nAnnotating JavaScript for the Closure Compiler and\nTypes in the Closure Type System.
\n\nLine-wrapped block tags are indented four spaces. Wrapped description text may\nbe lined up with the description on previous lines, but this horizontal\nalignment is discouraged.
\n\n/**\n * Illustrates line wrapping for long param/return descriptions.\n * @param {string} foo This is a param with a description too long to fit in\n * one line.\n * @return {number} This returns something that has a description too long to\n * fit in one line.\n */\nexports.method = function(foo) {\n return 5;\n};\nDo not indent when wrapping a @desc or @fileoverview description.
A file may have a top-level file overview. A copyright notice, author information,\nand default visibility level are optional.\nFile overviews are generally recommended whenever a\nfile consists of more than a single class definition. The top level comment is\ndesigned to orient readers unfamiliar with the code to what is in this file. If\npresent, it may provide a description of the file's contents and any\ndependencies or compatibility information. Wrapped lines are not indented.
\n\nExample:
\n\n/**\n * @fileoverview Description of file, its uses and information\n * about its dependencies.\n * @package\n */\nClasses, interfaces and records must be documented with a description and any\ntemplate parameters, implemented interfaces, visibility, or other appropriate\ntags. The class description should provide the reader with enough information to\nknow how and when to use the class, as well as any additional considerations\nnecessary to correctly use the class. Textual descriptions may be omitted on the\nconstructor. When defining a class @constructor and @extends annotations are\nnot used with the class keyword unless it extends a generic class. When\ndefining an @interface or a @record, the @extends annotation is used when\ndefining a subclass and the extends keyword is never used.
/**\n * A fancier event target that does cool things.\n * @implements {Iterable<string>}\n */\nclass MyFancyTarget extends EventTarget {\n /**\n * @param {string} arg1 An argument that makes this more interesting.\n * @param {!Array<number>} arg2 List of numbers to be processed.\n */\n constructor(arg1, arg2) {\n // ...\n }\n};\n\n/**\n * Records are also helpful.\n * @extends {Iterator<TYPE>}\n * @record\n * @template TYPE\n */\nclass Listable {\n /** @return {TYPE} The next item in line to be returned. */\n next() {}\n}\nAll enums and typedefs must be documented with appropriate JSDoc tags\n(@typedef or @enum) on the preceding line. Public enums and typedefs must\nalso have a description. Individual enum items may be documented with a JSDoc\ncomment on the preceding line.
/**\n * A useful type union, which is reused often.\n * @typedef {!FruitType|!FruitTypeEnum}\n */\nlet CoolUnionType;\n \n/**\n * Types of fruits.\n * @enum {string}\n */\nconst FruitTypeEnum = {\n /** This kind is very sour. */\n SOUR: 'sour',\n /** The less-sour kind. */\n SWEET: 'sweet',\n};\nTypedefs are useful for defining short record types, or aliases for unions,\ncomplex functions, or generic types. Typedefs should be avoided for record types\nwith many fields, since they do not allow documenting individual fields, nor\nusing templates or recursive references. For large record types, prefer\n@record.
In methods and named functions, parameter and return types must be documented,\neven in the case of same-signature @overrides. The this type should be\ndocumented when necessary. Return type may be omitted if the function has no\nnon-empty return statements.
Method, parameter, and return descriptions (but not types) may be omitted if\nthey are obvious from the rest of the method’s JSDoc or from its signature.
\n\nMethod descriptions begin with a verb phrase that describes what the method\ndoes. This phrase is not an imperative sentence, but instead is written in the\nthird person, as if there is an implied This method ...
before it.
If a method overrides a superclass method, it must include an @override\nannotation. For overridden methods, all @param and @return annotations must\nbe specified explicitly even if no type from the superclass method is refined.\nThis is to align with TypeScript.
/** A class that does something. */\nclass SomeClass extends SomeBaseClass {\n /**\n * Operates on an instance of MyClass and returns something.\n * @param {!MyClass} obj An object that for some reason needs detailed\n * explanation that spans multiple lines.\n * @param {!OtherClass} obviousOtherClass\n * @return {boolean} Whether something occurred.\n */\n someMethod(obj, obviousOtherClass) { ... }\n\n /**\n * @param {string} param\n * @return {string}\n * @override\n */\n overriddenMethod(param) { ... }\n}\n\n/**\n * Demonstrates how top-level functions follow the same rules. This one\n * makes an array.\n * @param {TYPE} arg\n * @return {!Array<TYPE>}\n * @template TYPE\n */\nfunction makeArray(arg) { ... }\nIf you only need to document the param and return types of a function, you may\noptionally use inline JSDocs in the function's signature. These inline JSDocs\nspecify the return and param types without tags.
\n\nfunction /** string */ foo(/** number */ arg) {...}\nIf you need descriptions or tags, use a single JSDoc comment above the method.\nFor example, methods which return values need a @return tag.
class MyClass {\n /**\n * @param {number} arg\n * @return {string}\n */\n bar(arg) {...}\n}\n// Illegal inline JSDocs.\n\nclass MyClass {\n /** @return {string} */ foo() {...}\n}\n\n/** No function description allowed inline here. */ function bar() {...}\n\nfunction /** Function description is also illegal here. */ baz() {...}\nIn anonymous functions annotations are generally optional. If the automatic type\ninference is insufficient or explicit annotation improves readability, then\nannotate param and return types like this:
\n\npromise.then(\n /** @return {string} */\n (/** !Array<string> */ items) => {\n doSomethingWith(items);\n return items[0];\n });\nFor function type expressions, see ??.
\n\nProperty types must be documented. The description may be omitted for private\nproperties, if name and type provide enough documentation for understanding the\ncode.
\n\nPublicly exported constants are commented the same way as properties.
\n\n/** My class. */\nclass MyClass {\n /** @param {string=} someString */\n constructor(someString = 'default string') {\n /** @private @const {string} */\n this.someString_ = someString;\n\n /** @private @const {!OtherType} */\n this.someOtherThing_ = functionThatReturnsAThing();\n\n /**\n * Maximum number of things per pane.\n * @type {number}\n */\n this.someProperty = 4;\n }\n}\n\n/**\n * The number of times we'll try before giving up.\n * @const {number}\n */\nMyClass.RETRY_COUNT = 33;\nType annotations are found on @param, @return, @this, and @type tags,\nand optionally on @const, @export, and any visibility tags. Type annotations\nattached to JSDoc tags must always be enclosed in braces.
The type system defines modifiers ! and ? for non-null and nullable,\nrespectively. These modifiers must precede the type.
Nullability modifiers have different requirements for different types, which\nfall into two broad categories:
\n\nstring, number, boolean, symbol,\nundefined, null) and literals ({function(...): ...} and {{foo:\nstring...}}) are always non-nullable by default. Use the ? modifier to\nmake it nullable, but omit the redundant !.UpperCamelCase, including\nsome.namespace.ReferenceType) refer to a class, enum, record, or typedef\ndefined elsewhere. Since these types may or may not be nullable, it is\nimpossible to tell from the name alone whether it is nullable or not. Always\nuse explicit ? and ! modifiers for these types to prevent ambiguity at\nuse sites.Bad:
\n\nconst /** MyObject */ myObject = null; // Non-primitive types must be annotated.\nconst /** !number */ someNum = 5; // Primitives are non-nullable by default.\nconst /** number? */ someNullableNum = null; // ? should precede the type.\nconst /** !{foo: string, bar: number} */ record = ...; // Already non-nullable.\nconst /** MyTypeDef */ def = ...; // Not sure if MyTypeDef is nullable.\n\n// Not sure if object (nullable), enum (non-nullable, unless otherwise\n// specified), or typedef (depends on definition).\nconst /** SomeCamelCaseName */ n = ...;\nGood:
\n\nconst /** ?MyObject */ myObject = null;\nconst /** number */ someNum = 5;\nconst /** ?number */ someNullableNum = null;\nconst /** {foo: string, bar: number} */ record = ...;\nconst /** !MyTypeDef */ def = ...;\nconst /** ?SomeCamelCaseName */ n = ...;\nIn cases where the compiler doesn't accurately infer the type of an expression,\nand the assertion functions in\ngoog.asserts\ncannot remedy it, it is\npossible to tighten the type by adding a type annotation comment and enclosing\nthe expression in parentheses. Note that the parentheses are required.
\n\n/** @type {number} */ (x)\nAlways specify template parameters. This way compiler can do a better job and it\nmakes it easier for readers to understand what code does.
\n\nBad:
\n\nconst /** !Object */ users = {};\nconst /** !Array */ books = [];\nconst /** !Promise */ response = ...;\nGood:
\n\nconst /** !Object<string, !User> */ users = {};\nconst /** !Array<string> */ books = [];\nconst /** !Promise<!Response> */ response = ...;\n\nconst /** !Promise<undefined> */ thisPromiseReturnsNothingButParameterIsStillUseful = ...;\nconst /** !Object<string, *> */ mapOfEverything = {};\nCases when template parameters should not be used:
\n\nObject is used for type hierarchy and not as map-like structure.Terminology Note: function type expression refers to a type annotation for\nfunction types with the keyword function in the annotation (see examples\nbelow).
Where the function definition is given, do not use a function type expression.\nSpecify parameter and return types with @param and @return, or with inline\nannotations (see ??). This includes\nanonymous functions and functions defined and assigned to a const (where the\nfunction jsdoc appears above the whole assignment expression).
Function type expressions are needed, for example, inside @typedef, @param\nor @return. Use it also for variables or properties of function type, if they\nare not immediately initialized with the function definition.
/** @private {function(string): string} */\n this.idGenerator_ = googFunctions.identity;\nWhen using a function type expression, always specify the return type\nexplicitly. Otherwise the default return type is unknown
(?), which leads to\nstrange and unexpected behavior, and is rarely what is actually desired.
Bad - type error, but no warning given:
\n\n/** @param {function()} generateNumber */\nfunction foo(generateNumber) {\n const /** number */ x = generateNumber(); // No compile-time type error here.\n}\n\nfoo(() => 'clearly not a number');\nGood:
\n\n/**\n * @param {function(): *} inputFunction1 Can return any type.\n * @param {function(): undefined} inputFunction2 Definitely doesn't return\n * anything.\n * NOTE: the return type of `foo` itself is safely implied to be {undefined}.\n */\nfunction foo(inputFunction1, inputFunction2) {...}\nWithin a type annotation, a single space or line break is required after each\ncomma or colon. Additional line breaks may be inserted to improve readability or\navoid exceeding the column limit. These breaks should be chosen and indented\nfollowing the applicable guidelines (e.g. ?? and\n??). No other whitespace is allowed in type\nannotations.
\n\nGood:
\n\n/** @type {function(string): number} */\n\n/** @type {{foo: number, bar: number}} */\n\n/** @type {number|string} */\n\n/** @type {!Object<string, string>} */\n\n/** @type {function(this: Object<string, string>, number): string} */\n\n/**\n * @type {function(\n * !SuperDuperReallyReallyLongTypedefThatForcesTheLineBreak,\n * !OtherVeryLongTypedef): string}\n */\n\n/**\n * @type {!SuperDuperReallyReallyLongTypedefThatForcesTheLineBreak|\n * !OtherVeryLongTypedef}\n */\nBad:
\n\n// Only put a space after the colon\n/** @type {function(string) : number} */\n\n// Put spaces after colons and commas\n/** @type {{foo:number,bar:number}} */\n\n// No space in union types\n/** @type {number | string} */\nVisibility annotations (@private, @package, @protected) may be specified\nin a @fileoverview block, or on any exported symbol or property. Do not\nspecify visibility for local variables, whether within a function or at the top\nlevel of a module. @private names may optionally end with an underscore.
For any style question that isn't settled definitively by this specification,\nprefer to do what the other code in the same file is already doing. If that\ndoesn't resolve the question, consider emulating the other files in the same\npackage.
\n\nAs far as possible projects should use\n--warning_level=VERBOSE.
Before doing anything, make sure you understand exactly what the warning is\ntelling you. If you're not positive why a warning is appearing, ask for help\n.
\n\nOnce you understand the warning, attempt the following solutions in order:
\n\n@suppress\nannotation.Warnings are suppressed at the narrowest reasonable scope, usually that of a\nsingle local variable or very small method. Often a variable or method is\nextracted for that reason alone.
\n\nExample
\n\n/** @suppress {uselessCode} Unrecognized 'use asm' declaration */\nfunction fn() {\n 'use asm';\n return 0;\n}\nEven a large number of suppressions in a class is still better than blinding the\nentire class to this type of warning.
\n\nMark deprecated methods, classes or interfaces with @deprecated annotations. A\ndeprecation comment must include simple, clear directions for people to fix\ntheir call sites.
You will occasionally encounter files in your codebase that are not in proper\nGoogle Style. These may have come from an acquisition, or may have been written\nbefore Google Style took a position on some issue, or may be in non-Google Style\nfor any other reason.
\n\nWhen updating the style of existing code, follow these guidelines.
\n\nBrand new files use Google Style, regardless of the style choices of other files\nin the same package.
\n\nWhen adding new code to a file that is not in Google Style, reformatting the\nexisting code first is recommended, subject to the advice in\n??.
\n\nIf this reformatting is not done, then new code should be as consistent as\npossible with existing code in the same file, but must not violate the style\nguide.
\n\nTeams and projects may adopt additional style rules beyond those in this\ndocument, but must accept that cleanup changes may not abide by these additional\nrules, and must not block such cleanup changes due to violating any additional\nrules. Beware of excessive rules which serve no purpose. The style guide does\nnot seek to define style in every possible scenario and neither should you.
\n\nSource code generated by the build process is not required to be in Google\nStyle. However, any generated identifiers that will be referenced from\nhand-written source code must follow the naming requirements. As a special\nexception, such identifiers are allowed to contain underscores, which may help\nto avoid conflicts with hand-written identifiers.
\n\nJSDoc serves multiple purposes in JavaScript. In addition to being used to\ngenerate documentation it is also used to control tooling. The best known are\nthe Closure Compiler type annotations.
\n\nDocumentation for JSDoc used by the Closure Compiler is described in\nAnnotating JavaScript for the Closure Compiler and\nTypes in the Closure Type System.
\n\nIn addition to the JSDoc described in\nAnnotating JavaScript for the Closure Compiler the following tags are common\nand well supported by various documentation generation tools (such as\nJsDossier) for purely documentation purposes.
\n\n@author or @owner - Not recommended.Not recommended.
\n\nSyntax: @author username@google.com (First Last)
/**\n * @fileoverview Utilities for handling textareas.\n * @author kuth@google.com (Uthur Pendragon)\n */\nDocuments the author of a file or the owner of a test, generally only used in\nthe @fileoverview comment. The @owner tag is used by the unit test dashboard\nto determine who owns the test results.
@bugSyntax: @bug bugnumber
/** @bug 1234567 */\nfunction testSomething() {\n // …\n}\n\n/**\n * @bug 1234568\n * @bug 1234569\n */\nfunction testTwoBugs() {\n // …\n}\nIndicates what bugs the given test function regression tests.
\n\nMultiple bugs should each have their own @bug line, to make searching for\nregression tests as easy as possible.
@code - Deprecated. Do not use.Deprecated. Do not use. Use Markdown backticks instead.
\n\nSyntax: {@code ...}
Historically, `BatchItem` was written as\n{@code BatchItem}.
/** Processes pending `BatchItem` instances. */\nfunction processBatchItems() {}\nIndicates that a term in a JSDoc description is code so it may be correctly\nformatted in generated documentation.
\n\n@descSyntax: @desc Message description
/** @desc Notifying a user that their account has been created. */\nexports.MSG_ACCOUNT_CREATED = goog.getMsg(\n 'Your account has been successfully created.');\n@linkSyntax: {@link ...}
This tag is used to generate cross-reference links within generated\ndocumentation.
\n\n/** Processes pending {@link BatchItem} instances. */\nfunction processBatchItems() {}\nHistorical note: @link tags have also been used to create external links in\ngenerated documentation. For external links, always use Markdown's link syntax\ninstead:
\n\n/**\n * This class implements a useful subset of the\n * [native Event interface](https://dom.spec.whatwg.org/#event).\n */\nclass ApplicationEvent {}\n@seeSyntax: @see Link
/**\n * Adds a single item, recklessly.\n * @see #addSafely\n * @see goog.Collect\n * @see goog.RecklessAdder#add\n */\nReference a lookup to another class function or method.
\n\n@supportedSyntax: @supported Description
/**\n * @fileoverview Event Manager\n * Provides an abstracted interface to the browsers' event systems.\n * @supported IE10+, Chrome, Safari\n */\nUsed in a fileoverview to indicate what browsers are supported by the file.
\n\nYou may also see other types of JSDoc annotations in third-party code. These\nannotations appear in the JSDoc Toolkit Tag Reference but are not considered\npart of valid Google style.
\n\nThe following annotations are specific to a particular framework.
\n\n@ngInject for Angular 1@polymerBehavior for Polymerhttps://github.com/google/closure-compiler/wiki/Polymer-Pass\n
\n\nThe following tags used to be standard but are now deprecated.
\n\n@expose - Deprecated. Do not use.Deprecated. Do not use. Use @export and/or @nocollapse instead.
@inheritDoc - Deprecated. Do not use.Deprecated. Do not use. Use @override instead.
Here is a collection of lesser-known or commonly misunderstood facts about\nGoogle Style for JavaScript. (The following are true statements; this is not a\nlist of myths.
)
@author credit is required in a source\nfile. (Neither is explicitly recommended, either.)hard and fastrule governing how to order the members of a\nclass (??).
{}, as detailed in\n(??).The following tools exist to support various aspects of Google Style.
\n\nThis program performs type checking and\nother checks, optimizations and other transformations (such as lowering code to\nECMAScript 5).
\n\nclang-formatThis program reformats\nJavaScript source code into Google Style, and also follows a number of\nnon-required but frequently readability-enhancing formatting practices. The\noutput produced by clang-format is compliant with the style guide.\n
clang-format is not required. Authors are allowed to change its output, and\nreviewers are allowed to ask for such changes; disputes are worked out in the\nusual way. However, subtrees may choose to opt in to such enforcement locally.
This program checks for a\nvariety of missteps and anti-patterns.
\n\nThe JS Conformance Framework is a tool that is part of the Closure Compiler that\nprovides developers a simple means to specify a set of additional checks to be\nrun against their code base above the standard checks. Conformance checks can,\nfor example, forbid access to a certain property, or calls to a certain\nfunction, or missing type information (unknowns).
\n\nThese rules are commonly used to enforce critical restrictions (such as defining\nglobals, which could break the codebase) and security patterns (such as using\neval or assigning to innerHTML), or more loosely to improve code quality.
For additional information see the official documentation for the\nJS Conformance Framework.
\n\nThis section describes exceptions and additional rules to be followed when\nmodern ECMAScript syntax is not available to the code authors. Exceptions to the\nrecommended style are required when modern ECMAScript syntax is not possible and\nare outlined here:
\n\nvar declarations is allowedarguments is allowedvarvar declarations are NOT block-scopedvar declarations are scoped to the beginning of the nearest enclosing\nfunction, script or module, which can cause unexpected behavior, especially with\nfunction closures that reference var declarations inside of loops. The\nfollowing code gives an example:
for (var i = 0; i < 3; ++i) {\n var iteration = i;\n setTimeout(function() { console.log(iteration); }, i*1000);\n}\n\n// logs 2, 2, 2 -- NOT 0, 1, 2\n// because `iteration` is function-scoped, not local to the loop.\n\nEven though var declarations are scoped to the beginning of the enclosing\nfunction, var declarations should be as close as possible to their first use,\nfor readability purposes. However, do not put a var declaration inside a block\nif that variable is referenced outside the block. For example:
function sillyFunction() {\n var count = 0;\n for (var x in y) {\n // \"count\" could be declared here, but don't do that.\n count++;\n }\n console.log(count + ' items in y');\n}\nFor global declarations where the const keyword would be used, if it were\navailable, annotate the var declaration with @const instead (this is\noptional for local variables).
Do not do this:
\n\nif (x) {\n function foo() {}\n}\nWhile most JavaScript VMs implemented before ECMAScript 6 support function\ndeclarations within blocks it was not standardized. Implementations were\ninconsistent with each other and with the now-standard ECMAScript behavior for\nblock scoped function declaration. The ECMAScript 5 standard and prior only\nallow for function declarations in the root statement list of a script or\nfunction and explicitly ban them in block scopes in strict mode.
\n\nTo get consistent behavior, instead use a var initialized with a function\nexpression to define a function within a block:
if (x) {\n var foo = function() {};\n}\ngoog.provide/goog.requireWARNING: goog.provide dependency management is deprecated. All new files,\neven in projects using goog.provide for older files, should use\ngoog.module. The following rules are for\npre-existing goog.provide files only.
goog.provides first, goog.requires second. Separate provides\nfrom requires with an empty line.goog.provide and goog.require statements. Exceed 80 columns\nif necessary.goog.provide statements should be grouped together and placed first. All\ngoog.require statements should follow. The two lists should be separated with\nan empty line.
Similar to import statements in other languages, goog.provide and\ngoog.require statements should be written in a single line, even if they\nexceed the 80 column line length limit.
The lines should be sorted alphabetically, with uppercase letters coming first:
\n\ngoog.provide('namespace.MyClass');\ngoog.provide('namespace.helperFoo');\n\ngoog.require('an.extremelyLongNamespace.thatSomeoneThought.wouldBeNice.andNowItIsLonger.Than80Columns');\ngoog.require('goog.dom');\ngoog.require('goog.dom.TagName');\ngoog.require('goog.dom.classes');\ngoog.require('goog.dominoes');\n\nAll members defined on a class should be in the same file. Only top-level\nclasses should be provided in a file that contains multiple members defined on\nthe same class (e.g. enums, inner classes, etc).
\n\nDo this:
\n\ngoog.provide('namespace.MyClass');\nNot this:
\n\ngoog.provide('namespace.MyClass');\ngoog.provide('namespace.MyClass.CONSTANT');\ngoog.provide('namespace.MyClass.Enum');\ngoog.provide('namespace.MyClass.InnerClass');\ngoog.provide('namespace.MyClass.TypeDef');\ngoog.provide('namespace.MyClass.staticMethod');\nMembers on namespaces may also be provided:
\n\ngoog.provide('foo.bar');\ngoog.provide('foo.bar.CONSTANT');\ngoog.provide('foo.bar.method');\ngoog.scopeWARNING: goog.scope is deprecated. New files should not use goog.scope\neven in projects with existing goog.scope usage.
goog.scope may be used to shorten references to namespaced symbols in code\nusing goog.provide/goog.require dependency management.
Only one goog.scope invocation may be added per file. Always place it in the\nglobal scope.
The opening goog.scope(function() { invocation must be preceded by exactly one\nblank line and follow any goog.provide statements, goog.require statements,\nor top-level comments. The invocation must be closed on the last line in the\nfile. Append // goog.scope to the closing statement of the scope. Separate the\ncomment from the semicolon by two spaces.
Similar to C++ namespaces, do not indent under goog.scope declarations.\nInstead, continue from the 0 column.
Only make aliases for names that will not be re-assigned to another object\n(e.g., most constructors, enums, and namespaces). Do not do this (see below for\nhow to alias a constructor):
\n\ngoog.scope(function() {\nvar Button = goog.ui.Button;\n\nButton = function() { ... };\n...\nNames must be the same as the last property of the global that they are\naliasing.
\n\ngoog.provide('my.module.SomeType');\n\ngoog.require('goog.dom');\ngoog.require('goog.ui.Button');\n\ngoog.scope(function() {\nvar Button = goog.ui.Button;\nvar dom = goog.dom;\n\n// Alias new types after the constructor declaration.\nmy.module.SomeType = function() { ... };\nvar SomeType = my.module.SomeType;\n\n// Declare methods on the prototype as usual:\nSomeType.prototype.findButton = function() {\n // Button as aliased above.\n this.button = new Button(dom.getElement('my-button'));\n};\n...\n}); // goog.scope\ngoog.forwardDeclarePrefer to use goog.requireType instead of goog.forwardDeclare to break\ncircular dependencies between files in the same library. Unlike goog.require,\na goog.requireType statement is allowed to import a namespace before it is\ndefined.
goog.forwardDeclare statements must follow the same style rules as\ngoog.require and goog.requireType. The entire block of\ngoog.forwardDeclare, goog.require and goog.requireType statements is\nsorted alphabetically.
goog.forwardDeclare is used in legacy code to break circular references\nspanning across library boundaries. This pattern however is poorly supported\nby build tools and should not be used. Code should be organized to avoid\ncircular dependencies across libraries (by splitting/merging libraries).
goog.module.get(name)If a goog.provide file depends on a goog.module file, the goog.provide\nfile can not normally refer to the module's exports via a global name. Instead,\nin addition to goog.require()ing the module, the goog.provide file must\nfetch the module's export object by calling goog.module.get('module.name').
Note: Only calling goog.module.get('module.name') does not create a build-time\ndependency of your code on the module. The goog.require is needed for the\nbuild dependency.
goog.module.declareLegacyNamespace()WARNING: goog.module.declareLegacyNamespace is only for transitional use.
goog.module.declareLegacyNamespace is only for use while migrating a\nJavaScript file and its consumers from goog.provide to goog.module\n. Update consumers of\nyour goog.module to use goog.module themselves.\nRemove calls to goog.module.declareLegacyNamespace whenever possible.\n
If you can't update consumers of a legacy namespace from goog.provide to\ngoog.module soon, please wrap the contents of your file in a call to\ngoog.scope, use goog.module.get to import the legacy namespace--and then\ndelete the call to goog.module.declareLegacyNamespace in your goog.module.
Calling goog.module.declareLegacyNamespace() inside a goog.module(name) will\ndeclare the module's namespace as a global name just like a goog.provide()\ncall does. This allows a non goog.module namespace to access the module's\nexports without calling goog.module.get(name).
\nRevision 0.9\n
\n\n\n\n\nHooray! Now you know you can expand points to get more details. Alternatively, there's an \"expand all\" at the top of this document.
\n\nThis 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.
\nFor the purposes of this style guide, we define the following terms:
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.
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.
\nIf 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.
\n\nData 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:
\nFlattened Address:
\nStructured Address:
\nProperty names must conform to the following guidelines:
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:
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\"]).
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.
\n\nArrays 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.
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:
\nIf in the future we wish to make ingredients a reserved word, we can do one of two things:
1) Choose a different name:
\n2) Rename the property on a major version boundary:
\nnull.\nThe spec at JSON.org specifies exactly what type of data is allowed in a property value. This includes booleans, numbers, Unicode 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:
\nBad:
\nnull values.\nIf 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.
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:
\nJSON object:
\nAs 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 strings formatted as recommended by RFC 3339
\nTime duration values should be strings formatted as recommended by ISO 8601.
\nLatitude/Longitude should be strings formatted as recommended by ISO 6709. Furthermore, they should favor the ±DD.DDDD±DDD.DDDD degrees format.
\nIn 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 recommended. 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.
\nThe 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.
\nRepresents 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:
\nClient 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:
\nRequest #2:
\nResponse #1:
\nResponse #2:
\nCommon JavaScript handler code to process both responses:
\nA 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:
\nRepresents 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:
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:
\nContainer 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.
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:
\nThe data property of the JSON object may contain the following properties.
data\nThe 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:
\ndata\nRepresents 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:
\ndata\nRepresents 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:
\ndata\nA globally unique string used to reference the object. The specific details of the id property are left up to the service.
Example:
\ndata (or any child element)\nIndicates 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:
\ndata\nIndicates the last date/time (RFC 3339) the item was updated, as defined by the service.
Example:
\ndata (or any child element)\nA 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:
\ndata\nThe 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:
\nThe 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:
nextLink and previousLink properties (described in the \"Reserved Property Names for Links\" section below) are used for this style of paging.?startIndex=200.?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.
\ndata\nThe 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:
\ndata\nThe 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:
\ndata\nThe 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:
\ndata\nThe 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:
\ndata\nA 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:
\ndata\nThe 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:
\ndata\nThe 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:
\nThe 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\").
data\nThe 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:
\ndata\nThe 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:
\ndata\nThe 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:
\ndata\nThe 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:
\nThe error property of the JSON object may contain the following properties.
error\nRepresents 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:
\nerror\nA human readable message providing more details about the error. If there are multiple errors, message will be the message for the first error.
Example:
\nerror\nContainer for any additional information regarding the error. If the service returns multiple errors, each element in the errors array represents a different error.
Example:
\nerror.errors\nUnique 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:
\nerror.errors\nUnique identifier for this error. Different from the error.code property in that this is not an http response code.
Example:
\nerror.errors\nA human readable message providing more details about the error. If there is only one error, this field will match error.message.
Example:
\nerror.errors\nThe location of the error (the interpretation of its value depends on locationType).
Example:
\nerror.errors\nIndicates how the location property should be interpreted.
Example:
\nerror.errors\nA URI for a help text that might shed some more light on the error.
Example:
\nerror.errors\nA 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:
\nProperties 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.
\nkind should be the first property\nSuppose 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\nThis 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.
\n\nThis sample is for illustrative purposes only. The API below does not actually exist.
Here's a sample Google search results page:![](\"jsoncstyleguide_example_01.png\")
![](\"jsoncstyleguide_example_02.png\")
Here's a sample JSON representation of this page:
\nHere's how each of the colored boxes from the screenshot would be represented (the background colors correspond to the colors in the images above):
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
\n\nExcept 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.\n
\n\nRevision 0.9\n
\n\n\n\n\n\n\nRevision 1.28\n
\n\n\n\nRobert Brown\n\n\n François-René Rideau\n\n\n\n In memoriam Dan Weinreb\n\n\n\nPatterns mean \"I have run out of language.\" — Rich Hickey\n
\n\n\n\n Hooray! Now you know you can expand points to get more details.\n Alternatively, there's an \"expand all\" at the top of this document.\n
\n \n\n Common Lisp is a powerful multiparadigm programming language.\n With great power comes great responsibility.\n
\n\n This guide recommends formatting and stylistic choices\n designed to make your code easier for other people to understand.\n For those internal applications and free software libraries that\n we develop at Google,\n you should keep within these guidelines when making changes.\n Note however that each project has its own rules and customs\n that complement or override these general guidelines;\n the speed-oriented QPX low fare search engine notably\n has a very different style and feel from the QRes reservation system.\n
\n\n If you're writing Common Lisp code outside Google,\n we invite you to consider these guidelines.\n You may find some of them useful\n where they don't conflict with other priorities you have.\n We welcome remarks and constructive feedback\n on how to improve our guide, and\n on what alternate styles work for you and why.\n
\n \n\n This guide is not a Common Lisp tutorial.\n For basic information about the language, please consult\n Practical Common Lisp.\n For a language reference, please consult the\n Common Lisp HyperSpec.\n For more detailed style guidance, take (with a pinch of salt)\n a look at Peter Norvig and Kent Pitman's\n style guide.\n
\n| MUST | \n\n \n This word, or the terms \"REQUIRED\" or \"SHALL\",\n means that the guideline is an absolute requirement.\n You must ask permission to violate a MUST.\n \n | \n
|---|---|
| MUST NOT | \n\n \n This phrase, or the phrase \"SHALL NOT\",\n means that the guideline is an absolute prohibition.\n You must ask permission to violate a MUST NOT.\n \n | \n
| SHOULD | \n\n \n This word, or the adjective \"RECOMMENDED\", means that\n there may exist valid reasons in particular circumstances\n to ignore the demands of the guideline, but\n the full implications must be understood and carefully weighed\n before choosing a different course.\n You must ask forgiveness for violating a SHOULD.\n \n | \n
| SHOULD NOT | \n\n \n This phrase, or the phrase \"NOT RECOMMENDED\", means that\n there may exist valid reasons in particular circumstances\n to ignore the prohibitions of this guideline, but\n the full implications should be understood and carefully weighed\n before choosing a different course.\n You must ask forgiveness for violating a SHOULD NOT.\n \n | \n
| MAY | \n\n \n This word, or the adjective \"OPTIONAL\",\n means that an item is truly optional.\n \n | \n
\n Unlike RFCs, we don't capitalize every instance of one of the above\n keywords when it is used.\n
\n \n\n Permission comes from the owners of your project.\n
\n \n\n Forgiveness is requested in a comment\n near the point of guideline violation,\n and is granted by your code reviewer.\n The original comment should be signed by you, and\n the reviewer should add a signed approval to the comment at review time.\n
\n \n \n\n Some of these guidelines are motivated by universal principles of good programming.\n Some guidelines are motivated by technical peculiarities of Common Lisp.\n Some guidelines were once motivated by a technical reason,\n but the guideline remained after the reason subsided.\n Some guidelines, such those about as comments and indentation,\n are based purely on convention, rather than on clear technical merit.\n Whatever the case may be, you must still follow these guidelines,\n as well as other conventional guidelines\n that have not been formalized in this document.\n
\n\n You MUST follow conventions.\n They are important for readability.\n When conventions are followed by default,\n violations of the convention are a signal\n that something notable is happening and deserves attention.\n When conventions are systematically violated,\n violations of the convention are a distracting noise\n that needs to be ignored.\n
\n\n Conventional guidelines are indoctrination.\n Their purpose is to make you follow the mores of the community,\n \n so you can more effectively cooperate with existing members.\n It is still useful to distinguish the parts that are technically motivated\n from the parts that are mere conventions,\n so you know when best to defy conventions for good effect,\n and when not to fall into the pitfalls that the conventions are there to help avoid.\n
\n \n\n A lot of our code was written before these guidelines existed.\n You should fix violations as you encounter them\n in the course of your normal coding.\n
\n\n You must not fix violations en masse\n without warning other developers and coordinating with them,\n so as not to make the merging of large branches\n more difficult than it already is.\n
\n \n\n When making decisions about how to write a given piece of\n code, aim for the following -ilities in this priority order:\n
\n\n Most of these are obvious.\n
\n\n Usability by the customer means that the system has to do what the\n customer requires; it has to handle the customer's transaction\n volumes, uptime requirements; etc.\n
\n\n For the Lisp efficiency point,\n given two options of equivalent complexity,\n pick the one that performs better.\n (This is often the same as the one that conses less,\n i.e. allocates less storage from the heap.)\n
\n\n Given two options where one is more complex than the other,\n pick the simpler option and revisit the decision only if\n profiling shows it to be a performance bottleneck.\n
\n\n However, avoid premature optimization.\n Don't add complexity to speed up something that runs rarely,\n since in the long run, it matters less whether such code is fast.\n
\n \n\n If your work affects other groups, might be reusable across groups,\n adds new components, has an impact on other groups\n (including QA or Ops), or otherwise isn't purely local,\n you must write it up using at least a couple of paragraphs,\n and get a design approval from the other parties involved\n before starting to write code — or be ready to scratch what you have\n when they object.\n
\n\n If you don't know or don't care about these issues,\n ask someone who does.\n
\n \n\n If you write a general-purpose library,\n or modify an existing open-source library,\n you are encouraged to publish the result\n separate from your main project and then\n have your project import it like any other open-source library.\n
\n \n\n Use your judgment to distinguish\n general-purpose versus business-specific code,\n and open-source the general-purpose parts,\n while keeping the business-specific parts a trade secret.\n
\n \n\n Open-Sourcing code has many advantages,\n including being able to leverage third parties for development,\n letting the development of features be user-directed,\n and keeping you honest with respect to code quality.\n Whatever code you write, you will have to maintain anyway,\n and make sure its quality is high enough to sustain use in production.\n There should therefore be no additional burden to Open-Sourcing,\n even of code that (at least initially)\n is not directly usable by third parties.\n
\n \n \n\n
\nUIOP:WITH-MUFFLED-COMPILER-CONDITIONS and\n UIOP:*UNINTERESTING-COMPILER-CONDITIONS*\n framework (part of UIOP, part of ASDF 3),\n either around the entire project, or around individual files\n (using ASDF's :around-compile hooks).\n \n You must use correct spelling in your comments,\n and most importantly in your identifiers.\n
\n\n When several correct spellings exist (including American vs English),\n and there isn't a consensus amongst developers as which to use,\n you should choose the shorter spelling.\n
\n\n You must use only common and domain-specific abbreviations, and\n must be consistent with these abbreviations. You may abbreviate\n lexical variables of limited scope in order to avoid overly-long\n symbol names.\n
\n\n If you're not sure, consult a dictionary,\n Google for alternative spellings,\n or ask a local expert.\n
\n\n Here are examples of choosing the correct spelling:\n
\n\n Here are examples of choosing the shorter spelling:\n
\n\n Make appropriate exceptions for industry standard nomenclature/jargon,\n including plain misspellings.\n For instance:\n
\n\n Some line length restriction is better than none at all.\n While old text terminals used to make 80 columns the standard,\n these days, allowing 100 columns seems better,\n since good style encourages the use of\n descriptive variables and function names.\n
\n \n \n\n Indent your code the way a properly configured GNU Emacs does.\n
\n\n Maintain a consistent indentation style throughout a project.\n
\n\n Indent carefully to make the code easier to understand.\n
\n\n Common Lisp indentation in Emacs is provided by the cl-indent library.\n The latest version of cl-indent is packaged with\n SLIME\n (under contrib/slime-cl-indent.el). After installing SLIME, set up Emacs\n to load SLIME automatically using\n these instructions, adding slime-indentation to the list of\n contrib libraries to be loaded in the call to slime-setup.\n
\n\n Ideally, use the default indentation settings provided by\n slime-indentation. If necessary, customize indentation parameters to\n maintain a consistent indentation style throughout an existing project.\n Parameters can be customized using the :variables setting in\n define-common-lisp-style. Indentation of specific forms can be\n customized using the :indentation setting of define-common-lisp-style.\n This is particularly useful when creating forms that behave like macros\n or special operators that are indented differently than standard\n function calls (e.g. defun, labels, or let). Add a\n hook to 'lisp-mode-hook that calls common-lisp-set-style to set\n the appropriate style automatically.\n
\n \n \n\n Use indentation to make complex function applications easier to read.\n When an application does not fit on one line\n or the function takes many arguments,\n consider inserting newlines between the arguments\n so that each one is on a separate line.\n However, do not insert newlines in a way that makes it hard to tell\n how many arguments the function takes\n or where an argument form starts and ends.\n
\n\n You should include a description at the top of each source file.\n
\n\n You should include neither authorship nor copyright information in a source file.\n
\n\n Every source file should begin with a brief description\n of the contents of that file.\n
\n\n After that description, every file should start the code itself with an\n (in-package #:package-name) form.\n
\n After that in-package form,\n every file should follow with any file-specific\n (declaim (optimize ...)) declaration\n that is not covered by an ASDF :around-compile hook.\n
\n You should not include authorship information at the top of a file:\n better information is available from version control,\n and such a mention will only cause confusion and grief.\n Indeed, whoever was the main author at the time such a mention was included\n might not be who eventually made the most significant contributions to the file,\n and even less who is responsible for the file at the moment.\n \n
\n\n You should not include copyright information in individual source code files.\n An exception is made for files meant to be disseminated as standalone.\n
\n \n \n \n\n You should include one blank line between top-level forms,\n such as function definitions.\n Exceptionally, blank lines can be omitted\n between simple, closely related defining forms of the same kind,\n such as a group of related type declarations or constant definitions.\n
\n\n Blank lines can be used to separate parts of a complicated function.\n Generally, however, you should break a large function into smaller ones\n instead of trying to make it more readable by adding vertical space.\n If you can't, you should document with a ;; comment\n what each of the separated parts of the function does.\n
\n You should strive to keep top-level forms,\n including comments but excluding the documentation string, of\n appropriate length; preferably short. Forms extending beyond a\n single page should be rare and their use should be justified.\n This applies to each of the forms in an eval-when,\n rather than to the eval-when itself.\n Additionally, defpackage forms may be longer,\n since they may include long lists of symbols.\n
\n You must not include extra horizontal whitespace\n before or after parentheses or around symbols.\n
\n\n You must not place right parentheses by themselves on a line.\n A set of consecutive trailing parentheses must appear on the same line.\n
\n\n You should use only one space between forms.\n
\n\n You should not use spaces to vertically align forms\n in the middle of consecutive lines.\n An exception is made when the code possesses\n an important yet otherwise not visible symmetry\n that you want to emphasize.\n
\n\n You must align nested forms if they occur across more than one line.\n
\n\n The convention is that the body of a binding form\n is indented two spaces after the form.\n Any binding data before the body is usually indented four spaces.\n Arguments to a function call are aligned with the first argument;\n if the first argument is on its own line,\n it is aligned with the function name.\n
\n\n An exception to the rule against lonely parentheses\n is made for an eval-when form around several definitions;\n in this case, include a comment ; eval-when\n after the closing parenthesis.\n
\n You must set your editor to\n avoid inserting tab characters in the files you edit.\n Tabs cause confusion when editors disagree\n on how many spaces they represent.\n In Emacs, do (setq-default indent-tabs-mode nil).\n
\n Unless some bit of code is painfully self-explanatory,\n document it with a documentation string (also known as docstring).\n
\n\n Documentation strings are destined to be read\n by the programmers who use your code.\n They can be extracted from functions, types, classes, variables and macros,\n and displayed by programming tools, such as IDEs,\n or by REPL queries such as (describe 'foo);\n web-based documentation or other reference works\n can be created based on them.\n Documentation strings are thus the perfect locus to document your API.\n They should describe how to use the code\n (including what pitfalls to avoid),\n as opposed to how the code works (and where more work is needed),\n which is what you'll put in comments.\n
\n Supply a documentation string when defining\n top-level functions, types, classes, variables and macros.\n Generally, add a documentation string wherever the language allows.\n
\n\n For functions, the docstring should describe the function's contract:\n what the function does,\n what the arguments mean,\n what values are returned,\n what conditions the function can signal.\n It should be expressed at the appropriate level of abstraction,\n explaining the intended meaning rather than, say, just the syntax.\n In documentation strings, capitalize the names of Lisp symbols,\n such as function arguments.\n For example, \"The value of LENGTH should be an integer.\"\n
\n\n A long docstring may usefully\n begin with a short, single-sentence summary,\n followed by the larger body of the docstring.\n
\n\n When the name of a type is used,\n the symbol may be quoted by surrounding it with\n a back quote at the beginning and a single quote at the end.\n Emacs will highlight the type, and the highlighting serves\n as a cue to the reader that M-.\n will lead to the symbol's definition.\n
\n\n Every method of a generic function should be independently documented\n when the specialization affects what the method does,\n beyond what is described in its generic function's docstring.\n
\n\n When you fix a bug,\n consider whether what the fixed code does is obviously correct or not;\n if not, you must add a comment explaining\n the reason for the code in terms of fixing the bug.\n Adding the bug number, if any, is also recommended.\n
\n \n\n Comments are explanations to the future maintainers of the code.\n Even if you're the only person who will ever see and touch the code,\n even if you're either immortal and never going to quit,\n or unconcerned with what happens after you leave\n (and have your code self-destruct in such an eventuality),\n you may find it useful to comment your code.\n Indeed, by the time you revisit your code,\n weeks, months or years later,\n you will find yourself a different person from the one who wrote it,\n and you will be grateful to that previous self\n for making the code readable.\n
\n\n You must comment anything complicated\n so that the next developer can understand what's going on.\n (Again, the \"hit by a truck\" principle.)\n
\n\n Also use comments as a way to guide those who read the code,\n so they know what to find where.\n
\n\n You should include a space between the semicolon and the text of the comment.\n
\n \n\n When a comment is a full sentence,\n you should capitalize the initial letter of the first word\n and end the comment with a period.\n In general, you should use correct punctuation.\n
\n \n\n For comments requiring special attention, such as\n incomplete code, todo items, questions, breakage, and danger,\n include a TODO comment indicating the type of problem,\n its nature, and any notes on how it may be addressed.\n
\n\n The comments begin with TODO in all capital letters,\n followed by the\n \n name, e-mail address, or other identifier\n of the person \n with the best context about the problem referenced by the TODO.\n The main purpose is to have a consistent TODO that\n can be searched to find out how to get more details upon\n request. A TODO is not a commitment that the\n person referenced will fix the problem. Thus when you create\n a TODO,\n it is almost always your \n name\n that is given.\n
\n When signing comments,\n you should use your username (for code within the company)\n or full email address (for code visible outside the company),\n not just initials.\n \n
\n\n Be specific when indicating times or software releases\n in a TODO comment and use\n YYYY-MM-DD\n format for dates to make automated processing of such dates easier,\n e.g., 2038-01-20 for the end of the 32-bit signed time_t.\n
\n For code that uses unobvious forms to accomplish a task, you must include a comment\n stating the purpose of the form and the task it accomplishes.\n
\n \n\n You should design your Domain Specific Language\n to be easy to read and understand by people familiar with the domain.\n
\n\n You must properly document all your Domain Specific Language.\n
\n\n Sometimes, your DSL is designed for terseness.\n In that case, it is important to document what each program does,\n if it's not painfully obvious from the context.\n
\n\n Notably, when you use regular expressions\n (e.g. with the CL-PPCRE package),\n you MUST ALWAYS put in a comment\n (usually a two-semicolon comment on the previous line)\n explaining, at least basically, what the regular expression does,\n or what the purpose of using it is.\n The comment need not spell out every bit of the syntax, but\n it should be possible for someone to follow the logic of the code\n without actually parsing the regular expression.\n
\n Use lower case for all symbols.\n Consistently using lower case makes searching for symbol names easier\n and is more readable.\n
\n\n Note that Common Lisp is case-converting,\n and that the symbol-name of your symbols\n will be upper case.\n Because of this case-converting,\n attempts to distinguish symbols by case are defeated,\n and only result in confusion.\n While it is possible to escape characters in symbols\n to force lower case,\n you should not use this capability\n unless this is somehow necessary\n to interoperate with third-party software.\n
\n Place hyphens between all the words in a symbol.\n If you can't easily say an identifier out loud,\n it is probably badly named.\n
\n\n You must not use \"/\" or \".\"\n instead of \"-\"\n unless you have a well-documented overarching reason to,\n and permission from other hackers who review your proposal.\n
\n See the section on Spelling and Abbreviations\n for guidelines on using abbreviations.\n
\n\n There are conventions in Common Lisp\n for the use of punctuation in symbols.\n You should not use punctuation in symbols outside these conventions.\n
\n\n Unless the scope of a variable is very small,\n do not use overly short names like\n i and zq.\n
\n You should name a variable according\n to the high-level concept that it represents,\n not according to the low-level implementation details\n of how the concept is represented.\n
\n\n Thus, you should avoid embedding\n data structure or aggregate type names,\n such as list, array, or\n hash-table inside variable names,\n unless you're writing a generic algorithm that applies to\n arbitrary lists, arrays, hash-tables, etc.\n In that case it's perfectly OK to name a variable\n list or array.\n
\n Indeed, you should be introducing new abstract data types\n with DEFCLASS or DEFTYPE,\n whenever a new kind of intent appears for objects in your protocols.\n Functions that manipulate such objects generically may then\n use variables the name of which reflect that abstract type.\n
\n For example, if a variable's value is always a row\n (or is either a row or NIL),\n it's good to call it row or first-row\n or something like that.\n It is alright is row has been\n DEFTYPE'd to STRING —\n precisely because you have abstracted the detail away,\n and the remaining salient point is that it is a row.\n You should not name the variable STRING in this context,\n except possibly in low-level functions that specifically manipulate\n the innards of rows to provide the suitable abstraction.\n
\n Be consistent.\n If a variable is named row in one function,\n and its value is being passed to a second function,\n then call it row rather than, say, value\n (this was a real case).\n
\n The names of global constants should start and end\n with plus characters.\n
\n\n Global variable names should start and end with asterisks\n (also known in this context as earmuffs).\n
\n\n In some projects, parameters that are not meant\n to be usually modified or bound under normal circumstances\n (but may be during experimentation or exceptional situations)\n should start (but do not end) with a dollar sign.\n If such a convention exists within your project,\n you should follow it consistently.\n Otherwise, you should avoid naming variables like this.\n
\n\n Common Lisp does not have global lexical variables,\n so a naming convention is used to ensure that globals,\n which are dynamically bound,\n never have names that overlap with local variables.\n It is possible to fake global lexical variables\n with a differently named global variable\n and a DEFINE-SYMBOL-MACRO.\n You should not use this trick,\n unless you first publish a library that abstracts it away.\n
\"P\".\n \n You should name boolean-valued functions and variables with a\n trailing \"P\" or \"-P\",\n to indicate they are predicates.\n Generally, you should use\n \"P\" when the rest of the function name is one word\n and \"-P\" when it is more than one word.\n
\n A rationale for this convention is given in\n the CLtL2 chapter on predicates.\n
\n\n For uniformity, you should follow the convention above,\n and not one of the alternatives below.\n
\n\n An alternative rule used in some existing packages\n is to always use \"-P\".\n Another alternative rule used in some existing packages\n is to always use \"?\".\n When you develop such a package,\n you must be consistent with the rest of the package.\n When you start a new package,\n you should not use such an alternative rule\n without a very good documented reason.\n
\n When naming a symbol (external or internal) in a package,\n you should not include the package name\n as a prefix within the name of the symbol.\n Naming a symbol this way makes it awkward to use\n from a client package accessing the symbol\n by qualifying it with a package prefix,\n where the package name then appears twice\n (once as a package prefix,\n another time as a prefix within the symbol name).\n
\n\n An exception to the above rule would be to include a prefix\n for the names of variables that would otherwise be expected to clash\n with variables in packages that use the current one.\n For instance, ASDF exports a variable *ASDF-VERBOSE*\n that controls the verbosity of ASDF only,\n rather than of the entire Lisp program.\n
\n Lisp packages are used to demarcate namespaces.\n Usually, each system has its own namespace.\n A package has a set of external symbols,\n which are intended to be used from outside the package,\n in order to allow other modules to use this module's facilities.\n
\n\n The internal symbols of a package\n should never be referred to from other packages.\n That is, you should never have to use\n the double-colon :: construct.\n (e.g. QUAKE::HIDDEN-FUNCTION).\n If you need to use double-colons to write real production code,\n something is wrong and needs to be fixed.\n
\n As an exception,\n unit tests may use the internals of the package being tested.\n So when you refactor, watch out for\n internals used by the package's unit tests.\n
\n\n The :: construct is also useful for very temporary hacks,\n and at the REPL.\n But if the symbol really is part of\n the externally-visible definition of the package,\n export it.\n
\n You may find that some internal symbols represent concepts\n you usually want to abstract away and hide under the hood,\n yet at times are necessary to expose for various extensions.\n For the former reason, you do not want to export them,\n yet for the latter reason, you have to export them.\n The solution is to have two different packages,\n one for your normal users to use, and\n another for the implementation and its extenders to use.\n
\n\n Each package is one of two types:\n
\n:use specification of other packages.\n If package A \"uses\" package B,\n then the external symbols of package B\n can be referenced from within package A\n without a package prefix.\n We mainly use this for low-level modules\n that provide widely-used facilities.\n B,\n code in package A must use an explicit package prefix,\n e.g. B:DO-THIS.\n \n If you add a new package, it should always be of the second type,\n unless you have a special reason and get permission.\n Usually a package is designed to be one or the other,\n by virtue of the names of the functions.\n For example, if you have an abstraction called FIFO,\n and it were in a package of the first type\n you'd have functions named things like\n FIFO-ADD-TO and FIFO-CLEAR-ALL.\n If you used a package of the second type,\n you'd have names like ADD-TO and CLEAR-ALL,\n because the callers would be saying\n FIFO:ADD-TO and FIFO:CLEAR-ALL.\n (FIFO:FIFO-CLEAR-ALL is redundant and ugly.)\n
\n Another good thing about packages is that\n your symbol names won't \"collide\" with the names of other packages,\n except the ones your packages \"uses\".\n So you have to stay away from symbols\n that are part of the Lisp implementation (since you always \"use\" that)\n and that are part of any other packages you \"use\",\n but otherwise you are free to make up your own names,\n even short ones, and not worry about some else\n having used the same name.\n You're isolated from each other.\n
\n\n Your package must not shadow (and thus effectively redefine)\n symbols that are part of the Common Lisp language.\n There are certain exceptions,\n but they should be very well-justified and extremely rare:\n
\nlog:error and log:warn\n and so on.\n \n Lisp is best used as a \"mostly functional\" language.\n
\n\n Avoid modifying local variables, try rebinding instead.\n
\n\n Avoid creating objects and the SETFing their slots.\n It's better to set the slots during initialization.\n
\n\n Make classes as immutable as possible, that is, avoid giving slots\n setter functions if at all possible.\n
\n\n Using a mostly functional style makes it much easier\n to write concurrent code that is thread-safe.\n It also makes it easier to test the code.\n
\n \n\n Common Lisp systems are not required to implement\n function calls from tail positions without leaking stack space\n — which is known as proper tail calls (PTC),\n tail call elimination (TCE),\n or tail call optimization (TCO).\n This means that indefinite recursion through tail calls\n may quickly blow out the stack,\n which hampers functional programming.\n Still, most serious implementations (including SBCL and CCL)\n do implement proper tail calls, but with restrictions:\n
\n(DECLARE (OPTIMIZE ...)) settings\n must favor SPEED enough and\n not favor DEBUG too much,\n for some compiler-dependent meanings of \"enough\" and \"too much\".\n (For instance, in SBCL, you should avoid (SPEED 0)\n and (DEBUG 3) to achieve proper tail calls.)\n \n For compatibility with all compilers and optimization settings,\n and to avoid stack overflow when debugging,\n you should prefer iteration or the built in mapping functions\n to relying on proper tail calls.\n
\n\n If you do rely on proper tail calls,\n you must prominently document the fact,\n and take appropriate measures to ensure an appropriate compiler is used\n with appropriate optimization settings.\n For fully portable code, you may have to use trampolines instead.\n
\n \n\n Using Lisp \"special\" (dynamically bound) variables\n as implicit arguments to functions should be used sparingly,\n and only in cases where it won't surprise the person reading the code,\n and where it offers significant benefits.\n
\n\n Indeed, each special variable constitutes state.\n Developers have to mentally track the state of all relevant variables\n when trying to understand what the code does and how it does it;\n tests have to be written and run with all relevant combinations;\n to isolate some activity, care has to be taken to locally bind\n all relevant variables, including those of indirectly used modules.\n They can hide precious information from being printed in a backtrace.\n Not only is there overhead associated to each new variable,\n but interactions between variables\n can make the code exponentially more complex\n as the number of such variables increases.\n The benefits have to match the costs.\n
\n\n Note though that a Lisp special variable is not a global variable\n in the sense of a global variable in, say, BASIC or C.\n As special variables can be dynamically bound to a local value,\n they are much more powerful than\n global value cells where all users necessarily interfere with each other.\n
\n\n Good candidates for such special variables\n are items for which \"the current\" can be naturally used as prefix,\n such as \"the current database connection\" or\n \"the current business data source\".\n They are singletons as far as the rest of the code is concerned,\n and often passing them as an explicit argument\n does not add anything to the readability or maintainability\n of the source code in question.\n
\n\n They can make it easier to write code that can be refactored.\n If you have a request processing chain,\n with a number of layers that all operate upon a \"current\" request,\n passing the request object explicitly to every function\n requires that every function in the chain have a request argument.\n Factoring out code into new functions often requires\n that these functions also have this argument,\n which clutters the code with boilerplate.\n
\n\n You should treat special variables\n as though they are per-thread variables.\n By default, you should leave a special variable\n with no top-level binding at all,\n and each thread of control\n that needs the variable should bind it explicitly.\n This will mean that any incorrect use of the variable\n will result in an \"unbound variable\" error, and\n each thread will see its own value for the variable.\n Variables with a default global value should usually be\n locally bound at thread creation time.\n You should use suitable infrastructure\n to automate the appropriate declaration of such variables.\n
\n \n \n\n There are several styles for dealing with assignment and side-effects;\n whichever a given package is using,\n keep using the same consistently when hacking said package.\n Pick a style that makes sense when starting a new package.\n
\n\n Regarding multiple assignment in a same form, there are two schools:\n the first style groups as many assignments as possible into a single\n SETF or PSETF form\n thus minimizing the number of forms with side-effects;\n the second style splits assignments into as many individual\n SETF (or SETQ, see below) forms as possible,\n to maximize the chances of locating forms that modify a kind of place\n by grepping for (setf (foo ....\n A grep pattern must actually contain as many place-modifying forms\n as you may use in your programs, which may make this rationale either\n convincing or moot depending on the rest of the style of your code.\n You should follow the convention used in the package you are hacking.\n We recommend the first convention for new packages.\n
\n Regarding SETF and SETQ,\n there are two schools:\n this first regards SETQ\n as an archaic implementation detail,\n and avoids it entirely in favor of SETF;\n the second regards SETF\n as an additional layer of complexity,\n and avoids it in favor of SETQ whenever possible\n (i.e. whenever the assigned place is a variable or symbol-macro).\n You should follow the convention used in the package you are hacking.\n We recommend the first convention for new packages.\n
\n In the spirit of a mostly pure functional style,\n which makes testing and maintenance easier,\n we invite you to consider how to do things with the fewest assignments required.\n
\n \nASSERT should be used ONLY to detect internal bugs.\n Code should ASSERT invariants whose failure indicates\n that the software is itself broken.\n Incorrect input should be handled properly at runtime,\n and must not cause an assertion violation.\n The audience for an ASSERT failure is a developer.\n Do not use the data-form and argument-form in ASSERT\n to specify a condition to signal.\n It's fine to use them to print out a message for debugging purposes\n (and since it's only for debugging, there's no issue of\n internationalization).\n CHECK-TYPE,\n ETYPECASE are also forms of assertion.\n When one of these fails, that's a detected bug.\n You should prefer to use CHECK-TYPE\n over (DECLARE (TYPE ...))\n for the inputs of functions.\n ERROR should be used\n to detect problems with user data, requests, permissions, etc.,\n or to report \"unusual outcomes\" to the caller.\n ERROR should always be called\n with an explicit condition type;\n it should never simply be called with a string.\n This enables internationalization.\n ERROR\n instead of ASSERT.\n \n WARN.\n Instead, you should use the appropriate logging framework.\n \n SIGNAL.\n Instead, use ERROR or ASSERT.\n THROW and CATCH;\n instead use the restart facility.\n T, or use IGNORE-ERRORS.\n Instead, let unknown conditions propagate to\n the standard ultimate handler for processing.\n \n ERROR, not T\n and not SERIOUS-CONDITION.\n (This is notably because CCL's process shutdown\n depends on being able to signal process-reset\n and have it handled by CCL's handler,\n so we must not interpose our own handler.)\n (error (make-condition 'foo-error ...))\n is equivalent to (error 'foo-error ...) —\n code must use the shorter form.\n UNWIND-PROTECT\n (unless they are always handled inside the cleanup form),\n or otherwise do non-local exits from cleanup handlers\n outside of the handler e.g. INVOKE-RESTART.\n \n If your function is using a special variable as an implicit argument,\n it's good to put in a CHECK-TYPE for the special variable,\n for two reasons:\n to clue in the person reading the code\n that this variable is being used implicitly as an argument,\n and also to help detect bugs.\n
\n Using (declare (type ...))\n is the least-desirable mechanism to use\n because, as Scott McKay puts it:\n
\n\n\n The fact is,
\n(declare (type ...))does different things\n depending on the compiler settings of speed, safety, etc.\n In some compilers, when speed is greater than safety,\n(declare (type ...))will tell the compiler\n \"please assume that these variables have these types\"\n without generating any type-checks.\n That is, if some variable has the value1432in it,\n and you declare it to be of typestring,\n the compiler might just go ahead and use it as though it's a string.\n\n Moral: don't use
\n(declare (type ...))\n to declare the contract of any API functions,\n it's not the right thing.\n Sure, use it for \"helper\" functions, but not API functions.\n
\n You should, of course, use appropriate declarations\n in internal low-level functions\n where these declarations are used for optimization.\n When you do, however, see our recommendations for\n Unsafe Operations.\n
\n \n\n When a generic function is intended to be called from other\n modules (other parts of the code), there should be an\n explicit DEFGENERIC form,\n with a :DOCUMENTATION string\n explaining the generic contract of the function\n (as opposed to its behavior for some specific class).\n It's generally good to do explicit DEFGENERIC forms,\n but for module entry points it is mandatory.\n
\n When the argument list of a generic function includes\n &KEY,\n the DEFGENERIC should always explicitly list\n all of the keyword arguments that are acceptable,\n and explain what they mean.\n (Common Lisp does not require this, but it is good form,\n and it may avoid spurious warnings on SBCL.)\n
\n You should avoid SLOT-VALUE and WITH-SLOTS,\n unless you absolutely intend to circumvent\n any sort of method combination that might be in effect for the slot.\n Rare exceptions include INITIALIZE-INSTANCE\n and PRINT-OBJECT methods and\n accessing normally hidden slots in the low-level implementation of\n methods that provide user-visible abstractions.\n Otherwise, you should use accessors,\n WITH-ACCESSORS\n
\n Accessor names generally follow a convention of\n <protocol-name>-<slot-name>,\n where a \"protocol\" in this case loosely indicates\n a set of functions with well-defined behavior.\n
\n No implication of a formal \"protocol\" concept is necessarily intended,\n much less first-class \"protocol\" objects.\n However, there may indeed be an abstract CLOS class\n or an\n Interface-Passing Style interface\n that embodies the protocol.\n Further (sub)classes or (sub)interfaces may then implement\n all or part of a protocol by defining\n some methods for (generic) functions in the protocol,\n including readers and writers.\n
\n\n For example, if there were a notional protocol called\n is pnr with accessors pnr-segments\n and pnr-passengers, then\n the classes air-pnr, hotel-pnr and\n car-pnr could each reasonably implement\n methods for pnr-segments and pnr-passengers\n as accessors.\n
\n By default, an abstract base class name is used\n as the notional protocol name, so accessor names default\n to <class-name>-<slot-name>;\n while such names are thus quite prevalent,\n this form is neither required nor even preferred.\n In general, it contributes to \"symbol bloat\",\n and in many cases has led to a proliferation of \"trampoline\" methods.\n
\n Accessors named <slot-name>-of should not be used.\n
\n Explicit DEFGENERIC forms should be used when there are\n (or it is anticipated that there will be)\n more than one DEFMETHOD for that generic function.\n The reason is that the documentation for the generic function\n explains the abstract contract for the function,\n as opposed to explaining what an individual method does for\n some specific class(es).\n
\n You must not use generic functions where there is no notional protocol.\n To put it more concretely,\n if you have more than one generic function that specializes its Nth argument,\n the specializing classes should all be descendants of a single class.\n Generic functions must not be used for \"overloading\",\n i.e. simply to use the same name for two entirely unrelated types.\n
\n\n More precisely, it's not really\n whether they descend from a common superclass,\n but whether they obey the same \"protocol\".\n That is, the two classes should handle the same set of generic functions,\n as if there were an explicit DEFGENERIC for each method.\n
\n Here's another way to put it.\n Suppose you have two classes, A and B, and a generic function F.\n There are two methods for F,\n which dispatch on an argument being of types A and B.\n Is it plausible that there might be a function call somewhere\n in the program that calls F,\n in which the argument might sometimes, at runtime,\n be of class A and other times be of class B?\n If not, you probably are overloading and\n should not be using a single generic function.\n
\n\n We allow one exception to this rule:\n it's OK to do overloading\n if the corresponding argument \"means\" the same thing.\n Typically one overloading allows an X object,\n and the other allows the name of an X object,\n which might be a symbol or something.\n
\n\n You must not use MOP \"intercessory\" operations at runtime.\n You should not use MOP \"intercessory\" operations at compile-time.\n At runtime, they are at worst a danger, at best a performance issue.\n At compile-time, it is usually cleaner that\n macros should set things up the right way in one pass\n than have to require a second pass of fixups through intercession;\n but sometimes, fixups are necessary to resolve forward references,\n and intercession is allowed then.\n MOP intercession is a great tool for interactive development,\n and you may enjoy it while developping and debugging;\n but you should not use it in normal applications.\n
\n\n If a class definition creates a method\n as a :READER, :WRITER,\n or :ACCESSOR,\n do not redefine that method.\n It's OK to add :BEFORE, :AFTER,\n and :AROUND methods,\n but don't override the primary method.\n
\n In methods with keyword arguments,\n you must always use &KEY,\n even if the method does not care about the values of any keys,\n and you should never use &ALLOW-OTHER-KEYS.\n As long as a keyword is accepted by any method of a generic function,\n it's OK to use it in the generic function,\n even if the other methods of the same generic function\n don't mention it explicitly.\n This is particularly important\n for INITIALIZE-INSTANCE methods,\n since if you did use &ALLOW-OTHER-KEYS,\n it would disable error checking for misspelled or wrong keywords\n in MAKE-INSTANCE calls!\n
\n A typical PRINT-OBJECT method might look like this:\n
\n Macros bring syntactic abstraction, which is a wonderful thing.\n It helps make your code clearer, by describing your intent\n without getting bogged in implementation details\n (indeed abstracting those details away).\n It helps make your code more concise and more readable,\n by eliminating both redundancy and irrelevant details.\n But it comes at a cost to the reader,\n which is learning a new syntactic concept for each macro.\n And so it should not be abused.\n
\n\n The general conclusion is that there shouldn't be\n any recognizable design pattern\n in a good Common Lisp program.\n The one and only pattern is: use the language,\n which includes defining and using syntactic abstractions.\n
\n\n Existing macros must be used\n whenever they make code clearer\n by conveying intent in a more concise way,\n which is often.\n When a macro is available in your project\n that expresses the concept you're using,\n you must not write the expansion rather than use the macro.\n
\n\n New macros should be defined as appropriate,\n which should be seldom,\n for common macros have already been provided\n by the language and its various libraries,\n and your program typically only needs few new ones\n relative to its size.\n
\n\n You should follow the OAOOM rule of thumb\n for deciding when to create a new abstraction,\n whether syntactic or not:\n if a particular pattern is used more than twice,\n it should probably be abstracted away.\n A more refined rule to decide when to use abstraction\n should take into account\n the benefit in term of number of uses and gain at each use,\n to the costs in term of having to get used to reading the code.\n For syntactic abstractions, costs and benefits to the reader\n is usually more important than costs and benefits to the writer,\n because good code is usually written once\n and read many times by many people\n (including the same programmer\n who has to maintain the program after having forgotten it).\n Yet the cost to the writer of the macro\n should also be taken into account;\n however, in doing so it should rather be compared\n to the cost of the programmer writing other code instead\n that may have higher benefits.\n
\n\n Using Lisp macros properly requires taste.\n Avoid writing complicated macros\n unless the benefit clearly outweighs the cost.\n It takes more effort for your fellow developers to learn your macro,\n so you should only use a macro if the gain in expressiveness\n is big enough to justify that cost.\n As usual, feel free to consult your colleagues if you're not sure,\n since without a lot of Lisp experience,\n it can be hard to make this judgment.\n
\n\n You must never use a macro where a function will do.\n That is, if the semantics of what you are writing\n conforms to the semantics of a function,\n then you must write it as a function rather than a macro.\n
\n\n You must not transform a function into a macro for performance reasons.\n If profiling shows that you have a performance problem\n with a specific function FOO,\n document the need and profiling-results appropriately,\n and\n (declaim (inline foo)).\n
\n You can also use a compiler-macro\n as a way to speed up function execution\n by specifying a source-to-source transformation.\n Beware that it interferes with tracing the optimized function.\n
\n\n When you write a macro-defining macro\n (a macro that generates macros),\n document and comment it particularly clearly,\n since these are harder to understand.\n
\n\n You must not install new reader macros\n without a consensus among the developers of your system.\n Reader macros must not leak out of the system that uses them\n to clients of that system or other systems used in the same project.\n You must use software such as\n cl-syntax or named-readtables\n to control how reader macros are used.\n This clients who desire it may use the same reader macros as you do.\n In any case, your system must be usable\n even to clients who do not use these reader macros.\n
\n If your macro has a parameter that is a Lisp form\n that will be evaluated when the expanded code is run,\n you should name the parameter with the suffix -form.\n This convention helps make it clearer to the macro's user\n which parameters are Lisp forms to be evaluated, and which are not.\n The common names body and end are\n exceptions to this rule.\n
\n You should follow the so-called CALL-WITH style when it applies.\n This style is explained at length in\n http://random-state.net/log/3390120648.html.\n The general principle is that the macro is strictly limited to processing the syntax,\n and as much of the semantics as possible is kept in normal functions.\n Therefore, a macro WITH-FOO is often limited to\n generating a call to an auxiliary function\n CALL-WITH-FOO\n with arguments deduced from the macro arguments.\n Macro &body arguments are typically\n wrapped into a lambda expression of which they become the body,\n which is passed as one of the arguments of the auxiliary function.\n
\n The separation of syntactic and semantic concerns\n is a general principle of style that applies\n beyond the case of WITH- macros.\n Its advantages are many.\n By keeping semantics outside the macro,\n the macro is made simpler, easier to get right, and less subject to change,\n which makes it easier to develop and maintain.\n The semantics is written in a simpler language — one without staging —\n which also makes it easier to develop and maintain.\n It becomes possible to debug and update the semantic function\n without having to recompile all clients of the macro.\n The semantic function appears in the stack trace\n which also helps debug client functions.\n The macro expansion is made shorter and\n each expansion shares more code with other expansions,\n which reduces memory pressure which in turn usually makes things faster.\n It also makes sense to write the semantic functions first,\n and write the macros last as syntactic sugar on top.\n You should use this style unless the macro is used\n in tight loops where performance matters;\n and even then, see our rules regarding optimization.\n
\n Any functions (closures) created by the macro should be named,\n which can be done using FLET.\n \n This also allows you to declare the function to be of dynamic extent\n (if it is — and often it is; yet see below regarding\n DYNAMIC-EXTENT).\n
\n If a macro call contains a form,\n and the macro expansion includes more than one copy of that form,\n the form can be evaluated more than once,\n and code it contains macro-expanded and compiled more than once.\n If someone uses the macro and calls it\n with a form that has side effects or that takes a long time to compute,\n the behavior will be undesirable\n (unless you're intentionally writing\n a control structure such as a loop).\n A convenient way to avoid this problem\n is to evaluate the form only once,\n and bind a (generated) variable to the result.\n There is a very useful macro called ALEXANDRIA:ONCE-ONLY\n that generates code to do this.\n See also ALEXANDRIA:WITH-GENSYMS,\n to make some temporary variables in the generated code.\n Note that if you follow our CALL-WITH style,\n you typically expand the code only once, as either\n an argument to the auxiliary function, or\n the body of a lambda passed as argument to it;\n you therefore avoid the above complexity.\n
\n When you write a macro with a body,\n such as a WITH-xxx macro,\n even if there aren't any parameters,\n you should leave space for them anyway.\n For example, if you invent WITH-LIGHTS-ON,\n do not make the call to it look like\n (defmacro with-lights-on (&body b) ...).\n Instead, do (defmacro with-lights-on (() &body b) ...).\n That way, if parameters are needed in the future,\n you can add them without necessarily having to change\n all the uses of the macro.\n
EVAL-WHEN, you should almost always use all of\n (:compile-toplevel :load-toplevel :execute).\n \n Lisp evaluation happens at several times,\n some of them interleaved.\n Be aware of them when writing macros.\n EVAL-WHEN considered harmful to your mental health.\n
\n\n In summary of the article linked above,\n unless you're doing truly advanced macrology,\n the only valid combination in an EVAL-WHEN\n is to include all of\n (eval-when (:compile-toplevel :load-toplevel :execute) ...)\n
\n You must use\n (eval-when (:compile-toplevel :load-toplevel :execute) ...)\n whenever you define functions, types, classes, constants, variables, etc.,\n that are going to be used in macros.\n
\n It is usually an error to omit the :execute,\n because it prevents LOADing the source rather than the fasl.\n It is usually an error to omit the :load-toplevel\n (except to modify e.g. readtables and compile-time settings),\n because it prevents LOADing future files\n or interactively compiling code\n that depends on the effects that happen at compile-time,\n unless the current file was COMPILE-FILEd\n within the same Lisp session.\n
\n Regarding variables, note that because macros may or may not\n be expanded in the same process that runs the expanded code,\n you must not depend on compile-time and runtime effects\n being either visible or invisible at the other time.\n There are still valid uses of variables in macros:\n
\nLOAD-TIME-VALUE for good effect.\n In extreme cases, you may have to use\n ASDF-FINALIZERS:EVAL-AT-TOPLEVEL.\n *readtable*\n or compiler-internal variables holding\n the current optimization settings.\n You can often manage existing and new such variables using\n the :AROUND-COMPILE hooks of ASDF.\n #. sparingly,\n and you must avoid read-time side-effects.\n \n The #. standard read-macro\n will read one object, evaluate the object, and\n have the reader return the resulting value.\n
\n You must not use it where other idioms will do, such as\n using EVAL-WHEN to evaluate side-effects at compile-time,\n using a regular macro to return an expression computed at compile-time,\n using LOAD-TIME-VALUE to compute it at load-time.\n
\n Read-time evaluation is often used as a quick way\n to get something evaluated at compile time\n (actually \"read time\" but it amounts to the same thing).\n If you use this, the evaluation MUST NOT have any side effects\n and MUST NOT depend on any variable global state.\n The #. should be treated as a way\n to force \"constant-folding\"\n that a sufficiently-clever compiler\n could have figure out all by itself,\n when the compiler isn't sufficiently-clever\n and the difference matters.\n
\n Another use of #. is to expand the equivalent of macros\n in places that are neither expressions nor (quasi)quotations,\n such as lambda-lists. However, if you find yourself using it a lot,\n it might be time to instead define macros to replace your consumers\n of lambda-lists with something that recognizes an extension.\n
\n Whenever you are going to use #.,\n you should consider using DEFCONSTANT and its variants,\n possibly in an EVAL-WHEN,\n to give the value a name explaining what it means.\n
EVAL at runtime.\n \n Places where it is actually appropriate to use EVAL\n are so few and far between that you must consult with your reviewers;\n it's easily misused.\n
\n If your code manipulates symbols at runtime\n and needs to get the value of a symbol,\n use SYMBOL-VALUE, not EVAL.\n
\n Often, what you really need is to write a macro,\n not to use EVAL.\n
\n You may be tempted to use EVAL as a shortcut\n to evaluating expressions in a safe subset of the language.\n But it often requires more scrutiny to properly check and sanitize\n all possible inputs to such use of EVAL\n than to build a special-purpose evaluator.\n You must not use EVAL in this way at runtime.\n
\n Places where it is OK to use EVAL are:\n
\n Note that in the latter case,\n if the macro isn't going to be used at the top-level,\n it might not be possible to make these definitions available\n as part of the expansion.\n The same phenomenon may happen in a DEFTYPE expansion,\n or in helper functions used by macros.\n In these cases, you may actually have to use\n ASDF-FINALIZERS:EVAL-AT-TOPLEVEL in your macro.\n It will not only EVAL your definitions\n at macro-expansion time for immediate availability,\n it will also save the form aside, for inclusion in a\n (ASDF-FINALIZERS:FINAL-FORMS)\n that you need to include at the end of the file being compiled\n (or before the form is needed).\n This way, the side-effects are present when loading the fasl\n without having compiled it as well as while compiling it;\n in either case, the form is made available at load-time.\n ASDF-FINALIZERS ensures that the form is present,\n by throwing an error if you omit it.\n
INTERN or UNINTERN at runtime.\n \n You must not use INTERN at runtime.\n Not only does it cons,\n it either creates a permanent symbol that won't be collected\n or gives access to internal symbols.\n This creates opportunities for memory leaks, denial of service attacks,\n unauthorized access to internals, clashes with other symbols.\n
\n You must not INTERN a string\n just to compare it to a keyword;\n use STRING= or STRING-EQUAL.\n
\n You must not use UNINTERN at runtime.\n It can break code that relies on dynamic binding.\n It makes things harder to debug.\n You must not dynamically intern any new symbol,\n and therefore you need not dynamically unintern anything.\n
\n You may of course use INTERN at compile-time,\n in the implementation of some macros.\n Even so, it is usually more appropriate\n to use abstractions on top of it, such as\n ALEXANDRIA:SYMBOLICATE or\n ALEXANDRIA:FORMAT-SYMBOL\n to create the symbols you need.\n
NIL.\n \n NIL can have several different interpretations:\n
NIL.\n You should test for false NIL\n using the operator NOT or\n using the predicate function NULL.\n '().\n (Be careful about quoting the empty-list when calling macros.)\n You should use ENDP to test for the empty list\n when the argument is known to be a proper list,\n or with NULL otherwise.\n NIL\n if there is no risk of ambiguity anywhere in your code;\n otherwise you should use an explicit, descriptive symbol.\n NIL.\n \n You must not introduce ambiguity in your data representations\n that will cause headaches for whoever has to debug code.\n If there is any risk of ambiguity,\n you should use an explicit, descriptive symbol or keyword\n for each case,\n instead of using NIL for either.\n If you do use NIL,\n you must make sure that the distinction is well documented.\n
\n In many contexts,\n instead of representing \"I don't know\" as a particular value,\n you should instead use multiple values,\n one for the value that is known if any,\n and one to denote whether the value was known or found.\n
\n \n\n When working with database classes, keep in mind that\n NIL need not always map to 'NULL'\n (and vice-versa)!\n The needs of the database may differ from the needs of the Lisp.\n
LIST data structure.\n \n Even though back in 1958, LISP was short for \"LISt Processing\",\n its successor Common Lisp has been a modern programming language\n with modern data structures since the 1980s.\n You must use the proper data structures in your programs.\n
\n\n You must not abuse the builtin (single-linked) LIST\n data structure where it is not appropriate,\n even though Common Lisp makes it especially easy to use it.\n
\n You must only use lists\n when their performance characteristics\n is appropriate for the algorithm at hand:\n sequential iteration over the entire contents of the list.\n
\n\n An exception where it is appropriate to use lists\n is when it is known in advance\n that the size of the list will remain very short\n (say, less than 16 elements).\n
\n\n List data structures are often (but not always)\n appropriate for macros and functions used by macros at compile-time:\n indeed, not only is source code passed as lists in Common Lisp,\n but the macro-expansion and compilation processes\n will typically walk over the entire source code, sequentially, once.\n (Note that advanced macro systems don't directly use lists, but instead\n use abstract syntax objects that track source code location and scope;\n however there is no such advanced macro system\n in Common Lisp at this time.)\n
\n\n Another exception where it is appropriate to use lists is\n for introducing literal constants\n that will be transformed into more appropriate data structures\n at compile-time or load-time.\n It is a good to have a function with a relatively short name\n to build your program's data structures from such literals.\n
\n\n In the many cases when lists are not the appropriate data structure,\n various libraries such as\n cl-containers or\n lisp-interface-library\n provide plenty of different data structures\n that should fulfill all the basic needs of your programs.\n If the existing libraries are not satisfactory, see above about\n Using Libraries and\n Open-Sourcing Code.\n
\n \n\n You should avoid using a list as anything\n besides a container of elements of like type.\n You must not use a list as method of passing\n multiple separate values of different types\n in and out of function calls.\n Sometimes it is convenient to use a list\n as a little ad hoc structure,\n i.e. \"the first element of the list is a FOO, and the second is a BAR\",\n but this should be used minimally\n since it gets harder to remember the little convention.\n You must only use a list that way\n when destructuring the list of arguments from a function,\n or creating a list of arguments\n to which to APPLY a function.\n
\n The proper way to pass around an object\n comprising several values of heterogeneous types\n is to use a structure as defined by DEFSTRUCT\n or DEFCLASS.\n
\n You should use multiple values only\n when function returns a small number of values\n that are meant to be destructured immediately by the caller,\n rather than passed together as arguments to further functions.\n
\n\n You should not return a condition object\n as one of a set of multiple values.\n Instead, you should signal the condition to denote an unusual outcome.\n
\n\n You should signal a condition to denote an unusual outcome,\n rather than relying on a special return type.\n
\n \n\n Use FIRST to access the first element of a list,\n SECOND to access the second element, etc.\n Use REST to access the tail of a list.\n Use ENDP to test for the end of the list.\n
\n Use CAR and CDR\n when the cons cell is not being used to implement a proper list\n and is instead being treated as a pair of more general objects.\n Use NULL to test for NIL in this context.\n
\n The latter case should be rare outside of alists,\n since you should be using structures and classes where they apply,\n and data structure libraries when you want trees.\n
\n\n Exceptionally, you may use CDADR and other variants\n on lists when manually destructuring them,\n instead of using a combination of several list accessor functions.\n In this context, using CAR and CDR\n instead of FIRST and REST also makes sense.\n However, keep in mind that it might be more appropriate in such cases\n to use higher-level constructs such as\n DESTRUCTURING-BIND or OPTIMA:MATCH.\n
\n ELT has O(n) behavior when used on lists.\n If you are to use random element access on an object,\n use arrays and AREF instead.\n
\n The exception is for code outside the critical path\n where the list is known to be small anyway.\n
\n \n\n Using lists as representations of sets is a bad idea\n unless you know the lists will be small,\n for accessors are O(n) instead of O(log n).\n For arbitrary big sets, use balanced binary trees,\n for instance using lisp-interface-library.\n
\n If you still use lists as sets,\n you should not UNION lists just to search them.\n
\n Indeed, UNION not only conses unnecessarily,\n but it can be O(n^2) on some implementations,\n and is rather slow even when it's O(n).\n
\n You must follow the proper usage regarding\n well-known functions, macros and special forms.\n
\n\n The Lisp system we primarily use, SBCL, is very picky and\n signals a condition whenever a constant is redefined to a value not\n EQL to its previous setting.\n You must not use DEFCONSTANT\n when defining variables that are not\n numbers, characters, or symbols (including booleans and keywords).\n Instead, consistently use whichever alternative\n is recommended for your project.\n
\n Open-Source libraries may use\n ALEXANDRIA:DEFINE-CONSTANT\n for constants other than numbers, characters and symbols\n (including booleans and keywords).\n You may use the :TEST keyword argument\n to specify an equality predicate.\n
\n Note that with optimizing implementations, such as SBCL or CMUCL,\n defining constants this way precludes any later redefinition\n short of UNINTERNing the symbol\n and recompiling all its clients.\n This may make it \"interesting\" to debug things at the REPL\n or to deploy live code upgrades.\n If there is a chance that your \"constants\" are not going to be constant\n over the lifetime of your server processes\n after taking into consideration scheduled and unscheduled code patches,\n you should consider using\n DEFPARAMETER or DEFVAR instead,\n or possibly a variant of DEFINE-CONSTANT\n that builds upon some future library implementing global lexicals\n rather than DEFCONSTANT.\n You may keep the +plus+ convention in these cases\n to document the intent of the parameter as a constant.\n
\n Also note that LOAD-TIME-VALUE may help you\n avoid the need for defined constants.\n
&OPTIONAL and\n &KEY arguments.\n You should not use &AUX arguments.\n \n You should avoid using &ALLOW-OTHER-KEYS,\n since it blurs the contract of a function.\n Almost any real function (generic or not) allows a certain\n fixed set of keywords, as far as its caller is concerned,\n and those are part of its contract.\n If you are implementing a method of a generic function,\n and it does not need to know\n the values of some of the keyword arguments,\n you should explicitly (DECLARE (IGNORE ...))\n all the arguments that you are not using.\n You must not use &ALLOW-OTHER-KEYS\n unless you explicitly want to disable checking of allowed keys\n for all methods when invoking the generic function on arguments\n that match this particular method.\n Note that the contract of a generic function belongs in\n the DEFGENERIC, not in the DEFMETHOD\n which is basically an \"implementation detail\" of the generic function\n as far as the caller of the generic is concerned.\n
\n A case where &ALLOW-OTHER-KEYS is appropriate\n is when you write a wrapper function to other some other functions\n that may vary (within the computation or during development),\n and pass around a plist as a &REST argument.\n
\n You should avoid using &AUX arguments.\n
\n You should avoid having both &OPTIONAL\n and &KEY arguments,\n unless it never makes sense to specify keyword arguments\n when the optional arguments are not all specified.\n You must not have non-NIL defaults\n to your &OPTIONAL arguments\n when your function has both &OPTIONAL\n and &KEY arguments.\n
\n For maximum portability of a library, it is good form\n that DEFMETHOD definitions should\n (DECLARE (IGNORABLE ...))\n all the required arguments that they are not using.\n Indeed, some implementations will issue a warning\n if you (DECLARE (IGNORE ...)) those arguments,\n whereas other implementations will issue a warning\n if you fail to (DECLARE (IGNORE ...)) them.\n (DECLARE (IGNORABLE ...)) works on all implementations.\n
\n You should avoid excessive nesting of binding forms inside a function.\n If your function ends up with massive nesting,\n you should probably break it up into several functions or macros.\n If it is really a single conceptual unit,\n consider using a macro such as FARE-UTILS:NEST\n to at least reduce the amount of indentation required.\n It is bad form to use NEST in typical short functions\n with 4 or fewer levels of nesting,\n but also bad form not to use it in the exceptional long functions\n with 10 or more levels of nesting.\n Use your judgment and consult your reviewers.\n
\n Use WHEN and UNLESS\n when there is only one alternative.\n Use IF when there are two alternatives\n and COND when there are several.\n
\n However, don't use PROGN for an IF clause\n — use COND, WHEN, or UNLESS.\n
\n Note that in Common Lisp,\n WHEN and UNLESS return NIL\n when the condition is not met.\n You may take advantage of it.\n Nevertheless, you may use an IF\n to explicitly return NIL\n if you have a specific reason to insist on the return value.\n You may similarly include a fall-through clause (t nil)\n as the last in your (otherwise nil) as the last in your
\n You should prefer AND and OR\n when it leads to more concise code than using\n IF, COND,\n WHEN or UNLESS,\n and there are no side-effects involved.\n You may also use an ERROR\n as a side-effect in the final clause of an OR.\n
\n You should only use CASE and ECASE\n to compare numbers, characters or symbols\n (including booleans and keywords).\n Indeed, CASE uses EQL for comparisons,\n so strings, pathnames and structures may not compare the way you expect,\n and 1 will differ from 1.0.\n
\n You should use ECASE and ETYPECASE\n in preference to CASE and TYPECASE.\n It is better to catch erroneous values early.\n
\n You should not use CCASE or CTYPECASE at all.\n At least, you should not use them in server processes,\n unless you have quite robust error handling infrastructure\n and make sure not to leak sensitive data this way.\n These are meant for interactive use,\n and can cause interesting damage\n if they cause data or control to leak to attackers.\n
\n You must not use gratuitous single quotes in CASE forms.\n This is a common error:\n
\n 'BAR there is (QUOTE BAR),\n meaning this leg of the case will be executed\n if X is QUOTE...\n and ditto for the second leg\n (though QUOTE will be caught by the first clause).\n This is unlikely to be what you really want.\n
\n In CASE forms,\n you must use otherwise instead of t\n when you mean \"execute this clause if the others fail\".\n You must use ((t) ...)\n when you mean \"match the symbol T\" rather than \"match anything\".\n You must also use ((nil) ...)\n when you mean \"match the symbol NIL\" rather than \"match nothing\".\n
\n Therefore, if you want to map booleans NIL and T\n to respective symbols :BAR and :QUUX,\n you should avoid the former way and do it the latter way:\n
\n Lisp provides four general equality predicates:\n EQ, EQL, EQUAL,\n and EQUALP,\n which subtly vary in semantics.\n Additionally, Lisp provides the type-specific predicates\n =, CHAR=, CHAR-EQUAL,\n STRING=, and STRING-EQUAL.\n Know the distinction!\n
\n You should use EQL to compare objects and symbols\n for identity.\n
\n You must not use EQ to compare numbers or characters.\n Two numbers or characters that are EQL\n are not required by Common Lisp to be EQ.\n
\n When choosing between EQ and EQL,\n you should use EQL unless you are writing\n performance-critical low-level code.\n EQL reduces the opportunity\n for a class of embarrassing errors\n (i.e. if numbers or characters are ever compared).\n There may a tiny performance cost relative to EQ,\n although under SBCL, it often compiles away entirely.\n EQ is equivalent to EQL and type declarations,\n and use of it for optimization should be treated just like\n any such unsafe operations.\n
\n You should use CHAR=\n for case-dependent character comparisons,\n and CHAR-EQUAL for case-ignoring character comparisons.\n
\n You should use STRING=\n for case-dependent string comparisons,\n and STRING-EQUAL for case-ignoring string comparisons.\n
\n A common mistake when using SEARCH on strings\n is to provide STRING= or STRING-EQUAL\n as the :TEST function.\n The :TEST function\n is given two sequence elements to compare.\n If the sequences are strings,\n the :TEST function is called on two characters,\n so the correct tests are CHAR= or CHAR-EQUAL.\n If you use STRING= or STRING-EQUAL,\n the result is what you expect,\n but in some Lisp implementations it's much slower.\n CCL (at least as of 8/2008)\n creates a one-character string upon each comparison, for example,\n which is very expensive.\n
\n Also, you should use :START and :END arguments\n to STRING= or STRING-EQUAL\n instead of using SUBSEQ;\n e.g. (string-equal (subseq s1 2 6) s2) should instead be\n (string-equal s1 s2 :start1 2 :end1 6)\n This is preferable because it does not cons.\n
\n You should use ZEROP,\n PLUSP, or MINUSP,\n instead of comparing a value to 0 or 0.0.\n
\n You must not use exact comparison on floating point numbers,\n since the vague nature of floating point arithmetic\n can produce little \"errors\" in numeric value.\n You should compare absolute values to a threshold.\n
\n\n You must use = to compare numbers,\n unless you really mean for 0,\n 0.0 and -0.0 to compare unequal,\n in which case you should use EQL.\n Then again, you must not usually use exact comparison\n on floating point numbers.\n
\n Monetary amounts should be using decimal (rational) numbers\n to avoid the complexities and rounding errors\n of floating-point arithmetic.\n Libraries such as\n wu-decimal\n may help you;\n once again, if this library is not satisfactory, see above about\n Using Libraries and\n Open-Sourcing Code.\n
\n \n \n\n You should use simpler forms such as\n DOLIST or DOTIMES\n instead of LOOP\n in simple cases when you're not going to use any\n of the LOOP facilities such as\n bindings, collection or block return.\n
\n Use the WITH clause of LOOP\n when it will avoid a level of nesting with LET.\n You may use LET if it makes it clearer\n to return one of bound variables after the LOOP,\n rather than use a clumsy FINALLY (RETURN ...) form.\n
\n In the body of a DOTIMES,\n do not set the iteration variable.\n (CCL will issue a compiler warning if you do.)\n
\n Most systems use unadorned symbols in the current package\n as LOOP keywords.\n Other systems use actual :keywords\n from the KEYWORD package\n as LOOP keywords.\n You must be consistent with the convention used in your system.\n
\n When writing a server,\n code must not send output to the standard streams such as\n *STANDARD-OUTPUT* or *ERROR-OUTPUT*.\n Instead, code must use the proper logging framework\n to output messages for debugging.\n We are running as a server, so there is no console!\n
\n Code must not use PRINT-OBJECT\n to communicate with a user —\n PRINT-OBJECT is for debugging purposes only.\n Modifying any PRINT-OBJECT method\n must not break any public interfaces.\n
\n You should not use a sequence of WRITE-XXX\n where a single FORMAT string could be used.\n Using format allows you\n to parameterize the format control string in the future\n if the need arises.\n
\n You should use WRITE-CHAR to emit a character\n rather than WRITE-STRING\n to emit a single-character string.\n
\n You should not use (format nil \"~A\" value);\n you should use PRINC-TO-STRING instead.\n
\n You should use ~<Newline>\n or ~@<Newline> in format strings\n to keep them from wrapping in 100-column editor windows,\n or to indent sections or clauses to make them more readable.\n
\n You should not use STRING-UPCASE\n or STRING-DOWNCASE\n on format control parameters;\n instead, it should use \"~:@(~A~)\" or \"~(~A~)\".\n
\n Be careful when using the FORMAT conditional directive.\n The parameters are easy to forget.\n
\"~[Siamese~;Manx~;Persian~] Cat\"\":\" in front of the last \";\".\n E.g. in \"~[Siamese~;Manx~;Persian~:;Alley~] Cat\",\n an out-of-range arg prints \"Alley\".\n : parameter, e.g. \"~:[Siamese~;Manx~]\"NIL,\n use the first clause, otherwise use the second clause.\n @ parameter, e.g. \"~@[Siamese ~a~]\"# parameter, e.g. \"~#[ none~; ~s~; ~s and ~s~]\"\"Items: ~#[ none~; ~S~; ~S and ~S~:;~@{~S~^~#[~; and ~:;, ~]~}~].\"\n \n In a language with automatic storage management (such as Lisp or Java),\n the colloquial phrase \"memory leak\" refers to situation\n where storage that is not actually needed\n nevertheless does not get deallocated,\n because it is still reachable.\n
\n\n You should be careful that when you create objects,\n you don't leave them reachable after they are no longer needed!\n
\n\n Here's a particular trap-for-the-unwary in Common Lisp.\n If you make an array with a fill pointer, and put objects in it,\n and then set the fill pointer back to zero,\n those objects are still reachable as far as Lisp goes\n (the Common Lisp spec says that it's still OK\n to refer to the array entries past the end of the fill pointer).\n
\n\n Don't cons (i.e., allocate) unnecessarily.\n Garbage collection is not magic.\n Excessive allocation is usually a performance problem.\n
\n \n\n Common Lisp implementations often provide backdoors\n to compute some operations faster in an unsafe way.\n For instance, some libraries provide arithmetic operations\n that are designed to be used with fixnums only,\n and yield the correct result faster if provided proper arguments.\n The downside is that the result of such operations\n is incorrect in case of overflow, and can\n have undefined behavior when called with anything but fixnums.\n
\n \n\n More generally, unsafe operations\n will yield the correct result faster\n than would the equivalent safe operation\n if the arguments satisfy some invariant such as\n being of the correct type and small enough;\n however if the arguments fail to satisfy the required invariants,\n then the operation may have undefined behavior,\n such as crashing the software, or,\n which is sometimes worse, silently giving wrong answers.\n Depending on whether the software is piloting an aircraft\n or other life-critical device,\n or whether it is accounting for large amounts money,\n such undefined behavior can kill or bankrupt people.\n Yet proper speed can sometimes make the difference between\n software that's unusably slow and software that does its job,\n or between software that is a net loss\n and software that can yield a profit.\n
\n\n You must not define or use unsafe operations without both\n profiling results indicating the need for this optimization,\n and careful documentation explaining why it is safe to use them.\n Unsafe operations should be restricted to internal functions;\n you should carefully documented how unsafe it is\n to use these functions with the wrong arguments.\n You should only use unsafe operations\n inside functions internal to a package and\n you should document the use of the declarations,\n since calling the functions with arguments of the wrong type\n can lead to undefined behavior.\n Use check-type in functions exported from a package\n to sanitize input arguments,\n so that internal functions are never passed illegal values.\n
\n On some compilers,\n new unsafe operations\n can usually be defined by combining\n type declarations with an OPTIMIZE declaration\n that has sufficiently high SPEED and low SAFETY.\n In addition to providing more speed for production code,\n such declarations may more helpful\n than check-type assertions\n for finding bugs at compile-time,\n on compilers that have type inference.\n These compilers may interpret those declarations as assertions\n if you switch to safer and slower optimize settings;\n this is good to locate a dynamic error in your code during development,\n but is not to be used for production code since\n it defeats the purpose of declarations as a performance trick.\n
DYNAMIC-EXTENT\n where it matters for performance,\n and you can document why it is correct.\n \n DYNAMIC-EXTENT declarations are\n a particular case of\n unsafe operations.\n
\n The purpose of a DYNAMIC-EXTENT declaration\n is to improve performance by reducing garbage collection\n in cases where it appears to be obvious that an object's lifetime\n is within the \"dynamic extent\" of a function.\n That means the object is created at some point\n after the function is called, and\n the object is always inaccessible after the function exits by any means.\n
\n By declaring a variable or a local function DYNAMIC-EXTENT,\n the programmer asserts to Lisp\n that any object that is ever a value of that variable\n or the closure that is the definition of the function\n has a lifetime within the dynamic extent of the (innermost) function\n that declares the variable.\n
\n The Lisp implementation is then free to use that information\n to make the program faster.\n Typically, Lisp implementations can take advantage of this knowledge\n to stack-allocate:\n
\n&REST parameters.\n \n If the assertion is wrong, i.e. if the programmer's claim is not true,\n the results can be catastrophic:\n Lisp can terminate any time after the function returns,\n or it can hang forever, or — worst of all —\n it can produce incorrect results without any runtime error!\n
\n\n Even if the assertion is correct,\n future changes to the function might introduce\n a violation of the assertion.\n This increases the danger.\n
\n\n In most cases, such objects are ephemeral.\n Modern Lisp implementations use generational garbage collectors,\n which are quite efficient under these circumstances.\n
\n\n Therefore, DYNAMIC-EXTENT declarations\n should be used sparingly. You must only use them if:\n
\n Point (1) is a special case of\n the principle of avoiding premature optimization.\n An optimization like this only matters if such objects\n are allocated at a very high rate, e.g. \"inside an inner loop\".\n
\n\n Note that is relatively easy to ascertain that\n a function will not escape the dynamic extent of the current call frame\n by analyzing where the function is called and\n what other functions it is passed to;\n therefore, you should somewhat wary of declaring a function\n DYNAMIC-EXTENT, but this is not a high-stress declaration.\n On the other hand, it is much harder to ascertain that\n none of the objects ever bound or assigned to that variable\n and none of their sub-objects\n will escape the dynamic extent of the current call frame,\n and that they still won't in any future modification of a function.\n Therefore, you should be extremely wary\n of declaring a variable DYNAMIC-EXTENT.\n
\n It's usually hard to predict the effect of such optimization on performance.\n When writing a function or macro\n that is part of a library of reusable code,\n there's no a priori way to know how often the code will run.\n Ideally, tools would be available to discover\n the availability and suitability of using such an optimization\n based on running simulations and test cases, but\n in practice this isn't as easy as it ought to be.\n It's a tradeoff.\n If you're very, very sure that the assertion is true\n (that any object bound to the variable and any of its sub-objects\n are only used within the dynamic extent of the specified scope),\n and it's not obvious how much time will be saved\n and it's not easy to measure,\n then it may be better to put in the declaration than to leave it out.\n (Ideally it would be easier to make such measurements\n than it actually is.)\n
\n \nREDUCE\n instead of APPLY where appropriate.\n \n You should use REDUCE\n instead of APPLY and a consed-up list,\n where the semantics of the first operator argument\n otherwise guarantees the same semantics.\n Of course, you must use APPLY\n if it does what you want and REDUCE doesn't.\n For instance:\n
\n This is preferable because it does not do extra consing,\n and does not risk going beyond CALL-ARGUMENTS-LIMIT\n on implementations where that limit is small,\n which could blow away the stack on long lists\n (we want to avoid gratuitous non-portability in our code).\n
\n However, you must be careful not to use REDUCE\n in ways that needlessly increase\n the complexity class of the computation.\n For instance, (REDUCE 'STRCAT ...) is O(n^2)\n when an appropriate implementation is only O(n).\n Moreover, (REDUCE 'APPEND ...)\n is also O(n^2) unless you specify :FROM-END T.\n In such cases, you MUST NOT use REDUCE,\n and you MUST NOT use (APPLY 'STRCAT ...)\n or (APPLY 'APPEND ...) either.\n Instead you MUST use proper abstractions\n from a suitable library (that you may have to contribute to)\n that properly handles those cases\n without burdening users with implementation details.\n See for instance UIOP:REDUCE/STRCAT.\n
NCONC;\n you should use APPEND instead,\n or better data structures.\n \n You should almost never use NCONC.\n You should use APPEND\n when you don't depend on any side-effect.\n You should use ALEXANDRIA:APPENDF\n when you need to update a variable.\n You should probably not depend on games\n being played with the CDR\n of the current CONS cell\n (which some might argue is suggested but not guaranteed by the specification);\n if you do, you must include a prominent\n comment explaining the use of NCONC;\n and you should probably reconsider your data representation strategy.\n
\n By extension, you should avoid MAPCAN\n or the NCONC feature of LOOP.\n You should instead respectively use\n ALEXANDRIA:MAPPEND\n and the APPEND feature of LOOP.\n
\n NCONC is very seldom a good idea,\n since its time complexity class is no better than APPEND,\n its space complexity class also is no better than APPEND\n in the common case where no one else is sharing the side-effected list,\n and its bug complexity class is way higher than APPEND.\n
\n If the small performance hit due\n to APPEND vs. NCONC\n is a limiting factor in your program,\n you have a big problem and are probably using the wrong data structure:\n you should be using sequences with constant-time append\n (see Okasaki's book, and add them to lisp-interface-library),\n or more simply you should be accumulating data in a tree\n that will get flattened once in linear time\n after the accumulation phase is complete.\n
\n You may only use NCONC, MAPCAN\n or the NCONC feature of LOOP\n in low-level functions where performance matters,\n where the use of lists as a data structure has been vetted\n because these lists are known to be short,\n and when the function or expression the result of which are accumulated\n explicitly promises in its contract that it only returns fresh lists\n (in particular, it can't be a constant quote or backquote expression).\n Even then, the use of such primitives must be rare,\n and accompanied by justifying documentation.\n
#'FUN rather than 'FUN.\n \n The former, which reads as (FUNCTION FUN),\n refers to the function object, and is lexically scoped.\n The latter, which reads as (QUOTE FUN),\n refers to the symbol, which when called\n uses the global FDEFINITION of the symbol.\n
\n When using functions that take a functional argument\n (e.g., MAPCAR, APPLY,\n :TEST and :KEY arguments),\n you should use the #' to refer to the function,\n not just single quote.\n
\n An exception is when you explicitly want dynamic linking,\n because you anticipate that\n the global function binding will be updated.\n
\n\n Another exception is when you explicitly want to access\n a global function binding,\n and avoid a possible shadowing lexical binding.\n This shouldn't happen often, as it is usually a bad idea\n to shadow a function when you will want to use the shadowed function;\n just use a different name for the lexical function.\n
\n\n You must consistently use either #'(lambda ...)\n or (lambda ...) without #' everywhere.\n Unlike the case of #'symbol vs 'symbol,\n it is only a syntactic difference with no semantic impact,\n except that the former works on Genera and the latter doesn't.\n \n You must use the former style if your code is intended as a library\n with maximal compatibility to all Common Lisp implementations;\n otherwise, it is optional which style you use.\n #' may be seen as a hint\n that you're introducing a function in expression context;\n but the lambda itself is usually sufficient hint,\n and concision is good.\n Choose wisely, but above all,\n consistently with yourself and other developers,\n within a same file, package, system, project, etc.\n
\n Note that if you start writing a new system\n in a heavily functional style,\n you may consider using\n lambda-reader,\n a system that lets you use the unicode character λ\n instead of LAMBDA.\n But you must not start using such a syntactic extension\n in an existing system without getting permission from other developers.\n
UIOP.\n \n It is surprisingly hard to properly deal with pathnames in Common Lisp.\n
\n\n ASDF 3 comes with a portability library UIOP\n that makes it much easier to deal with pathnames\n portably — and correctly — in Common Lisp.\n You should use it when appropriate.\n
\n First, be aware of the discrepancies between\n the syntax of Common Lisp pathnames,\n which depends on which implementation and operating system\n you are using,\n and the native syntax of pathnames on your operating system.\n The Lisp syntax may involves quoting of special characters\n such as #\\. and #\\*, etc.,\n in addition to the quoting of\n #\\\\ and #\\\" within strings.\n By contrast, your operating system's other\n system programming languages\n (shell, C, scripting languages)\n may only have one layer of quoting, into strings.\n
\n Second, when using MERGE-PATHNAMES,\n be wary of the treatment of the HOST component,\n which matters a lot on non-Unix platforms\n (and even on some Unix implementations).\n You probably should be using\n UIOP:MERGE-PATHNAMES* or UIOP:SUBPATHNAME\n instead of MERGE-PATHNAMES,\n especially if your expectations for relative pathnames\n are informed by the way they work in Unix or Windows;\n otherwise you might hit weird bugs whereby on some implementations,\n merging a relative pathnames with an absolute pathname\n results in overriding the absolute pathname's host\n and replace it with the host from the value of\n *DEFAULT-PATHNAME-DEFAULTS*\n at the time the relative pathname was created.\n
\n Third, be aware that DIRECTORY\n is not portable across implementations\n in how it handles wildcards, sub-directories, symlinks, etc.\n There again, UIOP provides several\n common abstractions to deal with pathnames,\n but only does so good a job.\n For a complete portable solution, use IOLib —\n though its Windows support lags behind.\n
\n LOGICAL-PATHNAMEs are not a portable abstraction,\n and should not be used in portable code.\n Many implementations have bugs in them, when they are supported at all.\n SBCL implements them very well,\n but strictly enforces the limitations on characters\n allowed by the standard, which restricts their applicability.\n Other implementations allow arbitrary characters in such pathnames,\n but in doing so are not being conformant,\n and are still incompatible with each other in many ways.\n You should use other pathname abstractions,\n such as ASDF:SYSTEM-RELATIVE-PATHNAME or\n the underlying UIOP:SUBPATHNAME and\n UIOP:PARSE-UNIX-NAMESTRING.\n
\n Finally, be aware that paths may change between\n the time you build the Lisp image for your application,\n and the time you run the application from its image.\n You should be careful to reset your image\n to forget irrelevant build-time paths and\n reinitialize any search path from current environment variables.\n ASDF for instance requires you to reset its paths\n with UIOP:CLEAR-CONFIGURATION.\n UIOP provides hooks\n to call functions before an image is dumped,\n from which to reset or makunbound relevant variables.\n
SATISFIES clause in a type specifier.\n \n Most Common Lisp implementations can't optimize\n based on a SATISFIES type,\n but many of them offer simple optimizations\n based on a type of the form\n (AND FOO (SATISFIES BAR-P))\n where the first term of the AND clause\n describes the structure of the object\n without any SATISFIES\n and the second term is the SATISFIES.\n
\n However, AND in the DEFTYPE language\n isn't a left-to-right short-circuit operator\n as in the expression language;\n it is a symmetrical connector that allows for reordering subterms\n and doesn't guarantee short-circuiting.\n Therefore, in the above example,\n you cannot rely on the test for INTEGERness\n to protect the function PRIME-NUMBER-P\n from being supplied non-integer arguments\n to test for being of instances of the type.\n Implementations may, and some will,\n invoke SATISFIES-specified function\n at compile-time to test various relevant objects.\n
\n That is why any function specified in a SATISFIES clause\n MUST accept objects of any type as argument to the function,\n and MUST be defined within an EVAL-WHEN\n (as well as any variable it uses or function it calls):\n
\n In particular, the above means that the\n example\n used in the Common Lisp Standard is erroneous:\n (and integer (satisfies evenp))\n is not a safe, conformant type specifier to use,\n because EVENP will throw an error\n rather than return NIL\n when passed a non-integer as an argument.\n
\n Finally, there is a catch when your DEFTYPE code expands\n to a SATISFIES with a dynamically generated function:\n
DEFTYPE.\n \n Therefore, you cannot merely create the function\n as a side-effect of expansion\n using EVAL at type-expansion time.\n The solution is to use\n ASDF-FINALIZERS:EVAL-AT-TOPLEVEL instead.\n See the very last point\n in the discussion about EVAL.\n
\n Common Lisp is hard to satisfy.\n
\n \n\nRevision 1.28\n
\n\n\n\nRobert Brown\n\n\n\n François-René Rideau\n\n\n\n\n\n The style guide has moved to\n objcguide.md\n
\n| %s, %s |
| %s, %s |
| Type | \nPublic | \nInternal | \n
|---|---|---|
| Packages | \nlower_with_under | \n \n |
| Modules | \nlower_with_under | \n _lower_with_under | \n
| Classes | \nCapWords | \n _CapWords | \n
| Exceptions | \nCapWords | \n \n |
| Functions | \nlower_with_under() | \n _lower_with_under() | \n
| Global/Class Constants | \nCAPS_WITH_UNDER | \n _CAPS_WITH_UNDER | \n
| Global/Class Variables | \nlower_with_under | \n _lower_with_under | \n
| Instance Variables | \nlower_with_under | \n _lower_with_under (protected) | \n
| Method Names | \nlower_with_under() | \n _lower_with_under() (protected) | \n
| Function/Method Parameters | \nlower_with_under | \n \n |
| Local Variables | \nlower_with_under | \n \n |
\n Each style point has a summary for which additional information is available\n by toggling the accompanying arrow button that looks this way:\n .\n You may toggle all summaries with the big arrow button:\n
\n\n
\n
\n
\n
\n
\n
\n