12 | The style guide has moved to Rguide.html
13 |
14 |
15 |
16 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE.md:
--------------------------------------------------------------------------------
1 | This repository publishes copies of Google's internal style guides to
2 | assist developers working on Google owned and originated open source
3 | projects. Development on these guides does not take place here.
4 |
5 | Substantive changes to the style rules and suggested new rules should
6 | not be submitted as issues in this repository. Material changes must be
7 | proposed, discussed, and approved on the internal forums first.
8 |
9 | If an issue points out a simple mistake — a typo, a broken link, etc. —
10 | then a correction might be made. However there is no commitment to do
11 | so. Issues are normally closed without comment.
12 |
--------------------------------------------------------------------------------
/.github/PULL_REQUEST_TEMPLATE.md:
--------------------------------------------------------------------------------
1 | These style guides are copies of Google's internal style guides to
2 | assist developers working on Google owned and originated open source
3 | projects. Changes should be made to the internal style guide first and
4 | only then copied here.
5 |
6 | Unsolicited pull requests will not be merged and are usually closed
7 | without comment. If a PR points out a simple mistake — a typo, a broken
8 | link, etc. — then the correction can be made internally and copied here
9 | through the usual process.
10 |
11 | Substantive changes to the style rules and suggested new rules should
12 | not be submitted as a PR in this repository. Material changes must be
13 | proposed, discussed, and approved on the internal forums first.
14 |
--------------------------------------------------------------------------------
/google-r-style.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 | Redirecting
7 |
8 |
14 |
15 | Redirecting you to Rguide.html.
16 |
17 |
18 |
--------------------------------------------------------------------------------
/cppguide.xml:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 | Redirecting
8 |
9 |
15 |
16 | Redirecting you to cppguide.html.
17 |
18 |
19 |
--------------------------------------------------------------------------------
/jsoncstyleguide.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 | Redirecting
8 |
9 |
15 |
16 | Redirecting you to jsoncstyleguide.xml.
17 |
18 |
19 |
--------------------------------------------------------------------------------
/google_python_style.vim:
--------------------------------------------------------------------------------
1 | " Copyright 2019 Google LLC
2 | "
3 | " Licensed under the Apache License, Version 2.0 (the "License");
4 | " you may not use this file except in compliance with the License.
5 | " You may obtain a copy of the License at
6 | "
7 | " https://www.apache.org/licenses/LICENSE-2.0
8 | "
9 | " Unless required by applicable law or agreed to in writing, software
10 | " distributed under the License is distributed on an "AS IS" BASIS,
11 | " WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 | " See the License for the specific language governing permissions and
13 | " limitations under the License.
14 |
15 | " Indent Python in the Google way.
16 |
17 | setlocal indentexpr=GetGooglePythonIndent(v:lnum)
18 |
19 | let s:maxoff = 50 " maximum number of lines to look backwards.
20 |
21 | function GetGooglePythonIndent(lnum)
22 |
23 | " Indent inside parens.
24 | " Align with the open paren unless it is at the end of the line.
25 | " E.g.
26 | " open_paren_not_at_EOL(100,
27 | " (200,
28 | " 300),
29 | " 400)
30 | " open_paren_at_EOL(
31 | " 100, 200, 300, 400)
32 | call cursor(a:lnum, 1)
33 | let [par_line, par_col] = searchpairpos('(\|{\|\[', '', ')\|}\|\]', 'bW',
34 | \ "line('.') < " . (a:lnum - s:maxoff) . " ? dummy :"
35 | \ . " synIDattr(synID(line('.'), col('.'), 1), 'name')"
36 | \ . " =~ '\\(Comment\\|String\\)$'")
37 | if par_line > 0
38 | call cursor(par_line, 1)
39 | if par_col != col("$") - 1
40 | return par_col
41 | endif
42 | endif
43 |
44 | " Delegate the rest to the original function.
45 | return GetPythonIndent(a:lnum)
46 |
47 | endfunction
48 |
49 | let pyindent_nested_paren="&sw*2"
50 | let pyindent_open_paren="&sw*2"
51 |
--------------------------------------------------------------------------------
/docguide/READMEs.md:
--------------------------------------------------------------------------------
1 | # README.md files
2 |
3 | About README.md files.
4 |
5 | 1. [Overview](#overview)
6 | 1. [Guidelines](#guidelines)
7 | 1. [Filename](#filename)
8 | 1. [Contents](#contents)
9 | 1. [Example](#example)
10 |
11 | ## Overview
12 |
13 | `README.md` files are Markdown files that describe a directory.
14 | GitHub and Gitiles renders it when you browse the directory.
15 |
16 | For example, the file /README.md is rendered when you view the contents of the
17 | containing directory:
18 |
19 | https://github.com/google/styleguide/tree/gh-pages
20 |
21 | Also `README.md` at `HEAD` ref is rendered by Gitiles when displaying repository
22 | index:
23 |
24 | https://gerrit.googlesource.com/gitiles/
25 |
26 | ## Guidelines
27 |
28 | **`README.md` files are intended to provide orientation for engineers browsing
29 | your code, especially first-time users.** The `README.md` is likely the first
30 | file a reader encounters when they browse a directory that
31 | contains your code. In this way, it acts as a landing page for the directory.
32 |
33 | We recommend that top-level directories for your code have an up-to-date
34 | `README.md` file. This is especially important for package directories that
35 | provide interfaces for other teams.
36 |
37 | ### Filename
38 |
39 | Use `README.md`.
40 |
41 | Files named `README` are not displayed in the directory view in Gitiles.
42 |
43 | ### Contents
44 |
45 | At minimum, every package-level `README.md` should include or point to the
46 | following information:
47 |
48 | 1. **What** is in this package/library and what's it used for.
49 | 2. **Who** to contact.
50 | 3. **Status**: whether this package/library is deprecated, or not for general
51 | release, etc.
52 | 4. **More info**: where to go for more detailed documentation, such as:
53 | * An overview.md file for more detailed conceptual information.
54 | * Any API documentation for using this package/library.
55 |
56 | ## Example
57 |
58 | ```markdown
59 | # APIs
60 |
61 | This is the top-level directory for all externally-visible APIs, plus some
62 | private APIs under `internal/` directories.
63 | See [API Style Guide](docs/apistyle.md) for more information.
64 |
65 | *TL;DR*: API definitions and configurations should be defined in `.proto` files,
66 | checked into `apis/`.
67 |
68 | ...
69 | ```
70 |
--------------------------------------------------------------------------------
/cpplint/README:
--------------------------------------------------------------------------------
1 | This is automated checker to make sure a C++ file follows Google's C++ style
2 | guide (https://google.github.io/styleguide/cppguide.html). As it
3 | heavily relies on regular expressions, cpplint.py won't catch all violations of
4 | the style guide and will very occasionally report a false positive. There is a
5 | list of things we currently don't handle very well at the top of cpplint.py,
6 | and we welcome patches to improve it.
7 |
8 | The linting tool takes a list of files as input. For full usage instructions,
9 | please see the output of:
10 |
11 | ./cpplint.py --help
12 |
13 | Unit tests are provided in cpplint_unittest.py. This file can safely be ignored
14 | by end users who have downloaded this package and only want to run the lint
15 | tool.
16 |
17 | ---
18 |
19 | cpplint.py and its corresponding unit tests are Copyright (C) 2009 Google Inc.
20 |
21 | Redistribution and use in source and binary forms, with or without
22 | modification, are permitted provided that the following conditions are
23 | met:
24 |
25 | * Redistributions of source code must retain the above copyright
26 | notice, this list of conditions and the following disclaimer.
27 | * Redistributions in binary form must reproduce the above
28 | copyright notice, this list of conditions and the following disclaimer
29 | in the documentation and/or other materials provided with the
30 | distribution.
31 | * Neither the name of Google Inc. nor the names of its
32 | contributors may be used to endorse or promote products derived from
33 | this software without specific prior written permission.
34 |
35 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
36 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
37 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
38 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
39 | OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41 | LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
42 | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
43 | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
44 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
45 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
46 |
--------------------------------------------------------------------------------
/include/jsguide.js:
--------------------------------------------------------------------------------
1 | window.initStyleGuide = function(init) {
2 | // Runs the callback on every element matched by the query selector.
3 | function find(querySelector, callback) {
4 | var elements = [].slice.call(document.querySelectorAll(querySelector));
5 | for (var i = 0; i < elements.length; i++) {
6 | callback(elements[i]);
7 | }
8 | }
9 | // Add the tocDiv at the top.
10 | var title = document.getElementsByTagName('h1')[0];
11 | var toc = document.createElement('div');
12 | toc.id = 'tocDiv';
13 | toc.className = 'vertical_toc';
14 | title.parentNode.insertBefore(toc, title.nextSibling);
15 |
16 | // If a paragraph starts with (e.g.) "Note:" or "Tip:" then add
17 | // that "callout class" to its element.
18 | find('p', function(paragraph) {
19 | var match = /^([a-z]+):/i.exec(paragraph.textContent);
20 | if (match) {
21 | paragraph.classList.add(match[1].toLowerCase());
22 | }
23 | });
24 |
25 | // Fill in text for intra-document links, ensuring that links
26 | // remain up-to-date even if sections are moved or renumbered.
27 | // This triggers on any link with "??" as its text and a URL
28 | // starting with "#", and the filled-in text is exactly the same
29 | // as the text of the referenced section heading.
30 | find('a[href^="#"]', function(link) {
31 | var href = link.getAttribute('href');
32 | var heading = document.getElementById(href.substring(1));
33 | // Fill in link text with heading title
34 | if (heading && link.textContent == '??') {
35 | link.textContent = heading.textContent;
36 | }
37 | });
38 |
39 | // Hoedown renders fenced code blocks incompatibly with what
40 | // prettify expects. As a result, prettify doesn't handle them
41 | // properly. Fix it by moving the code directly into the pre.
42 | find('pre > code', function(code) {
43 | var pre = code.parentElement;
44 | // Internal HTML/CSS & TS style guides do not use prettyprint.
45 | if (code.classList.contains('language-css') ||
46 | code.classList.contains('language-django') ||
47 | code.classList.contains('language-html') ||
48 | code.classList.contains('language-ts')) {
49 | code.classList.add('prettyprint');
50 | }
51 | pre.className = code.className;
52 | pre.innerHTML = code.innerHTML;
53 | });
54 |
55 | // Run the normal init function.
56 | init();
57 |
58 | // Call the pretty-printer after we've fixed up the code blocks.
59 | var pretty = document.createElement('script');
60 | pretty.src = 'https://cdn.rawgit.com/google/code-prettify/master/loader/' +
61 | 'run_prettify.js';
62 | document.body.appendChild(pretty);
63 | }.bind(null, window.initStyleGuide);
64 |
--------------------------------------------------------------------------------
/docguide/philosophy.md:
--------------------------------------------------------------------------------
1 | # Philosophy
2 |
3 | 埏埴以為器，當其無，有器之用.
4 |
5 | *Clay becomes pottery through craft, but it's the emptiness that makes a pot
6 | useful.*
7 |
8 | \- [Laozi](http://ctext.org/dictionary.pl?if=en&id=11602)
9 |
10 | Contents:
11 |
12 | 1. [Radical simplicity](#radical-simplicity)
13 | 1. [Readable source text](#readable-source-text)
14 | 1. [Minimum viable documentation](#minimum-viable-documentation)
15 | 1. [Better is better than perfect](#better-is-better-than-perfect)
16 |
17 | ## Radical simplicity
18 |
19 | * **Scalability and interoperability** are more important than a menagerie of
20 | unessential features. Scale comes from simplicity, speed, and ease.
21 | Interoperability comes from unadorned, digestible content.
22 |
23 | * **Fewer distractions** make for better writing and more productive reading.
24 |
25 | * **New features should never interfere with the simplest use case** and should
26 | remain invisible to users who don't need them.
27 |
28 | * **This guide is designed for the average engineer** -- the busy,
29 | just-want-to-go-back-to-coding engineer. Large and complex documentation is
30 | possible but not the primary focus.
31 |
32 | * **Minimizing context switching makes people happier.** Engineers should be
33 | able to interact with documentation using the same tools they use to read and
34 | write code.
35 |
36 | ## Readable source text
37 |
38 | * **Plain text not only suffices, it is superior**. Markdown itself is not
39 | essential to this formula, but it is the best and most widely supported
40 | solution right now. HTML is generally not encouraged.
41 |
42 | * **Content and presentation should not mingle**. It should always be possible
43 | to ditch the renderer and read the essential information at source. Users
44 | should never have to touch the presentation layer if they don't want to.
45 |
46 | * **Portability and future-proofing leave room for the unimagined integrations
47 | to come**, and are best achieved by keeping the source as human-readable as
48 | possible.
49 |
50 | * **Static content is better than dynamic**, because content should not depend
51 | on the features of any one server. However, **fresh is better than stale**. We
52 | strive to balance these needs.
53 |
54 | ## Minimum viable documentation
55 |
56 | * **Docs thrive when they're treated like tests**: a necessary chore one learns
57 | to savor because it rewards over time.
58 | See [Best Practices](best_practices.md).
59 |
60 | * **Brief and utilitarian is better than long and exhaustive**. The vast
61 | majority of users need only a small fraction of the author's total knowledge,
62 | but they need it quickly and often.
63 |
64 | ## Better is better than perfect
65 |
66 | * **Incremental improvement is better than prolonged debate**. Patience and
67 | tolerance of imperfection allow projects to evolve organically.
68 |
69 | * **Don't lick the cookie, pass the plate**. We're drowning in potentially
70 | impactful projects. Choose only those you can really handle and release those
71 | you can't.
72 |
--------------------------------------------------------------------------------
/styleguide.css:
--------------------------------------------------------------------------------
1 | body {
2 | background-color: #fff;
3 | color: #333;
4 | font-family: sans-serif;
5 | font-size: 10pt;
6 | margin-right: 100px;
7 | margin-left: 100px;
8 | }
9 |
10 | h1, h2, h3, h4, h5, h6, .toc_title {
11 | color: #06c;
12 | margin-top: 2em;
13 | margin-bottom: 1em;
14 | }
15 |
16 | h1 {
17 | text-align: center;
18 | font-size: 18pt;
19 | }
20 |
21 | h2, .toc_title {
22 | font-weight: bold;
23 | font-size: 12pt;
24 | margin-left: -40px;
25 | }
26 |
27 | h3, h4, h5, h6 {
28 | font-size: 10pt;
29 | margin-left: -20px;
30 | }
31 |
32 | .toc_category, .toc_stylepoint {
33 | font-size: 10pt;
34 | padding-top: .3em;
35 | padding-bottom: .3em;
36 | }
37 |
38 | table {
39 | border-collapse: collapse;
40 | }
41 |
42 | td, th {
43 | border: 1px solid #ccc;
44 | padding: 2px 12px;
45 | font-size: 10pt;
46 | }
47 |
48 | .toc td, .toc th {
49 | border-width: 1px 5px;
50 | }
51 |
52 | code, samp, var {
53 | color: #060;
54 | }
55 |
56 | pre {
57 | font-size: 10pt;
58 | display: block;
59 | color: #060;
60 | background-color: #f8fff8;
61 | border-color: #f0fff0;
62 | border-style: solid;
63 | border-top-width: 1px;
64 | border-bottom-width: 1px;
65 | border-right-width: 1px;
66 | border-left-width: 5px;
67 | padding-left: 12px;
68 | padding-right: 12px;
69 | padding-top: 4px;
70 | padding-bottom: 4px;
71 | }
72 |
73 | pre.badcode {
74 | color: #c00;
75 | background-color: #fff8f8;
76 | border-color: #fff0f0;
77 | }
78 |
79 | .showhide_button {
80 | float: left;
81 | cursor: pointer;
82 | border-width: 1px;
83 | border-style: solid;
84 | border-color: #ddd #aaa #aaa #ddd;
85 | padding: 0 3px 1px;
86 | margin: 0 4px 8px 0;
87 | border-radius: 3px;
88 | -webkit-border-radius: 3px;
89 | -moz-border-radius: 3px;
90 | }
91 |
92 | .link_button {
93 | float: left;
94 | display: none;
95 | background-color: #f8f8ff;
96 | border-color: #f0f0ff;
97 | border-style: solid;
98 | border-width: 1px;
99 | font-size: 75%;
100 | margin-top: 0;
101 | margin-left: -50px;
102 | padding: 4px;
103 | border-radius: 3px;
104 | -webkit-border-radius: 3px;
105 | -moz-border-radius: 3px;
106 | }
107 |
108 | address {
109 | text-align: right;
110 | }
111 |
112 | hr {
113 | margin-top: 3.5em;
114 | border-width: 1px;
115 | color: #fff;
116 | }
117 |
118 | .stylepoint_section {
119 | display: block;
120 | margin-bottom: 1em;
121 | color: #5588ff;
122 | font-family: sans-serif;
123 | font-size: 90%;
124 | font-weight: bold;
125 | margin-left: -2%;
126 | }
127 |
128 | .stylepoint_subsection {
129 | color: #667799;
130 | font-family: sans-serif;
131 | font-size: 90%;
132 | font-weight: bold;
133 | margin-left: -1%;
134 | }
135 |
136 | .stylepoint_subsubsection {
137 | color: #667799;
138 | font-family: sans-serif;
139 | font-size: 80%;
140 | font-weight: bold;
141 | margin-left: 0;
142 | }
143 |
144 | .revision {
145 | text-align: right;
146 | }
147 |
148 |
--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
1 | # Contributor Covenant Code of Conduct
2 |
3 | ## Our Pledge
4 |
5 | We as members, contributors, and leaders pledge to make participation in our
6 | community a harassment-free experience for everyone, regardless of age, body
7 | size, visible or invisible disability, ethnicity, sex characteristics, gender
8 | identity and expression, level of experience, education, socio-economic status,
9 | nationality, personal appearance, race, caste, color, religion, or sexual identity
10 | and orientation.
11 |
12 | We pledge to act and interact in ways that contribute to an open, welcoming,
13 | diverse, inclusive, and healthy community.
14 |
15 | ## Our Standards
16 |
17 | Examples of behavior that contributes to a positive environment for our
18 | community include:
19 |
20 | * Demonstrating empathy and kindness toward other people
21 | * Being respectful of differing opinions, viewpoints, and experiences
22 | * Giving and gracefully accepting constructive feedback
23 | * Accepting responsibility and apologizing to those affected by our mistakes,
24 | and learning from the experience
25 | * Focusing on what is best not just for us as individuals, but for the
26 | overall community
27 |
28 | Examples of unacceptable behavior include:
29 |
30 | * The use of sexualized language or imagery, and sexual attention or
31 | advances of any kind
32 | * Trolling, insulting or derogatory comments, and personal or political attacks
33 | * Public or private harassment
34 | * Publishing others' private information, such as a physical or email
35 | address, without their explicit permission
36 | * Other conduct which could reasonably be considered inappropriate in a
37 | professional setting
38 |
39 | ## Enforcement Responsibilities
40 |
41 | Repo maintainers are responsible for clarifying and enforcing our standards of
42 | acceptable behavior and will take appropriate and fair corrective action in
43 | response to any behavior that they deem inappropriate, threatening, offensive,
44 | or harmful.
45 |
46 | Repo maintainers have the right and responsibility to remove, edit, or reject
47 | comments, commits, code, wiki edits, issues, and other contributions that are
48 | not aligned to this Code of Conduct, and will communicate reasons for moderation
49 | decisions when appropriate.
50 |
51 | ## Scope
52 |
53 | This Code of Conduct applies within all community spaces, and also applies when
54 | an individual is officially representing the community in public spaces.
55 | Examples of representing our community include using an official e-mail address,
56 | posting via an official social media account, or acting as an appointed
57 | representative at an online or offline event.
58 |
59 | ## Attribution
60 |
61 | This Code of Conduct is adapted from the [Contributor Covenant][homepage],
62 | version 2.0, available at
63 | [https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0].
64 |
65 | Community Impact Guidelines were inspired by
66 | [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
67 |
68 | For answers to common questions about this code of conduct, see the FAQ at
69 | [https://www.contributor-covenant.org/faq][FAQ].
70 |
71 | [homepage]: https://www.contributor-covenant.org
72 | [v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html
73 | [Mozilla CoC]: https://github.com/mozilla/diversity
74 | [FAQ]: https://www.contributor-covenant.org/faq
75 |
--------------------------------------------------------------------------------
/Rguide.md:
--------------------------------------------------------------------------------
1 | # Google's R Style Guide
2 |
3 | R is a high-level programming language used primarily for statistical computing
4 | and graphics. The goal of the R Programming Style Guide is to make our R code
5 | easier to read, share, and verify.
6 |
7 | The Google R Style Guide is a fork of the
8 | [Tidyverse Style Guide](https://style.tidyverse.org/) by Hadley Wickham
9 | [license](https://creativecommons.org/licenses/by-sa/2.0/). Google modifications
10 | were developed in collaboration with the internal R user community. The rest of
11 | this document explains Google's primary differences with the Tidyverse guide,
12 | and why these differences exist.
13 |
14 | ## Syntax
15 |
16 | ### Naming conventions
17 |
18 | Google prefers identifying functions with `BigCamelCase` to clearly distinguish
19 | them from other objects.
20 |
21 | ```
22 | # Good
23 | DoNothing <- function() {
24 | return(invisible(NULL))
25 | }
26 | ```
27 |
28 | The names of private functions should begin with a dot. This helps communicate
29 | both the origin of the function and its intended use.
30 |
31 | ```
32 | # Good
33 | .DoNothingPrivately <- function() {
34 | return(invisible(NULL))
35 | }
36 | ```
37 |
38 | We previously recommended naming objects with `dot.case`. We're moving away from
39 | that, as it creates confusion with S3 methods.
40 |
41 | ### Don't use attach()
42 |
43 | The possibilities for creating errors when using `attach()` are numerous.
44 |
45 | ## Pipes
46 |
47 | ### Right-hand assignment
48 |
49 | We do not support using right-hand assignment.
50 |
51 | ```
52 | # Bad
53 | iris %>%
54 | dplyr::summarize(max_petal = max(Petal.Width)) -> results
55 | ```
56 |
57 | This convention differs substantially from practices in other languages and
58 | makes it harder to see in code where an object is defined. E.g. searching for
59 | `foo <-` is easier than searching for `foo <-` and `-> foo` (possibly split over
60 | lines).
61 |
62 | ### Use explicit returns
63 |
64 | Do not rely on R's implicit return feature. It is better to be clear about your
65 | intent to `return()` an object.
66 |
67 | ```
68 | # Good
69 | AddValues <- function(x, y) {
70 | return(x + y)
71 | }
72 |
73 | # Bad
74 | AddValues <- function(x, y) {
75 | x + y
76 | }
77 | ```
78 |
79 | ### Qualifying namespaces
80 |
81 | Users should explicitly qualify namespaces for all external functions.
82 |
83 | ```
84 | # Good
85 | purrr::map()
86 | ```
87 |
88 | We discourage using the `@import` Roxygen tag to bring in all functions into a
89 | NAMESPACE. Google has a very big R codebase, and importing all functions creates
90 | too much risk for name collisions.
91 |
92 | While there is a small performance penalty for using `::`, it makes it easier to
93 | understand dependencies in your code. There are some exceptions to this rule.
94 |
95 | * Infix functions (`%name%`) always need to be imported.
96 | * Certain `rlang` pronouns, notably `.data`, need to be imported.
97 | * Functions from default R packages, including `datasets`, `utils`,
98 | `grDevices`, `graphics`, `stats` and `methods`. If needed, you can `@import`
99 | the full package.
100 |
101 | When importing functions, place the `@importFrom` tag in the Roxygen header
102 | above the function where the external dependency is used.
103 |
104 | ## Documentation
105 |
106 | ### Package-level documentation
107 |
108 | All packages should have a package documentation file, in a
109 | `packagename-package.R` file.
110 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Google Style Guides
2 |
3 | Every major open-source project has its own style guide: a set of conventions
4 | (sometimes arbitrary) about how to write code for that project. It is much
5 | easier to understand a large codebase when all the code in it is in a
6 | consistent style.
7 |
8 | “Style” covers a lot of ground, from “use camelCase for variable names” to
9 | “never use global variables” to “never use exceptions.” This project
10 | ([google/styleguide](https://github.com/google/styleguide)) links to the
11 | style guidelines we use for Google code. If you are modifying a project that
12 | originated at Google, you may be pointed to this page to see the style guides
13 | that apply to that project.
14 |
15 | This project holds the [C++ Style Guide][cpp], [C# Style Guide][csharp],
16 | [Swift Style Guide][swift], [Objective-C Style Guide][objc],
17 | [Java Style Guide][java], [Python Style Guide][py], [R Style Guide][r],
18 | [Shell Style Guide][sh], [HTML/CSS Style Guide][htmlcss],
19 | [JavaScript Style Guide][js], [TypeScript Style Guide][ts], [AngularJS Style Guide][angular],
20 | [Common Lisp Style Guide][cl], and [Vimscript Style Guide][vim]. This project
21 | also contains [cpplint][cpplint], a tool to assist with style guide compliance,
22 | and [google-c-style.el][emacs], an Emacs settings file for Google style.
23 |
24 | If your project requires that you create a new XML document format, the [XML
25 | Document Format Style Guide][xml] may be helpful. In addition to actual style
26 | rules, it also contains advice on designing your own vs. adapting an existing
27 | format, on XML instance document formatting, and on elements vs. attributes.
28 |
29 | The style guides in this project are licensed under the CC-By 3.0 License,
30 | which encourages you to share these documents.
31 | See [https://creativecommons.org/licenses/by/3.0/][ccl] for more details.
32 |
33 | The following Google style guides live outside of this project:
34 | [Go Code Review Comments][go] and [Effective Dart][dart].
35 |
36 |
37 | ## Contributing
38 |
39 | With few exceptions, these style guides are copies of Google's internal style guides
40 | to assist developers working on Google owned and originated open source projects.
41 | Changes to the style guides are made to the internal style guides first and
42 | eventually copied into the versions found here. **External contributions are
43 | not accepted.**
44 | Pull requests are regularly closed without comment.
45 | Issues that raise questions, justify changes on technical merits,
46 | or point out obvious mistakes may get some engagement and could in theory lead to changes,
47 | but we are primarily optimizing for Google's internal needs.
48 |
49 |
50 |
51 | [cpp]: https://google.github.io/styleguide/cppguide.html
52 | [csharp]: https://google.github.io/styleguide/csharp-style.html
53 | [swift]: https://google.github.io/swift/
54 | [objc]: objcguide.md
55 | [java]: https://google.github.io/styleguide/javaguide.html
56 | [py]: https://google.github.io/styleguide/pyguide.html
57 | [r]: https://google.github.io/styleguide/Rguide.html
58 | [sh]: https://google.github.io/styleguide/shellguide.html
59 | [htmlcss]: https://google.github.io/styleguide/htmlcssguide.html
60 | [js]: https://google.github.io/styleguide/jsguide.html
61 | [ts]: https://google.github.io/styleguide/tsguide.html
62 | [angular]: https://google.github.io/styleguide/angularjs-google-style.html
63 | [cl]: https://google.github.io/styleguide/lispguide.xml
64 | [vim]: https://google.github.io/styleguide/vimscriptguide.xml
65 | [cpplint]: https://github.com/google/styleguide/tree/gh-pages/cpplint
66 | [emacs]: https://raw.githubusercontent.com/google/styleguide/gh-pages/google-c-style.el
67 | [xml]: https://google.github.io/styleguide/xmlstyle.html
68 | [go]: https://golang.org/wiki/CodeReviewComments
69 | [dart]: https://www.dartlang.org/guides/language/effective-dart
70 | [ccl]: https://creativecommons.org/licenses/by/3.0/
71 |
72 |
--------------------------------------------------------------------------------
/include/styleguide.css:
--------------------------------------------------------------------------------
1 | /* General CSS */
2 |
3 | body {
4 | background-color: #fff;
5 | color: #333;
6 | font-family: sans-serif;
7 | font-size: 10pt;
8 | margin-right: 100px;
9 | margin-left: 100px;
10 | }
11 |
12 | h1 {
13 | text-align: center;
14 | font-size: 18pt;
15 | }
16 |
17 | h1, h2, h3, h4, h5, h6 {
18 | color: #06c;
19 | margin-top: 2em;
20 | margin-bottom: 1em;
21 | padding: 25px;
22 | font-weight:bold;
23 | }
24 |
25 | h2,
26 | h3,
27 | h4,
28 | h5,
29 | h6 {
30 | margin-top:1.5em;
31 | margin-bottom:.75em;
32 | }
33 |
34 | h1 {font-size:200%;}
35 | h2 {font-size:167%;}
36 | h3 {font-size:133%;}
37 | h4 {font-size:120%;}
38 | h5 {font-size:110%;}
39 |
40 |
41 | table {
42 | border: 1px solid #bbb;
43 | border-spacing: 0;
44 | border-collapse: collapse;
45 | margin: 0 0 1.5em;
46 | vertical-align: middle;
47 | width: 100%
48 | }
49 |
50 | td, th {
51 | border: 1px solid #ccc;
52 | padding: 2px 12px;
53 | font-size: 10pt;
54 | }
55 |
56 | code, samp, var {
57 | background-color:#FAFAFA;
58 | white-space: nowrap
59 | }
60 |
61 | pre {
62 | padding:6px 10px;
63 | background-color:#FAFAFA;
64 | border:1px solid #bbb;
65 | overflow:auto;
66 | }
67 |
68 | pre.prettyprint {
69 | padding:6px 10px !important;
70 | border:1px solid #bbb !important;
71 | }
72 |
73 | code.bad, code.badcode {
74 | color: magenta;
75 | }
76 |
77 | pre.bad, pre.badcode {
78 | background-color:#ffe6d8;
79 | border-top:1px inset #a03;
80 | border-left:1px inset #a03;
81 | }
82 |
83 | hr {
84 | margin-top: 3.5em;
85 | border-width: 1px;
86 | color: #fff;
87 | }
88 |
89 | /* TOC CSS */
90 |
91 | table.columns {
92 | border: none;
93 | }
94 |
95 | td.two_columns {
96 | -webkit-column-count: 2;
97 | column-count: 2;
98 | }
99 |
100 | .toc_category {
101 | font-size: 10pt;
102 | padding-top: 1em;
103 | padding-bottom: 1em;
104 | border-left-width: 2px;
105 | border-right-width: 2px;
106 | border-color: grey;
107 | }
108 |
109 | .toc_stylepoint {
110 | font-size: 10pt;
111 | padding-top: 1em;
112 | padding-bottom: 1em;
113 | }
114 |
115 | li.toc_entry {
116 | padding-right: 1em;
117 | display: inline;
118 | list-style-type: none;
119 | }
120 |
121 | /*
122 | * This space is required to trigger the linewrap on the links
123 | * at href boundaries
124 | */
125 | li.toc_entry::after {
126 | content: " ";
127 | }
128 |
129 | li.toc_entry a {
130 | white-space: nowrap;
131 | }
132 |
133 | /* Horizontal TOC */
134 | .toc td, .toc th {
135 | border-width: 1px 5px;
136 | overflow: hidden;
137 | }
138 |
139 | /* Vertical TOC */
140 |
141 | .toc td.two_columns {
142 | border-width: 0px;
143 | }
144 |
145 | /* Special Sections */
146 |
147 | address {
148 | text-align: right;
149 | }
150 |
151 | .revision {
152 | text-align: right;
153 | }
154 |
155 | .headerbox {
156 | margin-left: 50%;
157 | font-size: 75%;
158 | }
159 |
160 | .legend {
161 | padding-top: 1em;
162 | margin-left: 50%;
163 | font-size: 10pt;
164 | }
165 |
166 | .link_button {
167 | float: left;
168 | display: none;
169 | background-color: #f8f8ff;
170 | border-color: #f0f0ff;
171 | border-style: solid;
172 | border-width: 1px;
173 | font-size: 75%;
174 | margin-top: 0;
175 | margin-left: -50px;
176 | padding: 24px;
177 | border-radius: 3px;
178 | -webkit-border-radius: 3px;
179 | -moz-border-radius: 3px;
180 | }
181 |
182 | .ignoreLink {
183 | padding: 0px;
184 | }
185 |
186 | .divider{
187 | width:5px;
188 | height:auto;
189 | display:inline-block;
190 | }
191 |
192 | /* Style Guide semantic CSS */
193 |
194 | .summary {
195 | margin-top: 1em;
196 | margin-bottom: 1em;
197 | }
198 |
199 | .stylebody {
200 | margin-top: 1em;
201 | margin-bottom: 1em;
202 | }
203 |
204 | .stylepoint_section {
205 | display: block;
206 | margin-bottom: 1em;
207 | font-family: sans-serif;
208 | font-weight: bold;
209 | }
210 |
211 | .stylepoint_subsection {
212 | display: block;
213 | margin-bottom: 1em;
214 | }
215 |
216 | .stylepoint_subsubsection {
217 | display: block;
218 | margin-bottom: 1em;
219 | }
220 |
221 | .definition:before {
222 | content: "Definition: ";
223 | font-weight: bold;
224 | display: block;
225 | margin-bottom: 1em;
226 | }
227 |
228 | .pros:before {
229 | content: "Pros: ";
230 | font-weight: bold;
231 | display: block;
232 | margin-bottom: 1em;
233 | }
234 |
235 | .cons:before {
236 | content: "Cons: ";
237 | font-weight: bold;
238 | display: block;
239 | margin-bottom: 1em;
240 | }
241 |
242 | .decision:before {
243 | content: "Decision: ";
244 | font-weight: bold;
245 | display: block;
246 | margin-bottom: 1em;
247 | }
248 |
249 | .exception:before {
250 | content: "Exception: ";
251 | font-weight: bold;
252 | display: block;
253 | margin-bottom: 1em;
254 | }
255 |
256 | .note:before {
257 | content: "Note: ";
258 | font-weight: bold;
259 | display: block;
260 | margin-bottom: 1em;
261 | }
262 |
--------------------------------------------------------------------------------
/docguide/best_practices.md:
--------------------------------------------------------------------------------
1 | # Documentation Best Practices
2 |
3 | "Say what you mean, simply and directly." - [Brian Kernighan]
4 | (https://en.wikipedia.org/wiki/The_Elements_of_Programming_Style)
5 |
6 | Contents:
7 |
8 | 1. [Minimum viable documentation](#minimum-viable-documentation)
9 | 1. [Update docs with code](#update-docs-with-code)
10 | 1. [Delete dead documentation](#delete-dead-documentation)
11 | 1. [Documentation is the story of your code](#documentation-is-the-story-of-your-code)
12 |
13 | ## Minimum viable documentation
14 |
15 | A small set of fresh and accurate docs are better than a sprawling, loose
16 | assembly of "documentation" in various states of disrepair.
17 |
18 | Write short and useful documents. Cut out everything unnecessary, while also
19 | making a habit of continually massaging and improving every doc to suit your
20 | changing needs. **Docs work best when they are alive but frequently trimmed,
21 | like a bonsai tree**.
22 |
23 | This guide encourages engineers to take ownership of their docs and keep
24 | them up to date with the same zeal we keep our tests in good order. Strive for
25 | this.
26 |
27 | * Identify what you really need: release docs, API docs, testing guidelines.
28 | * Delete cruft frequently and in small batches.
29 |
30 | ## Update docs with code
31 |
32 | **Change your documentation in the same CL as the code change**. This keeps your
33 | docs fresh, and is also a good place to explain to your reviewer what you're
34 | doing.
35 |
36 | A good reviewer can at least insist that docstrings, header files, README.md
37 | files, and any other docs get updated alongside the CL.
38 |
39 | ## Delete dead documentation
40 |
41 | Dead docs are bad. They misinform, they slow down, they incite despair in
42 | engineers and laziness in team leads. They set a precedent for leaving behind
43 | messes in a code base. If your home is clean, most guests will be clean without
44 | being asked.
45 |
46 | Just like any big cleaning project, **it's easy to be overwhelmed**. If your
47 | docs are in bad shape:
48 |
49 | * Take it slow, doc health is a gradual accumulation.
50 | * First delete what you're certain is wrong, ignore what's unclear.
51 | * Get your whole team involved. Devote time to quickly scan every doc and make
52 | a simple decision: Keep or delete?
53 | * Default to delete or leave behind if migrating. Stragglers can always be
54 | recovered.
55 | * Iterate.
56 |
57 | ## Prefer the good over the perfect
58 |
59 | Your documentation should be as good as possible within a reasonable time frame.
60 | The standards for a documentation review are different from the
61 | standards for code reviews. Reviewers can and should ask for improvements, but
62 | in general, the author should always be able to invoke the "Good Over Perfect
63 | Rule". It's preferable to allow authors to quickly submit changes that improve
64 | the document, instead of forcing rounds of review until it's "perfect". Docs are
65 | never perfect, and tend to gradually improve as the team learns what they really
66 | need to write down.
67 |
68 | ## Documentation is the story of your code
69 |
70 | Writing excellent code doesn't end when your code compiles or even if your
71 | test coverage reaches 100%. It's easy to write something a computer understands,
72 | it's much harder to write something both a human and a computer understand. Your
73 | mission as a Code Health-conscious engineer is to **write for humans first,
74 | computers second.** Documentation is an important part of this skill.
75 |
76 | There's a spectrum of engineering documentation that ranges from terse comments
77 | to detailed prose:
78 |
79 | 1. **Inline comments**: The primary purpose of inline comments is to provide
80 | information that the code itself cannot contain, such as why the code is
81 | there.
82 |
83 | 2. **Method and class comments**:
84 |
85 | * **Method API documentation**: The header / Javadoc / docstring
86 | comments that say what methods do and how to use them. This
87 | documentation is **the contract of how your code must behave**. The
88 | intended audience is future programmers who will use and modify your
89 | code.
90 |
91 | It is often reasonable to say that any behavior documented here should
92 | have a test verifying it. This documentation details what arguments the
93 | method takes, what it returns, any "gotchas" or restrictions, and what
94 | exceptions it can throw or errors it can return. It does not usually
95 | explain why code behaves a particular way unless that's relevant to a
96 | developer's understanding of how to use the method. "Why" explanations
97 | are for inline comments. Think in practical terms when writing method
98 | documentation: "This is a hammer. You use it to pound nails."
99 |
100 | * **Class / Module API documentation**: The header / Javadoc / docstring
101 | comments for a class or a whole file. This documentation gives a brief
102 | overview of what the class / file does and often gives a few short
103 | examples of how you might use the class / file.
104 |
105 | Examples are particularly relevant when there's several distinct ways to
106 | use the class (some advanced, some simple). Always list the simplest
107 | use case first.
108 |
109 | 3. **README.md**: A good README.md orients the new user to the directory and
110 | points to more detailed explanation and user guides:
111 | * What is this directory intended to hold?
112 | * Which files should the developer look at first? Are some files an API?
113 | * Who maintains this directory and where I can learn more?
114 |
115 | See the [README.md guidelines](READMEs.md).
116 |
--------------------------------------------------------------------------------
/google-c-style.el:
--------------------------------------------------------------------------------
1 | ;;; google-c-style.el --- Google's C/C++ style for c-mode
2 |
3 | ;; Keywords: c, tools
4 |
5 | ;; google-c-style.el is Copyright (C) 2008 Google Inc. All Rights Reserved.
6 | ;;
7 | ;; It is free software; you can redistribute it and/or modify it under the
8 | ;; terms of either:
9 | ;;
10 | ;; a) the GNU General Public License as published by the Free Software
11 | ;; Foundation; either version 1, or (at your option) any later version, or
12 | ;;
13 | ;; b) the "Artistic License".
14 |
15 | ;;; Commentary:
16 |
17 | ;; Provides the google C/C++ coding style. You may wish to add
18 | ;; `google-set-c-style' to your `c-mode-common-hook' after requiring this
19 | ;; file. For example:
20 | ;;
21 | ;; (add-hook 'c-mode-common-hook 'google-set-c-style)
22 | ;;
23 | ;; If you want the RETURN key to go to the next line and space over
24 | ;; to the right place, add this to your .emacs right after the load-file:
25 | ;;
26 | ;; (add-hook 'c-mode-common-hook 'google-make-newline-indent)
27 |
28 | ;;; Code:
29 |
30 | ;; For some reason 1) c-backward-syntactic-ws is a macro and 2) under Emacs 22
31 | ;; bytecode cannot call (unexpanded) macros at run time:
32 | (eval-when-compile (require 'cc-defs))
33 |
34 | ;; Wrapper function needed for Emacs 21 and XEmacs (Emacs 22 offers the more
35 | ;; elegant solution of composing a list of lineup functions or quantities with
36 | ;; operators such as "add")
37 | (defun google-c-lineup-expression-plus-4 (langelem)
38 | "Indents to the beginning of the current C expression plus 4 spaces.
39 |
40 | This implements title \"Function Declarations and Definitions\"
41 | of the Google C++ Style Guide for the case where the previous
42 | line ends with an open parenthesis.
43 |
44 | \"Current C expression\", as per the Google Style Guide and as
45 | clarified by subsequent discussions, means the whole expression
46 | regardless of the number of nested parentheses, but excluding
47 | non-expression material such as \"if(\" and \"for(\" control
48 | structures.
49 |
50 | Suitable for inclusion in `c-offsets-alist'."
51 | (save-excursion
52 | (back-to-indentation)
53 | ;; Go to beginning of *previous* line:
54 | (c-backward-syntactic-ws)
55 | (back-to-indentation)
56 | (cond
57 | ;; We are making a reasonable assumption that if there is a control
58 | ;; structure to indent past, it has to be at the beginning of the line.
59 | ((looking-at "\\(\\(if\\|for\\|while\\)\\s *(\\)")
60 | (goto-char (match-end 1)))
61 | ;; For constructor initializer lists, the reference point for line-up is
62 | ;; the token after the initial colon.
63 | ((looking-at ":\\s *")
64 | (goto-char (match-end 0))))
65 | (vector (+ 4 (current-column)))))
66 |
67 | ;;;###autoload
68 | (defconst google-c-style
69 | `((c-recognize-knr-p . nil)
70 | (c-enable-xemacs-performance-kludge-p . t) ; speed up indentation in XEmacs
71 | (c-basic-offset . 2)
72 | (indent-tabs-mode . nil)
73 | (c-comment-only-line-offset . 0)
74 | (c-hanging-braces-alist . ((defun-open after)
75 | (defun-close before after)
76 | (class-open after)
77 | (class-close before after)
78 | (inexpr-class-open after)
79 | (inexpr-class-close before)
80 | (namespace-open after)
81 | (inline-open after)
82 | (inline-close before after)
83 | (block-open after)
84 | (block-close . c-snug-do-while)
85 | (extern-lang-open after)
86 | (extern-lang-close after)
87 | (statement-case-open after)
88 | (substatement-open after)))
89 | (c-hanging-colons-alist . ((case-label)
90 | (label after)
91 | (access-label after)
92 | (member-init-intro before)
93 | (inher-intro)))
94 | (c-hanging-semi&comma-criteria
95 | . (c-semi&comma-no-newlines-for-oneline-inliners
96 | c-semi&comma-inside-parenlist
97 | c-semi&comma-no-newlines-before-nonblanks))
98 | (c-indent-comments-syntactically-p . t)
99 | (comment-column . 40)
100 | (c-indent-comment-alist . ((other . (space . 2))))
101 | (c-cleanup-list . (brace-else-brace
102 | brace-elseif-brace
103 | brace-catch-brace
104 | empty-defun-braces
105 | defun-close-semi
106 | list-close-comma
107 | scope-operator))
108 | (c-offsets-alist . ((arglist-intro google-c-lineup-expression-plus-4)
109 | (func-decl-cont . ++)
110 | (member-init-intro . ++)
111 | (inher-intro . ++)
112 | (comment-intro . 0)
113 | (arglist-close . c-lineup-arglist)
114 | (topmost-intro . 0)
115 | (block-open . 0)
116 | (inline-open . 0)
117 | (substatement-open . 0)
118 | (statement-cont
119 | .
120 | (,(when (fboundp 'c-no-indent-after-java-annotations)
121 | 'c-no-indent-after-java-annotations)
122 | ,(when (fboundp 'c-lineup-assignments)
123 | 'c-lineup-assignments)
124 | ++))
125 | (label . /)
126 | (case-label . +)
127 | (statement-case-open . +)
128 | (statement-case-intro . +) ; case w/o {
129 | (access-label . /)
130 | (innamespace . 0))))
131 | "Google C/C++ Programming Style.")
132 |
133 | ;;;###autoload
134 | (defun google-set-c-style ()
135 | "Set the current buffer's c-style to Google C/C++ Programming
136 | Style. Meant to be added to `c-mode-common-hook'."
137 | (interactive)
138 | (make-local-variable 'c-tab-always-indent)
139 | (setq c-tab-always-indent t)
140 | (c-add-style "Google" google-c-style t))
141 |
142 | ;;;###autoload
143 | (defun google-make-newline-indent ()
144 | "Sets up preferred newline behavior. Not set by default. Meant
145 | to be added to `c-mode-common-hook'."
146 | (interactive)
147 | (define-key c-mode-base-map "\C-m" 'newline-and-indent)
148 | (define-key c-mode-base-map [ret] 'newline-and-indent))
149 |
150 | (provide 'google-c-style)
151 | ;;; google-c-style.el ends here
152 |
--------------------------------------------------------------------------------
/shell.xsl:
--------------------------------------------------------------------------------
1 |
8 |
9 |
10 |
11 |
12 |
13 |
14 |
15 |
16 |
17 |
18 |
19 |
20 |
21 |
22 |
23 |
24 | <xsl:value-of select="@title"/>
25 |
26 |
27 |
28 |
30 |
32 |
33 |
160 |
161 |
162 |
163 |
164 |
165 |
166 |
167 |
168 |
170 |
171 |
172 |
173 |
174 |
175 |
176 |
177 |
178 |
179 |
--------------------------------------------------------------------------------
/include/styleguide.js:
--------------------------------------------------------------------------------
1 | TocTypeEnum = {
2 | VERTICAL: 1,
3 | HORIZONTAL: 2
4 | };
5 |
6 | function CreateTOC(tocElement) {
7 |
8 | // Find the toc element DIV. We'll place our TOC there.
9 | var toc = document.getElementById(tocElement);
10 |
11 | var tocTypeClass = toc.className;
12 | var tocType;
13 |
14 | switch (tocTypeClass) {
15 | case 'horizontal_toc':
16 | tocType = TocTypeEnum.HORIZONTAL;
17 | break;
18 | case 'vertical_toc':
19 | tocType = TocTypeEnum.VERTICAL;
20 | break;
21 | default:
22 | tocType = TocTypeEnum.VERTICAL;
23 | break;
24 | }
25 |
26 | // If toc_levels is defined, set headingLevels to it.
27 | // Otherwise, use default value of "h2,h3"
28 | var headingLevels;
29 | if (typeof toc_levels === 'undefined') {
30 | headingLevels = 'h2,h3';
31 | } else {
32 |
33 | }
34 |
35 | // Collect all section heading elements in an array
36 | var headings = document.querySelectorAll(headingLevels);
37 |
38 | // Add TOC title elements
39 | var tocHeadingDiv = document.createElement('div');
40 | toc.appendChild(tocHeadingDiv);
41 | tocHeadingDiv.className = 'toc_title';
42 | var tocHeading = document.createElement('h3');
43 | toc.appendChild(tocHeading);
44 | tocHeading.className = 'ignoreLink';
45 | tocHeading.id = 'toc';
46 | var tocText = document.createTextNode('Table of Contents');
47 | tocHeading.appendChild(tocText);
48 |
49 | // Add table and tbody
50 | var tocTable = document.createElement('table');
51 | if (tocType == TocTypeEnum.VERTICAL) {
52 | tocTable.className = 'columns';
53 | }
54 | toc.appendChild(tocTable);
55 |
56 | var tbody_element = document.createElement('tbody');
57 | tbody_element.setAttribute('valign', 'top');
58 | tbody_element.className = 'toc';
59 | tocTable.appendChild(tbody_element);
60 |
61 | // Get the highest level heading
62 | var firstHeading = headings[0];
63 | var masterLevel = parseInt(headingLevels.charAt(1));
64 |
65 | // Get the lowest heading level
66 | var lowestLevel = parseInt(headingLevels.charAt(headingLevels - 1));
67 |
68 | switch (tocType) {
69 | case TocTypeEnum.HORIZONTAL:
70 | CreateHorizontalTOC(headings, masterLevel, lowestLevel, tbody_element);
71 | break;
72 | case TocTypeEnum.VERTICAL:
73 | CreateVerticalTOC(headings, masterLevel, lowestLevel, tbody_element);
74 | break;
75 | default:
76 | }
77 | }
78 |
79 | function CreateHorizontalTOC(
80 | headings, masterLevel, lowestLevel, tbody_element) {
81 |
82 | // Initialize the header counter
83 | var h = 0;
84 | var ignoreChildren = false;
85 |
86 | while (h < headings.length) {
87 | // Get current heading
88 | var heading = headings[h];
89 |
90 | // Get the current heading level
91 | var level = parseInt(heading.tagName.charAt(1));
92 |
93 | if (isNaN(level) || level < 1 || level > lowestLevel) continue;
94 |
95 | // If level is a masterLevel, make it a TOC parent category
96 | if ((level == masterLevel) && (!hasClass(heading, 'ignoreLink'))) {
97 | toc_current_row = AddTOCMaster(tbody_element, heading);
98 | ignoreChildren = false;
99 | }
100 |
101 | if ((level == masterLevel) && (hasClass(heading, 'ignoreLink'))) {
102 | ignoreChildren = true;
103 | }
104 |
105 | if ((level != masterLevel) && (!ignoreChildren)) {
106 | AddTOCElements(toc_current_row, heading);
107 | }
108 |
109 | // Advance the header counter
110 | h++;
111 | }
112 | }
113 |
114 | // Adds a master Table of Content heading
115 | function AddTOCMaster(tocTable, heading) {
116 |
117 | // Add the table row scaffolding
118 | var toc_tr = document.createElement('tr');
119 | tocTable.appendChild(toc_tr);
120 | toc_tr.setAttribute('valign', 'top');
121 | var toc_tr_td = document.createElement('td');
122 | toc_tr.appendChild(toc_tr_td);
123 | var toc_category = document.createElement('div');
124 | toc_tr_td.appendChild(toc_category);
125 | toc_category.className = 'toc_category';
126 |
127 | // Create the link to this header
128 | var link = document.createElement('a');
129 | link.href = '#' + heading.id; // Create the anchor link
130 | link.textContent = heading.textContent; // Link text is same as heading
131 | toc_category.appendChild(link);
132 |
133 | // Add the container table cell for its children
134 | var toc_td = document.createElement('td');
135 | toc_tr.appendChild(toc_td);
136 | var toc_td_div = document.createElement('div');
137 | toc_td_div.className = 'toc_stylepoint';
138 | toc_td.appendChild(toc_td_div);
139 |
140 | return (toc_td_div);
141 | }
142 |
143 | // Adds Table of Contents element to a master heading as children
144 | function AddTOCElements(toc_div, heading) {
145 |
146 | if (heading.offsetParent === null) {
147 | // The element is currently hidden, so don't create a TOC entry
148 | } else {
149 | // Create the list item element
150 | var toc_list_element = document.createElement('li');
151 | toc_list_element.className = 'toc_entry';
152 | toc_div.appendChild(toc_list_element);
153 |
154 | // Create the link to this header
155 | var link = document.createElement('a');
156 | link.href = '#' + heading.id; // Create the anchor link
157 | link.textContent = heading.textContent; // Link text is same as heading
158 | toc_list_element.appendChild(link);
159 | }
160 | }
161 |
162 | function CreateVerticalTOC(headings, masterLevel, lowestLevel, tbody_element) {
163 |
164 | // Create the Column scaffolding
165 | var toc_tr = document.createElement('tr');
166 | tbody_element.appendChild(toc_tr);
167 | var toc_tr_td = document.createElement('td');
168 | toc_tr_td.className = 'two_columns';
169 | toc_tr.appendChild(toc_tr_td);
170 |
171 |
172 | // Initialize the header counter and the current row
173 | var h = 0;
174 | var toc_current_col = null;
175 | var ignoreChildren = false;
176 |
177 | while (h < headings.length) {
178 | // Get current heading
179 | var heading = headings[h];
180 |
181 | // Get the current heading level
182 | var level = parseInt(heading.tagName.charAt(1));
183 |
184 | if (isNaN(level) || level < 1 || level > lowestLevel) continue;
185 |
186 | // If level is a masterLevel, make it a TOC parent category
187 | if ((level == masterLevel) && (!hasClass(heading, 'ignoreLink'))) {
188 | if (heading.offsetParent === null) {
189 | // The element is currently hidden, so don't create a TOC entry
190 | } else {
191 | var td_dl = document.createElement('dl');
192 | toc_tr_td.appendChild(td_dl);
193 | var td_dt = document.createElement('dt');
194 | td_dl.appendChild(td_dt);
195 | toc_current_col = td_dl;
196 |
197 | // Create the link to this header
198 | var link = document.createElement('a');
199 | link.href = '#' + heading.id; // Create the anchor link
200 | link.textContent = heading.textContent; // Link text is same as heading
201 | td_dt.appendChild(link);
202 | ignoreChildren = false;
203 | }
204 | }
205 |
206 | // If level is a masterLevel but it's specified to ignore links, skip it
207 | // and its children.
208 | if ((level == masterLevel) && (hasClass(heading, 'ignoreLink'))) {
209 | ignoreChildren = true;
210 | }
211 |
212 | if ((level != masterLevel) && (!ignoreChildren)) {
213 | if (heading.offsetParent === null) {
214 | // The element is currently hidden, so don't create a TOC entry
215 | } else {
216 | var td_dd = document.createElement('dd');
217 | toc_current_col.appendChild(td_dd);
218 | // Create the link to this header
219 | var link = document.createElement('a');
220 | link.href = '#' + heading.id; // Create the anchor link
221 | link.textContent = heading.textContent; // Link text is same as heading
222 | td_dd.appendChild(link);
223 | }
224 | }
225 |
226 | // Advance the header counter
227 | h++;
228 | }
229 | }
230 |
231 | /*
232 | * Utility function for finding elements with a given
233 | * class.
234 | */
235 | function hasClass(element, cls) {
236 | return (' ' + element.className + ' ').indexOf(' ' + cls + ' ') > -1;
237 | }
238 |
239 | /*
240 | * Linkify all h2 through h4 headers, except for those marked
241 | * "ignoreLink"
242 | */
243 |
244 | // Add the link image to the element.
245 | function LinkifyHeader(header, fileName, sizePixels) {
246 | var link = document.createElement('a');
247 | link.href = '#' + header.id;
248 | link.setAttribute('alt', 'link to ' + header.id);
249 | link.innerHTML =
250 | '';
254 | header.appendChild(link);
255 | }
256 |
257 | // Find all elements of the given tag and linkify if
258 | // they don't have 'ignoreLink' in their class.
259 | function LinkifyHeadersForTag(tagName) {
260 | var headers = document.getElementsByTagName(tagName);
261 | var header;
262 | for (var j = 0; j != headers.length; j++) {
263 | header = headers[j];
264 | if (!hasClass(header, 'ignoreLink') && ('id' in header)) {
265 | if (header.id != '') {
266 | LinkifyHeader(header, 'link.png', 21);
267 | header.style.left = '-46px';
268 | header.style.position = 'relative';
269 | }
270 | }
271 | }
272 | }
273 |
274 | // Linkify all h2, h3, and h4s. h1s are titles.
275 | function LinkifyHeaders() {
276 | LinkifyHeadersForTag('h2');
277 | LinkifyHeadersForTag('h3');
278 | LinkifyHeadersForTag('h4');
279 | }
280 |
281 | /*
282 | * Initialize the style guide by showing all internal
283 | * elements and then linkifying the headers.
284 | */
285 |
286 | function initStyleGuide() {
287 | LinkifyHeaders();
288 | CreateTOC('tocDiv');
289 | }
290 |
--------------------------------------------------------------------------------
/javaguide.css:
--------------------------------------------------------------------------------
1 | table {
2 | border-collapse: collapse;
3 | }
4 |
5 | td, th {
6 | border: 1px solid #ccc;
7 | padding: 2px 12px;
8 | font-size: 10pt;
9 | }
10 |
11 | code, samp, var {
12 | color: #060;
13 | }
14 |
15 | pre {
16 | font-size: 10pt;
17 | display: block;
18 | color: #060;
19 | background-color: #e8fff6;
20 | border-color: #f0fff0;
21 | border-style: solid;
22 | border-top-width: 1px;
23 | border-bottom-width: 1px;
24 | border-right-width: 1px;
25 | border-left-width: 5px;
26 | padding-left: 12px;
27 | padding-right: 12px;
28 | padding-top: 4px;
29 | padding-bottom: 4px;
30 | }
31 |
32 | pre.badcode {
33 | color: #c00;
34 | background-color: #ffe6d8;
35 | border-color: #fff0f0;
36 | }
37 |
38 | hr {
39 | margin-top: 3.5em;
40 | border-width: 1px;
41 | color: #fff;
42 | }
43 |
44 | html {
45 | margin-top:2em;
46 | margin-left:10%;
47 | margin-right:10%;
48 | padding:0;
49 | }
50 |
51 | .bp-reset-element,
52 | body,
53 | h1,
54 | h2,
55 | h3,
56 | h4,
57 | h5,
58 | h6,
59 | article,
60 | aside,
61 | details,
62 | figcaption,
63 | figure,
64 | footer,
65 | header,
66 | hgroup,
67 | menu,
68 | nav,
69 | section,
70 | summary,
71 | blockquote,
72 | q,
73 | th,
74 | td,
75 | caption,
76 | table,
77 | div,
78 | span,
79 | object,
80 | iframe,
81 | p,
82 | pre,
83 | a,
84 | abbr,
85 | acronym,
86 | address,
87 | code,
88 | del,
89 | dfn,
90 | em,
91 | img,
92 | dl,
93 | dt,
94 | dd,
95 | ol,
96 | ul,
97 | li,
98 | fieldset,
99 | form,
100 | label,
101 | legend,
102 | caption,
103 | tbody,
104 | tfoot,
105 | thead,
106 | tr {
107 | margin:0;
108 | padding:0;
109 | border:0;
110 | font-weight:inherit;
111 | font-style:inherit;
112 | font-size:100%;
113 | font-family:inherit;
114 | vertical-align:baseline;
115 | }
116 |
117 | body {
118 | font-family:'Arial', sans-serif;
119 | font-size:81.25%;
120 | color:#222;
121 | background-color:#fff;
122 | line-height:1.67;
123 | overflow: auto;
124 | }
125 |
126 | .change {
127 | text-align: right;
128 | margin-bottom:1em;
129 | }
130 |
131 | em {
132 | font-style: italic
133 | }
134 |
135 | h1,
136 | h2,
137 | h3,
138 | h4,
139 | h5,
140 | h6 {
141 | font-weight:bold;
142 | }
143 |
144 | h1 {
145 | margin-bottom:.50em;
146 | text-align: center
147 | }
148 |
149 | h2,
150 | h3,
151 | h4,
152 | h5,
153 | h6 {
154 | margin-top:1.5em;
155 | margin-bottom:.75em;
156 | }
157 |
158 | h1 {font-size:200%;}
159 | h2 {font-size:167%;}
160 | h3 {font-size:133%;}
161 | h4 {font-size:120%;}
162 | h5 {font-size:110%;}
163 |
164 | p {
165 | margin:0 0 1.5em;
166 | }
167 |
168 | a[href=''] {
169 | cursor:default;
170 | }
171 |
172 | h1 img,
173 | h2 img,
174 | h3 img,
175 | h4 img,
176 | h5 img,
177 | h6 img {
178 | margin:0;
179 | }
180 |
181 | a img {
182 | border:none;
183 | }
184 |
185 | pre {
186 | margin:1.5em 0;
187 | white-space:pre;
188 | }
189 |
190 | pre,
191 | code,
192 | kbd,
193 | tt {
194 | font:1em 'Droid Sans Mono', monospace;
195 | line-height:1.5;
196 | }
197 |
198 | dl {
199 | margin:0 0 1.5em 0;
200 | }
201 |
202 | dl dt {
203 | font-weight:bold;
204 | }
205 |
206 | dd {
207 | margin-left:1.5em;
208 | }
209 |
210 | dd.toc3 {
211 | margin-left:3em;
212 | }
213 |
214 | hr {
215 | height:0;
216 | border:0;
217 | border-top:1px solid #ccc;
218 | background-color:#ccc;
219 | }
220 |
221 | table {
222 | border:1px solid #bbb;
223 | border-spacing:0;
224 | border-collapse:collapse;
225 | margin:0 0 1.5em;
226 | vertical-align:middle;
227 | width:100%;
228 | }
229 |
230 | table.unlined,
231 | table.unlined th,
232 | table.unlined tr,
233 | table.unlined td {
234 | border:0;
235 | }
236 |
237 | th,
238 | td,
239 | caption {
240 | float:none !important;
241 | text-align:left;
242 | font-weight:normal;
243 | vertical-align:middle;
244 | padding:4px;
245 | }
246 |
247 | caption {
248 | padding:0;
249 | }
250 |
251 | td {
252 | border:1px solid #bbb;
253 | vertical-align:top;
254 | }
255 |
256 | th {
257 | border:0;
258 | border-bottom:1px solid black;
259 | font-weight:bold;
260 | background:rgb(229, 236, 249);
261 | }
262 |
263 | table th code {
264 | background-color:inherit;
265 | color:inherit;
266 | }
267 |
268 | table tfoot th {
269 | border:1px solid #bbb;
270 | }
271 |
272 | tfoot {
273 | font-style:italic;
274 | }
275 |
276 | caption {
277 | background:#eee;
278 | }
279 |
280 | table[border='0'] {
281 | border:none;
282 | }
283 |
284 | table[border='0']>tbody>tr>td,
285 | table[border='0']>tr>td {
286 | border:none;
287 | }
288 |
289 | tr.alt td,
290 | td.alt {
291 | background-color:#efefef;
292 | }
293 |
294 | table.striped tr:nth-child(even) td,
295 | table tr.even td {
296 | background:#efefef;
297 | }
298 |
299 | table.columns {
300 | border:none;
301 | }
302 |
303 | table.columns>tbody>tr>td,
304 | table.columns>tr>td {
305 | border:none;
306 | padding:0 3em 0 0;
307 | }
308 |
309 | table.columns>tbody>tr>td:last-child,
310 | table.columns>tr>td:last-child {
311 | border:none;
312 | padding:0;
313 | }
314 |
315 | ul,
316 | ol {
317 | margin:0 1.5em 1.5em 0;
318 | padding-left:2em;
319 | }
320 |
321 | li ul,
322 | li ol {
323 | margin:0;
324 | }
325 |
326 | ul {
327 | list-style-type:disc;
328 | }
329 |
330 | ol {
331 | list-style-type:decimal;
332 | }
333 |
334 | ul {
335 | list-style-type:disc;
336 | }
337 |
338 | ul ul {
339 | list-style-type:circle;
340 | }
341 |
342 | ul ul ul {
343 | list-style-type:square;
344 | }
345 |
346 | ul.disc {
347 | list-style-type:disc;
348 | }
349 |
350 | ul.circle {
351 | list-style-type:circle;
352 | }
353 |
354 | ul.square {
355 | list-style-type:square;
356 | }
357 |
358 | ol {
359 | list-style-type:decimal;
360 | }
361 |
362 | ol ol {
363 | list-style-type:lower-alpha;
364 | }
365 |
366 | ol ol ol {
367 | list-style-type:lower-roman;
368 | }
369 |
370 | ol ul {
371 | list-style-type:circle;
372 | }
373 |
374 | ol.decimal {
375 | list-style-type:decimal;
376 | }
377 |
378 | ol.upper-alpha {
379 | list-style-type:upper-alpha;
380 | }
381 |
382 | ol.lower-alpha {
383 | list-style-type:lower-alpha;
384 | }
385 |
386 | ol.upper-roman {
387 | list-style-type:upper-roman;
388 | }
389 |
390 | ol.lower-roman {
391 | list-style-type:lower-roman;
392 | }
393 |
394 | ol.nolist,
395 | ul.nolist {
396 | padding-left:0;
397 | list-style-image:none;
398 | list-style-type:none;
399 | margin-left:0;
400 | }
401 |
402 | .center {
403 | text-align:center;
404 | }
405 |
406 | code,
407 | kbd,
408 | pre {
409 | color:#009900;
410 | }
411 |
412 | kbd {
413 | font-weight: bold;
414 | }
415 |
416 | table.striped code {
417 | background-color:inherit;
418 | }
419 |
420 | pre {
421 | padding:6px 10px;
422 | background-color:#FAFAFA;
423 | border:1px solid #bbb;
424 | overflow:auto;
425 | }
426 |
427 | pre.prettyprint {
428 | padding:6px 10px !important;
429 | border:1px solid #bbb !important;
430 | }
431 |
432 | code.bad, code.badcode {
433 | color: magenta;
434 | }
435 | pre.bad, pre.badcode {
436 | background-color:#ffe6d8;
437 | border-top:1px inset #a03;
438 | border-left:1px inset #a03;
439 | }
440 |
441 | .tip {
442 | background-color:#fffbd9;
443 | padding:6px 8px 6px 10px;
444 | border-left:6px solid #ffef70;
445 | }
446 |
447 | .note {
448 | background-color:#e5ecf9;
449 | padding:6px 8px 6px 10px;
450 | border-left:6px solid #36c;
451 | }
452 |
453 | @media print {
454 |
455 | .str {
456 | color:#060;
457 | }
458 |
459 | .kwd {
460 | color:#006;
461 | font-weight:bold;
462 | }
463 |
464 | .com {
465 | color:#600;
466 | font-style:italic;
467 | }
468 |
469 | .typ {
470 | color:#404;
471 | font-weight:bold;
472 | }
473 |
474 | .lit {
475 | color:#044;
476 | }
477 |
478 | .pun,
479 | .opn,
480 | .clo {
481 | color:#440;
482 | }
483 |
484 | .pln {
485 | color:#000;
486 | }
487 |
488 | .tag {
489 | color:#006;
490 | font-weight:bold;
491 | }
492 |
493 | .atn {
494 | color:#404;
495 | }
496 |
497 | .atv {
498 | color:#060;
499 | }
500 |
501 | h1 {
502 | font-style:italic;
503 | }
504 | }
505 |
506 | ol.linenums {
507 | margin-top:0;
508 | margin-bottom:0;
509 | }
510 |
511 | code {
512 | background-color:#FAFAFA;
513 | padding: 0.25em 0.5em;
514 | white-space: nowrap
515 | }
516 |
517 |
518 | /* TOC CSS */
519 |
520 | table.columns {
521 | border: none;
522 | }
523 |
524 | td.two_columns {
525 | -webkit-column-count: 2;
526 | column-count: 2;
527 | }
528 |
529 | .toc_category {
530 | font-size: 10pt;
531 | padding-top: 1em;
532 | padding-bottom: 1em;
533 | border-left-width: 2px;
534 | border-right-width: 2px;
535 | border-color: grey;
536 | }
537 |
538 | .toc_stylepoint {
539 | font-size: 10pt;
540 | padding-top: 1em;
541 | padding-bottom: 1em;
542 | }
543 |
544 | li.toc_entry {
545 | padding-right: 1em;
546 | display: inline;
547 | list-style-type: none;
548 | }
549 |
550 | /*
551 | * This space is required to trigger the linewrap on the links
552 | * at href boundaries
553 | */
554 | li.toc_entry::after {
555 | content: " ";
556 | }
557 |
558 | li.toc_entry a {
559 | white-space: nowrap;
560 | }
561 |
562 | /* Horizontal TOC */
563 | .toc td, .toc th {
564 | border-width: 1px 5px;
565 | overflow: hidden;
566 | }
567 |
568 | /* Vertical TOC */
569 |
570 | .toc td.two_columns {
571 | border-width: 0px;
572 | }
573 |
574 | /* Numbered sections */
575 |
576 | h1 {
577 | counter-reset: h2;
578 | }
579 |
580 | h2.numbered {
581 | counter-reset: h3;
582 | }
583 |
584 | h3.numbered {
585 | counter-reset: h4;
586 | }
587 |
588 | h2.numbered::before {
589 | content: counter(h2) ' ';
590 | counter-increment: h2;
591 | }
592 |
593 | h3.numbered::before {
594 | content: counter(h2) '.' counter(h3) ' ';
595 | counter-increment: h3;
596 | }
597 |
598 | h4.numbered::before {
599 | content: counter(h2) '.' counter(h3) '.' counter(h4) ' ';
600 | counter-increment: h4;
601 | }
602 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 |
2 | Apache License
3 | Version 2.0, January 2004
4 | http://www.apache.org/licenses/
5 |
6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7 |
8 | 1. Definitions.
9 |
10 | "License" shall mean the terms and conditions for use, reproduction,
11 | and distribution as defined by Sections 1 through 9 of this document.
12 |
13 | "Licensor" shall mean the copyright owner or entity authorized by
14 | the copyright owner that is granting the License.
15 |
16 | "Legal Entity" shall mean the union of the acting entity and all
17 | other entities that control, are controlled by, or are under common
18 | control with that entity. For the purposes of this definition,
19 | "control" means (i) the power, direct or indirect, to cause the
20 | direction or management of such entity, whether by contract or
21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the
22 | outstanding shares, or (iii) beneficial ownership of such entity.
23 |
24 | "You" (or "Your") shall mean an individual or Legal Entity
25 | exercising permissions granted by this License.
26 |
27 | "Source" form shall mean the preferred form for making modifications,
28 | including but not limited to software source code, documentation
29 | source, and configuration files.
30 |
31 | "Object" form shall mean any form resulting from mechanical
32 | transformation or translation of a Source form, including but
33 | not limited to compiled object code, generated documentation,
34 | and conversions to other media types.
35 |
36 | "Work" shall mean the work of authorship, whether in Source or
37 | Object form, made available under the License, as indicated by a
38 | copyright notice that is included in or attached to the work
39 | (an example is provided in the Appendix below).
40 |
41 | "Derivative Works" shall mean any work, whether in Source or Object
42 | form, that is based on (or derived from) the Work and for which the
43 | editorial revisions, annotations, elaborations, or other modifications
44 | represent, as a whole, an original work of authorship. For the purposes
45 | of this License, Derivative Works shall not include works that remain
46 | separable from, or merely link (or bind by name) to the interfaces of,
47 | the Work and Derivative Works thereof.
48 |
49 | "Contribution" shall mean any work of authorship, including
50 | the original version of the Work and any modifications or additions
51 | to that Work or Derivative Works thereof, that is intentionally
52 | submitted to Licensor for inclusion in the Work by the copyright owner
53 | or by an individual or Legal Entity authorized to submit on behalf of
54 | the copyright owner. For the purposes of this definition, "submitted"
55 | means any form of electronic, verbal, or written communication sent
56 | to the Licensor or its representatives, including but not limited to
57 | communication on electronic mailing lists, source code control systems,
58 | and issue tracking systems that are managed by, or on behalf of, the
59 | Licensor for the purpose of discussing and improving the Work, but
60 | excluding communication that is conspicuously marked or otherwise
61 | designated in writing by the copyright owner as "Not a Contribution."
62 |
63 | "Contributor" shall mean Licensor and any individual or Legal Entity
64 | on behalf of whom a Contribution has been received by Licensor and
65 | subsequently incorporated within the Work.
66 |
67 | 2. Grant of Copyright License. Subject to the terms and conditions of
68 | this License, each Contributor hereby grants to You a perpetual,
69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70 | copyright license to reproduce, prepare Derivative Works of,
71 | publicly display, publicly perform, sublicense, and distribute the
72 | Work and such Derivative Works in Source or Object form.
73 |
74 | 3. Grant of Patent License. Subject to the terms and conditions of
75 | this License, each Contributor hereby grants to You a perpetual,
76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77 | (except as stated in this section) patent license to make, have made,
78 | use, offer to sell, sell, import, and otherwise transfer the Work,
79 | where such license applies only to those patent claims licensable
80 | by such Contributor that are necessarily infringed by their
81 | Contribution(s) alone or by combination of their Contribution(s)
82 | with the Work to which such Contribution(s) was submitted. If You
83 | institute patent litigation against any entity (including a
84 | cross-claim or counterclaim in a lawsuit) alleging that the Work
85 | or a Contribution incorporated within the Work constitutes direct
86 | or contributory patent infringement, then any patent licenses
87 | granted to You under this License for that Work shall terminate
88 | as of the date such litigation is filed.
89 |
90 | 4. Redistribution. You may reproduce and distribute copies of the
91 | Work or Derivative Works thereof in any medium, with or without
92 | modifications, and in Source or Object form, provided that You
93 | meet the following conditions:
94 |
95 | (a) You must give any other recipients of the Work or
96 | Derivative Works a copy of this License; and
97 |
98 | (b) You must cause any modified files to carry prominent notices
99 | stating that You changed the files; and
100 |
101 | (c) You must retain, in the Source form of any Derivative Works
102 | that You distribute, all copyright, patent, trademark, and
103 | attribution notices from the Source form of the Work,
104 | excluding those notices that do not pertain to any part of
105 | the Derivative Works; and
106 |
107 | (d) If the Work includes a "NOTICE" text file as part of its
108 | distribution, then any Derivative Works that You distribute must
109 | include a readable copy of the attribution notices contained
110 | within such NOTICE file, excluding those notices that do not
111 | pertain to any part of the Derivative Works, in at least one
112 | of the following places: within a NOTICE text file distributed
113 | as part of the Derivative Works; within the Source form or
114 | documentation, if provided along with the Derivative Works; or,
115 | within a display generated by the Derivative Works, if and
116 | wherever such third-party notices normally appear. The contents
117 | of the NOTICE file are for informational purposes only and
118 | do not modify the License. You may add Your own attribution
119 | notices within Derivative Works that You distribute, alongside
120 | or as an addendum to the NOTICE text from the Work, provided
121 | that such additional attribution notices cannot be construed
122 | as modifying the License.
123 |
124 | You may add Your own copyright statement to Your modifications and
125 | may provide additional or different license terms and conditions
126 | for use, reproduction, or distribution of Your modifications, or
127 | for any such Derivative Works as a whole, provided Your use,
128 | reproduction, and distribution of the Work otherwise complies with
129 | the conditions stated in this License.
130 |
131 | 5. Submission of Contributions. Unless You explicitly state otherwise,
132 | any Contribution intentionally submitted for inclusion in the Work
133 | by You to the Licensor shall be under the terms and conditions of
134 | this License, without any additional terms or conditions.
135 | Notwithstanding the above, nothing herein shall supersede or modify
136 | the terms of any separate license agreement you may have executed
137 | with Licensor regarding such Contributions.
138 |
139 | 6. Trademarks. This License does not grant permission to use the trade
140 | names, trademarks, service marks, or product names of the Licensor,
141 | except as required for reasonable and customary use in describing the
142 | origin of the Work and reproducing the content of the NOTICE file.
143 |
144 | 7. Disclaimer of Warranty. Unless required by applicable law or
145 | agreed to in writing, Licensor provides the Work (and each
146 | Contributor provides its Contributions) on an "AS IS" BASIS,
147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148 | implied, including, without limitation, any warranties or conditions
149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150 | PARTICULAR PURPOSE. You are solely responsible for determining the
151 | appropriateness of using or redistributing the Work and assume any
152 | risks associated with Your exercise of permissions under this License.
153 |
154 | 8. Limitation of Liability. In no event and under no legal theory,
155 | whether in tort (including negligence), contract, or otherwise,
156 | unless required by applicable law (such as deliberate and grossly
157 | negligent acts) or agreed to in writing, shall any Contributor be
158 | liable to You for damages, including any direct, indirect, special,
159 | incidental, or consequential damages of any character arising as a
160 | result of this License or out of the use or inability to use the
161 | Work (including but not limited to damages for loss of goodwill,
162 | work stoppage, computer failure or malfunction, or any and all
163 | other commercial damages or losses), even if such Contributor
164 | has been advised of the possibility of such damages.
165 |
166 | 9. Accepting Warranty or Additional Liability. While redistributing
167 | the Work or Derivative Works thereof, You may choose to offer,
168 | and charge a fee for, acceptance of support, warranty, indemnity,
169 | or other liability obligations and/or rights consistent with this
170 | License. However, in accepting such obligations, You may act only
171 | on Your own behalf and on Your sole responsibility, not on behalf
172 | of any other Contributor, and only if You agree to indemnify,
173 | defend, and hold each Contributor harmless for any liability
174 | incurred by, or claims asserted against, such Contributor by reason
175 | of your accepting any such warranty or additional liability.
176 |
177 | END OF TERMS AND CONDITIONS
178 |
179 | APPENDIX: How to apply the Apache License to your work.
180 |
181 | To apply the Apache License to your work, attach the following
182 | boilerplate notice, with the fields enclosed by brackets "[]"
183 | replaced with your own identifying information. (Don't include
184 | the brackets!) The text should be enclosed in the appropriate
185 | comment syntax for the file format. We also recommend that a
186 | file or class name and description of purpose be included on the
187 | same "printed page" as the copyright notice for easier
188 | identification within third-party archives.
189 |
190 | Copyright [yyyy] [name of copyright owner]
191 |
192 | Licensed under the Apache License, Version 2.0 (the "License");
193 | you may not use this file except in compliance with the License.
194 | You may obtain a copy of the License at
195 |
196 | http://www.apache.org/licenses/LICENSE-2.0
197 |
198 | Unless required by applicable law or agreed to in writing, software
199 | distributed under the License is distributed on an "AS IS" BASIS,
200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201 | See the License for the specific language governing permissions and
202 | limitations under the License.
203 |
--------------------------------------------------------------------------------
/docguide/style.md:
--------------------------------------------------------------------------------
1 | # Markdown style guide
2 |
3 | Much of what makes Markdown great is the ability to write plain text, and get
4 | great formatted output as a result. To keep the slate clean for the next author,
5 | your Markdown should be simple and consistent with the whole corpus wherever
6 | possible.
7 |
8 | We seek to balance three goals:
9 |
10 | 1. *Source text is readable and portable.*
11 | 2. *Markdown files are maintainable over time and across teams.*
12 | 3. *The syntax is simple and easy to remember.*
13 |
14 | Contents:
15 |
16 | 1. [Document layout](#document-layout)
17 | 1. [Character line limit](#character-line-limit)
18 | 1. [Trailing whitespace](#trailing-whitespace)
19 | 1. [Headings](#headings)
20 | 1. [ATX-style headings](#atx-style-headings)
21 | 1. [Add spacing to headings](#add-spacing-to-headings)
22 | 1. [Lists](#lists)
23 | 1. [Use lazy numbering for long lists](#use-lazy-numbering-for-long-lists)
24 | 1. [Nested list spacing](#nested-list-spacing)
25 | 1. [Code](#code)
26 | 1. [Inline](#inline)
27 | 1. [Codeblocks](#codeblocks)
28 | 1. [Declare the language](#declare-the-language)
29 | 1. [Escape newlines](#escape-newlines)
30 | 1. [Nest codeblocks within lists](#nest-codeblocks-within-lists)
31 | 1. [Links](#links)
32 | 1. [Use informative Markdown link titles](#use-informative-markdown-link-titles)
33 | 1. [Images](#images)
34 | 1. [Prefer lists to tables](#prefer-lists-to-tables)
35 | 1. [Strongly prefer Markdown to HTML](#strongly-prefer-markdown-to-html)
36 |
37 | ## Document layout
38 |
39 | In general, most documents benefit from some variation of the following layout:
40 |
41 | ```markdown
42 | # Document Title
43 |
44 | Short introduction.
45 |
46 | [TOC]
47 |
48 | ## Topic
49 |
50 | Content.
51 |
52 | ## See also
53 |
54 | * https://link-to-more-info
55 | ```
56 |
57 | 1. `# Document Title`: The first heading should be a level one heading, and
58 | should ideally be the same or nearly the same as the filename. The first
59 | level one heading is used as the page ``.
60 |
61 | 1. `author`: *Optional*. If you'd like to claim ownership of the document or
62 | if you are very proud of it, add yourself under the title. However,
63 | revision history generally suffices.
64 |
65 | 1. `Short introduction.` 1-3 sentences providing a high-level overview of the
66 | topic. Imagine yourself as a complete newbie, who landed on your "Extending
67 | Foo" doc and needs to know the most basic assumptions you take for granted.
68 | "What is Foo? Why would I extend it?"
69 |
70 | 1. `[TOC]`: if you use hosting that supports table of contents, such as Gitiles,
71 | put `[TOC]` after the short introduction. See
72 | [`[TOC]` documentation](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Table-of-contents).
73 |
74 | 1. `## Topic`: The rest of your headings should start from level 2.
75 |
76 | 1. `## See also`: Put miscellaneous links at the bottom for the user who wants
77 | to know more or didn't find what she needed.
78 |
79 | ## Character line limit
80 |
81 | Obey projects' character line limit wherever possible. Long URLs and tables are
82 | the usual suspects when breaking the rule. (Headings also can't be wrapped, but
83 | we encourage keeping them short). Otherwise, wrap your text:
84 |
85 | ```markdown
86 | Lorem ipsum dolor sit amet, nec eius volumus patrioque cu, nec et commodo
87 | hendrerit, id nobis saperet fuisset ius.
88 |
89 | * Malorum moderatius vim eu. In vix dico persecuti. Te nam saperet percipitur
90 | interesset. See the [foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md).
91 | ```
92 |
93 | Often, inserting a newline before a long link preserves readability while
94 | minimizing the overflow:
95 |
96 | ```markdown
97 | Lorem ipsum dolor sit amet. See the
98 | [foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md)
99 | for details.
100 | ```
101 |
102 | ## Trailing whitespace
103 |
104 | Don't use trailing whitespace, use a trailing backslash.
105 |
106 | The [CommonMark spec](http://spec.commonmark.org/0.20/#hard-line-breaks) decrees
107 | that two spaces at the end of a line should insert a `<br />` tag. However, many
108 | directories have a trailing whitespace presubmit check in place, and many IDEs
109 | will clean it up anyway.
110 |
111 | Best practice is to avoid the need for a `<br />` altogether. Markdown creates
112 | paragraph tags for you simply with newlines: get used to that.
113 |
114 | ## Headings
115 |
116 | ### ATX-style headings
117 |
118 | ```markdown
119 | ## Heading 2
120 | ```
121 |
122 | Headings with `=` or `-` underlines can be annoying to maintain and don't fit
123 | with the rest of the heading syntax. The user has to ask: Does `---` mean H1 or
124 | H2?
125 |
126 | ```markdown
127 | Heading - do you remember what level? DO NOT DO THIS.
128 | ---------
129 | ```
130 |
131 | ### Add spacing to headings
132 |
133 | Prefer spacing after `#` and newlines before and after:
134 |
135 | ```markdown
136 | ...text before.
137 |
138 | # Heading 1
139 |
140 | Text after...
141 | ```
142 |
143 | Lack of spacing makes it a little harder to read in source:
144 |
145 | ```markdown
146 | ...text before.
147 |
148 | #Heading 1
149 | Text after... DO NOT DO THIS.
150 | ```
151 |
152 | ## Lists
153 |
154 | ### Use lazy numbering for long lists
155 |
156 | Markdown is smart enough to let the resulting HTML render your numbered lists
157 | correctly. For longer lists that may change, especially long nested lists, use
158 | "lazy" numbering:
159 |
160 | ```markdown
161 | 1. Foo.
162 | 1. Bar.
163 | 1. Foofoo.
164 | 1. Barbar.
165 | 1. Baz.
166 | ```
167 |
168 | However, if the list is small and you don't anticipate changing it, prefer fully
169 | numbered lists, because it's nicer to read in source:
170 |
171 | ```markdown
172 | 1. Foo.
173 | 2. Bar.
174 | 3. Baz.
175 | ```
176 |
177 | ### Nested list spacing
178 |
179 | When nesting lists, use a 4 space indent for both numbered and bulleted lists:
180 |
181 | ```markdown
182 | 1. 2 spaces after a numbered list.
183 | 4 space indent for wrapped text.
184 | 2. 2 spaces again.
185 |
186 | * 3 spaces after a bullet.
187 | 4 space indent for wrapped text.
188 | 1. 2 spaces after a numbered list.
189 | 8 space indent for the wrapped text of a nested list.
190 | 2. Looks nice, don't it?
191 | * 3 spaces after a bullet.
192 | ```
193 |
194 | The following works, but it's very messy:
195 |
196 | ```markdown
197 | * One space,
198 | with no indent for wrapped text.
199 | 1. Irregular nesting... DO NOT DO THIS.
200 | ```
201 |
202 | Even when there's no nesting, using the 4 space indent makes layout consistent
203 | for wrapped text:
204 |
205 | ```markdown
206 | * Foo,
207 | wrapped.
208 |
209 | 1. 2 spaces
210 | and 4 space indenting.
211 | 2. 2 spaces again.
212 | ```
213 |
214 | However, when lists are small, not nested, and a single line, one space can
215 | suffice for both kinds of lists:
216 |
217 | ```markdown
218 | * Foo
219 | * Bar
220 | * Baz.
221 |
222 | 1. Foo.
223 | 2. Bar.
224 | ```
225 |
226 | ## Code
227 |
228 | ### Inline
229 |
230 | `Backticks` designate `inline code`, and will render all wrapped content
231 | literally. Use them for short code quotations and field names:
232 |
233 | ```markdown
234 | You'll want to run `really_cool_script.sh arg`.
235 |
236 | Pay attention to the `foo_bar_whammy` field in that table.
237 | ```
238 |
239 | Use inline code when referring to file types in an abstract sense, rather than a
240 | specific file:
241 |
242 | ```markdown
243 | Be sure to update your `README.md`!
244 | ```
245 |
246 | Backticks are the most common approach for "escaping" Markdown metacharacters;
247 | in most situations where escaping would be needed, code font just makes sense
248 | anyway.
249 |
250 | ### Codeblocks
251 |
252 | For code quotations longer than a single line, use a codeblock:
253 |
254 | <pre>
255 | ```python
256 | def Foo(self, bar):
257 | self.bar = bar
258 | ```
259 | </pre>
260 |
261 | #### Declare the language
262 |
263 | It is best practice to explicitly declare the language, so that neither the
264 | syntax highlighter nor the next editor must guess.
265 |
266 | #### Indented codeblocks are sometimes cleaner
267 |
268 | Four-space indenting is also interpreted as a codeblock. These can look
269 | cleaner and be easier to read in source, but there is no way to specify the
270 | language. We encourage their use when writing many short snippets:
271 |
272 | ```markdown
273 | You'll need to run:
274 |
275 | bazel run :thing -- --foo
276 |
277 | And then:
278 |
279 | bazel run :another_thing -- --bar
280 |
281 | And again:
282 |
283 | bazel run :yet_again -- --baz
284 | ```
285 |
286 | #### Escape newlines
287 |
288 | Because most commandline snippets are intended to be copied and pasted directly
289 | into a terminal, it's best practice to escape any newlines. Use a single
290 | backslash at the end of the line:
291 |
292 | <pre>
293 | ```shell
294 | bazel run :target -- --flag --foo=longlonglonglonglongvalue \
295 | --bar=anotherlonglonglonglonglonglonglonglonglonglongvalue
296 | ```
297 | </pre>
298 |
299 | #### Nest codeblocks within lists
300 |
301 | If you need a codeblock within a list, make sure to indent it so as to not break
302 | the list:
303 |
304 | ```markdown
305 | * Bullet.
306 |
307 | ```c++
308 | int foo;
309 | ```
310 |
311 | * Next bullet.
312 | ```
313 |
314 | You can also create a nested code block with 4 spaces. Simply indent 4
315 | additional spaces from the list indentation:
316 |
317 | ```markdown
318 | * Bullet.
319 |
320 | int foo;
321 |
322 | * Next bullet.
323 | ```
324 |
325 | ## Links
326 |
327 | Long links make source Markdown difficult to read and break the 80 character
328 | wrapping. **Wherever possible, shorten your links**.
329 |
330 | ### Use informative Markdown link titles
331 |
332 | Markdown link syntax allows you to set a link title, just as HTML does. Use it
333 | wisely.
334 |
335 | Titling your links as "link" or "here" tells the reader precisely nothing when
336 | quickly scanning your doc and is a waste of space:
337 |
338 | ```markdown
339 | See the syntax guide for more info: [link](syntax_guide.md).
340 | Or, check out the style guide [here](style_guide.md).
341 | DO NOT DO THIS.
342 | ```
343 |
344 | Instead, write the sentence naturally, then go back and wrap the most
345 | appropriate phrase with the link:
346 |
347 | ```markdown
348 | See the [syntax guide](syntax_guide.md) for more info.
349 | Or, check out the [style guide](style_guide.md).
350 | ```
351 |
352 | ## Images
353 |
354 | Use images sparingly, and prefer simple screenshots. This guide is designed
355 | around the idea that plain text gets users down to the business of communication
356 | faster with less reader distraction and author procrastination. However, it's
357 | sometimes very helpful to show what you mean.
358 |
359 | See [image syntax](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Images).
360 |
361 | ## Prefer lists to tables
362 |
363 | Any tables in your Markdown should be small. Complex, large tables are difficult
364 | to read in source and most importantly, **a pain to modify later**.
365 |
366 | ```markdown
367 | Fruit | Attribute | Notes
368 | --- | --- | --- | ---
369 | Apple | [Juicy](https://example.com/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Firm, Sweet | Apples keep doctors away.
370 | Banana | [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Soft, Sweet | Contrary to popular belief, most apes prefer mangoes.
371 |
372 | DO NOT DO THIS
373 | ```
374 |
375 | [Lists](#lists) and subheadings usually suffice to present the same information
376 | in a slightly less compact, though much more edit-friendly way:
377 |
378 | ```markdown
379 | ## Fruits
380 |
381 | ### Apple
382 |
383 | * [Juicy](https://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)
384 | * Firm
385 | * Sweet
386 |
387 | Apples keep doctors away.
388 |
389 | ### Banana
390 |
391 | * [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery)
392 | * Soft
393 | * Sweet
394 |
395 | Contrary to popular belief, most apes prefer mangoes.
396 | ```
397 |
398 | However, there are times when a small table is called for:
399 |
400 | ```markdown
401 | Transport | Favored by | Advantages
402 | --- | --- | ---
403 | Swallow | Coconuts | Otherwise unladen
404 | Bicycle | Miss Gulch | Weatherproof
405 | X-34 landspeeder | Whiny farmboys | Cheap since the X-38 came out
406 | ```
407 |
408 | ## Strongly prefer Markdown to HTML
409 |
410 | Please prefer standard Markdown syntax wherever possible and avoid HTML hacks.
411 | If you can't seem to accomplish what you want, reconsider whether you really
412 | need it. Except for [big tables](#prefer-lists-to-tables), Markdown meets almost
413 | all needs already.
414 |
415 | Every bit of HTML or Javascript hacking reduces the readability and portability.
416 | This in turn limits the usefulness of integrations with
417 | other tools, which may either present the source as plain text or render it. See
418 | [Philosophy](philosophy.md).
419 |
420 | Gitiles does not render HTML.
421 |
--------------------------------------------------------------------------------
/angularjs-google-style.html:
--------------------------------------------------------------------------------
1 |
2 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "https://www.w3.org/TR/REC-html40/strict.dtd">
3 | <html>
4 | <head>
5 | <META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6 | <base target="_blank">
7 | <link rel="stylesheet" type="text/css" href="styleguide.css">
8 | <script src="https://google-code-prettify.googlecode.com/svn/loader/run_prettify.js"></script>
9 | <script language="javascript" src="/eng/doc/devguide/include/styleguide.js"></script>
10 | <title>Google's AngularJS Style Guide
11 |
14 |
15 |
16 |
An AngularJS Style Guide for Closure Users at Google
17 |
18 |
This is the external version of a document that was primarily written for Google
19 | engineers. It describes a recommended style for AngularJS apps that use Closure, as used
20 | internally at Google. Members of the broader AngularJS community should feel free to apply
21 | (or not apply) these recommendations, as relevant to their own use cases.
22 |
23 |
This document describes style for AngularJS apps in google3. This guide
24 | supplements and extends the
25 | Google JavaScript Style Guide.
26 |
27 |
28 |
Style Note: Examples on the AngularJS external webpage, and many external apps, are
29 | written in a style that freely uses closures, favors functional inheritance, and does not often use
30 |
32 | JavaScript types. Google follows a more rigorous Javascript style to support JSCompiler
33 | optimizations and large code bases - see the javascript-style mailing list.
34 | This is not an Angular-specific issue, and is not discussed further in this style guide.
35 | (But if you want further reading:
36 | Martin Fowler on closures,
37 | much longer description, appendix A of the
38 |
39 | closure book has a good description of inheritance patterns and why it prefers
40 | pseudoclassical,
41 |
42 | Javascript, the Good Parts as a counter.)
Why?
83 | Google BUILD rules integrate nicely with closure provide/require.
84 |
85 |
Modules
86 |
87 |
Your main application module should be in your root client directory. A module should never be
88 | altered other than the one where it is defined.
89 |
90 |
Modules may either be defined in the same file as their components (this works well for a module
91 | that contains exactly one service) or in a separate file for wiring pieces together.
92 |
93 |
Why?
94 | A module should be consistent for anyone that wants to include it as a reusable component.
95 | If a module can mean different things depending on which files are included, it is not consistent.
96 |
97 |
98 |
99 | Modules should reference other modules using the Angular Module's "name" property
100 |
Why?
120 | Using a property of my.submoduleA prevents Closure presubmit failures complaining that the file is
121 | required but never used. Using the .name property avoids duplicating strings.
122 |
123 |
Use a common externs file
124 |
125 |
This maximally allows the JS compiler to enforce type safety in the presence of externally
126 | provided types from Angular, and means you don't have to worry about Angular vars being obfuscated
127 | in a confusing way.
128 |
129 |
Note to readers outside Google: the current externs file is located in an internal-to-Google
130 | directory, but an example can be found on github
131 | here.
132 |
133 |
JSCompiler Flags
134 |
Reminder: According to the JS style guide, customer facing code must be compiled.
135 |
136 |
Recommended: Use the JSCompiler (the closure compiler that works with js_binary by
137 | default) and ANGULAR_COMPILER_FLAGS_FULL from //javascript/angular/build_defs/build_defs for
138 | your base flags.
139 |
140 |
141 |
Note - if you are using @export for methods, you will need to add the compiler flag
142 |
143 | "--generate_exports",
144 |
145 |
146 |
If you are using @export for properties, you will need to add the flags:
Controllers are classes. Methods should be defined on MyCtrl.prototype.
155 |
156 |
Google Angular applications should use the 'controller as' style to export the controller
157 | onto the scope. This is fully implemented in Angular 1.2 and can be mimicked in pre-Angular 1.2
158 | builds.
159 |
If you are compiling with property renaming, expose properties and methods using the @export
232 | annotation. Remember to @export the constructor as well.
233 |
234 |
And in the template:
235 |
236 |
237 | <div ng-controller="hello.mainpage.HomeCtrl as homeCtrl"/>
238 | <span ng-class="homeCtrl.myColor">I'm in a color!</span>
239 | <span>{{homeCtrl.add(5, 6)}}</span>
240 | </div>
241 |
242 |
243 |
Why?
244 | Putting methods and properties directly onto the controller, instead of building up a scope
245 | object, fits better with the Google Closure class style. Additionally, using 'controller as'
246 | makes it obvious which controller you are accessing when multiple controllers apply to an element.
247 | Since there is always a '.' in the bindings, you don't have to worry about prototypal inheritance
248 | masking primitives.
249 |
250 |
Directives
251 |
252 |
All DOM manipulation should be done inside directives. Directives should be kept small and use
253 | composition. Files defining directives should goog.provide a static function which returns the
254 | directive definition object.
Exception: DOM manipulation may occur in services for DOM elements disconnected from the
269 | rest of the view, e.g. dialogs or keyboard shortcuts.
270 |
271 |
Services
272 |
273 |
Services registered on the module with module.service are classes.
274 | Use module.service instead of module.provider or
275 | module.factory unless you need to do initialization beyond just creating a
276 | new instance of the class.
313 | $scope.$myModel = { value: 'foo' } // BAD
314 | $scope.myModel = { $value: 'foo' } // BAD
315 | myModule.service('$myService', function() { ... }); // BAD
316 | var MyCtrl = function($http) {this.$http_ = $http;}; // BAD
317 |
318 |
319 |
Why?
320 | It's useful to distinguish between Angular / jQuery builtins and things you add yourself.
321 | In addition, $ is not an acceptable character for variables names in the JS style guide.
322 |
323 |
324 |
Custom elements
325 |
326 |
For custom elements (e.g. <ng-include src="template"></ng-include>), IE8
327 | requires special support (html5shiv-like hacks) to enable css styling. Be aware of this
328 | restriction in apps targeting old versions of IE.
329 |
330 |
3 Angular Tips, Tricks, and Best Practices
331 |
332 |
These are not strict style guide rules, but are placed here as reference for folks getting
333 | started with Angular at Google.
334 |
335 |
Testing
336 |
337 |
Angular is designed for test-driven development.
338 |
339 |
The recommended unit testing setup is Jasmine + Karma (though you could use closure tests
340 | or js_test)
341 |
342 |
Angular provides easy adapters to load modules and use the injector in Jasmine tests.
343 |
Consider using the Best Practices for App Structure
351 |
352 | This directory structure doc describes how to structure your application with controllers in
353 | nested subdirectories and all components (e.g. services and directives) in a 'components' dir.
354 |
19 | This is a casual version of the vimscript style guide, because
20 | vimscript is a casual language. When submitting vim plugin code, you
21 | must adhere to these rules. For clarifications, justifications, and
22 | explanations about the finer points of vimscript, please refer to the
23 | heavy guide.
24 |
25 |
26 |
27 |
28 |
29 |
30 | It's hard to get vimscript right. Many commands depend upon the user's
31 | settings. By following these guidelines, you can hope to make your
32 | scripts portable.
33 |
34 |
35 | Prefer single quoted strings
36 |
37 |
38 | Double quoted strings are semantically different in vimscript, and
39 | you probably don't want them (they break regexes).
40 |
41 |
42 | Use double quoted strings when you need an escape sequence (such as
43 | "\n") or if you know it doesn't matter and you need to
44 | embed single quotes.
45 |
46 |
47 |
48 |
49 |
50 | Use the =~# or =~? operator families over the
51 | =~ family.
52 |
53 |
54 |
55 | The matching behavior depends upon the user's ignorecase and smartcase
56 | settings and on whether you compare them with the =~,
57 | =~#, or =~? family of operators. Use the
58 | =~# and =~? operator families explicitly
59 | when comparing strings unless you explicitly need to honor the user's
60 | case sensitivity settings.
61 |
62 |
63 |
64 |
65 | Prefix all regexes with \m\C.
66 |
67 |
68 | In addition to the case sensitivity settings, regex behavior depends
69 | upon the user's nomagic setting. To make regexes act like nomagic and
70 | noignorecase are set, prepend all regexes with \m\C.
71 |
72 |
73 | You are welcome to use other magic levels (\v) and case
74 | sensitivities (\c) so long as they are intentional and
75 | explicit.
76 |
77 |
78 |
79 |
80 | Avoid commands with unintended side effects.
81 |
82 |
83 | Avoid using :s[ubstitute] as it moves the cursor and
84 | prints error messages. Prefer functions (such as
85 | search()) better suited to scripts.
86 |
87 |
88 | For many vim commands, functions exist that do the same thing with
89 | fewer side effects. See :help functions() for a list of
90 | built-in functions.
91 |
92 |
93 |
94 |
95 | Avoid commands that rely on user settings.
96 |
97 |
98 | Always use normal! instead of normal. The
99 | latter depends upon the user's key mappings and could do anything.
100 |
101 |
102 | Avoid :s[ubstitute], as its behavior depends upon a
103 | number of local settings.
104 |
105 |
106 | The same applies to other commands not listed here.
107 |
108 |
109 |
110 |
111 | Match error codes, not error text.
112 |
113 |
125 | Loud scripts are annoying. Message the user only when:
126 |
127 |
A long-running process has kicked off.
128 |
An error has occurred.
129 |
130 |
131 |
132 |
133 |
134 | Use strict and explicit checks where possible.
135 |
136 |
137 | Vimscript has unsafe, unintuitive behavior when dealing with some
138 | types. For instance, 0 == 'foo' evaluates to true.
139 |
140 |
141 | Use strict comparison operators where possible. When comparing against
142 | a string literal, use the is# operator. Otherwise, prefer
143 | maktaba#value#IsEqual or check type()
144 | explicitly.
145 |
146 |
147 | Check variable types explicitly before using them. Use functions from
148 | maktaba#ensure, or check maktaba#value or
149 | type() and throw your own errors.
150 |
151 |
152 | Use :unlet for variables that may change types,
153 | particularly those assigned inside loops.
154 |
170 | Avoid using other scripting languages such as ruby and lua. We can
171 | not guarantee that the end user's vim has been compiled with support
172 | for non-vimscript languages.
173 |
188 |
189 |
190 |
191 |
192 | Organize functionality into modular plugins
193 |
194 |
195 | Group your functionality as a plugin, unified in one directory (or
196 | code repository) which shares your plugin's name (with a "vim-" prefix
197 | or ".vim" suffix if desired). It should be split into plugin/,
198 | autoload/, etc. subdirectories as necessary, and it should declare
199 | metadata in the addon-info.json format (see the
200 | VAM documentation for details).
201 |
202 |
203 |
204 |
205 |
206 | In the autoload/ directory, defined with [!] and
207 | [abort].
208 |
209 |
210 |
211 | Autoloading allows functions to be loaded on demand, which makes
212 | startuptime faster and enforces function namespacing.
213 |
214 |
215 | Script-local functions are welcome, but should also live in autoload/
216 | and be called by autoloaded functions.
217 |
218 |
219 | Non-library plugins should expose commands instead of functions.
220 | Command logic should be extracted into functions and autoloaded.
221 |
222 |
223 | [!] allows developers to reload their functions
224 | without complaint.
225 |
226 |
227 | [abort] forces the function to halt when it encounters
228 | an error.
229 |
230 |
231 |
232 |
233 |
234 | In the plugin/commands.vim or under the ftplugin/ directory, defined
235 | without [!].
236 |
237 |
238 |
239 | General commands go in plugin/commands.vim.
240 | Filetype-specific commands go in ftplugin/.
241 |
242 |
243 | Excluding [!] prevents your plugin from silently
244 | clobbering existing commands. Command conflicts should be resolved by
245 | the user.
246 |
247 |
248 |
249 |
250 |
251 | Place them in plugin/autocmds.vim, within augroups.
252 |
253 |
254 |
255 | Place all autocommands in augroups.
256 |
257 |
258 | The augroup name should be unique. It should either be, or be prefixed
259 | with, the plugin name.
260 |
261 |
262 | Clear the augroup with autocmd! before defining new
263 | autocommands in the augroup. This makes your plugin re-entrable.
264 |
265 |
266 |
267 |
268 |
269 | Place them in plugin/mappings.vim, using
270 | maktaba#plugin#MapPrefix to get a prefix.
271 |
272 |
273 |
274 | All key mappings should be defined in
275 | plugin/mappings.vim.
276 |
277 |
278 | Partial mappings (see :help using-<Plug>.) should be defined in
279 | plugin/plugs.vim.
280 |
346 | In general, use
347 | plugin-names-like-this,
348 | FunctionNamesLikeThis,
349 | CommandNamesLikeThis,
350 | augroup_names_like_this,
351 | variable_names_like_this.
352 |
353 |
Always prefix variables with their scope.
354 |
355 |
356 |
357 |
Keep them short and sweet.
358 |
359 |
360 |
361 |
Prefix script-local functions with s:
362 |
Autoloaded functions may not have a scope prefix.
363 |
364 | Do not create global functions. Use autoloaded functions
365 | instead.
366 |
367 |
368 |
369 |
Prefer succinct command names over common command prefixes.
370 |
371 |
372 |
Augroup names count as variables for naming purposes.
373 |
374 |
375 |
376 |
Global variables with g:
377 |
Script-local variables with s:
378 |
Function arguments with a:
379 |
Function-local variables with l:
380 |
Vim-predefined variables with v:
381 |
Buffer-local variables with b:
382 |
383 |
384 | g:, s:, and a: must always
385 | be used.
386 |
387 |
388 | b: changes the variable semantics; use it when you
389 | want buffer-local semantics.
390 |
391 |
392 | l: and v: should be used for consistency,
393 | future proofing, and to avoid subtle bugs. They are not strictly
394 | required. Add them in new code but don’t go out of your way to add
395 | them elsewhere.
396 |
397 |
398 |
399 |
400 |
401 |
402 |
403 | Revision 1.1
404 |
405 |
406 |
407 |
408 | Nate Soares
409 | Joshua Hoak
410 | David Barnett
411 |
412 |
413 |
--------------------------------------------------------------------------------
/pylintrc:
--------------------------------------------------------------------------------
1 | # This Pylint rcfile contains a best-effort configuration to uphold the
2 | # best-practices and style described in the Google Python style guide:
3 | # https://google.github.io/styleguide/pyguide.html
4 | #
5 | # Its canonical open-source location is:
6 | # https://google.github.io/styleguide/pylintrc
7 |
8 | [MASTER]
9 |
10 | # Files or directories to be skipped. They should be base names, not paths.
11 | ignore=third_party
12 |
13 | # Files or directories matching the regex patterns are skipped. The regex
14 | # matches against base names, not paths.
15 | ignore-patterns=
16 |
17 | # Pickle collected data for later comparisons.
18 | persistent=no
19 |
20 | # List of plugins (as comma separated values of python modules names) to load,
21 | # usually to register additional checkers.
22 | load-plugins=
23 |
24 | # Use multiple processes to speed up Pylint.
25 | jobs=4
26 |
27 | # Allow loading of arbitrary C extensions. Extensions are imported into the
28 | # active Python interpreter and may run arbitrary code.
29 | unsafe-load-any-extension=no
30 |
31 |
32 | [MESSAGES CONTROL]
33 |
34 | # Only show warnings with the listed confidence levels. Leave empty to show
35 | # all. Valid levels: HIGH, INFERENCE, INFERENCE_FAILURE, UNDEFINED
36 | confidence=
37 |
38 | # Enable the message, report, category or checker with the given id(s). You can
39 | # either give multiple identifier separated by comma (,) or put this option
40 | # multiple time (only on the command line, not in the configuration file where
41 | # it should appear only once). See also the "--disable" option for examples.
42 | #enable=
43 |
44 | # Disable the message, report, category or checker with the given id(s). You
45 | # can either give multiple identifiers separated by comma (,) or put this
46 | # option multiple times (only on the command line, not in the configuration
47 | # file where it should appear only once).You can also use "--disable=all" to
48 | # disable everything first and then reenable specific checks. For example, if
49 | # you want to run only the similarities checker, you can use "--disable=all
50 | # --enable=similarities". If you want to run only the classes checker, but have
51 | # no Warning level messages displayed, use"--disable=all --enable=classes
52 | # --disable=W"
53 | disable=abstract-method,
54 | apply-builtin,
55 | arguments-differ,
56 | attribute-defined-outside-init,
57 | backtick,
58 | bad-option-value,
59 | basestring-builtin,
60 | buffer-builtin,
61 | c-extension-no-member,
62 | consider-using-enumerate,
63 | cmp-builtin,
64 | cmp-method,
65 | coerce-builtin,
66 | coerce-method,
67 | delslice-method,
68 | div-method,
69 | duplicate-code,
70 | eq-without-hash,
71 | execfile-builtin,
72 | file-builtin,
73 | filter-builtin-not-iterating,
74 | fixme,
75 | getslice-method,
76 | global-statement,
77 | hex-method,
78 | idiv-method,
79 | implicit-str-concat-in-sequence,
80 | import-error,
81 | import-self,
82 | import-star-module-level,
83 | inconsistent-return-statements,
84 | input-builtin,
85 | intern-builtin,
86 | invalid-str-codec,
87 | locally-disabled,
88 | long-builtin,
89 | long-suffix,
90 | map-builtin-not-iterating,
91 | misplaced-comparison-constant,
92 | missing-function-docstring,
93 | metaclass-assignment,
94 | next-method-called,
95 | next-method-defined,
96 | no-absolute-import,
97 | no-else-break,
98 | no-else-continue,
99 | no-else-raise,
100 | no-else-return,
101 | no-init, # added
102 | no-member,
103 | no-name-in-module,
104 | no-self-use,
105 | nonzero-method,
106 | oct-method,
107 | old-division,
108 | old-ne-operator,
109 | old-octal-literal,
110 | old-raise-syntax,
111 | parameter-unpacking,
112 | print-statement,
113 | raising-string,
114 | range-builtin-not-iterating,
115 | raw_input-builtin,
116 | rdiv-method,
117 | reduce-builtin,
118 | relative-import,
119 | reload-builtin,
120 | round-builtin,
121 | setslice-method,
122 | signature-differs,
123 | standarderror-builtin,
124 | suppressed-message,
125 | sys-max-int,
126 | too-few-public-methods,
127 | too-many-ancestors,
128 | too-many-arguments,
129 | too-many-boolean-expressions,
130 | too-many-branches,
131 | too-many-instance-attributes,
132 | too-many-locals,
133 | too-many-nested-blocks,
134 | too-many-public-methods,
135 | too-many-return-statements,
136 | too-many-statements,
137 | trailing-newlines,
138 | unichr-builtin,
139 | unicode-builtin,
140 | unnecessary-pass,
141 | unpacking-in-except,
142 | useless-else-on-loop,
143 | useless-object-inheritance,
144 | useless-suppression,
145 | using-cmp-argument,
146 | wrong-import-order,
147 | xrange-builtin,
148 | zip-builtin-not-iterating,
149 |
150 |
151 | [REPORTS]
152 |
153 | # Set the output format. Available formats are text, parseable, colorized, msvs
154 | # (visual studio) and html. You can also give a reporter class, eg
155 | # mypackage.mymodule.MyReporterClass.
156 | output-format=text
157 |
158 | # Put messages in a separate file for each module / package specified on the
159 | # command line instead of printing them on stdout. Reports (if any) will be
160 | # written in a file name "pylint_global.[txt|html]". This option is deprecated
161 | # and it will be removed in Pylint 2.0.
162 | files-output=no
163 |
164 | # Tells whether to display a full report or only the messages
165 | reports=no
166 |
167 | # Python expression which should return a note less than 10 (10 is the highest
168 | # note). You have access to the variables errors warning, statement which
169 | # respectively contain the number of errors / warnings messages and the total
170 | # number of statements analyzed. This is used by the global evaluation report
171 | # (RP0004).
172 | evaluation=10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10)
173 |
174 | # Template used to display messages. This is a python new-style format string
175 | # used to format the message information. See doc for all details
176 | #msg-template=
177 |
178 |
179 | [BASIC]
180 |
181 | # Good variable names which should always be accepted, separated by a comma
182 | good-names=main,_
183 |
184 | # Bad variable names which should always be refused, separated by a comma
185 | bad-names=
186 |
187 | # Colon-delimited sets of names that determine each other's naming style when
188 | # the name regexes allow several styles.
189 | name-group=
190 |
191 | # Include a hint for the correct naming format with invalid-name
192 | include-naming-hint=no
193 |
194 | # List of decorators that produce properties, such as abc.abstractproperty. Add
195 | # to this list to register other decorators that produce valid properties.
196 | property-classes=abc.abstractproperty,cached_property.cached_property,cached_property.threaded_cached_property,cached_property.cached_property_with_ttl,cached_property.threaded_cached_property_with_ttl
197 |
198 | # Regular expression matching correct function names
199 | function-rgx=^(?:(?PsetUp|tearDown|setUpModule|tearDownModule)|(?P_?[A-Z][a-zA-Z0-9]*)|(?P_?[a-z][a-z0-9_]*))$
200 |
201 | # Regular expression matching correct variable names
202 | variable-rgx=^[a-z][a-z0-9_]*$
203 |
204 | # Regular expression matching correct constant names
205 | const-rgx=^(_?[A-Z][A-Z0-9_]*|__[a-z0-9_]+__|_?[a-z][a-z0-9_]*)$
206 |
207 | # Regular expression matching correct attribute names
208 | attr-rgx=^_{0,2}[a-z][a-z0-9_]*$
209 |
210 | # Regular expression matching correct argument names
211 | argument-rgx=^[a-z][a-z0-9_]*$
212 |
213 | # Regular expression matching correct class attribute names
214 | class-attribute-rgx=^(_?[A-Z][A-Z0-9_]*|__[a-z0-9_]+__|_?[a-z][a-z0-9_]*)$
215 |
216 | # Regular expression matching correct inline iteration names
217 | inlinevar-rgx=^[a-z][a-z0-9_]*$
218 |
219 | # Regular expression matching correct class names
220 | class-rgx=^_?[A-Z][a-zA-Z0-9]*$
221 |
222 | # Regular expression matching correct module names
223 | module-rgx=^(_?[a-z][a-z0-9_]*|__init__)$
224 |
225 | # Regular expression matching correct method names
226 | method-rgx=(?x)^(?:(?P_[a-z0-9_]+__|runTest|setUp|tearDown|setUpTestCase|tearDownTestCase|setupSelf|tearDownClass|setUpClass|(test|assert)_*[A-Z0-9][a-zA-Z0-9_]*|next)|(?P_{0,2}[A-Z][a-zA-Z0-9_]*)|(?P_{0,2}[a-z][a-z0-9_]*))$
227 |
228 | # Regular expression which should only match function or class names that do
229 | # not require a docstring.
230 | no-docstring-rgx=(__.*__|main|test.*|.*test|.*Test)$
231 |
232 | # Minimum line length for functions/classes that require docstrings, shorter
233 | # ones are exempt.
234 | docstring-min-length=10
235 |
236 |
237 | [TYPECHECK]
238 |
239 | # List of decorators that produce context managers, such as
240 | # contextlib.contextmanager. Add to this list to register other decorators that
241 | # produce valid context managers.
242 | contextmanager-decorators=contextlib.contextmanager,contextlib2.contextmanager
243 |
244 | # Tells whether missing members accessed in mixin class should be ignored. A
245 | # mixin class is detected if its name ends with "mixin" (case insensitive).
246 | ignore-mixin-members=yes
247 |
248 | # List of module names for which member attributes should not be checked
249 | # (useful for modules/projects where namespaces are manipulated during runtime
250 | # and thus existing member attributes cannot be deduced by static analysis. It
251 | # supports qualified module names, as well as Unix pattern matching.
252 | ignored-modules=
253 |
254 | # List of class names for which member attributes should not be checked (useful
255 | # for classes with dynamically set attributes). This supports the use of
256 | # qualified names.
257 | ignored-classes=optparse.Values,thread._local,_thread._local
258 |
259 | # List of members which are set dynamically and missed by pylint inference
260 | # system, and so shouldn't trigger E1101 when accessed. Python regular
261 | # expressions are accepted.
262 | generated-members=
263 |
264 |
265 | [FORMAT]
266 |
267 | # Maximum number of characters on a single line.
268 | max-line-length=80
269 |
270 | # TODO(https://github.com/PyCQA/pylint/issues/3352): Direct pylint to exempt
271 | # lines made too long by directives to pytype.
272 |
273 | # Regexp for a line that is allowed to be longer than the limit.
274 | ignore-long-lines=(?x)(
275 | ^\s*(\#\ )??$|
276 | ^\s*(from\s+\S+\s+)?import\s+.+$)
277 |
278 | # Allow the body of an if to be on the same line as the test if there is no
279 | # else.
280 | single-line-if-stmt=yes
281 |
282 | # List of optional constructs for which whitespace checking is disabled. `dict-
283 | # separator` is used to allow tabulation in dicts, etc.: {1 : 1,\n222: 2}.
284 | # `trailing-comma` allows a space between comma and closing bracket: (a, ).
285 | # `empty-line` allows space-only lines.
286 | no-space-check=
287 |
288 | # Maximum number of lines in a module
289 | max-module-lines=99999
290 |
291 | # String used as indentation unit. The internal Google style guide mandates 2
292 | # spaces. Google's externaly-published style guide says 4, consistent with
293 | # PEP 8. Here, we use 2 spaces, for conformity with many open-sourced Google
294 | # projects (like TensorFlow).
295 | indent-string=' '
296 |
297 | # Number of spaces of indent required inside a hanging or continued line.
298 | indent-after-paren=4
299 |
300 | # Expected format of line ending, e.g. empty (any line ending), LF or CRLF.
301 | expected-line-ending-format=
302 |
303 |
304 | [MISCELLANEOUS]
305 |
306 | # List of note tags to take in consideration, separated by a comma.
307 | notes=TODO
308 |
309 |
310 | [STRING]
311 |
312 | # This flag controls whether inconsistent-quotes generates a warning when the
313 | # character used as a quote delimiter is used inconsistently within a module.
314 | check-quote-consistency=yes
315 |
316 |
317 | [VARIABLES]
318 |
319 | # Tells whether we should check for unused import in __init__ files.
320 | init-import=no
321 |
322 | # A regular expression matching the name of dummy variables (i.e. expectedly
323 | # not used).
324 | dummy-variables-rgx=^\*{0,2}(_$|unused_|dummy_)
325 |
326 | # List of additional names supposed to be defined in builtins. Remember that
327 | # you should avoid to define new builtins when possible.
328 | additional-builtins=
329 |
330 | # List of strings which can identify a callback function by name. A callback
331 | # name must start or end with one of those strings.
332 | callbacks=cb_,_cb
333 |
334 | # List of qualified module names which can have objects that can redefine
335 | # builtins.
336 | redefining-builtins-modules=six,six.moves,past.builtins,future.builtins,functools
337 |
338 |
339 | [LOGGING]
340 |
341 | # Logging modules to check that the string format arguments are in logging
342 | # function parameter format
343 | logging-modules=logging,absl.logging,tensorflow.io.logging
344 |
345 |
346 | [SIMILARITIES]
347 |
348 | # Minimum lines number of a similarity.
349 | min-similarity-lines=4
350 |
351 | # Ignore comments when computing similarities.
352 | ignore-comments=yes
353 |
354 | # Ignore docstrings when computing similarities.
355 | ignore-docstrings=yes
356 |
357 | # Ignore imports when computing similarities.
358 | ignore-imports=no
359 |
360 |
361 | [SPELLING]
362 |
363 | # Spelling dictionary name. Available dictionaries: none. To make it working
364 | # install python-enchant package.
365 | spelling-dict=
366 |
367 | # List of comma separated words that should not be checked.
368 | spelling-ignore-words=
369 |
370 | # A path to a file that contains private dictionary; one word per line.
371 | spelling-private-dict-file=
372 |
373 | # Tells whether to store unknown words to indicated private dictionary in
374 | # --spelling-private-dict-file option instead of raising a message.
375 | spelling-store-unknown-words=no
376 |
377 |
378 | [IMPORTS]
379 |
380 | # Deprecated modules which should not be used, separated by a comma
381 | deprecated-modules=regsub,
382 | TERMIOS,
383 | Bastion,
384 | rexec,
385 | sets
386 |
387 | # Create a graph of every (i.e. internal and external) dependencies in the
388 | # given file (report RP0402 must not be disabled)
389 | import-graph=
390 |
391 | # Create a graph of external dependencies in the given file (report RP0402 must
392 | # not be disabled)
393 | ext-import-graph=
394 |
395 | # Create a graph of internal dependencies in the given file (report RP0402 must
396 | # not be disabled)
397 | int-import-graph=
398 |
399 | # Force import order to recognize a module as part of the standard
400 | # compatibility libraries.
401 | known-standard-library=
402 |
403 | # Force import order to recognize a module as part of a third party library.
404 | known-third-party=enchant, absl
405 |
406 | # Analyse import fallback blocks. This can be used to support both Python 2 and
407 | # 3 compatible code, which means that the block might have code that exists
408 | # only in one or another interpreter, leading to false positives when analysed.
409 | analyse-fallback-blocks=no
410 |
411 |
412 | [CLASSES]
413 |
414 | # List of method names used to declare (i.e. assign) instance attributes.
415 | defining-attr-methods=__init__,
416 | __new__,
417 | setUp
418 |
419 | # List of member names, which should be excluded from the protected access
420 | # warning.
421 | exclude-protected=_asdict,
422 | _fields,
423 | _replace,
424 | _source,
425 | _make
426 |
427 | # List of valid names for the first argument in a class method.
428 | valid-classmethod-first-arg=cls,
429 | class_
430 |
431 | # List of valid names for the first argument in a metaclass class method.
432 | valid-metaclass-classmethod-first-arg=mcs
433 |
434 |
435 | [EXCEPTIONS]
436 |
437 | # Exceptions that will emit a warning when being caught. Defaults to
438 | # "Exception"
439 | overgeneral-exceptions=StandardError,
440 | Exception,
441 | BaseException
442 |
--------------------------------------------------------------------------------
/eclipse-cpp-google-style.xml:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
9 |
10 |
11 |
12 |
13 |
14 |
15 |
16 |
17 |
18 |
19 |
20 |
21 |
22 |
23 |
24 |
25 |
26 |
27 |
28 |
29 |
30 |
31 |
32 |
33 |
34 |
35 |
36 |
37 |
38 |
39 |
40 |
41 |
42 |
43 |
44 |
45 |
46 |
47 |
48 |
49 |
50 |
51 |
52 |
53 |
54 |
55 |
56 |
57 |
58 |
59 |
60 |
61 |
62 |
63 |
64 |
65 |
66 |
67 |
68 |
69 |
70 |
71 |
72 |
73 |
74 |
75 |
76 |
77 |
78 |
79 |
80 |
81 |
82 |
83 |
84 |
85 |
86 |
87 |
88 |
89 |
90 |
91 |
92 |
93 |
94 |
95 |
96 |
97 |
98 |
99 |
100 |
101 |
102 |
103 |
104 |
105 |
106 |
107 |
108 |
109 |
110 |
111 |
112 |
113 |
114 |
115 |
116 |
117 |
118 |
119 |
120 |
121 |
122 |
123 |
124 |
125 |
126 |
127 |
128 |
129 |
130 |
131 |
132 |
133 |
134 |
135 |
136 |
137 |
138 |
139 |
140 |
141 |
142 |
143 |
144 |
145 |
146 |
147 |
148 |
149 |
150 |
151 |
152 |
153 |
154 |
155 |
156 |
157 |
158 |
159 |
160 |
161 |
162 |
163 |
164 |
165 |
166 |
167 |
168 |
--------------------------------------------------------------------------------
/csharp-style.md:
--------------------------------------------------------------------------------
1 | # C# at Google Style Guide
2 |
3 | This style guide is for C# code developed internally at Google, and is the
4 | default style for C# code at Google. It makes stylistic choices that conform to
5 | other languages at Google, such as Google C++ style and Google Java style.
6 |
7 | ## Formatting guidelines
8 |
9 | ### Naming rules
10 |
11 | Naming rules follow
12 | [Microsoft's C# naming guidelines](https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/naming-guidelines).
13 | Where Microsoft's naming guidelines are unspecified (e.g. private and local
14 | variables), rules are taken from the
15 | [CoreFX C# coding guidelines](https://github.com/dotnet/runtime/blob/master/docs/coding-guidelines/coding-style.md)
16 |
17 | Rule summary:
18 |
19 | #### Code
20 |
21 | * Names of classes, methods, enumerations, public fields, public properties,
22 | namespaces: `PascalCase`.
23 | * Names of local variables, parameters: `camelCase`.
24 | * Names of private, protected, internal and protected internal fields and
25 | properties: `_camelCase`.
26 | * Naming convention is unaffected by modifiers such as const, static,
27 | readonly, etc.
28 | * For casing, a "word" is anything written without internal spaces, including
29 | acronyms. For example, `MyRpc` instead of ~~`MyRPC`~~.
30 | * Names of interfaces start with `I`, e.g. `IInterface`.
31 |
32 | #### Files
33 |
34 | * Filenames and directory names are `PascalCase`, e.g. `MyFile.cs`.
35 | * Where possible the file name should be the same as the name of the main
36 | class in the file, e.g. `MyClass.cs`.
37 | * In general, prefer one core class per file.
38 |
39 | ### Organization
40 |
41 | * Modifiers occur in the following order: `public protected internal private
42 | new abstract virtual override sealed static readonly extern unsafe volatile
43 | async`.
44 | * Namespace `using` declarations go at the top, before any namespaces. `using`
45 | import order is alphabetical, apart from `System` imports which always go
46 | first.
47 | * Class member ordering:
48 | * Group class members in the following order:
49 | * Nested classes, enums, delegates and events.
50 | * Static, const and readonly fields.
51 | * Fields and properties.
52 | * Constructors and finalizers.
53 | * Methods.
54 | * Within each group, elements should be in the following order:
55 | * Public.
56 | * Internal.
57 | * Protected internal.
58 | * Protected.
59 | * Private.
60 | * Where possible, group interface implementations together.
61 |
62 | ### Whitespace rules
63 |
64 | Developed from Google Java style.
65 |
66 | * A maximum of one statement per line.
67 | * A maximum of one assignment per statement.
68 | * Indentation of 2 spaces, no tabs.
69 | * Column limit: 100.
70 | * No line break before opening brace.
71 | * No line break between closing brace and `else`.
72 | * Braces used even when optional.
73 | * Space after `if`/`for`/`while` etc., and after commas.
74 | * No space after an opening parenthesis or before a closing parenthesis.
75 | * No space between a unary operator and its operand. One space between the
76 | operator and each operand of all other operators.
77 | * Line wrapping developed from Google C++ style guidelines, with minor
78 | modifications for compatibility with Microsoft's C# formatting tools:
79 | * In general, line continuations are indented 4 spaces.
80 | * Line breaks with braces (e.g. list initializers, lambdas, object
81 | initializers, etc) do not count as continuations.
82 | * For function definitions and calls, if the arguments do not all fit on
83 | one line they should be broken up onto multiple lines, with each
84 | subsequent line aligned with the first argument. If there is not enough
85 | room for this, arguments may instead be placed on subsequent lines with
86 | a four space indent. The code example below illustrates this.
87 |
88 | ### Example
89 |
90 | ```c#
91 | using System; // `using` goes at the top, outside the
92 | // namespace.
93 |
94 | namespace MyNamespace { // Namespaces are PascalCase.
95 | // Indent after namespace.
96 | public interface IMyInterface { // Interfaces start with 'I'
97 | public int Calculate(float value, float exp); // Methods are PascalCase
98 | // ...and space after comma.
99 | }
100 |
101 | public enum MyEnum { // Enumerations are PascalCase.
102 | Yes, // Enumerators are PascalCase.
103 | No,
104 | }
105 |
106 | public class MyClass { // Classes are PascalCase.
107 | public int Foo = 0; // Public member variables are
108 | // PascalCase.
109 | public bool NoCounting = false; // Field initializers are encouraged.
110 | private class Results {
111 | public int NumNegativeResults = 0;
112 | public int NumPositiveResults = 0;
113 | }
114 | private Results _results; // Private member variables are
115 | // _camelCase.
116 | public static int NumTimesCalled = 0;
117 | private const int _bar = 100; // const does not affect naming
118 | // convention.
119 | private int[] _someTable = { // Container initializers use a 2
120 | 2, 3, 4, // space indent.
121 | }
122 |
123 | public MyClass() {
124 | _results = new Results {
125 | NumNegativeResults = 1, // Object initializers use a 2 space
126 | NumPositiveResults = 1, // indent.
127 | };
128 | }
129 |
130 | public int CalculateValue(int mulNumber) { // No line break before opening brace.
131 | var resultValue = Foo * mulNumber; // Local variables are camelCase.
132 | NumTimesCalled++;
133 | Foo += _bar;
134 |
135 | if (!NoCounting) { // No space after unary operator and
136 | // space after 'if'.
137 | if (resultValue < 0) { // Braces used even when optional and
138 | // spaces around comparison operator.
139 | _results.NumNegativeResults++;
140 | } else if (resultValue > 0) { // No newline between brace and else.
141 | _results.NumPositiveResults++;
142 | }
143 | }
144 |
145 | return resultValue;
146 | }
147 |
148 | public void ExpressionBodies() {
149 | // For simple lambdas, fit on one line if possible, no brackets or braces required.
150 | Func increment = x => x + 1;
151 |
152 | // Closing brace aligns with first character on line that includes the opening brace.
153 | Func difference1 = (x, y) => {
154 | long diff = (long)x - y;
155 | return diff >= 0 ? diff : -diff;
156 | };
157 |
158 | // If defining after a continuation line break, indent the whole body.
159 | Func difference2 =
160 | (x, y) => {
161 | long diff = (long)x - y;
162 | return diff >= 0 ? diff : -diff;
163 | };
164 |
165 | // Inline lambda arguments also follow these rules. Prefer a leading newline before
166 | // groups of arguments if they include lambdas.
167 | CallWithDelegate(
168 | (x, y) => {
169 | long diff = (long)x - y;
170 | return diff >= 0 ? diff : -diff;
171 | });
172 | }
173 |
174 | void DoNothing() {} // Empty blocks may be concise.
175 |
176 | // If possible, wrap arguments by aligning newlines with the first argument.
177 | void AVeryLongFunctionNameThatCausesLineWrappingProblems(int longArgumentName,
178 | int p1, int p2) {}
179 |
180 | // If aligning argument lines with the first argument doesn't fit, or is difficult to
181 | // read, wrap all arguments on new lines with a 4 space indent.
182 | void AnotherLongFunctionNameThatCausesLineWrappingProblems(
183 | int longArgumentName, int longArgumentName2, int longArgumentName3) {}
184 |
185 | void CallingLongFunctionName() {
186 | int veryLongArgumentName = 1234;
187 | int shortArg = 1;
188 | // If possible, wrap arguments by aligning newlines with the first argument.
189 | AnotherLongFunctionNameThatCausesLineWrappingProblems(shortArg, shortArg,
190 | veryLongArgumentName);
191 | // If aligning argument lines with the first argument doesn't fit, or is difficult to
192 | // read, wrap all arguments on new lines with a 4 space indent.
193 | AnotherLongFunctionNameThatCausesLineWrappingProblems(
194 | veryLongArgumentName, veryLongArgumentName, veryLongArgumentName);
195 | }
196 | }
197 | }
198 | ```
199 |
200 | ## C# coding guidelines
201 |
202 | ### Constants
203 |
204 | * Variables and fields that can be made `const` should always be made `const`.
205 | * If `const` isn’t possible, `readonly` can be a suitable alternative.
206 | * Prefer named constants to magic numbers.
207 |
208 | ### IEnumerable vs IList vs IReadOnlyList
209 |
210 | * For inputs use the most restrictive collection type possible, for example
211 | `IReadOnlyCollection` / `IReadOnlyList` / `IEnumerable` as inputs to methods
212 | when the inputs should be immutable.
213 | * For outputs, if passing ownership of the returned container to the owner,
214 | prefer `IList` over `IEnumerable`. If not transferring ownership, prefer the
215 | most restrictive option.
216 |
217 | ### Generators vs containers
218 |
219 | * Use your best judgement, bearing in mind:
220 | * Generator code is often less readable than filling in a container.
221 | * Generator code can be more performant if the results are going to be
222 | processed lazily, e.g. when not all the results are needed.
223 | * Generator code that is directly turned into a container via `ToList()`
224 | will be less performant than filling in a container directly.
225 | * Generator code that is called multiple times will be considerably slower
226 | than iterating over a container multiple times.
227 |
228 | ### Property styles
229 |
230 | * For single line read-only properties, prefer expression body properties
231 | (`=>`) when possible.
232 | * For everything else, use the older `{ get; set; }` syntax.
233 |
234 | ### Expression body syntax
235 |
236 | For example:
237 |
238 | ```c#
239 | int SomeProperty => _someProperty
240 | ```
241 |
242 | * Judiciously use expression body syntax in lambdas and properties.
243 | * Don’t use on method definitions. This will be reviewed when C# 7 is live,
244 | which uses this syntax heavily.
245 | * As with methods and other scoped blocks of code, align the closing with the
246 | first character of the line that includes the opening brace. See sample code
247 | for examples.
248 |
249 | ### Structs and classes:
250 |
251 | * Structs are very different from classes:
252 |
253 | * Structs are always passed and returned by value.
254 | * Assigning a value to a member of a returned struct doesn’t modify the
255 | original - e.g. `transform.position.x = 10` doesn’t set the transform’s
256 | position.x to 10; `position` here is a property that returns a `Vector3`
257 | by value, so this just sets the x parameter of a copy of the original.
258 |
259 | * Almost always use a class.
260 |
261 | * Consider struct when the type can be treated like other value types - for
262 | example, if instances of the type are small and commonly short-lived or are
263 | commonly embedded in other objects. Good examples include Vector3,
264 | Quaternion and Bounds.
265 |
266 | * Note that this guidance may vary from team to team where, for example,
267 | performance issues might force the use of structs.
268 |
269 | ### Lambdas vs named methods
270 |
271 | * If a lambda is non-trivial (e.g. more than a couple of statements, excluding
272 | declarations), or is reused in multiple places, it should probably be a
273 | named method.
274 |
275 | ### Field initializers
276 |
277 | * Field initializers are generally encouraged.
278 |
279 | ### Extension methods
280 |
281 | * Only use an extension method when the source of the original class is not
282 | available, or else when changing the source is not feasible.
283 | * Only use an extension method if the functionality being added is a ‘core’
284 | general feature that would be appropriate to add to the source of the
285 | original class.
286 | * Note - if we have the source to the class being extended, and the
287 | maintainer of the original class does not want to add the function,
288 | prefer not using an extension method.
289 | * Only put extension methods into core libraries that are available
290 | everywhere - extensions that are only available in some code will become a
291 | readability issue.
292 | * Be aware that using extension methods always obfuscates the code, so err on
293 | the side of not adding them.
294 |
295 | ### ref and out
296 |
297 | * Use `out` for returns that are not also inputs.
298 | * Place `out` parameters after all other parameters in the method definition.
299 | * `ref` should be used rarely, when mutating an input is necessary.
300 | * Do not use `ref` as an optimisation for passing structs.
301 | * Do not use `ref` to pass a modifiable container into a method. `ref` is only
302 | required when the supplied container needs be replaced with an entirely
303 | different container instance.
304 |
305 | ### LINQ
306 |
307 | * In general, prefer single line LINQ calls and imperative code, rather than
308 | long chains of LINQ. Mixing imperative code and heavily chained LINQ is
309 | often hard to read.
310 | * Prefer member extension methods over SQL-style LINQ keywords - e.g. prefer
311 | `myList.Where(x)` to `myList where x`.
312 | * Avoid `Container.ForEach(...)` for anything longer than a single statement.
313 |
314 | ### Array vs List
315 |
316 | * In general, prefer `List<>` over arrays for public variables, properties,
317 | and return types (keeping in mind the guidance on `IList` / `IEnumerable` /
318 | `IReadOnlyList` above).
319 | * Prefer `List<>` when the size of the container can change.
320 | * Prefer arrays when the size of the container is fixed and known at
321 | construction time.
322 | * Prefer array for multidimensional arrays.
323 | * Note:
324 | * array and `List<>` both represent linear, contiguous containers.
325 | * Similar to C++ arrays vs `std::vector`, arrays are of fixed capacity,
326 | whereas `List<>` can be added to.
327 | * In some cases arrays are more performant, but in general `List<>` is
328 | more flexible.
329 |
330 | ### Folders and file locations
331 |
332 | * Be consistent with the project.
333 | * Prefer a flat structure where possible.
334 |
335 | ### Use of tuple as a return type
336 |
337 | * In general, prefer a named class type over `Tuple<>`, particularly when
338 | returning complex types.
339 |
340 | ### String interpolation vs `String.Format()` vs `String.Concat` vs `operator+`
341 |
342 | * In general, use whatever is easiest to read, particularly for logging and
343 | assert messages.
344 | * Be aware that chained `operator+` concatenations will be slower and cause
345 | significant memory churn.
346 | * If performance is a concern, `StringBuilder` will be faster for multiple
347 | string concatenations.
348 |
349 | ### `using`
350 |
351 | * Generally, don’t alias long typenames with `using`. Often this is a sign
352 | that a `Tuple<>` needs to be turned into a class.
353 | * e.g. `using RecordList = List>` should probably be a
354 | named class instead.
355 | * Be aware that `using` statements are only file scoped and so of limited use.
356 | Type aliases will not be available for external users.
357 |
358 | ### Object Initializer syntax
359 |
360 | For example:
361 |
362 | ```c#
363 | var x = new SomeClass {
364 | Property1 = value1,
365 | Property2 = value2,
366 | };
367 | ```
368 |
369 | * Object Initializer Syntax is fine for ‘plain old data’ types.
370 | * Avoid using this syntax for classes or structs with constructors.
371 | * If splitting across multiple lines, indent one block level.
372 |
373 | ### Namespace naming
374 |
375 | * In general, namespaces should be no more than 2 levels deep.
376 | * Don't force file/folder layout to match namespaces.
377 | * For shared library/module code, use namespaces. For leaf 'application' code,
378 | such as `unity_app`, namespaces are not necessary.
379 | * New top-level namespace names must be globally unique and recognizable.
380 |
381 | ### Default values/null returns for structs
382 |
383 | * Prefer returning a ‘success’ boolean value and a struct `out` value.
384 | * Where performance isn't a concern and the resulting code significantly more
385 | readable (e.g. chained null conditional operators vs deeply nested if
386 | statements) nullable structs are acceptable.
387 | * Notes:
388 |
389 | * Nullable structs are convenient, but reinforce the general ‘null is
390 | failure’ pattern Google prefers to avoid. We will investigate a
391 | `StatusOr` equivalent in the future, if there is enough demand.
392 |
393 | ### Removing from containers while iterating
394 |
395 | C# (like many other languages) does not provide an obvious mechanism for
396 | removing items from containers while iterating. There are a couple of options:
397 |
398 | * If all that is required is to remove items that satisfy some condition,
399 | `someList.RemoveAll(somePredicate)` is recommended.
400 | * If other work needs to be done in the iteration, `RemoveAll` may not be
401 | sufficient. A common alternative pattern is to create a new container
402 | outside of the loop, insert items to keep in the new container, and swap the
403 | original container with the new one at the end of iteration.
404 |
405 | ### Calling delegates
406 |
407 | * When calling a delegate, use `Invoke()` and use the null conditional
408 | operator - e.g. `SomeDelegate?.Invoke()`. This clearly marks the call at the
409 | callsite as ‘a delegate that is being called’. The null check is concise and
410 | robust against threading race conditions.
411 |
412 | ### The `var` keyword
413 |
414 | * Use of `var` is encouraged if it aids readability by avoiding type names
415 | that are noisy, obvious, or unimportant.
416 | * Encouraged:
417 |
418 | * When the type is obvious - e.g. `var apple = new Apple();`, or `var
419 | request = Factory.Create();`
420 | * For transient variables that are only passed directly to other methods -
421 | e.g. `var item = GetItem(); ProcessItem(item);`
422 |
423 | * Discouraged:
424 |
425 | * When working with basic types - e.g. `var success = true;`
426 | * When working with compiler-resolved built-in numeric types - e.g. `var
427 | number = 12 * ReturnsFloat();`
428 | * When users would clearly benefit from knowing the type - e.g. `var
429 | listOfItems = GetList();`
430 |
431 | ### Attributes
432 |
433 | * Attributes should appear on the line above the field, property, or method
434 | they are associated with, separated from the member by a newline.
435 | * Multiple attributes should be separated by newlines. This allows for easier
436 | adding and removing of attributes, and ensures each attribute is easy to
437 | search for.
438 |
439 | ### Argument Naming
440 |
441 | Derived from the Google C++ style guide.
442 |
443 | When the meaning of a function argument is nonobvious, consider one of the
444 | following remedies:
445 |
446 | * If the argument is a literal constant, and the same constant is used in
447 | multiple function calls in a way that tacitly assumes they're the same, use
448 | a named constant to make that constraint explicit, and to guarantee that it
449 | holds.
450 | * Consider changing the function signature to replace a `bool` argument with
451 | an `enum` argument. This will make the argument values self-describing.
452 | * Replace large or complex nested expressions with named variables.
453 | * Consider using
454 | [Named Arguments](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/named-and-optional-arguments)
455 | to clarify argument meanings at the call site.
456 | * For functions that have several configuration options, consider defining a
457 | single class or struct to hold all the options and pass an instance of that.
458 | This approach has several advantages. Options are referenced by name at the
459 | call site, which clarifies their meaning. It also reduces function argument
460 | count, which makes function calls easier to read and write. As an added
461 | benefit, call sites don't need to be changed when another option is added.
462 |
463 | Consider the following example:
464 |
465 | ```c#
466 | // Bad - what are these arguments?
467 | DecimalNumber product = CalculateProduct(values, 7, false, null);
468 | ```
469 |
470 | versus:
471 |
472 | ```c#
473 | // Good
474 | ProductOptions options = new ProductOptions();
475 | options.PrecisionDecimals = 7;
476 | options.UseCache = CacheUsage.DontUseCache;
477 | DecimalNumber product = CalculateProduct(values, options, completionDelegate: null);
478 | ```
479 |
--------------------------------------------------------------------------------
/intellij-java-google-style.xml:
--------------------------------------------------------------------------------
1 |
2 |
3 |
15 |
16 |
17 |
18 |
21 |
28 |
29 |
30 |
31 |
32 |
33 |
34 |
35 |
36 |
37 |
38 |
39 |
40 |
41 |
42 |
43 |
44 |
45 |
46 |
47 |
48 |
49 |
50 |
51 |
52 |
53 |
54 |
55 |
56 |
57 |
58 |
59 |
60 |
65 |
66 |
67 |
68 |
69 |
70 |
71 |
72 |
73 |
74 |
75 |
76 |
77 |
78 |
79 |
80 |
81 |
82 |
83 |
84 |
85 |
86 |
87 |
88 |
89 |
90 |
91 |
92 |
93 |
94 |
95 |
96 |
97 |
98 |
99 |
100 |
101 |
102 |
103 |
104 |
105 |
106 |
107 |
108 |
109 |
110 |
111 |
112 |
113 |
114 |
115 |
116 |
117 |
118 |
119 |
120 |
121 |
122 |
123 |
124 |
125 |
126 |
127 |
128 |
129 |
130 |
131 |
132 |
133 |
134 |
135 |
136 |
137 |
138 |
139 |
140 |
141 |
142 |
143 |
144 |
145 |
146 |
147 |
148 |
149 |
150 |
151 |
152 |
153 |
154 |
155 |
156 |
157 |
158 |
159 |
160 |
161 |
162 |
163 |
164 |
165 |
166 |
167 |
168 |
169 |
170 |
171 |
172 |
173 |
174 |
175 |
176 |
177 |
178 |
179 |
180 |
181 |
182 |
183 |
184 |
185 |
186 |
187 |
188 |
189 |
190 |
191 |
192 |
193 |
194 |
195 |
196 |
197 |
198 |
199 |
200 |
201 |
202 |
203 |
204 |
205 |
206 |
207 |
208 |
209 |
210 |
211 |
212 |
213 |
214 |
215 |
216 |
217 |
218 |
219 |
220 |
221 |
222 |
223 |
224 |
225 |
226 |
227 |
228 | xmlns:android
229 |
230 | ^$
231 |
232 |
233 |
234 |
235 |
236 |
237 |
238 |
239 | xmlns:.*
240 |
241 | ^$
242 |
243 |
244 | BY_NAME
245 |
246 |
247 |
248 |
249 |
250 |
251 | .*:id
252 |
253 | http://schemas.android.com/apk/res/android
254 |
255 |
256 |
257 |
258 |
259 |
260 |
261 |
262 | style
263 |
264 | ^$
265 |
266 |
267 |
268 |
269 |
270 |
271 |
272 |
273 | .*
274 |
275 | ^$
276 |
277 |
278 | BY_NAME
279 |
280 |
281 |
282 |
283 |
284 |
285 | .*:.*Style
286 |
287 | http://schemas.android.com/apk/res/android
288 |
289 |
290 | BY_NAME
291 |
292 |
293 |
294 |
295 |
296 |
297 | .*:layout_width
298 |
299 | http://schemas.android.com/apk/res/android
300 |
301 |
302 |
303 |
304 |
305 |
306 |
307 |
308 | .*:layout_height
309 |
310 | http://schemas.android.com/apk/res/android
311 |
312 |
313 |
314 |
315 |
316 |
317 |
318 |
319 | .*:layout_weight
320 |
321 | http://schemas.android.com/apk/res/android
322 |
323 |
324 |
325 |
326 |
327 |
328 |
329 |
330 | .*:layout_margin
331 |
332 | http://schemas.android.com/apk/res/android
333 |
334 |
335 |
336 |
337 |
338 |
339 |
340 |
341 | .*:layout_marginTop
342 |
343 | http://schemas.android.com/apk/res/android
344 |
345 |
346 |
347 |
348 |
349 |
350 |
351 |
352 | .*:layout_marginBottom
353 |
354 | http://schemas.android.com/apk/res/android
355 |
356 |
357 |
358 |
359 |
360 |
361 |
362 |
363 | .*:layout_marginStart
364 |
365 | http://schemas.android.com/apk/res/android
366 |
367 |
368 |
369 |
370 |
371 |
372 |
373 |
374 | .*:layout_marginEnd
375 |
376 | http://schemas.android.com/apk/res/android
377 |
378 |
379 |
380 |
381 |
382 |
383 |
384 |
385 | .*:layout_marginLeft
386 |
387 | http://schemas.android.com/apk/res/android
388 |
389 |
390 |
391 |
392 |
393 |
394 |
395 |
396 | .*:layout_marginRight
397 |
398 | http://schemas.android.com/apk/res/android
399 |
400 |
401 |
402 |
403 |
404 |
405 |
406 |
407 | .*:layout_.*
408 |
409 | http://schemas.android.com/apk/res/android
410 |
411 |
412 | BY_NAME
413 |
414 |
415 |
416 |
417 |
418 |
419 | .*:padding
420 |
421 | http://schemas.android.com/apk/res/android
422 |
423 |
424 |
425 |
426 |
427 |
428 |
429 |
430 | .*:paddingTop
431 |
432 | http://schemas.android.com/apk/res/android
433 |
434 |
435 |
436 |
437 |
438 |
439 |
440 |
441 | .*:paddingBottom
442 |
443 | http://schemas.android.com/apk/res/android
444 |
445 |
446 |
447 |
448 |
449 |
450 |
451 |
452 | .*:paddingStart
453 |
454 | http://schemas.android.com/apk/res/android
455 |
456 |
457 |
458 |
459 |
460 |
461 |
462 |
463 | .*:paddingEnd
464 |
465 | http://schemas.android.com/apk/res/android
466 |
467 |
468 |
469 |
470 |
471 |
472 |
473 |
474 | .*:paddingLeft
475 |
476 | http://schemas.android.com/apk/res/android
477 |
478 |
479 |
480 |
481 |
482 |
483 |
484 |
485 | .*:paddingRight
486 |
487 | http://schemas.android.com/apk/res/android
488 |
489 |
490 |
491 |
492 |
493 |
494 |
495 |
496 | .*
497 | http://schemas.android.com/apk/res/android
498 |
499 |
500 | BY_NAME
501 |
502 |
503 |
504 |
505 |
506 |
507 | .*
508 | http://schemas.android.com/apk/res-auto
509 |
510 |
511 | BY_NAME
512 |
513 |
514 |
515 |
516 |
517 |
518 | .*
519 | http://schemas.android.com/tools
520 |
521 |
522 | BY_NAME
523 |
524 |
525 |
526 |
527 |
528 |
529 | .*
530 | .*
531 |
532 |
533 | BY_NAME
534 |
535 |
536 |
537 |
538 |
539 |
540 |
541 |
542 |
543 |
544 |
545 |
546 |
547 |
548 |
549 |
550 |
551 |
552 |
553 |
554 |
555 |
556 |
557 |
558 |
559 |
560 |
561 |
562 |
563 |
564 |
565 |
566 |
567 |
568 |
569 |
570 |
571 |
572 |
573 |
574 |
575 |
576 |
577 |
578 |
579 |
580 |
581 |
582 |
583 |
584 |
585 |
586 |
587 |
588 |
589 |
590 |
591 |
592 |
593 |
594 |
595 |
596 |
597 |
598 |
599 |
--------------------------------------------------------------------------------
