StarMirror/styleguide
1
0
Fork 0
mirror of https://github.com/google/styleguide.git synced 2024-03-22 13:11:43 +08:00
Code Issues Projects Releases Wiki Activity

Guides as Asciidoc files

Browse Source
This commit is contained in:
Thibault Kruse 2015-10-26 14:41:27 +01:00
parent 2bfe5f4aa8
commit 5748e09d81
35 changed files with 15973 additions and 27184 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

340
Rguide.asciidoc Normal file
View File

@ -0,0 +1,340 @@
= Google's R Style Guide
:sectlinks:
R is a high-level programming language used primarily for statistical computing and graphics. The goal of the R Programming Style Guide is to make our R code easier to read, share, and verify. The rules below were designed in collaboration with the entire R user community at Google.
== Summary: R Style Rules
1. link:#filenames[File Names]: end in `.R`
2. link:#identifiers[Identifiers]: `variable.name` (or `variableName`), `FunctionName`, `kConstantName`
3. link:#linelength[Line Length]: maximum 80 characters
4. link:#indentation[Indentation]: two spaces, no tabs
5. link:#spacing[Spacing]
6. link:#curlybraces[Curly Braces]: first on same line, last on own line
7. link:#else[else]: Surround else with braces
8. link:#assignment[Assignment]: use `<-`, not `=`
9. link:#semicolons[Semicolons]: don't use them
10. link:#generallayout[General Layout and Ordering]
11. link:#comments[Commenting Guidelines]: all comments begin with `#` followed by a space; inline comments need two spaces before the `#`
12. link:#functiondefinition[Function Definitions and Calls]
13. link:#functiondocumentation[Function Documentation]
14. link:#examplefunction[Example Function]
15. link:#todo[TODO Style]: `TODO(username)`
== Summary: R Language Rules
1. link:#attach[`attach`]: avoid using it
2. link:#functionlanguage[Functions]: errors should be raised using `stop()`
3. link:#object[Objects and Methods]: avoid S4 objects and methods when possible; never mix S3 and S4
=== Notation and Naming
[[filenames]]
==== File Names
File names should end in `.R` and, of course, be meaningful. +
GOOD: `predict_ad_revenue.R` +
BAD: `foo.R`
[[identifiers]]
==== Identifiers
Don't use underscores ( `_` ) or hyphens ( `-` ) in identifiers. Identifiers should be named according to the following conventions. The preferred form for variable names is all lower case letters and words separated with dots (`variable.name`), but `variableName` is also accepted; function names have initial capital letters and no dots (`FunctionName`); constants are named like functions but with an initial `k`.
* `variable.name` is preferred, `variableName` is accepted +
GOOD: `avg.clicks` +
OK: `avgClicks` +
BAD: `avg_Clicks`
* `FunctionName ` +
GOOD: `CalculateAvgClicks` +
BAD: `calculate_avg_clicks `, `calculateAvgClicks` +
Make function names verbs. +
_Exception: When creating a classed object, the function name (constructor) and class should match (e.g., lm)._
* `kConstantName `
=== Syntax
[[linelength]]
==== Line Length
The maximum line length is 80 characters.
[[indentation]]
==== Indentation
When indenting your code, use two spaces. Never use tabs or mix tabs and spaces. +
_Exception: When a line break occurs inside parentheses, align the wrapped line with the first character inside the parenthesis._
[[spacing]]
==== Spacing
Place spaces around all binary operators (`=`, `+`, `-`, `<-`, etc.). +
_Exception: Spaces around `=`'s are optional when passing parameters in a function call._
Do not place a space before a comma, but always place one after a comma. +
+
GOOD:
-----------------------------------------------------------
tab.prior <- table(df[df$days.from.opt < 0, "campaign.id"])
total <- sum(x[, 1])
total <- sum(x[1, ])
-----------------------------------------------------------
BAD:
-------------------------------------------------------------------------------------------
tab.prior <- table(df[df$days.from.opt<0, "campaign.id"]) # Needs spaces around '<'
tab.prior <- table(df[df$days.from.opt < 0,"campaign.id"]) # Needs a space after the comma
tab.prior<- table(df[df$days.from.opt < 0, "campaign.id"]) # Needs a space before <-
tab.prior<-table(df[df$days.from.opt < 0, "campaign.id"]) # Needs spaces around <-
total <- sum(x[,1]) # Needs a space after the comma
total <- sum(x[ ,1]) # Needs a space after the comma, not before
-------------------------------------------------------------------------------------------
Place a space before left parenthesis, except in a function call.
GOOD: +
`if (debug)`
BAD: +
`if(debug)`
Extra spacing (i.e., more than one space in a row) is okay if it improves alignment of equals signs or arrows (`<-`).
-----------------------------------------------------------------
plot(x = x.coord,
y = data.mat[, MakeColName(metric, ptiles[1], "roiOpt")],
ylim = ylim,
xlab = "dates",
ylab = metric,
main = (paste(metric, " for 3 samples ", sep = "")))
-----------------------------------------------------------------
Do not place spaces around code in parentheses or square brackets. +
_Exception: Always place a space after a comma._
GOOD:
----------
if (debug)
x[1, ]
----------
BAD:
---------------------------------------
if ( debug ) # No spaces around debug
x[1,] # Needs a space after the comma
---------------------------------------
[[curlybraces]]
==== Curly Braces
An opening curly brace should never go on its own line; a closing curly brace should always go on its own line. You may omit curly braces when a block consists of a single statement; however, you must _consistently_ either use or not use curly braces for single statement blocks.
--------------------
if (is.null(ylim)) {
ylim <- c(0, 0.06)
}
--------------------
xor (but not both)
--------------------
if (is.null(ylim))
ylim <- c(0, 0.06)
--------------------
Always begin the body of a block on a new line.
BAD: +
` if (is.null(ylim)) ylim <- c(0, 0.06)` +
` if (is.null(ylim)) {ylim <- c(0, 0.06)} `
[[else]]
==== Surround else with braces
An `else` statement should always be surrounded on the same line by curly braces.
-------------------
if (condition) {
one or more lines
} else {
one or more lines
}
-------------------
BAD: +
-------------------
if (condition) {
one or more lines
}
else {
one or more lines
}
-------------------
BAD: +
--------------
if (condition)
one line
else
one line
--------------
[[assignment]]
==== Assignment
Use `<-`, not `=`, for assignment.
GOOD: +
` x <- 5 `
BAD: +
` x = 5`
[[semicolons]]
==== Semicolons
Do not terminate your lines with semicolons or use semicolons to put more than one command on the same line. (Semicolons are not necessary, and are omitted for consistency with other Google style guides.)
=== Organization
[[generallayout]]
==== General Layout and Ordering
If everyone uses the same general ordering, we'll be able to read and understand each other's scripts faster and more easily.
1. Copyright statement comment
2. Author comment
3. File description comment, including purpose of program, inputs, and outputs
4. `source()` and `library()` statements
5. Function definitions
6. Executed statements, if applicable (e.g., ` print`, `plot`)
Unit tests should go in a separate file named `originalfilename_test.R`.
[[comments]]
==== Commenting Guidelines
Comment your code. Entire commented lines should begin with `#` and one space.
Short comments can be placed after code preceded by two spaces, `#`, and then one space.
-----------------------------------------------------------------
# Create histogram of frequency of campaigns by pct budget spent.
hist(df$pct.spent,
breaks = "scott", # method for choosing number of buckets
main = "Histogram: fraction budget spent by campaignid",
xlab = "Fraction of budget spent",
ylab = "Frequency (count of campaignids)")
-----------------------------------------------------------------
[[functiondefinition]]
==== Function Definitions and Calls
Function definitions should first list arguments without default values, followed by those with default values.
In both function definitions and function calls, multiple arguments per line are allowed; line breaks are only allowed between assignments. +
GOOD:
-------------------------------------------------
PredictCTR <- function(query, property, num.days,
show.plot = TRUE)
-------------------------------------------------
BAD:
-------------------------------------------------------------
PredictCTR <- function(query, property, num.days, show.plot =
TRUE)
-------------------------------------------------------------
Ideally, unit tests should serve as sample function calls (for shared library routines).
[[functiondocumentation]]
==== Function Documentation
Functions should contain a comments section immediately below the function definition line. These comments should consist of a one-sentence description of the function; a list of the function's arguments, denoted by `Args:`, with a description of each (including the data type); and a description of the return value, denoted by `Returns:`. The comments should be descriptive enough that a caller can use the function without reading any of the function's code.
[[examplefunction]]
==== Example Function
-------------------------------------------------------------------------------
CalculateSampleCovariance <- function(x, y, verbose = TRUE) {
# Computes the sample covariance between two vectors.
#
# Args:
# x: One of two vectors whose sample covariance is to be calculated.
# y: The other vector. x and y must have the same length, greater than one,
# with no missing values.
# verbose: If TRUE, prints sample covariance; if not, not. Default is TRUE.
#
# Returns:
# The sample covariance between x and y.
n <- length(x)
# Error handling
if (n <= 1 || n != length(y)) {
stop("Arguments x and y have different lengths: ",
length(x), " and ", length(y), ".")
}
if (TRUE %in% is.na(x) || TRUE %in% is.na(y)) {
stop(" Arguments x and y must not have missing values.")
}
covariance <- var(x, y)
if (verbose)
cat("Covariance = ", round(covariance, 4), ".\n", sep = "")
return(covariance)
}
-------------------------------------------------------------------------------
[[todo]]
==== TODO Style
Use a consistent style for TODOs throughout your code. +
`TODO(username): Explicit description of action to be taken`
=== Language
[[attach]]
==== Attach
The possibilities for creating errors when using `attach` are numerous. Avoid it.
[[functionlanguage]]
==== Functions
Errors should be raised using `stop()`.
[[object]]
==== Objects and Methods
The S language has two object systems, S3 and S4, both of which are available in R. S3 methods are more interactive and flexible, whereas S4 methods are more formal and rigorous. (For an illustration of the two systems, see Thomas Lumley's "Programmer's Niche: A Simple Class, in S3 and S4" in R News 4/1, 2004, pgs. 33 - 36: http://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf.)
Use S3 objects and methods unless there is a strong reason to use S4 objects or methods. A primary justification for an S4 object would be to use objects directly in C++ code. A primary justification for an S4 generic/method would be to dispatch on two arguments.
Avoid mixing S3 and S4: S4 methods ignore S3 inheritance and vice-versa.
=== Exceptions
The coding conventions described above should be followed, unless there is good reason to do otherwise. Exceptions include legacy code and modifying third-party code.
=== Parting Words
Use common sense and BE CONSISTENT.
If you are editing code, take a few minutes to look at the code around you and determine its style. If others use spaces around their `if ` clauses, you should, too. If their comments have little boxes of stars around them, make your comments have little boxes of stars around them, too.
The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on _what_ you are saying, rather than on _how_ you are saying it. We present global style rules here so people know the vocabulary. But local style is also important. If code you add to a file looks drastically different from the existing code around it, the discontinuity will throw readers out of their rhythm when they go to read it. Try to avoid this.
OK, enough writing about writing code; the code itself is much more interesting. Have fun!
=== References
http://www.maths.lth.se/help/R/RCC/ - R Coding Conventions
http://ess.r-project.org/ - For emacs users. This runs R in your emacs and has an emacs mode.

447
Rguide.xml
View File

@ -1,447 +0,0 @@
<?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<link rel="stylesheet" type="text/css" href="styleguide.css"/>
<title>Google's R Style Guide</title>
</head>
<body>
<h1>Google's R Style Guide</h1>
<p>
R is a high-level programming language used primarily for
statistical computing and graphics. The goal of the R
Programming Style Guide is to make our R code easier to read,
share, and verify. The rules below were designed in
collaboration with the entire R user community at Google.
</p>
<h2>Summary: R Style Rules</h2>
<ol>
<li><a href="#filenames">File Names</a>: end in <code>.R</code></li>
<li><a href="#identifiers">Identifiers</a>: <code>variable.name</code>
(or <code>variableName</code>),
<code>FunctionName</code>, <code>kConstantName</code></li>
<li><a href="#linelength">Line Length</a>: maximum 80 characters</li>
<li><a href="#indentation">Indentation</a>: two spaces, no tabs</li>
<li><a href="#spacing">Spacing</a></li>
<li><a href="#curlybraces">Curly Braces</a>: first on same line, last on
own line</li>
<li><a href="#else">else</a>: Surround else with braces </li>
<li><a href="#assignment">Assignment</a>: use <code>&lt;-</code>, not
<code>=</code></li>
<li><a href="#semicolons">Semicolons</a>: don't use them</li>
<li><a href="#generallayout"> General Layout and Ordering</a></li>
<li><a href="#comments"> Commenting Guidelines</a>: all comments begin
with <code>#</code> followed by a space; inline comments need two
spaces before the <code>#</code></li>
<li><a href="#functiondefinition">Function Definitions and Calls</a></li>
<li><a href="#functiondocumentation"> Function Documentation</a></li>
<li><a href="#examplefunction"> Example Function</a></li>
<li><a href="#todo"> TODO Style</a>: <code>TODO(username)</code></li>
</ol>
<h2>Summary: R Language Rules</h2>
<ol>
<li><a href="#attach"> <code>attach</code></a>: avoid using it</li>
<li><a href="#functionlanguage"> Functions</a>:
errors should be raised using <code>stop()</code></li>
<li><a href="#object"> Objects and Methods</a>: avoid S4 objects and
methods when possible; never mix S3 and S4 </li>
</ol>
<h3>Notation and Naming</h3>
<h4 id="filenames">File Names</h4>
<p>
File names should end in <code>.R</code> and, of course, be
meaningful.
<br/> GOOD: <code>predict_ad_revenue.R</code>
<br/> BAD: <code><span style="color:red">foo.R</span></code>
</p>
<h4 id="identifiers">Identifiers</h4>
<p>
Don't use underscores ( <code>_</code> ) or hyphens
( <code>-</code> ) in identifiers.
Identifiers should be named according to the following conventions.
The preferred form for variable names is all lower case
letters and words separated with dots
(<code>variable.name</code>), but <code>variableName</code>
is also accepted;
function names have initial capital letters and no dots
(<code>FunctionName</code>);
constants are named like functions but with an initial
<code>k</code>.
</p>
<ul>
<li><code>variable.name</code> is preferred, <code>variableName</code> is accepted
<br/> GOOD: <code>avg.clicks</code>
<br/> OK: <code>avgClicks</code>
<br/> BAD: <code><span style="color:red">avg_Clicks</span></code>
</li>
<li><code>FunctionName </code>
<br/> GOOD: <code>CalculateAvgClicks</code>
<br/> BAD: <code><span style="color:red">calculate_avg_clicks
</span></code>,
<code><span style="color:red">calculateAvgClicks</span></code>
<br/> Make function names verbs.
<br/><em>Exception: When creating a classed object, the function
name (constructor) and class should match (e.g., lm).</em></li>
<li><code>kConstantName </code></li>
</ul>
<h3>Syntax</h3>
<h4 id="linelength">Line Length</h4>
<p>
The maximum line length is 80 characters.
</p>
<h4 id="indentation">Indentation</h4>
<p>
When indenting your code, use two spaces. Never use tabs or mix
tabs and spaces.
<br/><em>Exception: When a line break occurs inside parentheses,
align the wrapped line with the first character inside the
parenthesis.</em>
</p>
<h4 id="spacing">Spacing</h4>
<p>
Place spaces around all binary operators (<code>=</code>,
<code>+</code>, <code>-</code>, <code>&lt;-</code>, etc.).
<br/><em> Exception: Spaces around <code>=</code>'s are
optional when passing parameters in a function call.</em>
</p>
<p>
Do not place a space before a comma, but always place one after a
comma.
<br/><br/> GOOD:
</p>
<pre>tab.prior &lt;- table(df[df$days.from.opt &lt; 0, "campaign.id"])
total &lt;- sum(x[, 1])
total &lt;- sum(x[1, ])</pre>
<p>
BAD:
</p>
<pre><span style="color:red">tab.prior &lt;- table(df[df$days.from.opt&lt;0, "campaign.id"]) # Needs spaces around '&lt;'
tab.prior &lt;- table(df[df$days.from.opt &lt; 0,"campaign.id"]) # Needs a space after the comma
tab.prior&lt;- table(df[df$days.from.opt &lt; 0, "campaign.id"]) # Needs a space before &lt;-
tab.prior&lt;-table(df[df$days.from.opt &lt; 0, "campaign.id"]) # Needs spaces around &lt;-
total &lt;- sum(x[,1]) # Needs a space after the comma
total &lt;- sum(x[ ,1]) # Needs a space after the comma, not before</span>
</pre>
<p>
Place a space before left parenthesis, except in a function call.
</p>
<p>
GOOD:
<br/><code>if (debug)</code>
</p>
<p>
BAD:
<br/><code><span style="color:red">if(debug)</span></code>
</p>
<p>
Extra spacing (i.e., more than one space in a row) is okay if it
improves alignment of equals signs or arrows (<code>&lt;-</code>).
</p>
<pre>plot(x = x.coord,
y = data.mat[, MakeColName(metric, ptiles[1], "roiOpt")],
ylim = ylim,
xlab = "dates",
ylab = metric,
main = (paste(metric, " for 3 samples ", sep = "")))
</pre>
<p>
Do not place spaces around code in parentheses or square brackets.
<br/><em> Exception: Always place a space after a comma.</em>
</p>
<p>
GOOD:</p><pre>if (debug)
x[1, ]</pre>
<p>
BAD:</p><pre><span style="color:red">if ( debug ) # No spaces around debug
x[1,] # Needs a space after the comma </span></pre>
<h4 id="curlybraces">Curly Braces</h4>
<p>
An opening curly brace should never go on its own line; a closing
curly brace should always go on its own line. You may omit curly
braces when a block consists of a single statement; however, you
must <em>consistently</em> either use or not use curly braces for
single statement blocks.
</p>
<pre>
if (is.null(ylim)) {
ylim &lt;- c(0, 0.06)
}</pre>
<p>
xor (but not both)
</p>
<pre>
if (is.null(ylim))
ylim &lt;- c(0, 0.06)</pre>
<p>
Always begin the body of a block on a new line.
</p>
<p>
BAD:
<br/><code><span style="color:red"> if (is.null(ylim))
ylim &lt;- c(0, 0.06)</span></code>
<br/><code><span style="color:red"> if (is.null(ylim))
{ylim &lt;- c(0, 0.06)} </span></code>
</p>
<h4 id="else">Surround else with braces</h4>
<p>
An <code>else</code> statement should always be surrounded on the
same line by curly braces.</p>
<pre>
if (condition) {
one or more lines
} else {
one or more lines
}
</pre>
<p>
BAD:<br/>
</p>
<pre style="color:red">
if (condition) {
one or more lines
}
else {
one or more lines
}
</pre>
<p>
BAD:<br/>
</p>
<pre style="color:red">
if (condition)
one line
else
one line
</pre>
<h4 id="assignment">Assignment</h4>
<p>
Use <code>&lt;-</code>, not <code>=</code>, for assignment.
</p>
<p>
GOOD:
<br/><code> x &lt;- 5 </code>
</p>
<p>
BAD:
<br/><code><span style="color:red"> x = 5</span></code>
</p>
<h4 id="semicolons">Semicolons</h4>
<p>
Do not terminate your lines with semicolons or use semicolons to
put more than one command on the same line. (Semicolons are not
necessary, and are omitted for consistency with other Google style
guides.)
</p>
<h3> Organization </h3>
<h4 id="generallayout">General Layout and Ordering</h4>
<p>
If everyone uses the same general ordering, we'll be able to
read and understand each other's scripts faster and more easily.
</p>
<ol>
<li>Copyright statement comment </li>
<li>Author comment</li>
<li>File description comment, including purpose of
program, inputs, and outputs</li>
<li><code>source()</code> and <code>library()</code> statements</li>
<li>Function definitions</li>
<li>Executed statements, if applicable (e.g.,
<code> print</code>, <code>plot</code>)</li>
</ol>
<p>
Unit tests should go in a separate file named
<code>originalfilename_test.R</code>.
</p>
<h4 id="comments">Commenting Guidelines</h4>
<p>
Comment your code. Entire commented lines should begin with
<code>#</code> and one space.
</p>
<p>
Short comments can be placed after code preceded by two spaces,
<code>#</code>, and then one space.
</p>
<pre># Create histogram of frequency of campaigns by pct budget spent.
hist(df$pct.spent,
breaks = "scott", # method for choosing number of buckets
main = "Histogram: fraction budget spent by campaignid",
xlab = "Fraction of budget spent",
ylab = "Frequency (count of campaignids)")
</pre>
<h4 id="functiondefinition">Function Definitions and
Calls</h4>
<p>
Function definitions should first list arguments without default
values, followed by those with default values.
</p>
<p>
In both function definitions and function calls, multiple
arguments per line are allowed; line breaks are only allowed
between assignments.
<br/>GOOD:
</p>
<pre>PredictCTR &lt;- function(query, property, num.days,
show.plot = TRUE)
</pre>
BAD:
<pre><span style="color:red">PredictCTR &lt;- function(query, property, num.days, show.plot =
TRUE)
</span></pre>
<p> Ideally, unit tests should serve as sample function calls (for
shared library routines).
</p>
<h4 id="functiondocumentation">Function Documentation</h4>
<p> Functions should contain a comments section immediately below
the function definition line. These comments should consist of a
one-sentence description of the function; a list of the function's
arguments, denoted by <code>Args:</code>, with a description of
each (including the data type); and a description of the return
value, denoted by <code>Returns:</code>. The comments should be
descriptive enough that a caller can use the function without
reading any of the function's code.
</p>
<h4 id="examplefunction">Example Function</h4>
<pre>
CalculateSampleCovariance &lt;- function(x, y, verbose = TRUE) {
# Computes the sample covariance between two vectors.
#
# Args:
# x: One of two vectors whose sample covariance is to be calculated.
# y: The other vector. x and y must have the same length, greater than one,
# with no missing values.
# verbose: If TRUE, prints sample covariance; if not, not. Default is TRUE.
#
# Returns:
# The sample covariance between x and y.
n &lt;- length(x)
# Error handling
if (n &lt;= 1 || n != length(y)) {
stop("Arguments x and y have different lengths: ",
length(x), " and ", length(y), ".")
}
if (TRUE %in% is.na(x) || TRUE %in% is.na(y)) {
stop(" Arguments x and y must not have missing values.")
}
covariance &lt;- var(x, y)
if (verbose)
cat("Covariance = ", round(covariance, 4), ".\n", sep = "")
return(covariance)
}
</pre>
<h4 id="todo">TODO Style</h4>
<p>
Use a consistent style for TODOs throughout your code.
<br/><code>TODO(username): Explicit description of action to
be taken</code>
</p>
<h3> Language </h3>
<h4 id="attach">Attach</h4>
<p> The possibilities for creating errors when using
<code>attach</code> are numerous. Avoid it.</p>
<h4 id="functionlanguage">Functions</h4>
<p> Errors should be raised using <code>stop()</code>.</p>
<h4 id="object">Objects and Methods</h4>
<p> The S language has two object systems, S3 and S4, both of which
are available in R. S3 methods are more interactive and flexible,
whereas S4 methods are more formal and rigorous. (For an illustration
of the two systems, see Thomas Lumley's
"Programmer's Niche: A Simple
Class, in S3 and S4" in R News 4/1, 2004, pgs. 33 - 36:
<a href="http://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf">
http://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf</a>.)
</p>
<p>Use S3 objects and methods unless there is a strong reason to use
S4 objects or methods. A primary justification for an S4 object
would be to use objects directly in C++ code. A primary
justification for an S4 generic/method would be to dispatch on two
arguments.
</p>
<p>Avoid mixing S3 and S4: S4 methods ignore S3 inheritance and
vice-versa.
</p>
<h3>Exceptions</h3>
<p>
The coding conventions described above should be followed, unless
there is good reason to do otherwise. Exceptions include legacy
code and modifying third-party code.
</p>
<h3>Parting Words</h3>
<p>
Use common sense and BE CONSISTENT.
</p>
<p>
If you are editing code, take a few minutes to look at the code around
you and determine its style. If others use spaces around their
<code>if </code>
clauses, you should, too. If their comments have little boxes of stars
around them, make your comments have little boxes of stars around them,
too.
</p>
<p>
The point of having style guidelines is to have a common vocabulary of
coding so people can concentrate on <em>what</em> you are saying,
rather than on <em>how</em> you are saying it. We present global style
rules here so people
know the vocabulary. But local style is also important. If code you add
to a file looks drastically different from the existing code around it,
the discontinuity will throw readers out of their rhythm when they go to
read it. Try to avoid this.
</p>
<p>
OK, enough writing about writing code; the code itself is much more
interesting. Have fun!
</p>
<h3>References</h3>
<p>
<a href="http://www.maths.lth.se/help/R/RCC/">
http://www.maths.lth.se/help/R/RCC/</a> - R Coding Conventions
</p>
<p>
<a href="http://ess.r-project.org/">http://ess.r-project.org/</a> - For
emacs users. This runs R in your emacs and has an emacs mode.
</p>
</body>
</html>

328
angularjs-google-style.asciidoc Normal file
View File

@ -0,0 +1,328 @@
= An AngularJS Style Guide for Closure Users at Google
:sectlinks:
This is the external version of a document that was primarily written for Google engineers. It describes a recommended style for AngularJS apps that use Closure, as used internally at Google. Members of the broader AngularJS community should feel free to apply (or not apply) these recommendations, as relevant to their own use cases.
This document describes style for AngularJS apps in google3. This guide supplements and extends the http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml[Google JavaScript Style Guide].
**Style Note**: Examples on the AngularJS external webpage, and many external apps, are written in a style that freely uses closures, favors functional inheritance, and does not often use http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml?showone=JavaScript_Types#JavaScript_Types[JavaScript types]. Google follows a more rigorous Javascript style to support JSCompiler optimizations and large code bases - see the javascript-style mailing list. This is not an Angular-specific issue, and is not discussed further in this style guide. (But if you want further reading: http://martinfowler.com/bliki/Lambda.html[Martin Fowler on closures], http://jibbering.com/faq/notes/closures/[much longer description], appendix A of the http://books.google.com/books/about/Closure_The_Definitive_Guide.html?id=p7uyWPcVGZsC[closure book] has a good description of inheritance patterns and why it prefers pseudoclassical, http://books.google.com/books/about/JavaScript.html?id=PXa2bby0oQ0C[Javascript, the Good Parts] as a counter.)
===== 1 Angular Language Rules
* link:#googprovide[Manage dependencies with Closure's goog.require and goog.provide]
* link:#modules[Modules]
* link:#moduledeps[Modules should reference other modules using the "name" property]
* link:#externs[Use the provided Angular externs file]
* link:#compilerflags[JSCompiler Flags]
* link:#controllers[Controllers and Scopes]
* link:#directives[Directives]
* link:#services[Services]
===== 2 Angular Style Rules
* link:#dollarsign[Reserve $ for Angular properties and services]
* link:#customelements[Custom elements.]
===== 3 Angular Tips, Tricks, and Best Practices
* link:#testing[Testing]
* link:#appstructure[Consider using the Best Practices for App Structure]
* link:#scopeinheritance[Be aware of how scope inheritance works]
* link:#nginject[Use @ngInject for easy dependency injection compilation]
===== link:#bestpractices[4 Best practices links and docs]
== 1 Angular Language Rules
[[googprovide]]
=== Manage dependencies with Closure's goog.require and goog.provide
Choose a namespace for your project, and use goog.provide and goog.require.
----------------------------------------
goog.provide('hello.about.AboutCtrl');
goog.provide('hello.versions.Versions');
----------------------------------------
*Why?* Google BUILD rules integrate nicely with closure provide/require.
[[modules]]
=== Modules
Your main application module should be in your root client directory. A module should never be altered other than the one where it is defined.
Modules may either be defined in the same file as their components (this works well for a module that contains exactly one service) or in a separate file for wiring pieces together.
*Why?* A module should be consistent for anyone that wants to include it as a reusable component. If a module can mean different things depending on which files are included, it is not consistent.
[[moduledeps]]
=== Modules should reference other modules using the Angular Module's "name" property
For example:
-----------------------------------------------------------------------------
// file submodulea.js:
goog.provide('my.submoduleA');
my.submoduleA = angular.module('my.submoduleA', []);
// ...
// file app.js
goog.require('my.submoduleA');
Yes: my.application.module = angular.module('hello', [my.submoduleA.name]);
No: my.application.module = angular.module('hello', ['my.submoduleA']);
-----------------------------------------------------------------------------
*Why?* Using a property of my.submoduleA prevents Closure presubmit failures complaining that the file is required but never used. Using the .name property avoids duplicating strings.
[[externs]]
=== Use a common externs file
This maximally allows the JS compiler to enforce type safety in the presence of externally provided types from Angular, and means you don't have to worry about Angular vars being obfuscated in a confusing way.
Note to readers outside Google: the current externs file is located in an internal-to-Google directory, but an example can be found on github https://github.com/angular/angular.js/pull/4722[here].
[[compilerflags]]
=== JSCompiler Flags
**Reminder**: According to the JS style guide, customer facing code must be compiled.
**Recommended**: Use the JSCompiler (the closure compiler that works with js_binary by default) and ANGULAR_COMPILER_FLAGS_FULL from //javascript/angular/build_defs/build_defs for your base flags.
Note - if you are using @export for methods, you will need to add the compiler flag
---------------------
"--generate_exports",
---------------------
If you are using @export for properties, you will need to add the flags:
---------------------------------------------------
"--generate_exports",
"--remove_unused_prototype_props_in_externs=false",
"--export_local_property_definitions",
---------------------------------------------------
[[controllers]]
=== Controllers and Scopes
Controllers are classes. Methods should be defined on MyCtrl.prototype. See http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml?showone=Method_and_property_definitions#Method_and_property_definitions[the JavaScript style guide]
Google Angular applications should use the *'controller as'* style to export the controller onto the scope. This is fully implemented in Angular 1.2 and can be mimicked in pre-Angular 1.2 builds.
Pre Angular 1.2, this looks like:
-----------------------------------------------------------------------------
/**
* Home controller.
*
* @param {!angular.Scope} $scope
* @constructor
* @ngInject
* @export
*/
hello.mainpage.HomeCtrl = function($scope) {
/** @export */
$scope.homeCtrl = this; // This is a bridge until Angular 1.2 controller-as
/**
* @type {string}
* @export
*/
this.myColor = 'blue';
};
/**
* @param {number} a
* @param {number} b
* @export
*/
hello.mainpage.HomeCtrl.prototype.add = function(a, b) {
return a + b;
};
-----------------------------------------------------------------------------
And the template:
----------------------------------------------------------
<div ng-controller="hello.mainpage.HomeCtrl"/>
<span ng-class="homeCtrl.myColor">I'm in a color!</span>
<span>{{homeCtrl.add(5, 6)}}</span>
</div>
----------------------------------------------------------
After Angular 1.2, this looks like:
--------------------------------------------------------
/**
* Home controller.
*
* @constructor
* @ngInject
* @export
*/
hello.mainpage.HomeCtrl = function() {
/**
* @type {string}
* @export
*/
this.myColor = 'blue';
};
/**
* @param {number} a
* @param {number} b
* @export
*/
hello.mainpage.HomeCtrl.prototype.add = function(a, b) {
return a + b;
};
--------------------------------------------------------
If you are compiling with property renaming, expose properties and methods using the @export annotation. Remember to @export the constructor as well.
And in the template:
----------------------------------------------------------
<div ng-controller="hello.mainpage.HomeCtrl as homeCtrl"/>
<span ng-class="homeCtrl.myColor">I'm in a color!</span>
<span>{{homeCtrl.add(5, 6)}}</span>
</div>
----------------------------------------------------------
*Why?* Putting methods and properties directly onto the controller, instead of building up a scope object, fits better with the Google Closure class style. Additionally, using 'controller as' makes it obvious which controller you are accessing when multiple controllers apply to an element. Since there is always a '.' in the bindings, you don't have to worry about prototypal inheritance masking primitives.
[[directives]]
=== Directives
All DOM manipulation should be done inside directives. Directives should be kept small and use composition. Files defining directives should goog.provide a static function which returns the directive definition object.
-----------------------------------------------------------
goog.provide('hello.pane.paneDirective');
/**
* Description and usage
* @return {angular.Directive} Directive definition object.
*/
hello.pane.paneDirective = function() {
// ...
};
-----------------------------------------------------------
**Exception**: DOM manipulation may occur in services for DOM elements disconnected from the rest of the view, e.g. dialogs or keyboard shortcuts.
[[services]]
=== Services
Services registered on the module with `module.service` are classes. Use `module.service` instead of `module.provider` or `module.factory` unless you need to do initialization beyond just creating a new instance of the class.
-----------------------------------------------------------
/**
* @param {!angular.$http} $http The Angular http service.
* @constructor
*/
hello.request.Request = function($http) {
/** @type {!angular.$http} */
this.http_ = $http;
};
hello.request.Request.prototype.get = function() {/*...*/};
-----------------------------------------------------------
In the module:
-------------------------------------------------
module.service('request', hello.request.Request);
-------------------------------------------------
== 2 Angular Style Rules
[[dollarsign]]
=== Reserve $ for Angular properties and services
Do not use $ to prepend your own object properties and service identifiers. Consider this style of naming reserved by AngularJS and jQuery.
Yes:
--------------------------------------------------------
$scope.myModel = { value: 'foo' }
myModule.service('myService', function() { /*...*/ });
var MyCtrl = function($http) {this.http_ = $http;};
--------------------------------------------------------
No:
-------------------------------------------------------------
$scope.$myModel = { value: 'foo' } // BAD
$scope.myModel = { $value: 'foo' } // BAD
myModule.service('$myService', function() { ... }); // BAD
var MyCtrl = function($http) {this.$http_ = $http;}; // BAD
-------------------------------------------------------------
*Why?* It's useful to distinguish between Angular / jQuery builtins and things you add yourself. In addition, $ is not an acceptable character for variables names in the JS style guide.
[[customelements]]
=== Custom elements
For custom elements (e.g. `<ng-include src="template"></ng-include>`), IE8 requires special support (html5shiv-like hacks) to enable css styling. Be aware of this restriction in apps targeting old versions of IE.
== 3 Angular Tips, Tricks, and Best Practices
These are not strict style guide rules, but are placed here as reference for folks getting started with Angular at Google.
[[testing]]
=== Testing
Angular is designed for test-driven development.
The recommended unit testing setup is Jasmine + Karma (though you could use closure tests or js_test)
Angular provides easy adapters to load modules and use the injector in Jasmine tests.
* http://docs.angularjs.org/api/angular.mock.module[module]
* http://docs.angularjs.org/api/angular.mock.inject[inject]
[[appstructure]]
=== Consider using the Best Practices for App Structure
This https://docs.google.com/document/d/1XXMvReO8-Awi1EZXAXS4PzDzdNvV6pGcuaF4Q9821Es/pub[directory structure doc] describes how to structure your application with controllers in nested subdirectories and all components (e.g. services and directives) in a 'components' dir.
[[scopeinheritance]]
=== Be aware of how scope inheritance works
See https://github.com/angular/angular.js/wiki/Understanding-Scopes#wiki-JSproto[The Nuances of Scope Prototypal Inheritance]
[[nginject]]
=== Use @ngInject for easy dependency injection compilation
This removes the need to add `myCtrl['$inject'] = ...` to prevent minification from messing up Angular's dependency injection.
Usage:
--------------------------------------------
/**
* My controller.
* @param {!angular.$http} $http
* @param {!my.app.myService} myService
* @constructor
* @export
* @ngInject
*/
my.app.MyCtrl = function($http, myService) {
//...
};
--------------------------------------------
[[bestpractices]]
== 4 Best practices links and docs
* https://github.com/angular/angular.js/wiki/Best-Practices[Best Practices] from Angular on GitHub
* http://www.youtube.com/watch?v=ZhfUv0spHCY[Meetup video] (not Google specific)
Last modified Feb 07 2013

395
angularjs-google-style.html
View File

@ -1,395 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<base target="_blank">
<link rel="stylesheet" type="text/css" href="styleguide.css">
<script src="https://google-code-prettify.googlecode.com/svn/loader/run_prettify.js"></script>
<script language="javascript" src="/eng/doc/devguide/include/styleguide.js"></script>
<title>Google's AngularJS Style Guide</title>
<style type="text/css"><!--
th { background-color: #ddd; }
//--></style>
</head>
<body onload="prettyPrint();initStyleGuide();">
<h1 class="external">An AngularJS Style Guide for Closure Users at Google</h1>
<p class="external">This is the external version of a document that was primarily written for Google
engineers. It describes a recommended style for AngularJS apps that use Closure, as used
internally at Google. Members of the broader AngularJS community should feel free to apply
(or not apply) these recommendations, as relevant to their own use cases.</p>
<p class="external">This document describes style for AngularJS apps in google3. This guide
supplements and extends the <a href="http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml">
Google JavaScript Style Guide</a>.
</p>
<p><b>Style Note</b>: Examples on the AngularJS external webpage, and many external apps, are
written in a style that freely uses closures, favors functional inheritance, and does not often use
<a class="external"
href="http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml?showone=JavaScript_Types#JavaScript_Types">
JavaScript types</a>. Google follows a more rigorous Javascript style to support JSCompiler
optimizations and large code bases - see the javascript-style mailing list.
This is not an Angular-specific issue, and is not discussed further in this style guide.
(But if you want further reading:
<a href="http://martinfowler.com/bliki/Lambda.html">Martin Fowler on closures</a>,
<a href="http://jibbering.com/faq/notes/closures/">much longer description</a>, appendix A of the
<a href="http://books.google.com/books/about/Closure_The_Definitive_Guide.html?id=p7uyWPcVGZsC">
closure book</a> has a good description of inheritance patterns and why it prefers
pseudoclassical,
<a href="http://books.google.com/books/about/JavaScript.html?id=PXa2bby0oQ0C">
Javascript, the Good Parts</a> as a counter.)</p>
<h5>1 Angular Language Rules</h5>
<ul>
<li> <a target="_self" href="#googprovide">Manage dependencies with Closure's goog.require and
goog.provide</a>
<li> <a target="_self" href="#modules"> Modules</a>
<li> <a target="_self" href="#moduledeps"> Modules should reference other modules using the
"name" property</a>
<li> <a target="_self" href="#externs">Use the provided Angular externs file</a>
<li> <a target="_self" href="#compilerflags">JSCompiler Flags</a>
<li> <a target="_self" href="#controllers">Controllers and Scopes</a>
<li> <a target="_self" href="#directives">Directives</a>
<li> <a target="_self" href="#services">Services</a>
</ul>
<h5>2 Angular Style Rules</h5>
<ul>
<li><a target="_self" href="#dollarsign">Reserve $ for Angular properties and services
</a>
<li><a target="_self" href="#customelements">Custom elements.</a>
</ul>
<h5>3 Angular Tips, Tricks, and Best Practices</h5>
<ul>
<li><a target="_self" href="#testing">Testing</a>
<li><a target="_self" href="#appstructure">Consider using the Best Practices for App Structure</a>
<li><a target="_self" href="#scopeinheritance">Be aware of how scope inheritance works</a>
<li><a target="_self" href="#nginject">Use @ngInject for easy dependency injection compilation</a>
</ul>
<h5><a target="_self" href="#bestpractices">4 Best practices links and docs</a></h5>
<h2>1 Angular Language Rules</h2>
<h3 id="googprovide">Manage dependencies with Closure's goog.require and goog.provide</h3>
<p>Choose a namespace for your project, and use goog.provide and goog.require.</p>
<pre class="prettyprint lang-js">
goog.provide('hello.about.AboutCtrl');
goog.provide('hello.versions.Versions');
</pre>
<p><b>Why?</b>
Google BUILD rules integrate nicely with closure provide/require.</p>
<h3 id="modules">Modules</h3>
<p>Your main application module should be in your root client directory. A module should never be
altered other than the one where it is defined.</p>
<p>Modules may either be defined in the same file as their components (this works well for a module
that contains exactly one service) or in a separate file for wiring pieces together.</p>
<p><b>Why?</b>
A module should be consistent for anyone that wants to include it as a reusable component.
If a module can mean different things depending on which files are included, it is not consistent.
</p>
<h3 id="moduledeps">
Modules should reference other modules using the Angular Module's "name" property
</h3>
<p>For example:</p>
<pre class="prettyprint lang-js">
// file submodulea.js:
goog.provide('my.submoduleA');
my.submoduleA = angular.module('my.submoduleA', []);
// ...
// file app.js
goog.require('my.submoduleA');
Yes: my.application.module = angular.module('hello', [my.submoduleA.name]);
<font color="red">
No: my.application.module = angular.module('hello', ['my.submoduleA']);
</font></pre>
<p><b>Why?</b>
Using a property of my.submoduleA prevents Closure presubmit failures complaining that the file is
required but never used. Using the .name property avoids duplicating strings.</p>
<h3 id="externs">Use a common externs file</h3>
<p>This maximally allows the JS compiler to enforce type safety in the presence of externally
provided types from Angular, and means you don't have to worry about Angular vars being obfuscated
in a confusing way. </p>
<p>Note to readers outside Google: the current externs file is located in an internal-to-Google
directory, but an example can be found on github <a href="https://github.com/angular/angular.js/pull/4722">
here</a>.</p>
<h3 id="compilerflags">JSCompiler Flags</h3>
<p><b>Reminder</b>: According to the JS style guide, customer facing code must be compiled.</p>
<p><b>Recommended</b>: Use the JSCompiler (the closure compiler that works with js_binary by
default) and ANGULAR_COMPILER_FLAGS_FULL from //javascript/angular/build_defs/build_defs for
your base flags.
</p>
<p>Note - if you are using @export for methods, you will need to add the compiler flag</p>
<pre>
"--generate_exports",
</pre>
<p>If you are using @export for properties, you will need to add the flags:</p>
<pre>
"--generate_exports",
"--remove_unused_prototype_props_in_externs=false",
"--export_local_property_definitions",
</pre>
<h3 id="controllers">Controllers and Scopes</h3>
<p>Controllers are classes. Methods should be defined on MyCtrl.prototype.
See <a href="http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml?showone=Method_and_property_definitions#Method_and_property_definitions">
the JavaScript style guide</a></p>
<p>Google Angular applications should use the <b>'controller as'</b> style to export the controller
onto the scope. This is fully implemented in Angular 1.2 and can be mimicked in pre-Angular 1.2
builds.
</p>
<p>Pre Angular 1.2, this looks like:</p>
<pre class="prettyprint lang-js">
/**
* Home controller.
*
* @param {!angular.Scope} $scope
* @constructor
* @ngInject
* @export
*/
hello.mainpage.HomeCtrl = function($scope) {
/** @export */
$scope.homeCtrl = this; // This is a bridge until Angular 1.2 controller-as
/**
* @type {string}
* @export
*/
this.myColor = 'blue';
};
/**
* @param {number} a
* @param {number} b
* @export
*/
hello.mainpage.HomeCtrl.prototype.add = function(a, b) {
return a + b;
};
</pre>
<p>And the template:</p>
<pre>
&lt;div ng-controller="hello.mainpage.HomeCtrl"/&gt;
&lt;span ng-class="homeCtrl.myColor"&gt;I'm in a color!&lt;/span&gt;
&lt;span&gt;{{homeCtrl.add(5, 6)}}&lt;/span&gt;
&lt;/div&gt;
</pre>
<p>After Angular 1.2, this looks like:</p>
<pre class="prettyprint lang-js">
/**
* Home controller.
*
* @constructor
* @ngInject
* @export
*/
hello.mainpage.HomeCtrl = function() {
/**
* @type {string}
* @export
*/
this.myColor = 'blue';
};
/**
* @param {number} a
* @param {number} b
* @export
*/
hello.mainpage.HomeCtrl.prototype.add = function(a, b) {
return a + b;
};
</pre>
<p>If you are compiling with property renaming, expose properties and methods using the @export
annotation. Remember to @export the constructor as well.</p>
<p>And in the template:</p>
<pre>
&lt;div ng-controller="hello.mainpage.HomeCtrl as homeCtrl"/&gt;
&lt;span ng-class="homeCtrl.myColor"&gt;I'm in a color!&lt;/span&gt;
&lt;span&gt;{{homeCtrl.add(5, 6)}}&lt;/span&gt;
&lt;/div&gt;
</pre>
<p><b>Why?</b>
Putting methods and properties directly onto the controller, instead of building up a scope
object, fits better with the Google Closure class style. Additionally, using 'controller as'
makes it obvious which controller you are accessing when multiple controllers apply to an element.
Since there is always a '.' in the bindings, you don't have to worry about prototypal inheritance
masking primitives.</p>
<h3 id="directives">Directives</h3>
<p>All DOM manipulation should be done inside directives. Directives should be kept small and use
composition. Files defining directives should goog.provide a static function which returns the
directive definition object.</p>
<pre class="prettyprint lang-js">
goog.provide('hello.pane.paneDirective');
/**
* Description and usage
* @return {angular.Directive} Directive definition object.
*/
hello.pane.paneDirective = function() {
// ...
};
</pre>
<p><b>Exception</b>: DOM manipulation may occur in services for DOM elements disconnected from the
rest of the view, e.g. dialogs or keyboard shortcuts.</p>
<h3 id="services">Services</h3>
<p>Services registered on the module with <code>module.service</code> are classes.
Use <code>module.service</code> instead of <code>module.provider</code> or
<code>module.factory</code> unless you need to do initialization beyond just creating a
new instance of the class.</p>
<pre class="prettyprint lang-js">
/**
* @param {!angular.$http} $http The Angular http service.
* @constructor
*/
hello.request.Request = function($http) {
/** @type {!angular.$http} */
this.http_ = $http;
};
hello.request.Request.prototype.get = function() {/*...*/};
</pre>
<p>In the module:</p>
<pre class="prettyprint lang-js">
module.service('request', hello.request.Request);
</pre>
<h2>2 Angular Style Rules</h2>
<h3 id="dollarsign">Reserve $ for Angular properties and services</h3>
<p>Do not use $ to prepend your own object properties and service identifiers. Consider this style
of naming reserved by AngularJS and jQuery.</p>
<p>Yes:</p>
<pre class="prettyprint lang-js">
$scope.myModel = { value: 'foo' }
myModule.service('myService', function() { /*...*/ });
var MyCtrl = function($http) {this.http_ = $http;};
</pre>
<p><font color="red">No:</font></p>
<pre class="prettyprint">
$scope.$myModel = { value: 'foo' } // BAD
$scope.myModel = { $value: 'foo' } // BAD
myModule.service('$myService', function() { ... }); // BAD
var MyCtrl = function($http) {this.$http_ = $http;}; // BAD
</pre>
<p><b>Why?</b>
It's useful to distinguish between Angular / jQuery builtins and things you add yourself.
In addition, $ is not an acceptable character for variables names in the JS style guide.
</p>
<h3 id="customelements">Custom elements</h3>
<p>For custom elements (e.g. <code>&lt;ng-include src="template"&gt;&lt;/ng-include&gt;</code>), IE8
requires special support (html5shiv-like hacks) to enable css styling. Be aware of this
restriction in apps targeting old versions of IE.</p>
<h2>3 Angular Tips, Tricks, and Best Practices</h2>
<p>These are not strict style guide rules, but are placed here as reference for folks getting
started with Angular at Google.</p>
<h3 id="testing">Testing</h3>
<p>Angular is designed for test-driven development.</p>
<p>The recommended unit testing setup is Jasmine + Karma (though you could use closure tests
or js_test)</p>
<p>Angular provides easy adapters to load modules and use the injector in Jasmine tests.
<ul>
<li><a href = "http://docs.angularjs.org/api/angular.mock.module">module</a>
<li><a href="http://docs.angularjs.org/api/angular.mock.inject">inject</a>
</ul>
</p>
<h3 id="appstructure">Consider using the Best Practices for App Structure</h3>
<p>
This <a href="https://docs.google.com/document/d/1XXMvReO8-Awi1EZXAXS4PzDzdNvV6pGcuaF4Q9821Es/pub">directory structure doc</a> describes how to structure your application with controllers in
nested subdirectories and all components (e.g. services and directives) in a 'components' dir.
</p>
<h3 id="scopeinheritance">Be aware of how scope inheritance works</h3>
<p>See <a href="https://github.com/angular/angular.js/wiki/Understanding-Scopes#wiki-JSproto">
The Nuances of Scope Prototypal Inheritance</a></p>
<h3 id="nginject">Use @ngInject for easy dependency injection compilation</h3>
<p>This removes the need to add <code>myCtrl['$inject'] = ...</code> to prevent minification from
messing up Angular's dependency injection.</p>
<p>Usage:</p>
<pre class="prettyprint lang-js">
/**
* My controller.
* @param {!angular.$http} $http
* @param {!my.app.myService} myService
* @constructor
* @export
* @ngInject
*/
my.app.MyCtrl = function($http, myService) {
//...
};
</pre>
<h2 id="bestpractices">4 Best practices links and docs</h2>
<ul>
<li><a href="https://github.com/angular/angular.js/wiki/Best-Practices">
Best Practices</a> from Angular on GitHub</li>
<li><a href="http://www.youtube.com/watch?v=ZhfUv0spHCY">
Meetup video</a> (not Google specific)</li>
</ul>
<address>
Last modified Feb 07 2013
</address>
</body>
<html>

2861
cppguide.asciidoc Normal file
View File

File diff suppressed because it is too large Load Diff

6117
cppguide.html
View File

File diff suppressed because it is too large Load Diff

18
cppguide.xml
View File

@ -1,18 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf8">
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<meta http-equiv="refresh" content="1; url=cppguide.html">
<title>Redirecting</title>
</head>
<!-- The BODY onLoad redirect is the best: it preserves #fragments and
?queries. But it requires javascript. If that fails, the
meta-refresh kicks in; it works more generally, but loses fragments
and queries, takes a second, and pollutes the browser history.
If they both fail, we let the user manually click on the new link.
-->
<body onload="location.replace(location.href.replace('.xml', '.html'))">
Redirecting you to <a href="cppguide.html">cppguide.html</a>.
</body>
</html>

18
google-r-style.html
View File

@ -1,18 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf8">
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<meta http-equiv="refresh" content="1; url=Rguide.xml">
<title>Redirecting</title>
</head>
<!-- The BODY onLoad redirect is the best: it preserves #fragments and
?queries. But it requires javascript. If that fails, the
meta-refresh kicks in; it works more generally, but loses fragments
and queries, takes a second, and pollutes the browser history.
If they both fail, we let the user manually click on the new link.
-->
<body onload="location.replace(location.href.replace('google-r-style.html', 'Rguide.xml'))">
Redirecting you to <a href="Rguide.xml">Rguide.xml</a>.
</body>
</html>

937
htmlcssguide.asciidoc Normal file
View File

@ -0,0 +1,937 @@
= Google HTML/CSS Style Guide
:sectlinks:
Revision 2.23
Table of Contents
[width="100%",cols="50%,50%",]
|=====================================================================================================================================================================================================================================================================================================================================================================================================================================================
a|
link:#general-style-rules[General Style Rules]
a|
link:#protocol[Protocol]
a|
link:#general-formatting-rules[General Formatting Rules]
a|
link:#indentation[Indentation] link:#capitalization[Capitalization] link:#trailing-whitespace[Trailing Whitespace]
a|
link:#general-meta-rules[General Meta Rules]
a|
link:#encoding[Encoding] link:#comments[Comments] link:#action-items[Action Items]
a|
link:#html-style-rules[HTML Style Rules]
a|
link:#document-type[Document Type] link:#html-validity[HTML Validity] link:#semantics[Semantics] link:#multimedia-fallback[Multimedia Fallback] link:#separation-of-concerns[Separation of Concerns] link:#entity-references[Entity References] link:#optional-tags[Optional Tags] link:#type-attributes[type Attributes]
a|
link:#html-formatting-rules[HTML Formatting Rules]
a|
link:#general-formatting[General Formatting] link:#html-quotation-marks[HTML Quotation Marks]
a|
link:#css-style-rules[CSS Style Rules]
a|
link:#css-validity[CSS Validity] link:#id-and-class-naming[ID and Class Naming] link:#id-and-class-name_style[ID and Class Name Style] link:#type-selectors[Type Selectors] link:#shorthand-properties[Shorthand Properties] link:#0_and_Units[0 and Units] link:#Leading_0s[Leading 0s] link:#hexadecimal-notation[Hexadecimal Notation] link:#prefixes[Prefixes] link:#id-and-class-name_delimiters[ID and Class Name Delimiters] link:#hacks[Hacks]
a|
link:#css-formatting-rules[CSS Formatting Rules]
a|
link:#declaration-order[Declaration Order] link:#block-content-indentation[Block Content Indentation] link:#declaration-stops[Declaration Stops] link:#property-name-stops[Property Name Stops] link:#declaration-block-separation[Declaration Block Separation] link:#selector-and-declaration-separation[Selector and Declaration Separation] link:#rule-separation[Rule Separation] link:#css-quotation-marks[CSS Quotation Marks]
a|
link:#css-meta-rules[CSS Meta Rules]
a|
link:#section-comments[Section Comments]
|=====================================================================================================================================================================================================================================================================================================================================================================================================================================================
[[Important_Note]]
== Important Note
=== Displaying Hidden Details in This Guide
This style guide contains many details that are initially hidden from view. They are marked by the triangle icon, which you see here on your left. Click it now. You should see “Hooray” appear below.
Hooray! Now you know you can expand points to get more details. Alternatively, there’s a “toggle all” at the top of this document.
[[Background]]
== Background
This document defines formatting and style rules for HTML and CSS. It aims at improving collaboration, code quality, and enabling supporting infrastructure. It applies to raw, working files that use HTML and CSS, including GSS files. Tools are free to obfuscate, minify, and compile as long as the general code quality is maintained.
[[General_Style_Rules]]
== General Style Rules
=== Protocol
Omit the protocol from embedded resources.
Omit the protocol portion (`http:`, `https:`) from URLs pointing to images and other media files, style sheets, and scripts unless the respective files are not available over both protocols.
Omitting the protocol—which makes the URL relative—prevents mixed content issues and results in minor file size savings.
----------------------------------------------------------------------------
<!-- Not recommended -->
<script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script>
----------------------------------------------------------------------------
-----------------------------------------------------------------------
<!-- Recommended -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
-----------------------------------------------------------------------
--------------------------------------------------------
/* Not recommended */
.example {
background: url(http://www.google.com/images/example);
}
--------------------------------------------------------
---------------------------------------------------
/* Recommended */
.example {
background: url(//www.google.com/images/example);
}
---------------------------------------------------
[[General_Formatting_Rules]]
== General Formatting Rules
=== Indentation
Indent by 2 spaces at a time.
Don’t use tabs or mix tabs and spaces for indentation.
---------------
<ul>
<li>Fantastic
<li>Great
</ul>
---------------
--------------
.example {
color: blue;
}
--------------
=== Capitalization
Use only lowercase.
All code has to be lowercase: This applies to HTML element names, attributes, attribute values (unless `text/CDATA`), CSS selectors, properties, and property values (with the exception of strings).
------------------------
<!-- Not recommended -->
<A HREF="/">Home</A>
------------------------
-----------------------------------
<!-- Recommended -->
<img src="google.png" alt="Google">
-----------------------------------
---------------------
/* Not recommended */
color: #E5E5E5;
---------------------
-----------------
/* Recommended */
color: #e5e5e5;
-----------------
=== Trailing Whitespace
Remove trailing white spaces.
Trailing white spaces are unnecessary and can complicate diffs.
------------------------
<!-- Not recommended -->
<p>What?_
------------------------
--------------------
<!-- Recommended -->
<p>Yes please.
--------------------
[[General_Meta_Rules]]
== General Meta Rules
=== Encoding
Use UTF-8 (no BOM).
Make sure your editor uses UTF-8 as character encoding, without a byte order mark.
Specify the encoding in HTML templates and documents via `<meta charset="utf-8">`. Do not specify the encoding of style sheets as these assume UTF-8.
(More on encodings and when and how to specify them can be found in http://www.w3.org/International/tutorials/tutorial-char-enc/[Handling character encodings in HTML and CSS].)
=== Comments
Explain code as needed, where possible.
Use comments to explain code: What does it cover, what purpose does it serve, why is respective solution used or preferred?
(This item is optional as it is not deemed a realistic expectation to always demand fully documented code. Mileage may vary heavily for HTML and CSS code and depends on the project’s complexity.)
=== Action Items
Mark todos and action items with `TODO`.
Highlight todos by using the keyword `TODO` only, not other common formats like `@@`.
Append a contact (username or mailing list) in parentheses as with the format `TODO(contact)`.
Append action items after a colon as in `TODO: action item`.
---------------------------------------
{# TODO(john.doe): revisit centering #}
<center>Test</center>
---------------------------------------
-----------------------------------
<!-- TODO: remove optional tags -->
<ul>
<li>Apples</li>
<li>Oranges</li>
</ul>
-----------------------------------
[[HTML_Style_Rules]]
== HTML Style Rules
=== Document Type
Use HTML5.
HTML5 (HTML syntax) is preferred for all HTML documents: `<!DOCTYPE html>`.
(It’s recommended to use HTML, as `text/html`. Do not use XHTML. XHTML, as http://hixie.ch/advocacy/xhtml[`application/xhtml+xml`], lacks both browser and infrastructure support and offers less room for optimization than HTML.)
Although fine with HTML, do not close void elements, i.e. write `<br>`, not `<br />`.
=== HTML Validity
Use valid HTML where possible.
Use valid HTML code unless that is not possible due to otherwise unattainable performance goals regarding file size.
Use tools such as the http://validator.w3.org/nu/[W3C HTML validator] to test.
Using valid HTML is a measurable baseline quality attribute that contributes to learning about technical requirements and constraints, and that ensures proper HTML usage.
-----------------------------
<!-- Not recommended -->
<title>Test</title>
<article>This is only a test.
-----------------------------
---------------------------------------
<!-- Recommended -->
<!DOCTYPE html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>
---------------------------------------
=== Semantics
Use HTML according to its purpose.
Use elements (sometimes incorrectly called “tags”) for what they have been created for. For example, use heading elements for headings, `p` elements for paragraphs, `a` elements for anchors, etc.
Using HTML according to its purpose is important for accessibility, reuse, and code efficiency reasons.
---------------------------------------------------------------
<!-- Not recommended -->
<div onclick="goToRecommendations();">All recommendations</div>
---------------------------------------------------------------
--------------------------------------------------
<!-- Recommended -->
<a href="recommendations/">All recommendations</a>
--------------------------------------------------
=== Multimedia Fallback
Provide alternative contents for multimedia.
For multimedia, such as images, videos, animated objects via `canvas`, make sure to offer alternative access. For images that means use of meaningful alternative text (`alt`) and for video and audio transcripts and captions, if available.
Providing alternative contents is important for accessibility reasons: A blind user has few cues to tell what an image is about without `@alt`, and other users may have no way of understanding what video or audio contents are about either.
(For images whose `alt` attributes would introduce redundancy, and for images whose purpose is purely decorative which you cannot immediately use CSS for, use no alternative text, as in `alt=""`.)
---------------------------
<!-- Not recommended -->
<img src="spreadsheet.png">
---------------------------
---------------------------------------------------------
<!-- Recommended -->
<img src="spreadsheet.png" alt="Spreadsheet screenshot.">
---------------------------------------------------------
=== Separation of Concerns
Separate structure from presentation from behavior.
Strictly keep structure (markup), presentation (styling), and behavior (scripting) apart, and try to keep the interaction between the three to an absolute minimum.
That is, make sure documents and templates contain only HTML and HTML that is solely serving structural purposes. Move everything presentational into style sheets, and everything behavioral into scripts.
In addition, keep the contact area as small as possible by linking as few style sheets and scripts as possible from documents and templates.
Separating structure from presentation from behavior is important for maintenance reasons. It is always more expensive to change HTML documents and templates than it is to update style sheets and scripts.
----------------------------------------------------------------
<!-- Not recommended -->
<!DOCTYPE html>
<title>HTML sucks</title>
<link rel="stylesheet" href="base.css" media="screen">
<link rel="stylesheet" href="grid.css" media="screen">
<link rel="stylesheet" href="print.css" media="print">
<h1 style="font-size: 1em;">HTML sucks</h1>
<p>I’ve read about this on a few sites but now I’m sure:
<u>HTML is stupid!!1</u>
<center>I can’t believe there’s no way to control the styling of
my website without doing everything all over again!</center>
----------------------------------------------------------------
--------------------------------------------------------------------
<!-- Recommended -->
<!DOCTYPE html>
<title>My first CSS-only redesign</title>
<link rel="stylesheet" href="default.css">
<h1>My first CSS-only redesign</h1>
<p>I’ve read about this on a few sites but today I’m actually
doing it: separating concerns and avoiding anything in the HTML of
my website that is presentational.
<p>It’s awesome!
--------------------------------------------------------------------
=== Entity References
Do not use entity references.
There is no need to use entity references like `&mdash;`, `&rdquo;`, or `&#x263a;`, assuming the same encoding (UTF-8) is used for files and editors as well as among teams.
The only exceptions apply to characters with special meaning in HTML (like `<` and `&`) as well as control or “invisible” characters (like no-break spaces).
--------------------------------------------------------
<!-- Not recommended -->
The currency symbol for the Euro is &ldquo;&eur;&rdquo;.
--------------------------------------------------------
----------------------------------------
<!-- Recommended -->
The currency symbol for the Euro is “€”.
----------------------------------------
=== Optional Tags
Omit optional tags (optional).
For file size optimization and scannability purposes, consider omitting optional tags. The http://www.whatwg.org/specs/web-apps/current-work/multipage/syntax.html#syntax-tag-omission[HTML5 specification] defines what tags can be omitted.
(This approach may require a grace period to be established as a wider guideline as it’s significantly different from what web developers are typically taught. For consistency and simplicity reasons it’s best served omitting all optional tags, not just a selection.)
-------------------------------------------------
<!-- Not recommended -->
<!DOCTYPE html>
<html>
<head>
<title>Spending money, spending bytes</title>
</head>
<body>
<p>Sic.</p>
</body>
</html>
-------------------------------------------------
-----------------------------------------
<!-- Recommended -->
<!DOCTYPE html>
<title>Saving money, saving bytes</title>
<p>Qed.
-----------------------------------------
=== type Attributes
Omit `type` attributes for style sheets and scripts.
Do not use `type` attributes for style sheets (unless not using CSS) and scripts (unless not using JavaScript).
Specifying `type` attributes in these contexts is not necessary as HTML5 implies http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#attr-style-type[`text/css`] and http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#attr-script-type[`text/javascript`] as defaults. This can be safely done even for older browsers.
-----------------------------------------------------------
<!-- Not recommended -->
<link rel="stylesheet" href="//www.google.com/css/maia.css"
type="text/css">
-----------------------------------------------------------
------------------------------------------------------------
<!-- Recommended -->
<link rel="stylesheet" href="//www.google.com/css/maia.css">
------------------------------------------------------------
-------------------------------------------------------------
<!-- Not recommended -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"
type="text/javascript"></script>
-------------------------------------------------------------
-----------------------------------------------------------------------
<!-- Recommended -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
-----------------------------------------------------------------------
[[HTML_Formatting_Rules]]
== HTML Formatting Rules
=== General Formatting
Use a new line for every block, list, or table element, and indent every such child element.
Independent of the styling of an element (as CSS allows elements to assume a different role per `display` property), put every block, list, or table element on a new line.
Also, indent them if they are child elements of a block, list, or table element.
(If you run into issues around whitespace between list items it’s acceptable to put all `li` elements in one line. A linter is encouraged to throw a warning instead of an error.)
--------------------------------------------
<blockquote>
<p><em>Space</em>, the final frontier.</p>
</blockquote>
--------------------------------------------
-----------
<ul>
<li>Moe
<li>Larry
<li>Curly
</ul>
-----------
----------------------------
<table>
<thead>
<tr>
<th scope="col">Income
<th scope="col">Taxes
<tbody>
<tr>
<td>$ 5.00
<td>$ 4.50
</table>
----------------------------
=== HTML Quotation Marks
When quoting attributes values, use double quotation marks.
Use double (`""`) rather than single quotation marks (`''`) around attribute values.
--------------------------------------------------------
<!-- Not recommended -->
<a class='maia-button maia-button-secondary'>Sign in</a>
--------------------------------------------------------
--------------------------------------------------------
<!-- Recommended -->
<a class="maia-button maia-button-secondary">Sign in</a>
--------------------------------------------------------
[[CSS_Style_Rules]]
== CSS Style Rules
=== CSS Validity
Use valid CSS where possible.
Unless dealing with CSS validator bugs or requiring proprietary syntax, use valid CSS code.
Use tools such as the http://jigsaw.w3.org/css-validator/[W3C CSS validator] to test.
Using valid CSS is a measurable baseline quality attribute that allows to spot CSS code that may not have any effect and can be removed, and that ensures proper CSS usage.
=== ID and Class Naming
Use meaningful or generic ID and class names.
Instead of presentational or cryptic names, always use ID and class names that reflect the purpose of the element in question, or that are otherwise generic.
Names that are specific and reflect the purpose of the element should be preferred as these are most understandable and the least likely to change.
Generic names are simply a fallback for elements that have no particular or no meaning different from their siblings. They are typically needed as “helpers.”
Using functional or generic names reduces the probability of unnecessary document or template changes.
-------------------------------------
/* Not recommended: meaningless */
#yee-1901 {}
/* Not recommended: presentational */
.button-green {}
.clear {}
-------------------------------------
---------------------------
/* Recommended: specific */
#gallery {}
#login {}
.video {}
/* Recommended: generic */
.aux {}
.alt {}
---------------------------
=== ID and Class Name Style
Use ID and class names that are as short as possible but as long as necessary.
Try to convey what an ID or class is about while being as brief as possible.
Using ID and class names this way contributes to acceptable levels of understandability and code efficiency.
---------------------
/* Not recommended */
#navigation {}
.atr {}
---------------------
-----------------
/* Recommended */
#nav {}
.author {}
-----------------
=== Type Selectors
Avoid qualifying ID and class names with type selectors.
Unless necessary (for example with helper classes), do not use element names in conjunction with IDs or classes.
Avoiding unnecessary ancestor selectors is useful for http://www.stevesouders.com/blog/2009/06/18/simplifying-css-selectors/[performance reasons].
---------------------
/* Not recommended */
ul#example {}
div.error {}
---------------------
-----------------
/* Recommended */
#example {}
.error {}
-----------------
=== Shorthand Properties
Use shorthand properties where possible.
CSS offers a variety of http://www.w3.org/TR/CSS21/about.html#shorthand[shorthand] properties (like `font`) that should be used whenever possible, even in cases where only one value is explicitly set.
Using shorthand properties is useful for code efficiency and understandability.
--------------------------------------
/* Not recommended */
border-top-style: none;
font-family: palatino, georgia, serif;
font-size: 100%;
line-height: 1.6;
padding-bottom: 2em;
padding-left: 1em;
padding-right: 1em;
padding-top: 0;
--------------------------------------
----------------------------------------
/* Recommended */
border-top: 0;
font: 100%/1.6 palatino, georgia, serif;
padding: 0 1em 2em;
----------------------------------------
=== 0 and Units
Omit unit specification after “0” values.
Do not use units after `0` values unless they are required.
-----------
margin: 0;
padding: 0;
-----------
=== Leading 0s
Omit leading “0”s in values.
Do not use put `0`s in front of values or lengths between -1 and 1.
----------------
font-size: .8em;
----------------
=== Hexadecimal Notation
Use 3 character hexadecimal notation where possible.
For color values that permit it, 3 character hexadecimal notation is shorter and more succinct.
---------------------
/* Not recommended */
color: #eebbcc;
---------------------
-----------------
/* Recommended */
color: #ebc;
-----------------
=== Prefixes
Prefix selectors with an application-specific prefix (optional).
In large projects as well as for code that gets embedded in other projects or on external sites use prefixes (as namespaces) for ID and class names. Use short, unique identifiers followed by a dash.
Using namespaces helps preventing naming conflicts and can make maintenance easier, for example in search and replace operations.
--------------------------
.adw-help {} /* AdWords */
#maia-note {} /* Maia */
--------------------------
=== ID and Class Name Delimiters
Separate words in ID and class names by a hyphen.
Do not concatenate words and abbreviations in selectors by any characters (including none at all) other than hyphens, in order to improve understanding and scannability.
---------------------------------------------------------------------
/* Not recommended: does not separate the words “demo” and “image” */
.demoimage {}
/* Not recommended: uses underscore instead of hyphen */
.error_status {}
---------------------------------------------------------------------
-----------------
/* Recommended */
#video-id {}
.ads-sample {}
-----------------
=== Hacks
Avoid user agent detection as well as CSS “hacks”—try a different approach first.
It’s tempting to address styling differences over user agent detection or special CSS filters, workarounds, and hacks. Both approaches should be considered last resort in order to achieve and maintain an efficient and manageable code base. Put another way, giving detection and hacks a free pass will hurt projects in the long run as projects tend to take the way of least resistance. That is, allowing and making it easy to use detection and hacks means using detection and hacks more frequently—and more frequently is too frequently.
[[CSS_Formatting_Rules]]
== CSS Formatting Rules
=== Declaration Order
Alphabetize declarations.
Put declarations in alphabetical order in order to achieve consistent code in a way that is easy to remember and maintain.
Ignore vendor-specific prefixes for sorting purposes. However, multiple vendor-specific prefixes for a certain CSS property should be kept sorted (e.g. -moz prefix comes before -webkit).
---------------------------
background: fuchsia;
border: 1px solid;
-moz-border-radius: 4px;
-webkit-border-radius: 4px;
border-radius: 4px;
color: black;
text-align: center;
text-indent: 2em;
---------------------------
=== Block Content Indentation
Indent all block content.
Indent all http://www.w3.org/TR/CSS21/syndata.html#block[block content], that is rules within rules as well as declarations, so to reflect hierarchy and improve understanding.
---------------------------
@media screen, projection {
html {
background: #fff;
color: #444;
}
}
---------------------------
=== Declaration Stops
Use a semicolon after every declaration.
End every declaration with a semicolon for consistency and extensibility reasons.
---------------------
/* Not recommended */
.test {
display: block;
height: 100px
}
---------------------
-----------------
/* Recommended */
.test {
display: block;
height: 100px;
}
-----------------
=== Property Name Stops
Use a space after a property name’s colon.
Always use a single space between property and value (but no space between property and colon) for consistency reasons.
---------------------
/* Not recommended */
h3 {
font-weight:bold;
}
---------------------
--------------------
/* Recommended */
h3 {
font-weight: bold;
}
--------------------
=== Declaration Block Separation
Use a space between the last selector and the declaration block.
Always use a single space between the last selector and the opening brace that begins the http://www.w3.org/TR/CSS21/syndata.html#rule-sets[declaration block].
The opening brace should be on the same line as the last selector in a given rule.
---------------------------------------------
/* Not recommended: missing space */
#video{
margin-top: 1em;
}
/* Not recommended: unnecessary line break */
#video
{
margin-top: 1em;
}
---------------------------------------------
------------------
/* Recommended */
#video {
margin-top: 1em;
}
------------------
=== Selector and Declaration Separation
Separate selectors and declarations by new lines.
Always start a new line for each selector and declaration.
-------------------------------
/* Not recommended */
a:focus, a:active {
position: relative; top: 1px;
}
-------------------------------
----------------------
/* Recommended */
h1,
h2,
h3 {
font-weight: normal;
line-height: 1.2;
}
----------------------
=== Rule Separation
Separate rules by new lines.
Always put a blank line (two line breaks) between rules.
-------------------
html {
background: #fff;
}
body {
margin: auto;
width: 50%;
}
-------------------
=== CSS Quotation Marks
Use single quotation marks for attribute selectors and property values.
Use single (`''`) rather than double (`""`) quotation marks for attribute selectors or property values. Do not use quotation marks in URI values (`url()`).
Exception: If you do need to use the `@charset` rule, use double quotation marks—http://www.w3.org/TR/CSS21/syndata.html#charset[single quotation marks are not permitted].
----------------------------------------------
/* Not recommended */
@import url("//www.google.com/css/maia.css");
html {
font-family: "open sans", arial, sans-serif;
}
----------------------------------------------
----------------------------------------------
/* Recommended */
@import url(//www.google.com/css/maia.css);
html {
font-family: 'open sans', arial, sans-serif;
}
----------------------------------------------
[[CSS_Meta_Rules]]
== CSS Meta Rules
=== Section Comments
Group sections by a section comment (optional).
If possible, group style sheet sections together by using comments. Separate sections with new lines.
---------------
/* Header */
#adw-header {}
/* Footer */
#adw-footer {}
/* Gallery */
.adw-gallery {}
---------------
== Parting Words
_Be consistent._
If you’re editing code, take a few minutes to look at the code around you and determine its style. If they use spaces around all their arithmetic operators, you should too. If their comments have little boxes of hash marks around them, make your comments have little boxes of hash marks around them too.
The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you’re saying rather than on how you’re saying it. We present global style rules here so people know the vocabulary, but local style is also important. If code you add to a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to read it. Avoid this.
Revision 2.23

1117
htmlcssguide.xml
View File

File diff suppressed because it is too large Load Diff

847
javaguide.asciidoc Normal file
View File

@ -0,0 +1,847 @@
= Google Java Style
Last changed: March 21, 2014
[width="100%",cols="34%,33%,33%",]
|===========================================================================================
a|
link:#s1-introduction[1 Introduction] ::
link:#s1.1-terminology[1.1 Terminology notes]
+
link:#s1.2-guide-notes[1.2 Guide notes]
link:#s2-source-file-basics[2 Source file basics] ::
link:#s2.1-file-name[2.1 File name]
+
link:#s2.2-file-encoding[2.2 File encoding: UTF-8]
+
link:#s2.3-special-characters[2.3 Special characters]
+
link:#s2.3.1-whitespace-characters[2.3.1 Whitespace characters]
+
link:#s2.3.2-special-escape-sequences[2.3.2 Special escape sequences]
+
link:#s2.3.3-non-ascii-characters[2.3.3 Non-ASCII characters]
link:#s3-source-file-structure[3 Source file structure] ::
link:#s3.1-copyright-statement[3.1 License or copyright information, if present]
+
link:#s3.2-package-statement[3.2 Package statement]
+
link:#s3.3-import-statements[3.3 Import statements]
+
link:#s3.3.1-wildcard-imports[3.3.1 No wildcard imports]
+
link:#s3.3.2-import-line-wrapping[3.3.2 No line-wrapping]
+
link:#s3.3.3-import-ordering-and-spacing[3.3.3 Ordering and spacing]
+
link:#s3.4-class-declaration[3.4 Class declaration]
+
link:#s3.4.1-one-top-level-class[3.4.1 Exactly one top-level class declaration]
+
link:#s3.4.2-class-member-ordering[3.4.2 Class member ordering]
a|
link:#s4-formatting[4 Formatting] ::
link:#s4.1-braces[4.1 Braces]
+
link:#s4.1.1-braces-always-used[4.1.1 Braces are used where optional]
+
link:#s4.1.2-blocks-k-r-style[4.1.2 Nonempty blocks: K & R style]
+
link:#s4.1.3-braces-empty-blocks[4.1.3 Empty blocks: may be concise]
+
link:#s4.2-block-indentation[4.2 Block indentation: +2 spaces]
+
link:#s4.3-one-statement-per-line[4.3 One statement per line]
+
link:#s4.4-column-limit[4.4 Column limit: 80 or 100]
+
link:#s4.5-line-wrapping[4.5 Line-wrapping]
+
link:#s4.5.1-line-wrapping-where-to-break[4.5.1 Where to break]
+
link:#s4.5.2-line-wrapping-indent[4.5.2 Indent continuation lines at least +4 spaces]
+
link:#s4.6-whitespace[4.6 Whitespace]
+
link:#s4.6.1-vertical-whitespace[4.6.1 Vertical Whitespace]
+
link:#s4.6.2-horizontal-whitespace[4.6.2 Horizontal whitespace]
+
link:#s4.6.3-horizontal-alignment[4.6.3 Horizontal alignment: never required]
+
link:#s4.7-grouping-parentheses[4.7 Grouping parentheses: recommended]
+
link:#s4.8-specific-constructs[4.8 Specific constructs]
+
link:#s4.8.1-enum-classes[4.8.1 Enum classes]
+
link:#s4.8.2-variable-declarations[4.8.2 Variable declarations]
+
link:#s4.8.3-arrays[4.8.3 Arrays]
+
link:#s4.8.4-switch[4.8.4 Switch statements]
+
link:#s4.8.5-annotations[4.8.5 Annotations]
+
link:#s4.8.6-comments[4.8.6 Comments]
+
link:#s4.8.7-modifiers[4.8.7 Modifiers]
+
link:#s4.8.8-numeric-literals[4.8.8 Numeric Literals]
a|
link:#s5-naming[5 Naming] ::
link:#s5.1-identifier-names[5.1 Rules common to all identifiers]
+
link:#s5.2-specific-identifier-names[5.2 Rules by identifier type]
+
link:#s5.2.1-package-names[5.2.1 Package names]
+
link:#s5.2.2-class-names[5.2.2 Class names]
+
link:#s5.2.3-method-names[5.2.3 Method names]
+
link:#s5.2.4-constant-names[5.2.4 Constant names]
+
link:#s5.2.5-non-constant-field-names[5.2.5 Non-constant field names]
+
link:#s5.2.6-parameter-names[5.2.6 Parameter names]
+
link:#s5.2.7-local-variable-names[5.2.7 Local variable names]
+
link:#s5.2.8-type-variable-names[5.2.8 Type variable names]
+
link:#s5.3-camel-case[5.3 Camel case: defined]
link:#s6-programming-practices[6 Programming Practices] ::
link:#s6.1-override-annotation[6.1 @Override: always used]
+
link:#s6.2-caught-exceptions[6.2 Caught exceptions: not ignored]
+
link:#s6.3-static-members[6.3 Static members: qualified using class]
+
link:#s6.4-finalizers[6.4 Finalizers: not used]
link:#s7-javadoc[7 Javadoc] ::
link:#s7.1-javadoc-formatting[7.1 Formatting]
+
link:#s7.1.1-javadoc-multi-line[7.1.1 General form]
+
link:#s7.1.2-javadoc-paragraphs[7.1.2 Paragraphs]
+
link:#s7.1.3-javadoc-at-clauses[7.1.3 At-clauses]
+
link:#s7.2-summary-fragment[7.2 The summary fragment]
+
link:#s7.3-javadoc-where-required[7.3 Where Javadoc is used]
+
link:#s7.3.1-javadoc-exception-self-explanatory[7.3.1 Exception: self-explanatory methods]
+
link:#s7.3.2-javadoc-exception-overrides[7.3.2 Exception: overrides]
|===========================================================================================
[[s1-introduction]]
== 1 Introduction
This document serves as the *complete* definition of Google's coding standards for source code in the Java™ Programming Language. A Java source file is described as being _in Google Style_ if and only if it adheres to the rules herein.
Like other programming style guides, the issues covered span not only aesthetic issues of formatting, but other types of conventions or coding standards as well. However, this document focuses primarily on the *hard-and-fast rules* that we follow universally, and avoids giving _advice_ that isn't clearly enforceable (whether by human or tool).
[[s1.1-terminology]]
=== 1.1 Terminology notes
In this document, unless otherwise clarified:
1. The term _class_ is used inclusively to mean an "ordinary" class, enum class, interface or annotation type (`@interface`).
2. The term _comment_ always refers to _implementation_ comments. We do not use the phrase "documentation comments", instead using the common term "Javadoc."
Other "terminology notes" will appear occasionally throughout the document.
[[s1.2-guide-notes]]
=== 1.2 Guide notes
Example code in this document is **non-normative**. That is, while the examples are in Google Style, they may not illustrate the _only_ stylish way to represent the code. Optional formatting choices made in examples should not be enforced as rules.
[[s2-source-file-basics]]
== 2 Source file basics
[[s2.1-file-name]]
=== 2.1 File name
The source file name consists of the case-sensitive name of the top-level class it contains, plus the `.java` extension.
[[s2.2-file-encoding]]
=== 2.2 File encoding: UTF-8
Source files are encoded in **UTF-8**.
[[s2.3-special-characters]]
=== 2.3 Special characters
[[s2.3.1-whitespace-characters]]
==== 2.3.1 Whitespace characters
Aside from the line terminator sequence, the *ASCII horizontal space character* (**0x20**) is the only whitespace character that appears anywhere in a source file. This implies that:
1. All other whitespace characters in string and character literals are escaped.
2. Tab characters are *not* used for indentation.
[[s2.3.2-special-escape-sequences]]
==== 2.3.2 Special escape sequences
For any character that has a special escape sequence (`\b`, `\t`, `\n`, `\f`, `\r`, `\"`, `\'` and `\\`), that sequence is used rather than the corresponding octal (e.g. `\012`) or Unicode (e.g. `\u000a`) escape.
[[s2.3.3-non-ascii-characters]]
==== 2.3.3 Non-ASCII characters
For the remaining non-ASCII characters, either the actual Unicode character (e.g. `∞`) or the equivalent Unicode escape (e.g. `\u221e`) is used, depending only on which makes the code **easier to read and understand**.
*Tip:* In the Unicode escape case, and occasionally even when actual Unicode characters are used, an explanatory comment can be very helpful.
Examples:
[cols=",",options="header",]
|=================================================================================================================================
|Example |Discussion
|`String unitAbbrev = "μs";` |Best: perfectly clear even without a comment.
|`String unitAbbrev = "\u03bcs"; // "μs"` |Allowed, but there's no reason to do this.
|`String unitAbbrev = "\u03bcs"; // Greek letter mu, "s"` |Allowed, but awkward and prone to mistakes.
|`String unitAbbrev = "\u03bcs";` |Poor: the reader has no idea what this is.
|`return '\ufeff' + content; // byte order mark` |Good: use escapes for non-printable characters, and comment if necessary.
|=================================================================================================================================
*Tip:* Never make your code less readable simply out of fear that some programs might not handle non-ASCII characters properly. If that should happen, those programs are *broken* and they must be **fixed**.
[[s3-source-file-structure]]
== 3 Source file structure
A source file consists of, **in order**:
1. License or copyright information, if present
2. Package statement
3. Import statements
4. Exactly one top-level class
*Exactly one blank line* separates each section that is present.
[[s3.1-copyright-statement]]
=== 3.1 License or copyright information, if present
If license or copyright information belongs in a file, it belongs here.
[[s3.2-package-statement]]
=== 3.2 Package statement
The package statement is **not line-wrapped**. The column limit (Section 4.4, link:#s4.4-column-limit[Column limit: 80 or 100]) does not apply to package statements.
[[s3.3-import-statements]]
=== 3.3 Import statements
[[s3.3.1-wildcard-imports]]
==== 3.3.1 No wildcard imports
**Wildcard imports**, static or otherwise, **are not used**.
[[s3.3.2-import-line-wrapping]]
==== 3.3.2 No line-wrapping
Import statements are **not line-wrapped**. The column limit (Section 4.4, link:#s4.4-column-limit[Column limit: 80 or 100]) does not apply to import statements.
[[s3.3.3-import-ordering-and-spacing]]
==== 3.3.3 Ordering and spacing
Import statements are divided into the following groups, in this order, with each group separated by a single blank line:
1. All static imports in a single group
2. `com.google` imports (only if this source file is in the `com.google` package space)
3. Third-party imports, one group per top-level package, in ASCII sort order
* for example: `android`, `com`, `junit`, `org`, `sun`
4. `java` imports
5. `javax` imports
Within a group there are no blank lines, and the imported names appear in ASCII sort order. (**Note:** this is not the same as the import _statements_ being in ASCII sort order; the presence of semicolons warps the result.)
[[s3.4-class-declaration]]
=== 3.4 Class declaration
[[s3.4.1-one-top-level-class]]
==== 3.4.1 Exactly one top-level class declaration
Each top-level class resides in a source file of its own.
[[s3.4.2-class-member-ordering]]
==== 3.4.2 Class member ordering
The ordering of the members of a class can have a great effect on learnability, but there is no single correct recipe for how to do it. Different classes may order their members differently.
What is important is that each class order its members in **_some_ logical order**, which its maintainer could explain if asked. For example, new methods are not just habitually added to the end of the class, as that would yield "chronological by date added" ordering, which is not a logical ordering.
[[s3.4.2.1-overloads-never-split]]
===== 3.4.2.1 Overloads: never split
When a class has multiple constructors, or multiple methods with the same name, these appear sequentially, with no intervening members.
[[s4-formatting]]
== 4 Formatting
*Terminology Note:* _block-like construct_ refers to the body of a class, method or constructor. Note that, by Section 4.8.3.1 on link:#s4.8.3.1-array-initializers[array initializers], any array initializer _may_ optionally be treated as if it were a block-like construct.
[[s4.1-braces]]
=== 4.1 Braces
[[s4.1.1-braces-always-used]]
==== 4.1.1 Braces are used where optional
Braces are used with `if`, `else`, `for`, `do` and `while` statements, even when the body is empty or contains only a single statement.
[[s4.1.2-blocks-k-r-style]]
==== 4.1.2 Nonempty blocks: K & R style
Braces follow the Kernighan and Ritchie style ("http://www.codinghorror.com/blog/2012/07/new-programming-jargon.html[Egyptian brackets]") for _nonempty_ blocks and block-like constructs:
* No line break before the opening brace.
* Line break after the opening brace.
* Line break before the closing brace.
* Line break after the closing brace _if_ that brace terminates a statement or the body of a method, constructor or _named_ class. For example, there is _no_ line break after the brace if it is followed by `else` or a comma.
Example:
------------------------------------
return new MyClass() {
@Override public void method() {
if (condition()) {
try {
something();
} catch (ProblemException e) {
recover();
}
}
}
};
------------------------------------
A few exceptions for enum classes are given in Section 4.8.1, link:#s4.8.1-enum-classes[Enum classes].
[[s4.1.3-braces-empty-blocks]]
==== 4.1.3 Empty blocks: may be concise
An empty block or block-like construct _may_ be closed immediately after it is opened, with no characters or line break in between (`{}`), *unless* it is part of a _multi-block statement_ (one that directly contains multiple blocks: `if/else-if/else` or `try/catch/finally`).
Example:
---------------------
void doNothing() {}
---------------------
[[s4.2-block-indentation]]
=== 4.2 Block indentation: +2 spaces
Each time a new block or block-like construct is opened, the indent increases by two spaces. When the block ends, the indent returns to the previous indent level. The indent level applies to both code and comments throughout the block. (See the example in Section 4.1.2, link:#s4.1.2-blocks-k-r-style[Nonempty blocks: K & R Style].)
[[s4.3-one-statement-per-line]]
=== 4.3 One statement per line
Each statement is followed by a line-break.
[[s4.4-column-limit]]
=== 4.4 Column limit: 80 or 100
Projects are free to choose a column limit of either 80 or 100 characters. Except as noted below, any line that would exceed this limit must be line-wrapped, as explained in Section 4.5, link:#s4.5-line-wrapping[Line-wrapping].
*Exceptions:*
1. Lines where obeying the column limit is not possible (for example, a long URL in Javadoc, or a long JSNI method reference).
2. `package` and `import` statements (see Sections 3.2 link:#s3.2-package-statement[Package statement] and 3.3 link:#s3.3-import-statements[Import statements]).
3. Command lines in a comment that may be cut-and-pasted into a shell.
[[s4.5-line-wrapping]]
=== 4.5 Line-wrapping
*Terminology Note:* When code that might otherwise legally occupy a single line is divided into multiple lines, typically to avoid overflowing the column limit, this activity is called __line-wrapping__.
There is no comprehensive, deterministic formula showing _exactly_ how to line-wrap in every situation. Very often there are several valid ways to line-wrap the same piece of code.
*Tip:* Extracting a method or local variable may solve the problem without the need to line-wrap.
[[s4.5.1-line-wrapping-where-to-break]]
==== 4.5.1 Where to break
The prime directive of line-wrapping is: prefer to break at a **higher syntactic level**. Also:
1. When a line is broken at a _non-assignment_ operator the break comes _before_ the symbol. (Note that this is not the same practice used in Google style for other languages, such as C++ and JavaScript.)
* This also applies to the following "operator-like" symbols: the dot separator (`.`), the ampersand in type bounds (`<T extends Foo & Bar>`), and the pipe in catch blocks (`catch (FooException | BarException e)`).
2. When a line is broken at an _assignment_ operator the break typically comes _after_ the symbol, but either way is acceptable.
* This also applies to the "assignment-operator-like" colon in an enhanced `for` ("foreach") statement.
3. A method or constructor name stays attached to the open parenthesis (`(`) that follows it.
4. A comma (`,`) stays attached to the token that precedes it.
[[s4.5.2-line-wrapping-indent]]
==== 4.5.2 Indent continuation lines at least +4 spaces
When line-wrapping, each line after the first (each __continuation line__) is indented at least +4 from the original line.
When there are multiple continuation lines, indentation may be varied beyond +4 as desired. In general, two continuation lines use the same indentation level if and only if they begin with syntactically parallel elements.
Section 4.6.3 on link:#s4.6.3-horizontal-alignment[Horizontal alignment] addresses the discouraged practice of using a variable number of spaces to align certain tokens with previous lines.
[[s4.6-whitespace]]
=== 4.6 Whitespace
[[s4.6.1-vertical-whitespace]]
==== 4.6.1 Vertical Whitespace
A single blank line appears:
1. _Between_ consecutive members (or initializers) of a class: fields, constructors, methods, nested classes, static initializers, instance initializers.
* *Exception:* A blank line between two consecutive fields (having no other code between them) is optional. Such blank lines are used as needed to create _logical groupings_ of fields.
2. Within method bodies, as needed to create _logical groupings_ of statements.
3. _Optionally_ before the first member or after the last member of the class (neither encouraged nor discouraged).
4. As required by other sections of this document (such as Section 3.3, link:#s3.3-import-statements[Import statements]).
_Multiple_ consecutive blank lines are permitted, but never required (or encouraged).
[[s4.6.2-horizontal-whitespace]]
==== 4.6.2 Horizontal whitespace
Beyond where required by the language or other style rules, and apart from literals, comments and Javadoc, a single ASCII space also appears in the following places **only**.
1. Separating any reserved word, such as `if`, `for` or `catch`, from an open parenthesis (`(`) that follows it on that line
2. Separating any reserved word, such as `else` or `catch`, from a closing curly brace (`}`) that precedes it on that line
3. Before any open curly brace (`{`), with two exceptions:
* `@SomeAnnotation({a, b})` (no space is used)
* `String[][] x = {{"foo"}};` (no space is required between `{{`, by item 8 below)
4. On both sides of any binary or ternary operator. This also applies to the following "operator-like" symbols:
* the ampersand in a conjunctive type bound: `<T extends Foo & Bar>`
* the pipe for a catch block that handles multiple exceptions: `catch (FooException | BarException e)`
* the colon (`:`) in an enhanced `for` ("foreach") statement
5. After `,:;` or the closing parenthesis (`)`) of a cast
6. On both sides of the double slash (`//`) that begins an end-of-line comment. Here, multiple spaces are allowed, but not required.
7. Between the type and variable of a declaration: `List<String> list`
8. _Optional_ just inside both braces of an array initializer
* `new int[] {5, 6}` and `new int[] { 5, 6 }` are both valid
*Note:* This rule never requires or forbids additional space at the start or end of a line, only _interior_ space.
[[s4.6.3-horizontal-alignment]]
==== 4.6.3 Horizontal alignment: never required
*Terminology Note:* _Horizontal alignment_ is the practice of adding a variable number of additional spaces in your code with the goal of making certain tokens appear directly below certain other tokens on previous lines.
This practice is permitted, but is *never required* by Google Style. It is not even required to _maintain_ horizontal alignment in places where it was already used.
Here is an example without alignment, then using alignment:
----------------------------------------------------
private int x; // this is fine
private Color color; // this too
private int x; // permitted, but future edits
private Color color; // may leave it unaligned
----------------------------------------------------
*Tip:* Alignment can aid readability, but it creates problems for future maintenance. Consider a future change that needs to touch just one line. This change may leave the formerly-pleasing formatting mangled, and that is **allowed**. More often it prompts the coder (perhaps you) to adjust whitespace on nearby lines as well, possibly triggering a cascading series of reformattings. That one-line change now has a "blast radius." This can at worst result in pointless busywork, but at best it still corrupts version history information, slows down reviewers and exacerbates merge conflicts.
[[s4.7-grouping-parentheses]]
=== 4.7 Grouping parentheses: recommended
Optional grouping parentheses are omitted only when author and reviewer agree that there is no reasonable chance the code will be misinterpreted without them, nor would they have made the code easier to read. It is _not_ reasonable to assume that every reader has the entire Java operator precedence table memorized.
[[s4.8-specific-constructs]]
=== 4.8 Specific constructs
[[s4.8.1-enum-classes]]
==== 4.8.1 Enum classes
After each comma that follows an enum constant, a line-break is optional.
An enum class with no methods and no documentation on its constants may optionally be formatted as if it were an array initializer (see Section 4.8.3.1 on link:#s4.8.3.1-array-initializers[array initializers]).
-----------------------------------------------------
private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }
-----------------------------------------------------
Since enum classes __are classes__, all other rules for formatting classes apply.
[[s4.8.2-variable-declarations]]
==== 4.8.2 Variable declarations
[[s4.8.2.1-variables-per-declaration]]
===== 4.8.2.1 One variable per declaration
Every variable declaration (field or local) declares only one variable: declarations such as `int a, b;` are not used.
[[s4.8.2.2-variables-limited-scope]]
===== 4.8.2.2 Declared when needed, initialized as soon as possible
Local variables are *not* habitually declared at the start of their containing block or block-like construct. Instead, local variables are declared close to the point they are first used (within reason), to minimize their scope. Local variable declarations typically have initializers, or are initialized immediately after declaration.
[[s4.8.3-arrays]]
==== 4.8.3 Arrays
[[s4.8.3.1-array-initializers]]
===== 4.8.3.1 Array initializers: can be "block-like"
Any array initializer may _optionally_ be formatted as if it were a "block-like construct." For example, the following are all valid (**not** an exhaustive list):
--------------------------------------
new int[] { new int[] {
0, 1, 2, 3 0,
} 1,
2,
new int[] { 3,
0, 1, }
2, 3
} new int[]
{0, 1, 2, 3}
--------------------------------------
[[s4.8.3.2-array-declarations]]
===== 4.8.3.2 No C-style array declarations
The square brackets form a part of the __type__, not the variable: `String[] args`, not `String args[]`.
[[s4.8.4-switch]]
==== 4.8.4 Switch statements
*Terminology Note:* Inside the braces of a _switch block_ are one or more __statement groups__. Each statement group consists of one or more _switch labels_ (either `case FOO:` or `default:`), followed by one or more statements.
[[s4.8.4.1-switch-indentation]]
===== 4.8.4.1 Indentation
As with any other block, the contents of a switch block are indented +2.
After a switch label, a newline appears, and the indentation level is increased +2, exactly as if a block were being opened. The following switch label returns to the previous indentation level, as if a block had been closed.
[[s4.8.4.2-switch-fall-through]]
===== 4.8.4.2 Fall-through: commented
Within a switch block, each statement group either terminates abruptly (with a `break`, `continue`, `return` or thrown exception), or is marked with a comment to indicate that execution will or _might_ continue into the next statement group. Any comment that communicates the idea of fall-through is sufficient (typically `// fall through`). This special comment is not required in the last statement group of the switch block. Example:
-----------------------------
switch (input) {
case 1:
case 2:
prepareOneOrTwo();
// fall through
case 3:
handleOneTwoOrThree();
break;
default:
handleLargeNumber(input);
}
-----------------------------
[[s4.8.4.3-switch-default]]
===== 4.8.4.3 The default case is present
Each switch statement includes a `default` statement group, even if it contains no code.
[[s4.8.5-annotations]]
==== 4.8.5 Annotations
Annotations applying to a class, method or constructor appear immediately after the documentation block, and each annotation is listed on a line of its own (that is, one annotation per line). These line breaks do not constitute line-wrapping (Section 4.5, link:#s4.5-line-wrapping[Line-wrapping]), so the indentation level is not increased. Example:
----------------------------------------
@Override
@Nullable
public String getNameIfPresent() { ... }
----------------------------------------
*Exception:* A _single_ parameterless annotation _may_ instead appear together with the first line of the signature, for example:
---------------------------------------
@Override public int hashCode() { ... }
---------------------------------------
Annotations applying to a field also appear immediately after the documentation block, but in this case, _multiple_ annotations (possibly parameterized) may be listed on the same line; for example:
---------------------------------
@Partial @Mock DataLoader loader;
---------------------------------
There are no specific rules for formatting parameter and local variable annotations.
[[s4.8.6-comments]]
==== 4.8.6 Comments
[[s4.8.6.1-block-comment-style]]
===== 4.8.6.1 Block comment style
Block comments are indented at the same level as the surrounding code. They may be in `/* ... */` style or `// ...` style. For multi-line `/* ... */` comments, subsequent lines must start with `*` aligned with the `*` on the previous line.
-----------------------------------------------------------
/*
* This is // And so /* Or you can
* okay. // is this. * even do this. */
*/
-----------------------------------------------------------
Comments are not enclosed in boxes drawn with asterisks or other characters.
*Tip:* When writing multi-line comments, use the `/* ... */` style if you want automatic code formatters to re-wrap the lines when necessary (paragraph-style). Most formatters don't re-wrap lines in `// ...` style comment blocks.
[[s4.8.7-modifiers]]
==== 4.8.7 Modifiers
Class and member modifiers, when present, appear in the order recommended by the Java Language Specification:
----------------------------------------------------------------------------------------------
public protected private abstract static final transient volatile synchronized native strictfp
----------------------------------------------------------------------------------------------
[[s4.8.8-numeric-literals]]
==== 4.8.8 Numeric Literals
`long`-valued integer literals use an uppercase `L` suffix, never lowercase (to avoid confusion with the digit `1`). For example, `3000000000L` rather than `3000000000l`.
[[s5-naming]]
== 5 Naming
[[s5.1-identifier-names]]
=== 5.1 Rules common to all identifiers
Identifiers use only ASCII letters and digits, and in two cases noted below, underscores. Thus each valid identifier name is matched by the regular expression `\w+` .
In Google Style special prefixes or suffixes, like those seen in the examples `name_`, `mName`, `s_name` and `kName`, are *not* used.
[[s5.2-specific-identifier-names]]
=== 5.2 Rules by identifier type
[[s5.2.1-package-names]]
==== 5.2.1 Package names
Package names are all lowercase, with consecutive words simply concatenated together (no underscores). For example, `com.example.deepspace`, not `com.example.deepSpace` or `com.example.deep_space`.
[[s5.2.2-class-names]]
==== 5.2.2 Class names
Class names are written in link:#s5.3-camel-case[UpperCamelCase].
Class names are typically nouns or noun phrases. For example, `Character` or `ImmutableList`. Interface names may also be nouns or noun phrases (for example, `List`), but may sometimes be adjectives or adjective phrases instead (for example, `Readable`).
There are no specific rules or even well-established conventions for naming annotation types.
_Test_ classes are named starting with the name of the class they are testing, and ending with `Test`. For example, `HashTest` or `HashIntegrationTest`.
[[s5.2.3-method-names]]
==== 5.2.3 Method names
Method names are written in link:#s5.3-camel-case[lowerCamelCase].
Method names are typically verbs or verb phrases. For example, `sendMessage` or `stop`.
Underscores may appear in JUnit _test_ method names to separate logical components of the name. One typical pattern is `test<MethodUnderTest>_<state>`, for example `testPop_emptyStack`. There is no One Correct Way to name test methods.
[[s5.2.4-constant-names]]
==== 5.2.4 Constant names
Constant names use `CONSTANT_CASE`: all uppercase letters, with words separated by underscores. But what _is_ a constant, exactly?
Every constant is a static final field, but not all static final fields are constants. Before choosing constant case, consider whether the field really _feels like_ a constant. For example, if any of that instance's observable state can change, it is almost certainly not a constant. Merely _intending_ to never mutate the object is generally not enough. Examples:
--------------------------------------------------------------------------------------
// Constants
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final Joiner COMMA_JOINER = Joiner.on(','); // because Joiner is immutable
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }
// Not constants
static String nonFinal = "non-final";
final String nonStatic = "non-static";
static final Set<String> mutableCollection = new HashSet<String>();
static final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these", "can", "change"};
--------------------------------------------------------------------------------------
These names are typically nouns or noun phrases.
[[s5.2.5-non-constant-field-names]]
==== 5.2.5 Non-constant field names
Non-constant field names (static or otherwise) are written in link:#s5.3-camel-case[lowerCamelCase].
These names are typically nouns or noun phrases. For example, `computedValues` or `index`.
[[s5.2.6-parameter-names]]
==== 5.2.6 Parameter names
Parameter names are written in link:#s5.3-camel-case[lowerCamelCase].
One-character parameter names should be avoided.
[[s5.2.7-local-variable-names]]
==== 5.2.7 Local variable names
Local variable names are written in link:#s5.3-camel-case[lowerCamelCase], and can be abbreviated more liberally than other types of names.
However, one-character names should be avoided, except for temporary and looping variables.
Even when final and immutable, local variables are not considered to be constants, and should not be styled as constants.
[[s5.2.8-type-variable-names]]
==== 5.2.8 Type variable names
Each type variable is named in one of two styles:
* A single capital letter, optionally followed by a single numeral (such as `E`, `T`, `X`, `T2`)
* A name in the form used for classes (see Section 5.2.2, link:#s5.2.2-class-names[Class names]), followed by the capital letter `T` (examples: `RequestT`, `FooBarT`).
[[s5.3-camel-case]]
=== 5.3 Camel case: defined
Sometimes there is more than one reasonable way to convert an English phrase into camel case, such as when acronyms or unusual constructs like "IPv6" or "iOS" are present. To improve predictability, Google Style specifies the following (nearly) deterministic scheme.
Beginning with the prose form of the name:
1. Convert the phrase to plain ASCII and remove any apostrophes. For example, "Müller's algorithm" might become "Muellers algorithm".
2. Divide this result into words, splitting on spaces and any remaining punctuation (typically hyphens).
* _Recommended:_ if any word already has a conventional camel-case appearance in common usage, split this into its constituent parts (e.g., "AdWords" becomes "ad words"). Note that a word such as "iOS" is not really in camel case __per se__; it defies _any_ convention, so this recommendation does not apply.
3. Now lowercase _everything_ (including acronyms), then uppercase only the first character of:
* ... each word, to yield __upper camel case__, or
* ... each word except the first, to yield _lower camel case_
4. Finally, join all the words into a single identifier.
Note that the casing of the original words is almost entirely disregarded. Examples:
[width="100%",cols="34%,33%,33%",options="header",]
|=================================================================
|Prose form |Correct |Incorrect
|"XML HTTP request" |`XmlHttpRequest` |`XMLHTTPRequest`
|"new customer ID" |`newCustomerId` |`newCustomerID`
|"inner stopwatch" |`innerStopwatch` |`innerStopWatch`
|"supports IPv6 on iOS?" |`supportsIpv6OnIos` |`supportsIPv6OnIOS`
|"YouTube importer" |`YouTubeImporter` +
`YoutubeImporter`* |
|=================================================================
*Acceptable, but not recommended.
*Note:* Some words are ambiguously hyphenated in the English language: for example "nonempty" and "non-empty" are both correct, so the method names `checkNonempty` and `checkNonEmpty` are likewise both correct.
[[s6-programming-practices]]
== 6 Programming Practices
[[s6.1-override-annotation]]
=== 6.1 @Override: always used
A method is marked with the `@Override` annotation whenever it is legal. This includes a class method overriding a superclass method, a class method implementing an interface method, and an interface method respecifying a superinterface method.
**Exception:**`@Override` may be omitted when the parent method is `@Deprecated`.
[[s6.2-caught-exceptions]]
=== 6.2 Caught exceptions: not ignored
Except as noted below, it is very rarely correct to do nothing in response to a caught exception. (Typical responses are to log it, or if it is considered "impossible", rethrow it as an `AssertionError`.)
When it truly is appropriate to take no action whatsoever in a catch block, the reason this is justified is explained in a comment.
-------------------------------------------------
try {
int i = Integer.parseInt(response);
return handleNumericResponse(i);
} catch (NumberFormatException ok) {
// it's not numeric; that's fine, just continue
}
return handleTextResponse(response);
-------------------------------------------------
*Exception:* In tests, a caught exception may be ignored without comment _if_ it is named `expected`. The following is a very common idiom for ensuring that the method under test _does_ throw an exception of the expected type, so a comment is unnecessary here.
-------------------------------------------
try {
emptyStack.pop();
fail();
} catch (NoSuchElementException expected) {
}
-------------------------------------------
[[s6.3-static-members]]
=== 6.3 Static members: qualified using class
When a reference to a static class member must be qualified, it is qualified with that class's name, not with a reference or expression of that class's type.
------------------------------------------------------
Foo aFoo = ...;
Foo.aStaticMethod(); // good
aFoo.aStaticMethod(); // bad
somethingThatYieldsAFoo().aStaticMethod(); // very bad
------------------------------------------------------
[[s6.4-finalizers]]
=== 6.4 Finalizers: not used
It is *extremely rare* to override `Object.finalize`.
*Tip:* Don't do it. If you absolutely must, first read and understand http://books.google.com/books?isbn=8131726592[_Effective Java_] Item 7, "Avoid Finalizers," very carefully, and _then_ don't do it.
[[s7-javadoc]]
== 7 Javadoc
[[s7.1-javadoc-formatting]]
=== 7.1 Formatting
[[s7.1.1-javadoc-multi-line]]
==== 7.1.1 General form
The _basic_ formatting of Javadoc blocks is as seen in this example:
---------------------------------------------------
/**
* Multiple lines of Javadoc text are written here,
* wrapped normally...
*/
public int method(String p1) { ... }
---------------------------------------------------
... or in this single-line example:
------------------------------------------
/** An especially short bit of Javadoc. */
------------------------------------------
The basic form is always acceptable. The single-line form may be substituted when there are no at-clauses present, and the entirety of the Javadoc block (including comment markers) can fit on a single line.
[[s7.1.2-javadoc-paragraphs]]
==== 7.1.2 Paragraphs
One blank line—that is, a line containing only the aligned leading asterisk (`*`)—appears between paragraphs, and before the group of "at-clauses" if present. Each paragraph but the first has `<p>` immediately before the first word, with no space after.
[[s7.1.3-javadoc-at-clauses]]
==== 7.1.3 At-clauses
Any of the standard "at-clauses" that are used appear in the order `@param`, `@return`, `@throws`, `@deprecated`, and these four types never appear with an empty description. When an at-clause doesn't fit on a single line, continuation lines are indented four (or more) spaces from the position of the `@`.
[[s7.2-summary-fragment]]
=== 7.2 The summary fragment
The Javadoc for each class and member begins with a brief **summary fragment**. This fragment is very important: it is the only part of the text that appears in certain contexts such as class and method indexes.
This is a fragment—a noun phrase or verb phrase, not a complete sentence. It does *not* begin with `A {@code Foo} is a...`, or `This method returns...`, nor does it form a complete imperative sentence like `Save the record.`. However, the fragment is capitalized and punctuated as if it were a complete sentence.
*Tip:* A common mistake is to write simple Javadoc in the form `/** @return the customer ID */`. This is incorrect, and should be changed to `/** Returns the customer ID. */`.
[[s7.3-javadoc-where-required]]
=== 7.3 Where Javadoc is used
At the __minimum__, Javadoc is present for every `public` class, and every `public` or `protected` member of such a class, with a few exceptions noted below.
Other classes and members still have Javadoc __as needed__. Whenever an implementation comment would be used to define the overall purpose or behavior of a class, method or field, that comment is written as Javadoc instead. (It's more uniform, and more tool-friendly.)
[[s7.3.1-javadoc-exception-self-explanatory]]
==== 7.3.1 Exception: self-explanatory methods
Javadoc is optional for "simple, obvious" methods like `getFoo`, in cases where there _really and truly_ is nothing else worthwhile to say but "Returns the foo".
*Important:* it is not appropriate to cite this exception to justify omitting relevant information that a typical reader might need to know. For example, for a method named `getCanonicalName`, don't omit its documentation (with the rationale that it would say only `/** Returns the canonical name. */`) if a typical reader may have no idea what the term "canonical name" means!
[[s7.3.2-javadoc-exception-overrides]]
==== 7.3.2 Exception: overrides
Javadoc is not always present on a method that overrides a supertype method.
'''''
Last changed: March 21, 2014

515
javaguide.css
View File

@ -1,515 +0,0 @@
table {
border-collapse: collapse;
}
td, th {
border: 1px solid #ccc;
padding: 2px 12px;
font-size: 10pt;
}
code, samp, var {
color: #060;
}
pre {
font-size: 10pt;
display: block;
color: #060;
background-color: #e8fff6;
border-color: #f0fff0;
border-style: solid;
border-top-width: 1px;
border-bottom-width: 1px;
border-right-width: 1px;
border-left-width: 5px;
padding-left: 12px;
padding-right: 12px;
padding-top: 4px;
padding-bottom: 4px;
}
pre.badcode {
color: #c00;
background-color: #ffe6d8;
border-color: #fff0f0;
}
hr {
margin-top: 3.5em;
border-width: 1px;
color: #fff;
}
html {
margin-top:2em;
margin-left:10%;
margin-right:10%;
padding:0;
}
.bp-reset-element,
body,
h1,
h2,
h3,
h4,
h5,
h6,
article,
aside,
details,
figcaption,
figure,
footer,
header,
hgroup,
menu,
nav,
section,
summary,
blockquote,
q,
th,
td,
caption,
table,
div,
span,
object,
iframe,
p,
pre,
a,
abbr,
acronym,
address,
code,
del,
dfn,
em,
img,
dl,
dt,
dd,
ol,
ul,
li,
fieldset,
form,
label,
legend,
caption,
tbody,
tfoot,
thead,
tr {
margin:0;
padding:0;
border:0;
font-weight:inherit;
font-style:inherit;
font-size:100%;
font-family:inherit;
vertical-align:baseline;
}
body {
font-family:'Arial', sans-serif;
font-size:81.25%;
color:#222;
background-color:#fff;
line-height:1.67;
overflow: auto;
}
.change {
text-align: right;
margin-bottom:1em;
}
em {
font-style: italic
}
h1,
h2,
h3,
h4,
h5,
h6 {
font-weight:bold;
}
h1 {
margin-bottom:.50em;
text-align: center
}
h2,
h3,
h4,
h5,
h6 {
margin-top:1.5em;
margin-bottom:.75em;
}
h1 {font-size:200%;}
h2 {font-size:167%;}
h3 {font-size:133%;}
h4 {font-size:120%;}
h5 {font-size:110%;}
p {
margin:0 0 1.5em;
}
a[href=''] {
cursor:default;
}
h1 img,
h2 img,
h3 img,
h4 img,
h5 img,
h6 img {
margin:0;
}
a img {
border:none;
}
pre {
margin:1.5em 0;
white-space:pre;
}
pre,
code,
kbd,
tt {
font:1em 'Droid Sans Mono', monospace;
line-height:1.5;
}
dl {
margin:0 0 1.5em 0;
}
dl dt {
font-weight:bold;
}
dd {
margin-left:1.5em;
}
dd.toc3 {
margin-left:3em;
}
hr {
height:0;
border:0;
border-top:1px solid #ccc;
background-color:#ccc;
}
table {
border:1px solid #bbb;
border-spacing:0;
border-collapse:collapse;
margin:0 0 1.5em;
vertical-align:middle;
width:100%;
}
table.unlined,
table.unlined th,
table.unlined tr,
table.unlined td {
border:0;
}
th,
td,
caption {
float:none !important;
text-align:left;
font-weight:normal;
vertical-align:middle;
padding:4px;
}
caption {
padding:0;
}
td {
border:1px solid #bbb;
vertical-align:top;
}
th {
border:0;
border-bottom:1px solid black;
font-weight:bold;
background:rgb(229, 236, 249);
}
table th code {
background-color:inherit;
color:inherit;
}
table tfoot th {
border:1px solid #bbb;
}
tfoot {
font-style:italic;
}
caption {
background:#eee;
}
table[border='0'] {
border:none;
}
table[border='0']>tbody>tr>td,
table[border='0']>tr>td {
border:none;
}
tr.alt td,
td.alt {
background-color:#efefef;
}
table.striped tr:nth-child(even) td,
table tr.even td {
background:#efefef;
}
table.columns {
border:none;
}
table.columns>tbody>tr>td,
table.columns>tr>td {
border:none;
padding:0 3em 0 0;
}
table.columns>tbody>tr>td:last-child,
table.columns>tr>td:last-child {
border:none;
padding:0;
}
ul,
ol {
margin:0 1.5em 1.5em 0;
padding-left:2em;
}
li ul,
li ol {
margin:0;
}
ul {
list-style-type:disc;
}
ol {
list-style-type:decimal;
}
ul {
list-style-type:disc;
}
ul ul {
list-style-type:circle;
}
ul ul ul {
list-style-type:square;
}
ul.disc {
list-style-type:disc;
}
ul.circle {
list-style-type:circle;
}
ul.square {
list-style-type:square;
}
ol {
list-style-type:decimal;
}
ol ol {
list-style-type:lower-alpha;
}
ol ol ol {
list-style-type:lower-roman;
}
ol ul {
list-style-type:circle;
}
ol.decimal {
list-style-type:decimal;
}
ol.upper-alpha {
list-style-type:upper-alpha;
}
ol.lower-alpha {
list-style-type:lower-alpha;
}
ol.upper-roman {
list-style-type:upper-roman;
}
ol.lower-roman {
list-style-type:lower-roman;
}
ol.nolist,
ul.nolist {
padding-left:0;
list-style-image:none;
list-style-type:none;
margin-left:0;
}
.center {
text-align:center;
}
code,
kbd,
pre {
color:#009900;
}
kbd {
font-weight: bold;
}
table.striped code {
background-color:inherit;
}
pre {
padding:6px 10px;
background-color:#FAFAFA;
border:1px solid #bbb;
overflow:auto;
}
pre.prettyprint {
padding:6px 10px !important;
border:1px solid #bbb !important;
}
code.bad, code.badcode {
color: magenta;
}
pre.bad, pre.badcode {
background-color:#ffe6d8;
border-top:1px inset #a03;
border-left:1px inset #a03;
}
.tip {
background-color:#fffbd9;
padding:6px 8px 6px 10px;
border-left:6px solid #ffef70;
}
.note {
background-color:#e5ecf9;
padding:6px 8px 6px 10px;
border-left:6px solid #36c;
}
@media print {
.str {
color:#060;
}
.kwd {
color:#006;
font-weight:bold;
}
.com {
color:#600;
font-style:italic;
}
.typ {
color:#404;
font-weight:bold;
}
.lit {
color:#044;
}
.pun,
.opn,
.clo {
color:#440;
}
.pln {
color:#000;
}
.tag {
color:#006;
font-weight:bold;
}
.atn {
color:#404;
}
.atv {
color:#060;
}
h1 {
font-style:italic;
}
}
ol.linenums {
margin-top:0;
margin-bottom:0;
}
code {
background-color:#FAFAFA;
padding: 0.25em 0.5em;
white-space: nowrap
}

793
javaguide.html
View File

@ -1,793 +0,0 @@
<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<link rel="stylesheet" type="text/css" href="javaguide.css"/>
<script src="https://google-code-prettify.googlecode.com/svn/loader/run_prettify.js"
type="text/javascript"></script>
<link href="http://www.google.com/favicon.ico"
type="image/x-icon" rel="shortcut icon" />
<title>Google Java Style</title>
</head>
<body>
<h1>Google Java Style</h1>
<div class="change">Last changed: March 21, 2014</div>
<table border="0">
<tr>
<td>
<dl>
<br>
<dt class="toc1">
<a href="#s1-introduction">1 Introduction</a>
</dt>
<dd>
<a href="#s1.1-terminology">1.1 Terminology notes</a>
</dd>
<dd>
<a href="#s1.2-guide-notes">1.2 Guide notes</a>
</dd>
<br>
<dt class="toc1">
<a href="#s2-source-file-basics">2 Source file basics</a>
</dt>
<dd>
<a href="#s2.1-file-name">2.1 File name</a>
</dd>
<dd>
<a href="#s2.2-file-encoding">2.2 File encoding: UTF-8</a>
</dd>
<dd>
<a href="#s2.3-special-characters">2.3 Special characters</a>
</dd>
<dd class="toc3">
<a href="#s2.3.1-whitespace-characters">2.3.1 Whitespace characters</a>
</dd>
<dd class="toc3">
<a href="#s2.3.2-special-escape-sequences">2.3.2 Special escape sequences</a>
</dd>
<dd class="toc3">
<a href="#s2.3.3-non-ascii-characters">2.3.3 Non-ASCII characters</a>
</dd>
<br>
<dt class="toc1">
<a href="#s3-source-file-structure">3 Source file structure</a>
</dt>
<dd>
<a href="#s3.1-copyright-statement">3.1 License or copyright information, if present</a>
</dd>
<dd>
<a href="#s3.2-package-statement">3.2 Package statement</a>
</dd>
<dd>
<a href="#s3.3-import-statements">3.3 Import statements</a>
</dd>
<dd class="toc3">
<a href="#s3.3.1-wildcard-imports">3.3.1 No wildcard imports</a>
</dd>
<dd class="toc3">
<a href="#s3.3.2-import-line-wrapping">3.3.2 No line-wrapping</a>
</dd>
<dd class="toc3">
<a href="#s3.3.3-import-ordering-and-spacing">3.3.3 Ordering and spacing</a>
</dd>
<dd>
<a href="#s3.4-class-declaration">3.4 Class declaration</a>
</dd>
<dd class="toc3">
<a href="#s3.4.1-one-top-level-class">3.4.1 Exactly one top-level class declaration</a>
</dd>
<dd class="toc3">
<a href="#s3.4.2-class-member-ordering">3.4.2 Class member ordering</a>
</dd>
</dl>
</td><td>
<dl>
<br>
<dt class="toc1">
<a href="#s4-formatting">4 Formatting</a>
</dt>
<dd>
<a href="#s4.1-braces">4.1 Braces</a>
</dd>
<dd class="toc3">
<a href="#s4.1.1-braces-always-used">4.1.1 Braces are used where optional</a>
</dd>
<dd class="toc3">
<a href="#s4.1.2-blocks-k-r-style">4.1.2 Nonempty blocks: K &amp; R style</a>
</dd>
<dd class="toc3">
<a href="#s4.1.3-braces-empty-blocks">4.1.3 Empty blocks: may be concise</a>
</dd>
<dd>
<a href="#s4.2-block-indentation">4.2 Block indentation: +2 spaces</a>
</dd>
<dd>
<a href="#s4.3-one-statement-per-line">4.3 One statement per line</a>
</dd>
<dd>
<a href="#s4.4-column-limit">4.4 Column limit: 80 or 100</a>
</dd>
<dd>
<a href="#s4.5-line-wrapping">4.5 Line-wrapping</a>
</dd>
<dd class="toc3">
<a href="#s4.5.1-line-wrapping-where-to-break">4.5.1 Where to break</a>
</dd>
<dd class="toc3">
<a href="#s4.5.2-line-wrapping-indent">4.5.2 Indent continuation lines at least +4 spaces</a>
</dd>
<dd>
<a href="#s4.6-whitespace">4.6 Whitespace</a>
</dd>
<dd class="toc3">
<a href="#s4.6.1-vertical-whitespace">4.6.1 Vertical Whitespace</a>
</dd>
<dd class="toc3">
<a href="#s4.6.2-horizontal-whitespace">4.6.2 Horizontal whitespace</a>
</dd>
<dd class="toc3">
<a href="#s4.6.3-horizontal-alignment">4.6.3 Horizontal alignment: never required</a>
</dd>
<dd>
<a href="#s4.7-grouping-parentheses">4.7 Grouping parentheses: recommended</a>
</dd>
<dd>
<a href="#s4.8-specific-constructs">4.8 Specific constructs</a>
</dd>
<dd class="toc3">
<a href="#s4.8.1-enum-classes">4.8.1 Enum classes</a>
</dd>
<dd class="toc3">
<a href="#s4.8.2-variable-declarations">4.8.2 Variable declarations</a>
</dd>
<dd class="toc3">
<a href="#s4.8.3-arrays">4.8.3 Arrays</a>
</dd>
<dd class="toc3">
<a href="#s4.8.4-switch">4.8.4 Switch statements</a>
</dd>
<dd class="toc3">
<a href="#s4.8.5-annotations">4.8.5 Annotations</a>
</dd>
<dd class="toc3">
<a href="#s4.8.6-comments">4.8.6 Comments</a>
</dd>
<dd class="toc3">
<a href="#s4.8.7-modifiers">4.8.7 Modifiers</a>
</dd>
<dd class="toc3">
<a href="#s4.8.8-numeric-literals">4.8.8 Numeric Literals</a>
</dd>
</dl>
</td><td>
<dl>
<br>
<dt class="toc1">
<a href="#s5-naming">5 Naming</a>
</dt>
<dd>
<a href="#s5.1-identifier-names">5.1 Rules common to all identifiers</a>
</dd>
<dd>
<a href="#s5.2-specific-identifier-names">5.2 Rules by identifier type</a>
</dd>
<dd class="toc3">
<a href="#s5.2.1-package-names">5.2.1 Package names</a>
</dd>
<dd class="toc3">
<a href="#s5.2.2-class-names">5.2.2 Class names</a>
</dd>
<dd class="toc3">
<a href="#s5.2.3-method-names">5.2.3 Method names</a>
</dd>
<dd class="toc3">
<a href="#s5.2.4-constant-names">5.2.4 Constant names</a>
</dd>
<dd class="toc3">
<a href="#s5.2.5-non-constant-field-names">5.2.5 Non-constant field names</a>
</dd>
<dd class="toc3">
<a href="#s5.2.6-parameter-names">5.2.6 Parameter names</a>
</dd>
<dd class="toc3">
<a href="#s5.2.7-local-variable-names">5.2.7 Local variable names</a>
</dd>
<dd class="toc3">
<a href="#s5.2.8-type-variable-names">5.2.8 Type variable names</a>
</dd>
<dd>
<a href="#s5.3-camel-case">5.3 Camel case: defined</a>
</dd>
<br>
<dt class="toc1">
<a href="#s6-programming-practices">6 Programming Practices</a>
</dt>
<dd>
<a href="#s6.1-override-annotation">6.1 @Override: always used</a>
</dd>
<dd>
<a href="#s6.2-caught-exceptions">6.2 Caught exceptions: not ignored</a>
</dd>
<dd>
<a href="#s6.3-static-members">6.3 Static members: qualified using class</a>
</dd>
<dd>
<a href="#s6.4-finalizers">6.4 Finalizers: not used</a>
</dd>
<br>
<dt class="toc1">
<a href="#s7-javadoc">7 Javadoc</a>
</dt>
<dd>
<a href="#s7.1-javadoc-formatting">7.1 Formatting</a>
</dd>
<dd class="toc3">
<a href="#s7.1.1-javadoc-multi-line">7.1.1 General form</a>
</dd>
<dd class="toc3">
<a href="#s7.1.2-javadoc-paragraphs">7.1.2 Paragraphs</a>
</dd>
<dd class="toc3">
<a href="#s7.1.3-javadoc-at-clauses">7.1.3 At-clauses</a>
</dd>
<dd>
<a href="#s7.2-summary-fragment">7.2 The summary fragment</a>
</dd>
<dd>
<a href="#s7.3-javadoc-where-required">7.3 Where Javadoc is used</a>
</dd>
<dd class="toc3">
<a href="#s7.3.1-javadoc-exception-self-explanatory">7.3.1 Exception: self-explanatory methods</a>
</dd>
<dd class="toc3">
<a href="#s7.3.2-javadoc-exception-overrides">7.3.2 Exception: overrides</a>
</dd>
</dl>
</td>
</tr>
</table>
<div><a name="s1-introduction"/>
<h2>1 Introduction&nbsp;<a href="#s1-introduction"><img height="21" width="21" src="javaguidelink.png"/></a></h2>
<p>This document serves as the <strong>complete</strong> definition of Google's coding standards for
source code in the Java™ Programming Language. A Java source file is described as being <em>in
Google Style</em> if and only if it adheres to the rules herein.</p><p>Like other programming style guides, the issues covered span not only aesthetic issues of
formatting, but other types of conventions or coding standards as well. However, this document
focuses primarily on the <strong>hard-and-fast rules</strong> that we follow universally, and
avoids giving <em>advice</em> that isn't clearly enforceable (whether by human or tool).
</p><a name="s1.1-terminology"/>
<h3>1.1 Terminology notes&nbsp;<a href="#s1.1-terminology"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>In this document, unless otherwise clarified:</p><ol><li>The term <em>class</em> is used inclusively to mean an "ordinary" class, enum class,
interface or annotation type (<code class="prettyprint lang-java">@interface</code>).</li><li>The term <em>comment</em> always refers to <em>implementation</em> comments. We do not
use the phrase "documentation comments", instead using the common term "Javadoc."</li></ol><p>Other "terminology notes" will appear occasionally throughout the document.</p><a name="s1.2-guide-notes"/>
<h3>1.2 Guide notes&nbsp;<a href="#s1.2-guide-notes"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>Example code in this document is <strong>non-normative</strong>. That is, while the examples
are in Google Style, they may not illustrate the <em>only</em> stylish way to represent the
code. Optional formatting choices made in examples should not be enforced as rules.</p><a name="s2-source-file-basics"/>
<h2>2 Source file basics&nbsp;<a href="#s2-source-file-basics"><img height="21" width="21" src="javaguidelink.png"/></a></h2>
<a name="s2.1-file-name"/>
<h3>2.1 File name&nbsp;<a href="#s2.1-file-name"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>The source file name consists of the case-sensitive name of the top-level class it contains,
plus the <code>.java</code> extension.</p><a name="s2.2-file-encoding"/>
<h3>2.2 File encoding: UTF-8&nbsp;<a href="#s2.2-file-encoding"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>Source files are encoded in <strong>UTF-8</strong>.</p><a name="s2.3-special-characters"/>
<h3>2.3 Special characters&nbsp;<a href="#s2.3-special-characters"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<a name="s2.3.1-whitespace-characters"/>
<h4>2.3.1 Whitespace characters&nbsp;<a href="#s2.3.1-whitespace-characters"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Aside from the line terminator sequence, the <strong>ASCII horizontal space
character</strong> (<strong>0x20</strong>) is the only whitespace character that appears
anywhere in a source file. This implies that:</p><ol><li>All other whitespace characters in string and character literals are escaped.</li><li>Tab characters are <strong>not</strong> used for indentation.</li></ol><a name="s2.3.2-special-escape-sequences"/>
<h4>2.3.2 Special escape sequences&nbsp;<a href="#s2.3.2-special-escape-sequences"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>For any character that has a special escape sequence
(<code class="prettyprint lang-java">\b</code>,
<code class="prettyprint lang-java">\t</code>,
<code class="prettyprint lang-java">\n</code>,
<code class="prettyprint lang-java">\f</code>,
<code class="prettyprint lang-java">\r</code>,
<code class="prettyprint lang-java">\"</code>,
<code class="prettyprint lang-java">\'</code> and
<code class="prettyprint lang-java">\\</code>), that sequence
is used rather than the corresponding octal
(e.g. <code class="badcode">\012</code>) or Unicode
(e.g. <code class="badcode">\u000a</code>) escape.</p><a name="s2.3.3-non-ascii-characters"/>
<h4>2.3.3 Non-ASCII characters&nbsp;<a href="#s2.3.3-non-ascii-characters"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>For the remaining non-ASCII characters, either the actual Unicode character
(e.g. <code class="prettyprint lang-java">∞</code>) or the equivalent Unicode escape
(e.g. <code class="prettyprint lang-java">\u221e</code>) is used, depending only on which
makes the code <strong>easier to read and understand</strong>.</p><p class="tip"><strong>Tip:</strong> In the Unicode escape case, and occasionally even when actual
Unicode characters are used, an explanatory comment can be very helpful.</p><p>Examples:</p><table><tr><th>Example</th><th>Discussion</th></tr><tr><td><code class="prettyprint lang-java">String unitAbbrev = "μs";</code></td><td>Best: perfectly clear even without a comment.</td></tr><tr><td><code class="prettyprint lang-java">String unitAbbrev = "\u03bcs"; // "μs"</code></td><td>Allowed, but there's no reason to do this.</td></tr><tr><td><code class="prettyprint lang-java">String unitAbbrev = "\u03bcs";
// Greek letter mu, "s"</code></td><td>Allowed, but awkward and prone to mistakes.</td></tr><tr><td><code class="badcode">String unitAbbrev = "\u03bcs";</code></td><td>Poor: the reader has no idea what this is.</td></tr><tr><td><code class="prettyprint lang-java">return '\ufeff' + content;
// byte order mark</code></td><td>Good: use escapes for non-printable characters, and comment if necessary.</td></tr></table><p class="tip"><strong>Tip:</strong> Never make your code less readable simply out of fear that
some programs might not handle non-ASCII characters properly. If that should happen, those
programs are <strong>broken</strong> and they must be <strong>fixed</strong>.</p><a name="filestructure"/><a name="s3-source-file-structure"/>
<h2>3 Source file structure&nbsp;<a href="#s3-source-file-structure"><img height="21" width="21" src="javaguidelink.png"/></a></h2>
<div><p>A source file consists of, <strong>in order</strong>:</p><ol><li>License or copyright information, if present</li><li>Package statement</li><li>Import statements</li><li>Exactly one top-level class</li></ol></div><p><strong>Exactly one blank line</strong> separates each section that is present.</p><a name="s3.1-copyright-statement"/>
<h3>3.1 License or copyright information, if present&nbsp;<a href="#s3.1-copyright-statement"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>If license or copyright information belongs in a file, it belongs here.</p><a name="s3.2-package-statement"/>
<h3>3.2 Package statement&nbsp;<a href="#s3.2-package-statement"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>The package statement is <strong>not line-wrapped</strong>. The column limit (Section 4.4,
<a href="#s4.4-column-limit">Column limit: 80 or 100</a>) does not apply to package statements.</p><a name="imports"/><a name="s3.3-import-statements"/>
<h3>3.3 Import statements&nbsp;<a href="#s3.3-import-statements"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<a name="s3.3.1-wildcard-imports"/>
<h4>3.3.1 No wildcard imports&nbsp;<a href="#s3.3.1-wildcard-imports"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p><strong>Wildcard imports</strong>, static or otherwise, <strong>are not used</strong>.</p><a name="s3.3.2-import-line-wrapping"/>
<h4>3.3.2 No line-wrapping&nbsp;<a href="#s3.3.2-import-line-wrapping"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Import statements are <strong>not line-wrapped</strong>. The column limit (Section 4.4,
<a href="#s4.4-column-limit">Column limit: 80 or 100</a>) does not apply to import
statements.</p><a name="s3.3.3-import-ordering-and-spacing"/>
<h4>3.3.3 Ordering and spacing&nbsp;<a href="#s3.3.3-import-ordering-and-spacing"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Import statements are divided into the following groups, in this order, with each group
separated by a single blank line:</p><ol><li>All static imports in a single group</li><li><code>com.google</code> imports
(only if this source file is in the <code>com.google</code> package
space)</li><li>Third-party imports, one group per top-level package, in ASCII sort order
<ul><li>for example: <code>android</code>, <code>com</code>, <code>junit</code>, <code>org</code>,
<code>sun</code></li></ul></li><li><code>java</code> imports</li><li><code>javax</code> imports</li></ol><p>Within a group there are no blank lines, and the imported names appear in ASCII sort
order. (<strong>Note:</strong> this is not the same as the import <em>statements</em> being in
ASCII sort order; the presence of semicolons warps the result.)</p><a name="s3.4-class-declaration"/>
<h3>3.4 Class declaration&nbsp;<a href="#s3.4-class-declaration"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<a name="oneclassperfile"/><a name="s3.4.1-one-top-level-class"/>
<h4>3.4.1 Exactly one top-level class declaration&nbsp;<a href="#s3.4.1-one-top-level-class"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Each top-level class resides in a source file of its own.</p><a name="s3.4.2-class-member-ordering"/>
<h4>3.4.2 Class member ordering&nbsp;<a href="#s3.4.2-class-member-ordering"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>The ordering of the members of a class can have a great effect on learnability, but there is
no single correct recipe for how to do it. Different classes may order their members
differently.</p><p>What is important is that each class order its members in <strong><em>some</em> logical
order</strong>, which its maintainer could explain if asked. For example, new methods are not
just habitually added to the end of the class, as that would yield "chronological by date
added" ordering, which is not a logical ordering.</p><a name="overloads"/><a name="s3.4.2.1-overloads-never-split"/>
<h5>3.4.2.1 Overloads: never split&nbsp;<a href="#s3.4.2.1-overloads-never-split"><img height="21" width="21" src="javaguidelink.png"/></a></h5>
<p>When a class has multiple constructors, or multiple methods with the same name, these appear
sequentially, with no intervening members.</p><a name="s4-formatting"/>
<h2>4 Formatting&nbsp;<a href="#s4-formatting"><img height="21" width="21" src="javaguidelink.png"/></a></h2>
<p class="terminology"><strong>Terminology Note:</strong> <em>block-like construct</em> refers to
the body of a class, method or constructor. Note that, by Section 4.8.3.1 on
<a href="#s4.8.3.1-array-initializers">array initializers</a>, any array initializer
<em>may</em> optionally be treated as if it were a block-like construct.</p><a name="braces"/><a name="s4.1-braces"/>
<h3>4.1 Braces&nbsp;<a href="#s4.1-braces"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<a name="s4.1.1-braces-always-used"/>
<h4>4.1.1 Braces are used where optional&nbsp;<a href="#s4.1.1-braces-always-used"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Braces are used with
<code class="prettyprint lang-java">if</code>,
<code class="prettyprint lang-java">else</code>,
<code class="prettyprint lang-java">for</code>,
<code class="prettyprint lang-java">do</code> and
<code class="prettyprint lang-java">while</code> statements, even when the
body is empty or contains only a single statement.</p><a name="s4.1.2-blocks-k-r-style"/>
<h4>4.1.2 Nonempty blocks: K &amp; R style&nbsp;<a href="#s4.1.2-blocks-k-r-style"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Braces follow the Kernighan and Ritchie style
("<a href="http://www.codinghorror.com/blog/2012/07/new-programming-jargon.html">Egyptian brackets</a>")
for <em>nonempty</em> blocks and block-like constructs:</p><ul><li>No line break before the opening brace.</li><li>Line break after the opening brace.</li><li>Line break before the closing brace.</li><li>Line break after the closing brace <em>if</em> that brace terminates a statement or the body
of a method, constructor or <em>named</em> class. For example, there is <em>no</em> line break
after the brace if it is followed by <code class="prettyprint lang-java">else</code> or a
comma.</li></ul><p>Example:</p><pre class="prettyprint lang-java">
return new MyClass() {
@Override public void method() {
if (condition()) {
try {
something();
} catch (ProblemException e) {
recover();
}
}
}
};
</pre><p>A few exceptions for enum classes are given in Section 4.8.1,
<a href="#s4.8.1-enum-classes">Enum classes</a>.</p><a name="emptyblocks"/><a name="s4.1.3-braces-empty-blocks"/>
<h4>4.1.3 Empty blocks: may be concise&nbsp;<a href="#s4.1.3-braces-empty-blocks"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>An empty block or block-like construct <em>may</em> be closed immediately after it is
opened, with no characters or line break in between
(<code class="prettyprint lang-java">{}</code>), <strong>unless</strong> it is part of a
<em>multi-block statement</em> (one that directly contains multiple blocks:
<code class="prettyprint lang-java">if/else-if/else</code> or
<code class="prettyprint lang-java">try/catch/finally</code>).</p><p>Example:</p><pre class="prettyprint lang-java">
void doNothing() {}
</pre><a name="s4.2-block-indentation"/>
<h3>4.2 Block indentation: +2 spaces&nbsp;<a href="#s4.2-block-indentation"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>Each time a new block or block-like construct is opened, the indent increases by two
spaces. When the block ends, the indent returns to the previous indent level. The indent level
applies to both code and comments throughout the block. (See the example in Section 4.1.2,
<a href="#s4.1.2-blocks-k-r-style">Nonempty blocks: K &amp; R Style</a>.)</p><a name="s4.3-one-statement-per-line"/>
<h3>4.3 One statement per line&nbsp;<a href="#s4.3-one-statement-per-line"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>Each statement is followed by a line-break.</p><a name="columnlimit"/><a name="s4.4-column-limit"/>
<h3>4.4 Column limit: 80 or 100&nbsp;<a href="#s4.4-column-limit"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>
Projects are free to choose a column limit of either 80 or 100 characters.
Except as noted below, any line that would exceed this limit must be line-wrapped, as explained in
Section 4.5, <a href="#s4.5-line-wrapping">Line-wrapping</a>.
</p><p><strong>Exceptions:</strong></p><ol><li>Lines where obeying the column limit is not possible (for example, a long URL in Javadoc,
or a long JSNI method reference).</li><li><code class="prettyprint lang-java">package</code> and
<code class="prettyprint lang-java">import</code> statements (see Sections
3.2 <a href="#s3.2-package-statement">Package statement</a> and
3.3 <a href="#s3.3-import-statements">Import statements</a>).</li><li>Command lines in a comment that may be cut-and-pasted into a shell.</li></ol><a name="s4.5-line-wrapping"/>
<h3>4.5 Line-wrapping&nbsp;<a href="#s4.5-line-wrapping"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p class="terminology"><strong>Terminology Note:</strong> When code that might otherwise legally
occupy a single line is divided into multiple lines, typically to avoid overflowing the column
limit, this activity is called
<em>line-wrapping</em>.</p><p>There is no comprehensive, deterministic formula showing <em>exactly</em> how to line-wrap in
every situation. Very often there are several valid ways to line-wrap the same piece of code.</p><p class="tip"><strong>Tip:</strong> Extracting a method or local variable may solve the problem
without the need to line-wrap.</p><a name="s4.5.1-line-wrapping-where-to-break"/>
<h4>4.5.1 Where to break&nbsp;<a href="#s4.5.1-line-wrapping-where-to-break"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>The prime directive of line-wrapping is: prefer to break at a
<strong>higher syntactic level</strong>. Also:</p><ol><li>When a line is broken at a <em>non-assignment</em> operator the break comes <em>before</em>
the symbol. (Note that this is not the same practice used in Google style for other languages,
such as C++ and JavaScript.)
<ul><li>This also applies to the following "operator-like" symbols: the dot separator
(<code class="prettyprint lang-java">.</code>), the ampersand in type bounds
(<code class="prettyprint lang-java">&lt;T extends Foo &amp; Bar&gt;</code>), and the pipe in
catch blocks
(<code class="prettyprint lang-java">catch (FooException | BarException e)</code>).</li></ul></li><li>When a line is broken at an <em>assignment</em> operator the break typically comes
<em>after</em> the symbol, but either way is acceptable.
<ul><li>This also applies to the "assignment-operator-like" colon in an enhanced
<code class="prettyprint lang-java">for</code> ("foreach") statement.</li></ul></li><li>A method or constructor name stays attached to the open parenthesis
(<code class="prettyprint lang-java">(</code>) that follows it.</li><li>A comma (<code class="prettyprint lang-java">,</code>) stays attached to the token that
precedes it.</li></ol><a name="indentation"/><a name="s4.5.2-line-wrapping-indent"/>
<h4>4.5.2 Indent continuation lines at least +4 spaces&nbsp;<a href="#s4.5.2-line-wrapping-indent"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>When line-wrapping, each line after the first (each <em>continuation line</em>) is indented
at least +4 from the original line.</p><p>When there are multiple continuation lines, indentation may be varied beyond +4 as
desired. In general, two continuation lines use the same indentation level if and only if they
begin with syntactically parallel elements.</p><p>Section 4.6.3 on <a href="#s4.6.3-horizontal-alignment">Horizontal alignment</a> addresses
the discouraged practice of using a variable number of spaces to align certain tokens with
previous lines.</p><a name="s4.6-whitespace"/>
<h3>4.6 Whitespace&nbsp;<a href="#s4.6-whitespace"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<a name="s4.6.1-vertical-whitespace"/>
<h4>4.6.1 Vertical Whitespace&nbsp;<a href="#s4.6.1-vertical-whitespace"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>A single blank line appears:</p><ol><li><em>Between</em> consecutive members (or initializers) of a class: fields, constructors,
methods, nested classes, static initializers, instance initializers.
<ul><li><span class="exception"><strong>Exception:</strong> A blank line between two consecutive
fields (having no other code between them) is optional. Such blank lines are used as needed to
create <em>logical groupings</em> of fields.</span></li></ul></li><li>Within method bodies, as needed to create <em>logical groupings</em> of statements.</li><li><em>Optionally</em> before the first member or after the last member of the class (neither
encouraged nor discouraged).</li><li>As required by other sections of this document (such as Section 3.3,
<a href="#s3.3-import-statements">Import statements</a>).</li></ol><p><em>Multiple</em> consecutive blank lines are permitted, but never required (or encouraged).</p><a name="s4.6.2-horizontal-whitespace"/>
<h4>4.6.2 Horizontal whitespace&nbsp;<a href="#s4.6.2-horizontal-whitespace"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Beyond where required by the language or other style rules, and apart from literals, comments and
Javadoc, a single ASCII space also appears in the following places <strong>only</strong>.</p><ol><li>Separating any reserved word, such as
<code class="prettyprint lang-java">if</code>,
<code class="prettyprint lang-java">for</code> or
<code class="prettyprint lang-java">catch</code>, from an open parenthesis
(<code class="prettyprint lang-java">(</code>)
that follows it on that line</li><li>Separating any reserved word, such as
<code class="prettyprint lang-java">else</code> or
<code class="prettyprint lang-java">catch</code>, from a closing curly brace
(<code class="prettyprint lang-java">}</code>) that precedes it on that line</li><li>Before any open curly brace
(<code class="prettyprint lang-java">{</code>), with two exceptions:
<ul><li><code class="prettyprint lang-java">@SomeAnnotation({a, b})</code> (no space is used)</li><li><code class="prettyprint lang-java">String[][] x = {{"foo"}};</code> (no space is required
between <code class="prettyprint lang-java">{{</code>, by item 8 below)</li></ul></li><li>On both sides of any binary or ternary operator. This also applies to the following
"operator-like" symbols:
<ul><li>the ampersand in a conjunctive type bound:
<code class="prettyprint lang-java">&lt;T extends Foo &amp; Bar&gt;</code></li><li>the pipe for a catch block that handles multiple exceptions:
<code class="prettyprint lang-java">catch (FooException | BarException e)</code></li><li>the colon (<code class="prettyprint lang-java">:</code>) in an enhanced
<code class="prettyprint lang-java">for</code> ("foreach") statement</li></ul></li><li>After <code class="prettyprint lang-java">,:;</code> or the closing parenthesis
(<code class="prettyprint lang-java">)</code>) of a cast</li><li>On both sides of the double slash (<code class="prettyprint lang-java">//</code>) that
begins an end-of-line comment. Here, multiple spaces are allowed, but not required.</li><li>Between the type and variable of a declaration:
<code class="prettyprint lang-java">List&lt;String&gt; list</code></li><li><em>Optional</em> just inside both braces of an array initializer
<ul><li><code class="prettyprint lang-java">new int[] {5, 6}</code> and
<code class="prettyprint lang-java">new int[] { 5, 6 }</code> are both valid</li></ul></li></ol><p class="note"><strong>Note:</strong> This rule never requires or forbids additional space at the
start or end of a line, only <em>interior</em> space.</p><a name="s4.6.3-horizontal-alignment"/>
<h4>4.6.3 Horizontal alignment: never required&nbsp;<a href="#s4.6.3-horizontal-alignment"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p class="terminology"><strong>Terminology Note:</strong> <em>Horizontal alignment</em> is the
practice of adding a variable number of additional spaces in your code with the goal of making
certain tokens appear directly below certain other tokens on previous lines.</p><p>This practice is permitted, but is <strong>never required</strong> by Google Style. It is not
even required to <em>maintain</em> horizontal alignment in places where it was already used.</p><p>Here is an example without alignment, then using alignment:</p><pre class="prettyprint lang-java">
private int x; // this is fine
private Color color; // this too
private int x; // permitted, but future edits
private Color color; // may leave it unaligned
</pre><p class="tip"><strong>Tip:</strong> Alignment can aid readability, but it creates problems for
future maintenance. Consider a future change that needs to touch just one line. This change may
leave the formerly-pleasing formatting mangled, and that is <strong>allowed</strong>. More often
it prompts the coder (perhaps you) to adjust whitespace on nearby lines as well, possibly
triggering a cascading series of reformattings. That one-line change now has a "blast radius."
This can at worst result in pointless busywork, but at best it still corrupts version history
information, slows down reviewers and exacerbates merge conflicts.</p><a name="parentheses"/><a name="s4.7-grouping-parentheses"/>
<h3>4.7 Grouping parentheses: recommended&nbsp;<a href="#s4.7-grouping-parentheses"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>Optional grouping parentheses are omitted only when author and reviewer agree that there is no
reasonable chance the code will be misinterpreted without them, nor would they have made the code
easier to read. It is <em>not</em> reasonable to assume that every reader has the entire Java
operator precedence table memorized.</p><a name="s4.8-specific-constructs"/>
<h3>4.8 Specific constructs&nbsp;<a href="#s4.8-specific-constructs"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<a name="s4.8.1-enum-classes"/>
<h4>4.8.1 Enum classes&nbsp;<a href="#s4.8.1-enum-classes"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>After each comma that follows an enum constant, a line-break is optional.</p><p>An enum class with no methods and no documentation on its constants may optionally be formatted
as if it were an array initializer (see Section 4.8.3.1 on
<a href="#s4.8.3.1-array-initializers">array initializers</a>).</p><pre class="prettyprint lang-java">
private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }
</pre><p>Since enum classes <em>are classes</em>, all other rules for formatting classes apply.</p><a name="localvariables"/><a name="s4.8.2-variable-declarations"/>
<h4>4.8.2 Variable declarations&nbsp;<a href="#s4.8.2-variable-declarations"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<a name="s4.8.2.1-variables-per-declaration"/>
<h5>4.8.2.1 One variable per declaration&nbsp;<a href="#s4.8.2.1-variables-per-declaration"><img height="21" width="21" src="javaguidelink.png"/></a></h5>
<p>Every variable declaration (field or local) declares only one variable: declarations such as
<code class="badcode">int a, b;</code> are not used.</p><a name="s4.8.2.2-variables-limited-scope"/>
<h5>4.8.2.2 Declared when needed, initialized as soon as
possible&nbsp;<a href="#s4.8.2.2-variables-limited-scope"><img height="21" width="21" src="javaguidelink.png"/></a></h5>
<p>Local variables are <strong>not</strong> habitually declared at the start of their containing
block or block-like construct. Instead, local variables are declared close to the point they are
first used (within reason), to minimize their scope. Local variable declarations typically have
initializers, or are initialized immediately after declaration.</p><a name="s4.8.3-arrays"/>
<h4>4.8.3 Arrays&nbsp;<a href="#s4.8.3-arrays"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<a name="s4.8.3.1-array-initializers"/>
<h5>4.8.3.1 Array initializers: can be "block-like"&nbsp;<a href="#s4.8.3.1-array-initializers"><img height="21" width="21" src="javaguidelink.png"/></a></h5>
<p>Any array initializer may <em>optionally</em> be formatted as if it were a "block-like
construct." For example, the following are all valid (<strong>not</strong> an exhaustive
list):</p><pre class="prettyprint lang-java">
new int[] { new int[] {
0, 1, 2, 3 0,
} 1,
2,
new int[] { 3,
0, 1, }
2, 3
} new int[]
{0, 1, 2, 3}
</pre><a name="s4.8.3.2-array-declarations"/>
<h5>4.8.3.2 No C-style array declarations&nbsp;<a href="#s4.8.3.2-array-declarations"><img height="21" width="21" src="javaguidelink.png"/></a></h5>
<p>The square brackets form a part of the <em>type</em>, not the variable:
<code class="prettyprint lang-java">String[] args</code>, not
<code class="badcode">String args[]</code>.</p><a name="s4.8.4-switch"/>
<h4>4.8.4 Switch statements&nbsp;<a href="#s4.8.4-switch"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p class="terminology"><strong>Terminology Note:</strong> Inside the braces of a
<em>switch block</em> are one or more <em>statement groups</em>. Each statement group consists of
one or more <em>switch labels</em> (either <code class="prettyprint lang-java">case FOO:</code> or
<code class="prettyprint lang-java">default:</code>), followed by one or more statements.</p><a name="s4.8.4.1-switch-indentation"/>
<h5>4.8.4.1 Indentation&nbsp;<a href="#s4.8.4.1-switch-indentation"><img height="21" width="21" src="javaguidelink.png"/></a></h5>
<p>As with any other block, the contents of a switch block are indented +2.</p><p>After a switch label, a newline appears, and the indentation level is increased +2, exactly as
if a block were being opened. The following switch label returns to the previous indentation
level, as if a block had been closed.</p><a name="fallthrough"/><a name="s4.8.4.2-switch-fall-through"/>
<h5>4.8.4.2 Fall-through: commented&nbsp;<a href="#s4.8.4.2-switch-fall-through"><img height="21" width="21" src="javaguidelink.png"/></a></h5>
<p>Within a switch block, each statement group either terminates abruptly (with a
<code class="prettyprint lang-java">break</code>,
<code class="prettyprint lang-java">continue</code>,
<code class="prettyprint lang-java">return</code> or thrown exception), or is marked with a comment
to indicate that execution will or <em>might</em> continue into the next statement group. Any
comment that communicates the idea of fall-through is sufficient (typically
<code class="prettyprint lang-java">// fall through</code>). This special comment is not required in
the last statement group of the switch block. Example:</p><pre class="prettyprint lang-java">
switch (input) {
case 1:
case 2:
prepareOneOrTwo();
// fall through
case 3:
handleOneTwoOrThree();
break;
default:
handleLargeNumber(input);
}
</pre><a name="s4.8.4.3-switch-default"/>
<h5>4.8.4.3 The default case is present&nbsp;<a href="#s4.8.4.3-switch-default"><img height="21" width="21" src="javaguidelink.png"/></a></h5>
<p>Each switch statement includes a <code class="prettyprint lang-java">default</code> statement
group, even if it contains no code.</p><a name="annotations"/><a name="s4.8.5-annotations"/>
<h4>4.8.5 Annotations&nbsp;<a href="#s4.8.5-annotations"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Annotations applying to a class, method or constructor appear immediately after the
documentation block, and each annotation is listed on a line of its own (that is, one annotation
per line). These line breaks do not constitute line-wrapping (Section
4.5, <a href="#s4.5-line-wrapping">Line-wrapping</a>), so the indentation level is not
increased. Example:</p><pre class="prettyprint lang-java">
@Override
@Nullable
public String getNameIfPresent() { ... }
</pre><p class="exception"><strong>Exception:</strong> A <em>single</em> parameterless annotation
<em>may</em> instead appear together with the first line of the signature, for example:</p><pre class="prettyprint lang-java">
@Override public int hashCode() { ... }
</pre><p>Annotations applying to a field also appear immediately after the documentation block, but in
this case, <em>multiple</em> annotations (possibly parameterized) may be listed on the same line;
for example:</p><pre class="prettyprint lang-java">
@Partial @Mock DataLoader loader;
</pre><p>There are no specific rules for formatting parameter and local variable annotations.</p><a name="comments"/><a name="s4.8.6-comments"/>
<h4>4.8.6 Comments&nbsp;<a href="#s4.8.6-comments"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<a name="s4.8.6.1-block-comment-style"/>
<h5>4.8.6.1 Block comment style&nbsp;<a href="#s4.8.6.1-block-comment-style"><img height="21" width="21" src="javaguidelink.png"/></a></h5>
<p>Block comments are indented at the same level as the surrounding code. They may be in
<code class="prettyprint lang-java">/* ... */</code> style or
<code class="prettyprint lang-java">// ...</code> style. For multi-line
<code class="prettyprint lang-java">/* ... */</code> comments, subsequent lines must start with
<code>*</code> aligned with the <code>*</code> on the previous line.</p><pre class="prettyprint lang-java">
/*
* This is // And so /* Or you can
* okay. // is this. * even do this. */
*/
</pre><p>Comments are not enclosed in boxes drawn with asterisks or other characters.</p><p class="tip"><strong>Tip:</strong> When writing multi-line comments, use the
<code class="prettyprint lang-java">/* ... */</code> style if you want automatic code formatters to
re-wrap the lines when necessary (paragraph-style). Most formatters don't re-wrap lines in
<code class="prettyprint lang-java">// ...</code> style comment blocks.</p><a name="modifiers"/><a name="s4.8.7-modifiers"/>
<h4>4.8.7 Modifiers&nbsp;<a href="#s4.8.7-modifiers"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Class and member modifiers, when present, appear in the order
recommended by the Java Language Specification:
</p><pre>
public protected private abstract static final transient volatile synchronized native strictfp
</pre><a name="s4.8.8-numeric-literals"/>
<h4>4.8.8 Numeric Literals&nbsp;<a href="#s4.8.8-numeric-literals"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p><code>long</code>-valued integer literals use an uppercase <code>L</code> suffix, never
lowercase (to avoid confusion with the digit <code>1</code>). For example, <code>3000000000L</code>
rather than <code class="badcode">3000000000l</code>.</p><a name="naming"/><a name="s5-naming"/>
<h2>5 Naming&nbsp;<a href="#s5-naming"><img height="21" width="21" src="javaguidelink.png"/></a></h2>
<a name="s5.1-identifier-names"/>
<h3>5.1 Rules common to all identifiers&nbsp;<a href="#s5.1-identifier-names"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>Identifiers use only ASCII letters and digits, and in two cases noted below, underscores. Thus
each valid identifier name is matched by the regular expression <code>\w+</code> .</p><p> In Google Style special prefixes or
suffixes, like those seen in the examples <code class="badcode">name_</code>,
<code class="badcode">mName</code>, <code class="badcode">s_name</code> and
<code class="badcode">kName</code>, are <strong>not</strong> used.</p><a name="s5.2-specific-identifier-names"/>
<h3>5.2 Rules by identifier type&nbsp;<a href="#s5.2-specific-identifier-names"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<a name="s5.2.1-package-names"/>
<h4>5.2.1 Package names&nbsp;<a href="#s5.2.1-package-names"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Package names are all lowercase, with consecutive words simply concatenated together (no
underscores). For example, <code>com.example.deepspace</code>, not
<code class="badcode">com.example.deepSpace</code> or
<code class="badcode">com.example.deep_space</code>.</p><a name="s5.2.2-class-names"/>
<h4>5.2.2 Class names&nbsp;<a href="#s5.2.2-class-names"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Class names are written in <a href="#s5.3-camel-case">UpperCamelCase</a>.</p><p>Class names are typically nouns or noun phrases. For example,
<code class="prettyprint lang-java">Character</code> or
<code class="prettyprint lang-java">ImmutableList</code>. Interface names may also be nouns or
noun phrases (for example, <code class="prettyprint lang-java">List</code>), but may sometimes be
adjectives or adjective phrases instead (for example,
<code class="prettyprint lang-java">Readable</code>).</p><p>There are no specific rules or even well-established conventions for naming annotation types.</p><p><em>Test</em> classes are named starting with the name of the class they are testing, and ending
with <code class="prettyprint lang-java">Test</code>. For example,
<code class="prettyprint lang-java">HashTest</code> or
<code class="prettyprint lang-java">HashIntegrationTest</code>.</p><a name="s5.2.3-method-names"/>
<h4>5.2.3 Method names&nbsp;<a href="#s5.2.3-method-names"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Method names are written in <a href="#s5.3-camel-case">lowerCamelCase</a>.</p><p>Method names are typically verbs or verb phrases. For example,
<code class="prettyprint lang-java">sendMessage</code> or
<code class="prettyprint lang-java">stop</code>.</p><p>Underscores may appear in JUnit <em>test</em> method names to separate logical components of the
name. One typical pattern is <code>test<i>&lt;MethodUnderTest&gt;</i>_<i>&lt;state&gt;</i></code>,
for example <code class="prettyprint lang-java">testPop_emptyStack</code>. There is no One Correct
Way to name test methods.</p><a name="constants"/><a name="s5.2.4-constant-names"/>
<h4>5.2.4 Constant names&nbsp;<a href="#s5.2.4-constant-names"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Constant names use <code class="prettyprint lang-java">CONSTANT_CASE</code>: all uppercase
letters, with words separated by underscores. But what <em>is</em> a constant, exactly?</p><p>Every constant is a static final field, but not all static final fields are constants. Before
choosing constant case, consider whether the field really <em>feels like</em> a constant. For
example, if any of that instance's observable state can change, it is almost certainly not a
constant. Merely <em>intending</em> to never mutate the object is generally not
enough. Examples:</p><pre class="prettyprint lang-java">
// Constants
static final int NUMBER = 5;
static final ImmutableList&lt;String&gt; NAMES = ImmutableList.of("Ed", "Ann");
static final Joiner COMMA_JOINER = Joiner.on(','); // because Joiner is immutable
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }
// Not constants
static String nonFinal = "non-final";
final String nonStatic = "non-static";
static final Set&lt;String&gt; mutableCollection = new HashSet&lt;String&gt;();
static final ImmutableSet&lt;SomeMutableType&gt; mutableElements = ImmutableSet.of(mutable);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these", "can", "change"};
</pre><p>These names are typically nouns or noun phrases.</p><a name="s5.2.5-non-constant-field-names"/>
<h4>5.2.5 Non-constant field names&nbsp;<a href="#s5.2.5-non-constant-field-names"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Non-constant field names (static or otherwise) are written
in <a href="#s5.3-camel-case">lowerCamelCase</a>.</p><p>These names are typically nouns or noun phrases. For example,
<code class="prettyprint lang-java">computedValues</code> or
<code class="prettyprint lang-java">index</code>.</p><a name="s5.2.6-parameter-names"/>
<h4>5.2.6 Parameter names&nbsp;<a href="#s5.2.6-parameter-names"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Parameter names are written in <a href="#s5.3-camel-case">lowerCamelCase</a>.</p><p>One-character parameter names should be avoided.</p><a name="s5.2.7-local-variable-names"/>
<h4>5.2.7 Local variable names&nbsp;<a href="#s5.2.7-local-variable-names"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Local variable names are written in <a href="#s5.3-camel-case">lowerCamelCase</a>, and can be
abbreviated more liberally than other types of names.</p><p>However, one-character names should be avoided, except for temporary and looping variables.</p><p>Even when final and immutable, local variables are not considered to be constants, and should not
be styled as constants.</p><a name="s5.2.8-type-variable-names"/>
<h4>5.2.8 Type variable names&nbsp;<a href="#s5.2.8-type-variable-names"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Each type variable is named in one of two styles:</p><ul><li>A single capital letter, optionally followed by a single numeral (such as
<code class="prettyprint lang-java">E</code>, <code class="prettyprint lang-java">T</code>,
<code class="prettyprint lang-java">X</code>, <code class="prettyprint lang-java">T2</code>)
</li><li>A name in the form used for classes (see Section 5.2.2,
<a href="#s5.2.2-class-names">Class names</a>), followed by the capital letter
<code class="prettyprint lang-java">T</code> (examples:
<code class="prettyprint lang-java">RequestT</code>,
<code class="prettyprint lang-java">FooBarT</code>).</li></ul><a name="acronyms"/><a name="camelcase"/><a name="s5.3-camel-case"/>
<h3>5.3 Camel case: defined&nbsp;<a href="#s5.3-camel-case"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>Sometimes there is more than one reasonable way to convert an English phrase into camel case,
such as when acronyms or unusual constructs like "IPv6" or "iOS" are present. To improve
predictability, Google Style specifies the following (nearly) deterministic scheme.</p><p>Beginning with the prose form of the name:</p><ol><li>Convert the phrase to plain ASCII and remove any apostrophes. For example, "Müller's
algorithm" might become "Muellers algorithm".</li><li>Divide this result into words, splitting on spaces and any remaining punctuation (typically
hyphens).
<ul><li><em>Recommended:</em> if any word already has a conventional camel-case appearance in common
usage, split this into its constituent parts (e.g., "AdWords" becomes "ad words"). Note
that a word such as "iOS" is not really in camel case <em>per se</em>; it defies <em>any</em>
convention, so this recommendation does not apply.</li></ul></li><li>Now lowercase <em>everything</em> (including acronyms), then uppercase only the first
character of:
<ul><li>... each word, to yield <em>upper camel case</em>, or</li><li>... each word except the first, to yield <em>lower camel case</em></li></ul></li><li>Finally, join all the words into a single identifier.</li></ol><p>Note that the casing of the original words is almost entirely disregarded. Examples:</p><table><tr><th>Prose form</th><th>Correct</th><th>Incorrect</th></tr><tr><td>"XML HTTP request"</td><td><code class="prettyprint lang-java">XmlHttpRequest</code></td><td><code class="badcode">XMLHTTPRequest</code></td></tr><tr><td>"new customer ID"</td><td><code class="prettyprint lang-java">newCustomerId</code></td><td><code class="badcode">newCustomerID</code></td></tr><tr><td>"inner stopwatch"</td><td><code class="prettyprint lang-java">innerStopwatch</code></td><td><code class="badcode">innerStopWatch</code></td></tr><tr><td>"supports IPv6 on iOS?"</td><td><code class="prettyprint lang-java">supportsIpv6OnIos</code></td><td><code class="badcode">supportsIPv6OnIOS</code></td></tr><tr><td>"YouTube importer"</td><td><code class="prettyprint lang-java">YouTubeImporter</code><br/><code class="prettyprint lang-java">YoutubeImporter</code>*</td><td/></tr></table><p>*Acceptable, but not recommended.</p><p class="note"><strong>Note:</strong> Some words are ambiguously hyphenated in the English
language: for example "nonempty" and "non-empty" are both correct, so the method names
<code class="prettyprint lang-java">checkNonempty</code> and
<code class="prettyprint lang-java">checkNonEmpty</code> are likewise both correct.</p><a name="s6-programming-practices"/>
<h2>6 Programming Practices&nbsp;<a href="#s6-programming-practices"><img height="21" width="21" src="javaguidelink.png"/></a></h2>
<a name="s6.1-override-annotation"/>
<h3>6.1 @Override: always used&nbsp;<a href="#s6.1-override-annotation"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>A method is marked with the <code class="prettyprint lang-java">@Override</code> annotation
whenever it is legal. This includes a class method overriding a superclass method, a class method
implementing an interface method, and an interface method respecifying a superinterface
method.</p><p class="exception"><strong>Exception:</strong><code class="prettyprint lang-java">@Override</code> may be omitted when the parent method is
<code class="prettyprint lang-java">@Deprecated</code>.</p><a name="caughtexceptions"/><a name="s6.2-caught-exceptions"/>
<h3>6.2 Caught exceptions: not ignored&nbsp;<a href="#s6.2-caught-exceptions"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>Except as noted below, it is very rarely correct to do nothing in response to a caught
exception. (Typical responses are to log it, or if it is considered "impossible", rethrow it as an
<code class="prettyprint lang-java">AssertionError</code>.)</p><p>When it truly is appropriate to take no action whatsoever in a catch block, the reason this is
justified is explained in a comment.</p><pre class="prettyprint lang-java">
try {
int i = Integer.parseInt(response);
return handleNumericResponse(i);
} catch (NumberFormatException ok) {
// it's not numeric; that's fine, just continue
}
return handleTextResponse(response);
</pre><p class="exception"><strong>Exception:</strong> In tests, a caught exception may be ignored
without comment <em>if</em> it is named <code class="prettyprint lang-java">expected</code>. The
following is a very common idiom for ensuring that the method under test <em>does</em> throw an
exception of the expected type, so a comment is unnecessary here.</p><pre class="prettyprint lang-java">
try {
emptyStack.pop();
fail();
} catch (NoSuchElementException expected) {
}
</pre><a name="s6.3-static-members"/>
<h3>6.3 Static members: qualified using class&nbsp;<a href="#s6.3-static-members"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>When a reference to a static class member must be qualified, it is qualified with that class's
name, not with a reference or expression of that class's type.</p><pre class="prettyprint lang-java">
Foo aFoo = ...;
Foo.aStaticMethod(); // good
<span class="badcode">aFoo.aStaticMethod();</span> // bad
<span class="badcode">somethingThatYieldsAFoo().aStaticMethod();</span> // very bad
</pre><a name="finalizers"/><a name="s6.4-finalizers"/>
<h3>6.4 Finalizers: not used&nbsp;<a href="#s6.4-finalizers"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>It is <strong>extremely rare</strong> to override <code class="prettyprint lang-java">Object.finalize</code>.</p><p class="tip"><strong>Tip:</strong> Don't do it. If you absolutely must, first read and understand
<a href="http://books.google.com/books?isbn=8131726592"><em>Effective Java</em></a>
Item 7, "Avoid Finalizers," very carefully, and <em>then</em> don't do it.</p><a name="javadoc"/><a name="s7-javadoc"/>
<h2>7 Javadoc&nbsp;<a href="#s7-javadoc"><img height="21" width="21" src="javaguidelink.png"/></a></h2>
<a name="s7.1-javadoc-formatting"/>
<h3>7.1 Formatting&nbsp;<a href="#s7.1-javadoc-formatting"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<a name="s7.1.1-javadoc-multi-line"/>
<h4>7.1.1 General form&nbsp;<a href="#s7.1.1-javadoc-multi-line"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>The <em>basic</em> formatting of Javadoc blocks is as seen in this example:</p><pre class="prettyprint lang-java">
/**
* Multiple lines of Javadoc text are written here,
* wrapped normally...
*/
public int method(String p1) { ... }
</pre><p>... or in this single-line example:</p><pre class="prettyprint lang-java">
/** An especially short bit of Javadoc. */
</pre><p>The basic form is always acceptable. The single-line form may be substituted when there are no
at-clauses present, and the entirety of the Javadoc block (including comment markers) can fit on a
single line.</p><a name="s7.1.2-javadoc-paragraphs"/>
<h4>7.1.2 Paragraphs&nbsp;<a href="#s7.1.2-javadoc-paragraphs"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>One blank line—that is, a line containing only the aligned leading asterisk
(<code>*</code>)—appears between paragraphs, and before the group of "at-clauses" if
present. Each paragraph but the first has <code>&lt;p&gt;</code> immediately before the first word,
with no space after.</p><a name="s7.1.3-javadoc-at-clauses"/>
<h4>7.1.3 At-clauses&nbsp;<a href="#s7.1.3-javadoc-at-clauses"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Any of the standard "at-clauses" that are used appear in the order <code>@param</code>,
<code>@return</code>, <code>@throws</code>, <code>@deprecated</code>, and these four types never
appear with an empty description. When an at-clause doesn't fit on a single line, continuation lines
are indented four (or more) spaces from the position of the <code>@</code>.
</p><a name="s7.2-summary-fragment"/>
<h3>7.2 The summary fragment&nbsp;<a href="#s7.2-summary-fragment"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>The Javadoc for each class and member begins with a brief <strong>summary fragment</strong>. This
fragment is very important: it is the only part of the text that appears in certain contexts such as
class and method indexes.</p><p>This is a fragment—a noun phrase or verb phrase, not a complete sentence. It does
<strong>not</strong> begin with <code class="badcode">A {@code Foo} is a...</code>, or
<code class="badcode">This method returns...</code>, nor does it form a complete imperative sentence
like <code class="badcode">Save the record.</code>. However, the fragment is capitalized and
punctuated as if it were a complete sentence.</p><p class="tip"><strong>Tip:</strong> A common mistake is to write simple Javadoc in the form
<code class="badcode">/** @return the customer ID */</code>. This is incorrect, and should be
changed to <code class="prettyprint lang-java">/** Returns the customer ID. */</code>.</p><a name="s7.3.3-javadoc-optional"/><a name="s7.3-javadoc-where-required"/>
<h3>7.3 Where Javadoc is used&nbsp;<a href="#s7.3-javadoc-where-required"><img height="21" width="21" src="javaguidelink.png"/></a></h3>
<p>At the <em>minimum</em>, Javadoc is present for every
<code class="prettyprint lang-java">public</code> class, and every
<code class="prettyprint lang-java">public</code> or
<code class="prettyprint lang-java">protected</code> member of such a class, with a few exceptions
noted below.</p><p>Other classes and members still have Javadoc <em>as needed</em>. Whenever an implementation
comment would be used to define the overall purpose or behavior of a class, method or field, that
comment is written as Javadoc instead. (It's more uniform, and more tool-friendly.)</p><a name="s7.3.1-javadoc-exception-self-explanatory"/>
<h4>7.3.1 Exception: self-explanatory methods&nbsp;<a href="#s7.3.1-javadoc-exception-self-explanatory"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Javadoc is optional for "simple, obvious" methods like
<code class="prettyprint lang-java">getFoo</code>, in cases where there <em>really and truly</em> is
nothing else worthwhile to say but "Returns the foo".</p><p class="note"><strong>Important:</strong> it is not appropriate to cite this exception to justify
omitting relevant information that a typical reader might need to know. For example, for a method
named <code class="prettyprint lang-java">getCanonicalName</code>, don't omit its documentation
(with the rationale that it would say only
<code class="badcode">/** Returns the canonical name. */</code>) if a typical reader may have no idea
what the term "canonical name" means!</p><a name="s7.3.2-javadoc-exception-overrides"/>
<h4>7.3.2 Exception: overrides&nbsp;<a href="#s7.3.2-javadoc-exception-overrides"><img height="21" width="21" src="javaguidelink.png"/></a></h4>
<p>Javadoc is not always present on a method that overrides a supertype method.
</p></div> <hr/>
<div class="change">Last changed: March 21, 2014</div>
</body>
</html>

BIN
javaguidelink.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 189 B

2733
javascriptguide.asciidoc Normal file
View File

File diff suppressed because it is too large Load Diff

3627
javascriptguide.xml
View File

File diff suppressed because it is too large Load Diff

1478
jsoncstyleguide.asciidoc Normal file
View File

File diff suppressed because it is too large Load Diff

18
jsoncstyleguide.html
View File

@ -1,18 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf8">
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<meta http-equiv="refresh" content="1; url=jsoncstyleguide.xml">
<title>Redirecting</title>
</head>
<!-- The BODY onLoad redirect is the best: it preserves #fragments and
?queries. But it requires javascript. If that fails, the
meta-refresh kicks in; it works more generally, but loses fragments
and queries, takes a second, and pollutes the browser history.
If they both fail, we let the user manually click on the new link.
-->
<body onload="location.replace(location.href.replace('.html', '.xml'))">
Redirecting you to <a href="jsoncstyleguide.xml">jsoncstyleguide.xml</a>.
</body>
</html>

1187
jsoncstyleguide.xml
View File

File diff suppressed because it is too large Load Diff

1653
lispguide.asciidoc Normal file
View File

File diff suppressed because it is too large Load Diff

3887
lispguide.xml
View File

File diff suppressed because it is too large Load Diff

1286
objcguide.asciidoc Normal file
View File

File diff suppressed because it is too large Load Diff

1884
objcguide.xml
View File

File diff suppressed because it is too large Load Diff

1250
pyguide.asciidoc Normal file
View File

File diff suppressed because it is too large Load Diff

2311
pyguide.html
View File

File diff suppressed because it is too large Load Diff

889
shell.asciidoc Normal file
View File

@ -0,0 +1,889 @@
= Shell Style Guide
Revision 1.26
Paul Armstrong +
Too many more to mention +
Each style point has a summary for which additional information is available by toggling the accompanying arrow button that looks this way: ▶. You may toggle all summaries with the big arrow button:
▶ Toggle all summaries
Table of Contents
[width="100%",cols="50%,50%",]
|====================================================================================================================================================================================================================================================================================================================================================================
a|
link:#shell-files-and-interpreter_invocation[Shell Files and Interpreter Invocation]
a|
link:#file-extensions[File Extensions] link:#suid-sgid[SUID/SGID]
a|
link:#environment[Environment]
a|
link:#stdout-vs-stderr[STDOUT vs STDERR]
a|
link:#comments[Comments]
a|
link:#file-header[File Header] link:#function-comments[Function Comments] link:#implementation-comments[Implementation Comments] link:#todo-comments[TODO Comments]
a|
link:#formatting[Formatting]
a|
link:#indentation[Indentation] link:#line-length-and-long_strings[Line Length and Long Strings] link:#pipelines[Pipelines] link:#loops[Loops] link:#case-statement[Case statement] link:#variable-expansion[Variable expansion] link:#quoting[Quoting]
a|
link:#features-and-bugs[Features and Bugs]
a|
link:#command-substitution[Command Substitution] link:#Test,_%5B_and_%5B%5B[Test, [ and [[] link:#testing-strings[Testing Strings] link:#wildcard-expansion-of-filenames[Wildcard Expansion of Filenames] link:#eval[Eval] link:#pipes-to-while[Pipes to While]
a|
link:#naming-conventions[Naming Conventions]
a|
link:#function-names[Function Names] link:#variable-names[Variable Names] link:#constants-and-environment-variable_names[Constants and Environment Variable Names] link:#source-filenames[Source Filenames] link:#Read-only_Variables[Read-only Variables] link:#use-local-variables[Use Local Variables] link:#function-location[Function Location] link:#main[main]
a|
link:#calling-commands[Calling Commands]
a|
link:#checking-return-values[Checking Return Values] link:#Builtin_Commands_vs._External_Commands[Builtin Commands vs. External Commands]
a|
link:#conclusion[Conclusion]
a|
|====================================================================================================================================================================================================================================================================================================================================================================
[[Background]]
== Background
=== Which Shell to Use
link:?showone=Which_Shell_to_Use#Which_Shell_to_Use[link]▶
`Bash` is the only shell scripting language permitted for executables.
Executables must start with `#!/bin/bash` and a minimum number of flags. Use `set` to set shell options so that calling your script as `bash <script_name>` does not break its functionality.
Restricting all executable shell scripts to bash gives us a consistent shell language that's installed on all our machines.
The only exception to this is where you're forced to by whatever you're coding for. One example of this is Solaris SVR4 packages which require plain Bourne shell for any scripts.
=== When to use Shell
link:?showone=When_to_use_Shell#When_to_use_Shell[link]▶
Shell should only be used for small utilities or simple wrapper scripts.
While shell scripting isn't a development language, it is used for writing various utility scripts throughout Google. This style guide is more a recognition of its use rather than a suggestion that it be used for widespread deployment.
Some guidelines:
* If you're mostly calling other utilities and are doing relatively little data manipulation, shell is an acceptable choice for the task.
* If performance matters, use something other than shell.
* If you find you need to use arrays for anything more than assignment of `${PIPESTATUS}`, you should use Python.
* If you are writing a script that is more than 100 lines long, you should probably be writing it in Python instead. Bear in mind that scripts grow. Rewrite your script in another language early to avoid a time-consuming rewrite at a later date.
[[Shell_Files_and_Interpreter_Invocation]]
== Shell Files and Interpreter Invocation
=== File Extensions
link:?showone=File_Extensions#File_Extensions[link]▶
Executables should have no extension (strongly preferred) or a `.sh` extension. Libraries must have a `.sh` extension and should not be executable.
It is not necessary to know what language a program is written in when executing it and shell doesn't require an extension so we prefer not to use one for executables.
However, for libraries it's important to know what language it is and sometimes there's a need to have similar libraries in different languages. This allows library files with identical purposes but different languages to be identically named except for the language-specific suffix.
=== SUID/SGID
link:?showone=SUID/SGID#SUID/SGID[link]▶
SUID and SGID are _forbidden_ on shell scripts.
There are too many security issues with shell that make it nearly impossible to secure sufficiently to allow SUID/SGID. While bash does make it difficult to run SUID, it's still possible on some platforms which is why we're being explicit about banning it.
Use `sudo` to provide elevated access if you need it.
[[Environment]]
== Environment
=== STDOUT vs STDERR
link:?showone=STDOUT_vs_STDERR#STDOUT_vs_STDERR[link]▶
All error messages should go to `STDERR`.
This makes it easier to separate normal status from actual issues.
A function to print out error messages along with other status information is recommended.
-------------------------------------------------
err() {
echo "[$(date +'%Y-%m-%dT%H:%M:%S%z')]: $@" >&2
}
if ! do_something; then
err "Unable to do_something"
exit "${E_DID_NOTHING}"
fi
-------------------------------------------------
[[Comments]]
== Comments
=== File Header
link:?showone=File_Header#File_Header[link]▶
Start each file with a description of its contents.
Every file must have a top-level comment including a brief overview of its contents. A copyright notice and author information are optional.
Example:
------------------------------------------
#!/bin/bash
#
# Perform hot backups of Oracle databases.
------------------------------------------
=== Function Comments
link:?showone=Function_Comments#Function_Comments[link]▶
Any function that is not both obvious and short must be commented. Any function in a library must be commented regardless of length or complexity.
It should be possible for someone else to learn how to use your program or to use a function in your library by reading the comments (and self-help, if provided) without reading the code.
All function comments should contain:
* Description of the function
* Global variables used and modified
* Arguments taken
* Returned values other than the default exit status of the last command run
Example:
---------------------------------------------------------------
#!/bin/bash
#
# Perform hot backups of Oracle databases.
export PATH='/usr/xpg4/bin:/usr/bin:/opt/csw/bin:/opt/goog/bin'
#######################################
# Cleanup files from the backup dir
# Globals:
# BACKUP_DIR
# ORACLE_SID
# Arguments:
# None
# Returns:
# None
#######################################
cleanup() {
...
}
---------------------------------------------------------------
=== Implementation Comments
link:?showone=Implementation_Comments#Implementation_Comments[link]▶
Comment tricky, non-obvious, interesting or important parts of your code.
This follows general Google coding comment practice. Don't comment everything. If there's a complex algorithm or you're doing something out of the ordinary, put a short comment in.
=== TODO Comments
link:?showone=TODO_Comments#TODO_Comments[link]▶
Use TODO comments for code that is temporary, a short-term solution, or good-enough but not perfect.
This matches the convention in the link:cppguide.xml?showone=TODO_Comments#TODO_Comments[C++ Guide].
TODOs should include the string TODO in all caps, followed by your username in parentheses. A colon is optional. It's preferable to put a bug/ticket number next to the TODO item as well.
Examples:
-----------------------------------------------------------
# TODO(mrmonkey): Handle the unlikely edge cases (bug ####)
-----------------------------------------------------------
[[Formatting]]
== Formatting
While you should follow the style that's already there for files that you're modifying, the following are required for any new code.
=== Indentation
link:?showone=Indentation#Indentation[link]▶
Indent 2 spaces. No tabs.
Use blank lines between blocks to improve readability. Indentation is two spaces. Whatever you do, don't use tabs. For existing files, stay faithful to the existing indentation.
=== Line Length and Long Strings
link:?showone=Line_Length_and_Long_Strings#Line_Length_and_Long_Strings[link]▶
Maximum line length is 80 characters.
If you have to write strings that are longer than 80 characters, this should be done with a here document or an embedded newline if possible. Literal strings that have to be longer than 80 chars and can't sensibly be split are ok, but it's strongly preferred to find a way to make it shorter.
----------------------------------
# DO use 'here document's
cat <<END;
I am an exceptionally long
string.
END
# Embedded newlines are ok too
long_string="I am an exceptionally
long string."
----------------------------------
=== Pipelines
link:?showone=Pipelines#Pipelines[link]▶
Pipelines should be split one per line if they don't all fit on one line.
If a pipeline all fits on one line, it should be on one line.
If not, it should be split at one pipe segment per line with the pipe on the newline and a 2 space indent for the next section of the pipe. This applies to a chain of commands combined using '|' as well as to logical compounds using '||' and '&&'.
----------------------
# All fits on one line
command1 | command2
# Long commands
command1 \
| command2 \
| command3 \
| command4
----------------------
=== Loops
link:?showone=Loops#Loops[link]▶
Put `; do` and `; then` on the same line as the `while`, `for` or `if`.
Loops in shell are a bit different, but we follow the same principles as with braces when declaring functions. That is: `; then` and `; do` should be on the same line as the if/for/while. `else` should be on its own line and closing statements should be on their own line vertically aligned with the opening statement.
Example:
------------------------------------------------------------
for dir in ${dirs_to_cleanup}; do
if [[ -d "${dir}/${ORACLE_SID}" ]]; then
log_date "Cleaning up old files in ${dir}/${ORACLE_SID}"
rm "${dir}/${ORACLE_SID}/"*
if [[ "$?" -ne 0 ]]; then
error_message
fi
else
mkdir -p "${dir}/${ORACLE_SID}"
if [[ "$?" -ne 0 ]]; then
error_message
fi
fi
done
------------------------------------------------------------
=== Case statement
link:?showone=Case_statement#Case_statement[link]▶
* Indent alternatives by 2 spaces.
* A one-line alternative needs a space after the close parenthesis of the pattern and before the `;;`.
* Long or multi-command alternatives should be split over multiple lines with the pattern, actions, and `;;` on separate lines.
The matching expressions are indented one level from the 'case' and 'esac'. Multiline actions are indented another level. In general, there is no need to quote match expressions. Pattern expressions should not be preceded by an open parenthesis. Avoid the `;&` and `;;&` notations.
----------------------------------------------------
case "${expression}" in
a)
variable="..."
some_command "${variable}" "${other_expr}" ...
;;
absolute)
actions="relative"
another_command "${actions}" "${other_expr}" ...
;;
*)
error "Unexpected expression '${expression}'"
;;
esac
----------------------------------------------------
Simple commands may be put on the same line as the pattern _and_ `;;` as long as the expression remains readable. This is often appropriate for single-letter option processing. When the actions don't fit on a single line, put the pattern on a line on its own, then the actions, then `;;` also on a line of its own. When on the same line as the actions, use a space after the close parenthesis of the pattern and another before the `;;`.
-------------------------------------------
verbose='false'
aflag=''
bflag=''
files=''
while getopts 'abf:v' flag; do
case "${flag}" in
a) aflag='true' ;;
b) bflag='true' ;;
f) files="${OPTARG}" ;;
v) verbose='true' ;;
*) error "Unexpected option ${flag}" ;;
esac
done
-------------------------------------------
=== Variable expansion
link:?showone=Variable_expansion#Variable_expansion[link]▶
In order of precedence: Stay consistent with what you find; quote your variables; prefer "$\{var}" over "$var", but see details.
These are meant to be guidelines, as the topic seems too controversial for a mandatory regulation. +
They are listed in order of precedence.
1. Stay consistent with what you find for existing code.
2. Quote variables, see link:#quoting[Quoting section below].
3. Don't brace-quote single character shell specials / positional parameters, unless strictly necessary or avoiding deep confusion. +
Prefer brace-quoting all other variables.
+
-----------------------------------------------------------------
# Section of recommended cases.
# Preferred style for 'special' variables:
echo "Positional: $1" "$5" "$3"
echo "Specials: !=$!, -=$-, _=$_. ?=$?, #=$# *=$* @=$@ \$=$$ ..."
# Braces necessary:
echo "many parameters: ${10}"
# Braces avoiding confusion:
# Output is "a0b0c0"
set -- a b c
echo "${1}0${2}0${3}0"
# Preferred style for other variables:
echo "PATH=${PATH}, PWD=${PWD}, mine=${some_var}"
while read f; do
echo "file=${f}"
done < <(ls -l /tmp)
# Section of discouraged cases
# Unquoted vars, unbraced vars, brace-quoted single letter
# shell specials.
echo a=$avar "b=$bvar" "PID=${$}" "${1}"
# Confusing use: this is expanded as "${1}0${2}0${3}0",
# not "${10}${20}${30}
set -- a b c
echo "$10$20$30"
-----------------------------------------------------------------
=== Quoting
link:?showone=Quoting#Quoting[link]▶
* Always quote strings containing variables, command substitutions, spaces or shell meta characters, unless careful unquoted expansion is required.
* Prefer quoting strings that are "words" (as opposed to command options or path names).
* Never quote _literal_ integers.
* Be aware of the quoting rules for link:#Test,_%5B_and_%5B%5B[pattern matches in [[].
* Use "$@" unless you have a specific reason to use $*.
----------------------------------------------------------------------
# 'Single' quotes indicate that no substitution is desired.
# "Double" quotes indicate that substitution is required/tolerated.
# Simple examples
# "quote command substitutions"
flag="$(some_command and its args "$@" 'quoted separately')"
# "quote variables"
echo "${flag}"
# "never quote literal integers"
value=32
# "quote command substitutions", even when you expect integers
number="$(generate_number)"
# "prefer quoting words", not compulsory
readonly USE_INTEGER='true'
# "quote shell meta characters"
echo 'Hello stranger, and well met. Earn lots of $$$'
echo "Process $$: Done making \$\$\$."
# "command options or path names"
# ($1 is assumed to contain a value here)
grep -li Hugo /dev/null "$1"
# Less simple examples
# "quote variables, unless proven false": ccs might be empty
git send-email --to "${reviewers}" ${ccs:+"--cc" "${ccs}"}
# Positional parameter precautions: $1 might be unset
# Single quotes leave regex as-is.
grep -cP '([Ss]pecial|\|?characters*)$' ${1:+"$1"}
# For passing on arguments,
# "$@" is right almost everytime, and
# $* is wrong almost everytime:
#
# * $* and $@ will split on spaces, clobbering up arguments
# that contain spaces and dropping empty strings;
# * "$@" will retain arguments as-is, so no args
# provided will result in no args being passed on;
# This is in most cases what you want to use for passing
# on arguments.
# * "$*" expands to one argument, with all args joined
# by (usually) spaces,
# so no args provided will result in one empty string
# being passed on.
# (Consult 'man bash' for the nit-grits ;-)
set -- 1 "2 two" "3 three tres"; echo $# ; set -- "$*"; echo "$#, $@")
set -- 1 "2 two" "3 three tres"; echo $# ; set -- "$@"; echo "$#, $@")
----------------------------------------------------------------------
[[Features_and_Bugs]]
== Features and Bugs
=== Command Substitution
link:?showone=Command_Substitution#Command_Substitution[link]▶
Use `$(command)` instead of backticks.
Nested backticks require escaping the inner ones with `\`. The `$(command)` format doesn't change when nested and is easier to read.
Example:
------------------------------
# This is preferred:
var="$(command "$(command1)")"
# This is not:
var="`command \`command1\``"
------------------------------
=== Test, [ and [[
link:?showone=Test,_%5B_and_%5B%5B#Test,_%5B_and_%5B%5B[link]▶
`[[ ... ]]` is preferred over `[`, `test` and `/usr/bin/[`.
`[[ ... ]]` reduces errors as no pathname expansion or word splitting takes place between `[[` and `]]` and `[[ ... ]]` allows for regular expression matching where `[ ... ]` does not.
---------------------------------------------------------------------
# This ensures the string on the left is made up of characters in the
# alnum character class followed by the string name.
# Note that the RHS should not be quoted here.
# For the gory details, see
# E14 at http://tiswww.case.edu/php/chet/bash/FAQ
if [[ "filename" =~ ^[[:alnum:]]+name ]]; then
echo "Match"
fi
# This matches the exact pattern "f*" (Does not match in this case)
if [[ "filename" == "f*" ]]; then
echo "Match"
fi
# This gives a "too many arguments" error as f* is expanded to the
# contents of the current directory
if [ "filename" == f* ]; then
echo "Match"
fi
---------------------------------------------------------------------
=== Testing Strings
link:?showone=Testing_Strings#Testing_Strings[link]▶
Use quotes rather than filler characters where possible.
Bash is smart enough to deal with an empty string in a test. So, given that the code is much easier to read, use tests for empty/non-empty strings or empty strings rather than filler characters.
-------------------------------------------------------------------
# Do this:
if [[ "${my_var}" = "some_string" ]]; then
do_something
fi
# -z (string length is zero) and -n (string length is not zero) are
# preferred over testing for an empty string
if [[ -z "${my_var}" ]]; then
do_something
fi
# This is OK (ensure quotes on the empty side), but not preferred:
if [[ "${my_var}" = "" ]]; then
do_something
fi
# Not this:
if [[ "${my_var}X" = "some_stringX" ]]; then
do_something
fi
-------------------------------------------------------------------
To avoid confusion about what you're testing for, explicitly use `-z` or `-n`.
--------------------------------------------------------------------
# Use this
if [[ -n "${my_var}" ]]; then
do_something
fi
# Instead of this as errors can occur if ${my_var} expands to a test
# flag
if [[ "${my_var}" ]]; then
do_something
fi
--------------------------------------------------------------------
=== Wildcard Expansion of Filenames
link:?showone=Wildcard_Expansion_of_Filenames#Wildcard_Expansion_of_Filenames[link]▶
Use an explicit path when doing wildcard expansion of filenames.
As filenames can begin with a `-`, it's a lot safer to expand wildcards with `./*` instead of `*`.
----------------------------------------------------------
# Here's the contents of the directory:
# -f -r somedir somefile
# This deletes almost everything in the directory by force
psa@bilby$ rm -v *
removed directory: `somedir'
removed `somefile'
# As opposed to:
psa@bilby$ rm -v ./*
removed `./-f'
removed `./-r'
rm: cannot remove `./somedir': Is a directory
removed `./somefile'
----------------------------------------------------------
=== Eval
link:?showone=Eval#Eval[link]▶
`eval` should be avoided.
Eval munges the input when used for assignment to variables and can set variables without making it possible to check what those variables were.
---------------------------------------------------------------
# What does this set?
# Did it succeed? In part or whole?
eval $(set_my_variables)
# What happens if one of the returned values has a space in it?
variable="$(eval some_function)"
---------------------------------------------------------------
=== Pipes to While
link:?showone=Pipes_to_While#Pipes_to_While[link]▶
Use process substitution or for loops in preference to piping to while. Variables modified in a while loop do not propagate to the parent because the loop's commands run in a subshell.
The implicit subshell in a pipe to while can make it difficult to track down bugs.
----------------------------------
last_line='NULL'
your_command | while read line; do
last_line="${line}"
done
# This will output 'NULL'
echo "${last_line}"
----------------------------------
Use a for loop if you are confident that the input will not contain spaces or special characters (usually, this means not user input).
-------------------------------------------------------
total=0
# Only do this if there are no spaces in return values.
for value in $(command); do
total+="${value}"
done
-------------------------------------------------------
Using process substitution allows redirecting output but puts the commands in an explicit subshell rather than the implicit subshell that bash creates for the while loop.
-------------------------------------------------------------------
total=0
last_file=
while read count filename; do
total+="${count}"
last_file="${filename}"
done < <(your_command | uniq -c)
# This will output the second field of the last line of output from
# the command.
echo "Total = ${total}"
echo "Last one = ${last_file}"
-------------------------------------------------------------------
Use while loops where it is not necessary to pass complex results to the parent shell - this is typically where some more complex "parsing" is required. Beware that simple examples are probably more easily done with a tool such as awk. This may also be useful where you specifically don't want to change the parent scope variables.
--------------------------------------------------------------
# Trivial implementation of awk expression:
# awk '$3 == "nfs" { print $2 " maps to " $1 }' /proc/mounts
cat /proc/mounts | while read src dest type opts rest; do
if [[ ${type} == "nfs" ]]; then
echo "NFS ${dest} maps to ${src}"
fi
done
--------------------------------------------------------------
[[Naming_Conventions]]
== Naming Conventions
=== Function Names
link:?showone=Function_Names#Function_Names[link]▶
Lower-case, with underscores to separate words. Separate libraries with `::`. Parentheses are required after the function name. The keyword `function` is optional, but must be used consistently throughout a project.
If you're writing single functions, use lowercase and separate words with underscore. If you're writing a package, separate package names with `::`. Braces must be on the same line as the function name (as with other languages at Google) and no space between the function name and the parenthesis.
----------------------
# Single function
my_func() {
...
}
# Part of a package
mypackage::my_func() {
...
}
----------------------
The `function` keyword is extraneous when "()" is present after the function name, but enhances quick identification of functions.
=== Variable Names
link:?showone=Variable_Names#Variable_Names[link]▶
As for function names.
Variables names for loops should be similarly named for any variable you're looping through.
--------------------------
for zone in ${zones}; do
something_with "${zone}"
done
--------------------------
=== Constants and Environment Variable Names
link:?showone=Constants_and_Environment_Variable_Names#Constants_and_Environment_Variable_Names[link]▶
All caps, separated with underscores, declared at the top of the file.
Constants and anything exported to the environment should be capitalized.
-----------------------------------
# Constant
readonly PATH_TO_FILES='/some/path'
# Both constant and environment
declare -xr ORACLE_SID='PROD'
-----------------------------------
Some things become constant at their first setting (for example, via getopts). Thus, it's OK to set a constant in getopts or based on a condition, but it should be made readonly immediately afterwards. Note that `declare` doesn't operate on global variables within functions, so `readonly` or `export` is recommended instead.
--------------------------
VERBOSE='false'
while getopts 'v' flag; do
case "${flag}" in
v) VERBOSE='true' ;;
esac
done
readonly VERBOSE
--------------------------
=== Source Filenames
link:?showone=Source_Filenames#Source_Filenames[link]▶
Lowercase, with underscores to separate words if desired.
This is for consistency with other code styles in Google: `maketemplate` or `make_template` but not `make-template`.
=== Read-only Variables
link:?showone=Read-only_Variables#Read-only_Variables[link]▶
Use `readonly` or `declare -r` to ensure they're read only.
As globals are widely used in shell, it's important to catch errors when working with them. When you declare a variable that is meant to be read-only, make this explicit.
--------------------------------------------------------------------
zip_version="$(dpkg --status zip | grep Version: | cut -d ' ' -f 2)"
if [[ -z "${zip_version}" ]]; then
error_message
else
readonly zip_version
fi
--------------------------------------------------------------------
=== Use Local Variables
link:?showone=Use_Local_Variables#Use_Local_Variables[link]▶
Declare function-specific variables with `local`. Declaration and assignment should be on different lines.
Ensure that local variables are only seen inside a function and its children by using `local` when declaring them. This avoids polluting the global name space and inadvertently setting variables that may have significance outside the function.
Declaration and assignment must be separate statements when the assignment value is provided by a command substitution; as the 'local' builtin does not propagate the exit code from the command substitution.
---------------------------------------------------------------------
my_func2() {
local name="$1"
# Separate lines for declaration and assignment:
local my_var
my_var="$(my_func)" || return
# DO NOT do this: $? contains the exit code of 'local', not my_func
local my_var="$(my_func)"
[[ $? -eq 0 ]] || return
...
}
---------------------------------------------------------------------
=== Function Location
link:?showone=Function_Location#Function_Location[link]▶
Put all functions together in the file just below constants. Don't hide executable code between functions.
If you've got functions, put them all together near the top of the file. Only includes, `set` statements and setting constants may be done before declaring functions.
Don't hide executable code between functions. Doing so makes the code difficult to follow and results in nasty surprises when debugging.
=== main
link:?showone=main#main[link]▶
A function called `main` is required for scripts long enough to contain at least one other function.
In order to easily find the start of the program, put the main program in a function called `main` as the bottom most function. This provides consistency with the rest of the code base as well as allowing you to define more variables as `local` (which can't be done if the main code is not a function). The last non-comment line in the file should be a call to `main`:
---------
main "$@"
---------
Obviously, for short scripts where it's just a linear flow, `main` is overkill and so is not required.
[[Calling_Commands]]
== Calling Commands
=== Checking Return Values
link:?showone=Checking_Return_Values#Checking_Return_Values[link]▶
Always check return values and give informative return values.
For unpiped commands, use `$?` or check directly via an `if` statement to keep it simple.
Example:
-------------------------------------------------------
if ! mv "${file_list}" "${dest_dir}/" ; then
echo "Unable to move ${file_list} to ${dest_dir}" >&2
exit "${E_BAD_MOVE}"
fi
# Or
mv "${file_list}" "${dest_dir}/"
if [[ "$?" -ne 0 ]]; then
echo "Unable to move ${file_list} to ${dest_dir}" >&2
exit "${E_BAD_MOVE}"
fi
-------------------------------------------------------
Bash also has the `PIPESTATUS` variable that allows checking of the return code from all parts of a pipe. If it's only necessary to check success or failure of the whole pipe, then the following is acceptable:
-------------------------------------------------------------------
tar -cf - ./* | ( cd "${dir}" && tar -xf - )
if [[ "${PIPESTATUS[0]}" -ne 0 || "${PIPESTATUS[1]}" -ne 0 ]]; then
echo "Unable to tar files to ${dir}" >&2
fi
-------------------------------------------------------------------
However, as `PIPESTATUS` will be overwritten as soon as you do any other command, if you need to act differently on errors based on where it happened in the pipe, you'll need to assign `PIPESTATUS` to another variable immediately after running the command (don't forget that `[` is a command and will wipe out `PIPESTATUS`).
--------------------------------------------
tar -cf - ./* | ( cd "${DIR}" && tar -xf - )
return_codes=(${PIPESTATUS[*]})
if [[ "${return_codes[0]}" -ne 0 ]]; then
do_something
fi
if [[ "${return_codes[1]}" -ne 0 ]]; then
do_something_else
fi
--------------------------------------------
=== Builtin Commands vs. External Commands
link:?showone=Builtin_Commands_vs._External_Commands#Builtin_Commands_vs._External_Commands[link]▶
Given the choice between invoking a shell builtin and invoking a separate process, choose the builtin.
We prefer the use of builtins such as the _Parameter Expansion_ functions in `bash(1)` as it's more robust and portable (especially when compared to things like sed).
Example:
---------------------------------------------------------
# Prefer this:
addition=$((${X} + ${Y}))
substitution="${string/#foo/bar}"
# Instead of this:
addition="$(expr ${X} + ${Y})"
substitution="$(echo "${string}" | sed -e 's/^foo/bar/')"
---------------------------------------------------------
[[Conclusion]]
== Conclusion
Use common sense and __BE CONSISTENT__.
Please take a few minutes to read the Parting Words section at the bottom of the link:cppguide.xml[C++ Guide].
Revision 1.26

1152
shell.xml
View File

File diff suppressed because it is too large Load Diff

147
styleguide.css
View File

@ -1,147 +0,0 @@
body {
background-color: #fff;
color: #333;
font-family: sans-serif;
font-size: 10pt;
margin-right: 100px;
margin-left: 100px;
}
h1, h2, h3, h4, h5, h6, .toc_title {
color: #06c;
margin-top: 2em;
margin-bottom: 1em;
}
h1 {
text-align: center;
font-size: 18pt;
}
h2, .toc_title {
font-weight: bold;
font-size: 12pt;
margin-left: -40px;
}
h3, h4, h5, h6 {
font-size: 10pt;
margin-left: -20px;
}
.toc_category, .toc_stylepoint {
font-size: 10pt;
padding-top: .3em;
padding-bottom: .3em;
}
table {
border-collapse: collapse;
}
td, th {
border: 1px solid #ccc;
padding: 2px 12px;
font-size: 10pt;
}
.toc td, .toc th {
border-width: 1px 5px;
}
code, samp, var {
color: #060;
}
pre {
font-size: 10pt;
display: block;
color: #060;
background-color: #f8fff8;
border-color: #f0fff0;
border-style: solid;
border-top-width: 1px;
border-bottom-width: 1px;
border-right-width: 1px;
border-left-width: 5px;
padding-left: 12px;
padding-right: 12px;
padding-top: 4px;
padding-bottom: 4px;
}
pre.badcode {
color: #c00;
background-color: #fff8f8;
border-color: #fff0f0;
}
.showhide_button {
float: left;
cursor: pointer;
border-width: 1px;
border-style: solid;
border-color: #ddd #aaa #aaa #ddd;
padding: 0 3px 1px;
margin: 0 4px 8px 0;
border-radius: 3px;
-webkit-border-radius: 3px;
-moz-border-radius: 3px;
}
.link_button {
float: left;
display: none;
background-color: #f8f8ff;
border-color: #f0f0ff;
border-style: solid;
border-width: 1px;
font-size: 75%;
margin-top: 0;
margin-left: -50px;
padding: 4px;
border-radius: 3px;
-webkit-border-radius: 3px;
-moz-border-radius: 3px;
}
address {
text-align: right;
}
hr {
margin-top: 3.5em;
border-width: 1px;
color: #fff;
}
.stylepoint_section {
display: block;
margin-bottom: 1em;
color: #5588ff;
font-family: sans-serif;
font-size: 90%;
font-weight: bold;
margin-left: -2%;
}
.stylepoint_subsection {
color: #667799;
font-family: sans-serif;
font-size: 90%;
font-weight: bold;
margin-left: -1%;
}
.stylepoint_subsubsection {
color: #667799;
font-family: sans-serif;
font-size: 80%;
font-weight: bold;
margin-left: 0;
}
.revision {
text-align: right;
}

924
styleguide.xsl
View File

@ -1,924 +0,0 @@
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:dcq="http://purl.org/dc/qualifiers/1.0/"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:fn="http://www.w3.org/2005/xpath-functions">
<xsl:output method="html"/>
<!-- Set to 1 to show explanations by default. Set to 0 to hide them -->
<xsl:variable name="show_explanation_default" select="0" />
<!-- The characters within the Webdings font that show the triangles -->
<xsl:variable name="show_button_text" select="'&#x25B6;'" />
<xsl:variable name="hide_button_text" select="'&#x25BD;'" />
<!-- The suffix for names -->
<xsl:variable name="button_suffix" select="'__button'"/>
<xsl:variable name="body_suffix" select="'__body'"/>
<!-- For easy reference, the name of the button -->
<xsl:variable name="show_hide_all_button" select="'show_hide_all_button'"/>
<!-- The top-level element -->
<xsl:template match="GUIDE">
<HTML>
<HEAD>
<TITLE><xsl:value-of select="@title"/></TITLE>
<META http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<LINK HREF="http://www.google.com/favicon.ico" type="image/x-icon"
rel="shortcut icon"/>
<LINK HREF="styleguide.css"
type="text/css" rel="stylesheet"/>
<SCRIPT language="javascript" type="text/javascript">
function GetElementsByName(name) {
// Workaround a bug on old versions of opera.
if (document.getElementsByName) {
return document.getElementsByName(name);
} else {
return [document.getElementById(name)];
}
}
/**
* @param {string} namePrefix The prefix of the body name.
* @param {function(boolean): boolean} getVisibility Computes the new
* visibility state, given the current one.
*/
function ChangeVisibility(namePrefix, getVisibility) {
var bodyName = namePrefix + '<xsl:value-of select="$body_suffix"/>';
var buttonName = namePrefix + '<xsl:value-of select="$button_suffix"/>';
var bodyElements = GetElementsByName(bodyName);
var linkElement = GetElementsByName('link-' + buttonName)[0];
if (bodyElements.length != 1) {
throw Error('ShowHideByName() got the wrong number of bodyElements: ' +
bodyElements.length);
} else {
var bodyElement = bodyElements[0];
var buttonElement = GetElementsByName(buttonName)[0];
var isVisible = bodyElement.style.display != "none";
if (getVisibility(isVisible)) {
bodyElement.style.display = "inline";
linkElement.style.display = "block";
buttonElement.innerHTML = '<xsl:value-of select="$hide_button_text"/>';
} else {
bodyElement.style.display = "none";
linkElement.style.display = "none";
buttonElement.innerHTML = '<xsl:value-of select="$show_button_text"/>';
}
}
}
function ShowHideByName(namePrefix) {
ChangeVisibility(namePrefix, function(old) { return !old; });
}
function ShowByName(namePrefix) {
ChangeVisibility(namePrefix, function() { return true; });
}
function ShowHideAll() {
var allButton = GetElementsByName("show_hide_all_button")[0];
if (allButton.innerHTML == '<xsl:value-of select="$hide_button_text"/>') {
allButton.innerHTML = '<xsl:value-of select="$show_button_text"/>';
SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "none", '<xsl:value-of select="$show_button_text"/>');
} else {
allButton.innerHTML = '<xsl:value-of select="$hide_button_text"/>';
SetHiddenState(document.getElementsByTagName("body")[0].childNodes, "inline", '<xsl:value-of select="$hide_button_text"/>');
}
}
// Recursively sets state of all children
// of a particular node.
function SetHiddenState(root, newState, newButton) {
for (var i = 0; i != root.length; i++) {
SetHiddenState(root[i].childNodes, newState, newButton);
if (root[i].className == 'showhide_button') {
root[i].innerHTML = newButton;
}
if (root[i].className == 'stylepoint_body' ||
root[i].className == 'link_button') {
root[i].style.display = newState;
}
}
}
function EndsWith(str, suffix) {
var l = str.length - suffix.length;
return l >= 0 &amp;&amp; str.indexOf(suffix, l) == l;
}
function RefreshVisibilityFromHashParam() {
var hashRegexp = new RegExp('#([^&amp;#]*)$');
var hashMatch = hashRegexp.exec(window.location.href);
var anchor = hashMatch &amp;&amp; GetElementsByName(hashMatch[1])[0];
var node = anchor;
var suffix = '<xsl:value-of select="$body_suffix"/>';
while (node) {
var id = node.id;
var matched = id &amp;&amp; EndsWith(id, suffix);
if (matched) {
var len = id.length - suffix.length;
ShowByName(id.substring(0, len));
if (anchor.scrollIntoView) {
anchor.scrollIntoView();
}
return;
}
node = node.parentNode;
}
}
window.onhashchange = RefreshVisibilityFromHashParam;
window.onload = function() {
// if the URL contains "?showall=y", expand the details of all children
var showHideAllRegex = new RegExp("[\\?&amp;](showall)=([^&amp;#]*)");
var showHideAllValue = showHideAllRegex.exec(window.location.href);
if (showHideAllValue != null) {
if (showHideAllValue[2] == "y") {
SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
"inline", '<xsl:value-of select="$hide_button_text"/>');
} else {
SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
"none", '<xsl:value-of select="$show_button_text"/>');
}
}
var showOneRegex = new RegExp("[\\?&amp;](showone)=([^&amp;#]*)");
var showOneValue = showOneRegex.exec(window.location.href);
if (showOneValue) {
ShowHideByName(showOneValue[2]);
}
RefreshVisibilityFromHashParam();
}
</SCRIPT>
</HEAD>
<BODY>
<H1><xsl:value-of select="@title"/></H1>
<xsl:apply-templates/>
</BODY>
</HTML>
</xsl:template>
<xsl:template match="OVERVIEW">
<xsl:variable name="button_text">
<xsl:choose>
<xsl:when test="$show_explanation_default">
<xsl:value-of select="$hide_button_text"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$show_button_text"/>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<DIV style="margin-left: 50%; font-size: 75%;">
<P>
Each style point has a summary for which additional information is available
by toggling the accompanying arrow button that looks this way:
<SPAN class="showhide_button" style="margin-left: 0; float: none">
<xsl:value-of select="$show_button_text"/></SPAN>.
You may toggle all summaries with the big arrow button:
</P>
<DIV style=" font-size: larger; margin-left: +2em;">
<SPAN class="showhide_button" style="font-size: 180%; float: none">
<xsl:attribute name="onclick"><xsl:value-of select="'javascript:ShowHideAll()'"/></xsl:attribute>
<xsl:attribute name="name"><xsl:value-of select="$show_hide_all_button"/></xsl:attribute>
<xsl:attribute name="id"><xsl:value-of select="$show_hide_all_button"/></xsl:attribute>
<xsl:value-of select="$button_text"/>
</SPAN>
Toggle all summaries
</DIV>
</DIV>
<xsl:call-template name="TOC">
<xsl:with-param name="root" select=".."/>
</xsl:call-template>
<xsl:apply-templates/>
</xsl:template>
<xsl:template match="PARTING_WORDS">
<H2>Parting Words</H2>
<xsl:apply-templates/>
</xsl:template>
<xsl:template match="CATEGORY">
<DIV>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<H2>
<xsl:variable name="category_name">
<xsl:call-template name="anchorname">
<xsl:with-param name="sectionname" select="@title"/>
</xsl:call-template>
</xsl:variable>
<xsl:attribute name="name"><xsl:value-of select="$category_name"/></xsl:attribute>
<xsl:attribute name="id"><xsl:value-of select="$category_name"/></xsl:attribute>
<xsl:value-of select="@title"/>
</H2>
<xsl:apply-templates/>
</DIV>
</xsl:template>
<xsl:template match="STYLEPOINT">
<DIV>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<xsl:variable name="stylepoint_name">
<xsl:call-template name="anchorname">
<xsl:with-param name="sectionname" select="@title"/>
</xsl:call-template>
</xsl:variable>
<xsl:variable name="button_text">
<xsl:choose>
<xsl:when test="$show_explanation_default">
<xsl:value-of select="$hide_button_text"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$show_button_text"/>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<H3>
<A>
<xsl:attribute name="name"><xsl:value-of select="$stylepoint_name"/></xsl:attribute>
<xsl:attribute name="id"><xsl:value-of select="$stylepoint_name"/></xsl:attribute>
<xsl:value-of select="@title"/>
</A>
</H3>
<xsl:variable name="buttonName">
<xsl:value-of select="$stylepoint_name"/><xsl:value-of select="$button_suffix"/>
</xsl:variable>
<xsl:variable name="onclick_definition">
<xsl:text>javascript:ShowHideByName('</xsl:text>
<xsl:value-of select="$stylepoint_name"/>
<xsl:text>')</xsl:text>
</xsl:variable>
<SPAN class="link_button" id="link-{$buttonName}" name="link-{$buttonName}">
<A>
<xsl:attribute name="href">?showone=<xsl:value-of select="$stylepoint_name"/>#<xsl:value-of select="$stylepoint_name"/></xsl:attribute>
link
</A>
</SPAN>
<SPAN class="showhide_button">
<xsl:attribute name="onclick"><xsl:value-of select="$onclick_definition"/></xsl:attribute>
<xsl:attribute name="name"><xsl:value-of select="$buttonName"/></xsl:attribute>
<xsl:attribute name="id"><xsl:value-of select="$buttonName"/></xsl:attribute>
<xsl:value-of select="$button_text"/>
</SPAN>
<xsl:apply-templates>
<xsl:with-param name="anchor_prefix" select="$stylepoint_name" />
</xsl:apply-templates>
</DIV>
</xsl:template>
<xsl:template match="SUMMARY">
<xsl:param name="anchor_prefix" />
<DIV style="display:inline;">
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<xsl:apply-templates/>
</DIV>
</xsl:template>
<xsl:template match="BODY">
<xsl:param name="anchor_prefix" />
<DIV>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<DIV class="stylepoint_body">
<xsl:attribute name="name"><xsl:value-of select="$anchor_prefix"/><xsl:value-of select="$body_suffix"/></xsl:attribute>
<xsl:attribute name="id"><xsl:value-of select="$anchor_prefix"/><xsl:value-of select="$body_suffix"/></xsl:attribute>
<xsl:attribute name="style">
<xsl:choose>
<xsl:when test="$show_explanation_default">display: inline</xsl:when>
<xsl:otherwise>display: none</xsl:otherwise>
</xsl:choose>
</xsl:attribute>
<xsl:apply-templates/>
</DIV>
</DIV>
</xsl:template>
<xsl:template match="DEFINITION">
<P>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<SPAN class="stylepoint_section">Definition: </SPAN>
<xsl:apply-templates/>
</P>
</xsl:template>
<xsl:template match="PROS">
<P>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<SPAN class="stylepoint_section">Pros: </SPAN>
<xsl:apply-templates/>
</P>
</xsl:template>
<xsl:template match="CONS">
<P>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<SPAN class="stylepoint_section">Cons: </SPAN>
<xsl:apply-templates/>
</P>
</xsl:template>
<xsl:template match="DECISION">
<P>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<SPAN class="stylepoint_section">Decision: </SPAN>
<xsl:apply-templates/>
</P>
</xsl:template>
<xsl:template match="TODO">
<P>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<DIV style="font-size: 150%;">TODO:
<xsl:apply-templates/>
</DIV>
</P>
</xsl:template>
<xsl:template match="SUBSECTION">
<P>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<SPAN class="stylepoint_subsection"><xsl:value-of select="@title"/> </SPAN>
<xsl:apply-templates/>
</P>
</xsl:template>
<xsl:template match="SUBSUBSECTION">
<P>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<SPAN class="stylepoint_subsubsection"><xsl:value-of select="@title"/> </SPAN>
<xsl:apply-templates/>
</P>
</xsl:template>
<xsl:template match="CODE_SNIPPET">
<DIV>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<PRE><xsl:call-template name="print_without_leading_chars">
<xsl:with-param name="text" select="."/>
<xsl:with-param name="strip" select="1"/>
<xsl:with-param name="is_firstline" select="1"/>
<xsl:with-param name="trim_count">
<xsl:call-template name="num_leading_spaces">
<xsl:with-param name="text" select="."/>
<xsl:with-param name="max_so_far" select="1000"/>
</xsl:call-template>
</xsl:with-param>
</xsl:call-template></PRE>
</DIV>
</xsl:template>
<xsl:template match="BAD_CODE_SNIPPET">
<DIV>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<PRE class="badcode"><xsl:call-template name="print_without_leading_chars">
<xsl:with-param name="text" select="."/>
<xsl:with-param name="strip" select="1"/>
<xsl:with-param name="is_firstline" select="1"/>
<xsl:with-param name="trim_count">
<xsl:call-template name="num_leading_spaces">
<xsl:with-param name="text" select="."/>
<xsl:with-param name="max_so_far" select="1000"/>
</xsl:call-template>
</xsl:with-param>
</xsl:call-template></PRE>
</DIV>
</xsl:template>
<xsl:template match="PY_CODE_SNIPPET">
<DIV>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<PRE><xsl:call-template name="print_python_code">
<xsl:with-param name="text" select="."/>
</xsl:call-template></PRE>
</DIV>
</xsl:template>
<xsl:template match="BAD_PY_CODE_SNIPPET">
<DIV>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<PRE class="badcode"><xsl:call-template name="print_python_code">
<xsl:with-param name="text" select="."/>
</xsl:call-template></PRE>
</DIV>
</xsl:template>
<xsl:template match="FUNCTION">
<xsl:call-template name="print_function_name">
<xsl:with-param name="text" select="."/>
</xsl:call-template>
</xsl:template>
<xsl:template match="SYNTAX">
<I>
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<xsl:apply-templates/>
</I>
</xsl:template>
<!-- This passes through any HTML elements that the
XML doc uses for minor formatting -->
<xsl:template match="a|address|blockquote|br|center|cite|code|dd|div|dl|dt|em|hr|i|img|li|ol|p|pre|span|table|td|th|tr|ul|var|A|ADDRESS|BLOCKQUOTE|BR|CENTER|CITE|CODE|DD|DIV|DL|DT|EM|HR|I|LI|OL|P|PRE|SPAN|TABLE|TD|TH|TR|UL|VAR">
<xsl:element name="{local-name()}">
<xsl:copy-of select="@*"/>
<xsl:apply-templates/>
</xsl:element>
</xsl:template>
<!-- Builds the table of contents -->
<xsl:template name="TOC">
<xsl:param name="root"/>
<DIV class="toc">
<DIV class="toc_title">Table of Contents</DIV>
<TABLE>
<xsl:for-each select="$root/CATEGORY">
<TR valign="top">
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<TD>
<DIV class="toc_category">
<A>
<xsl:attribute name="href">
<xsl:text>#</xsl:text>
<xsl:call-template name="anchorname">
<xsl:with-param name="sectionname" select="@title"/>
</xsl:call-template>
</xsl:attribute>
<xsl:value-of select="@title"/>
</A>
</DIV>
</TD><TD>
<DIV class="toc_stylepoint">
<xsl:for-each select="./STYLEPOINT">
<SPAN style="padding-right: 1em; white-space:nowrap;">
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
<A>
<xsl:attribute name="href">
<xsl:text>#</xsl:text>
<xsl:call-template name="anchorname">
<xsl:with-param name="sectionname" select="@title"/>
</xsl:call-template>
</xsl:attribute>
<xsl:value-of select="@title"/>
</A>
</SPAN>
<xsl:text> </xsl:text>
</xsl:for-each>
</DIV>
</TD>
</TR>
</xsl:for-each>
</TABLE>
</DIV>
</xsl:template>
<xsl:template name="TOC_one_stylepoint">
<xsl:param name="stylepoint"/>
</xsl:template>
<!-- Creates a standard anchor given any text.
Substitutes underscore for characters unsuitable for URLs -->
<xsl:template name="anchorname">
<xsl:param name="sectionname"/>
<!-- strange quoting necessary to strip apostrophes -->
<xsl:variable name="bad_characters" select="&quot; ()#'&quot;"/>
<xsl:value-of select="translate($sectionname,$bad_characters,'_____')"/>
</xsl:template>
<!-- Given text, evaluates to the number of leading spaces. -->
<!-- TODO(csilvers): deal well with leading tabs (treat as 8 spaces?) -->
<xsl:template name="num_leading_spaces_one_line">
<xsl:param name="text"/>
<xsl:param name="current_count"/>
<xsl:choose>
<xsl:when test="starts-with($text, ' ')">
<xsl:call-template name="num_leading_spaces_one_line">
<xsl:with-param name="text" select="substring($text, 2)"/>
<xsl:with-param name="current_count" select="$current_count + 1"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$current_count"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Given a block of text, each line terminated by \n, evaluates to
the indentation-level of that text; that is, the largest number
n such that every non-blank line starts with at least n spaces. -->
<xsl:template name="num_leading_spaces">
<xsl:param name="text"/>
<xsl:param name="max_so_far"/>
<!-- TODO(csilvers): deal with case text doesn't end in a newline -->
<xsl:variable name="line" select="substring-before($text, '&#xA;')"/>
<xsl:variable name="rest" select="substring-after($text, '&#xA;')"/>
<xsl:variable name="num_spaces_this_line">
<xsl:choose>
<xsl:when test="$line=''">
<xsl:value-of select="$max_so_far"/>
</xsl:when>
<xsl:otherwise>
<xsl:call-template name="num_leading_spaces_one_line">
<xsl:with-param name="text" select="$line"/>
<xsl:with-param name="current_count" select="0"/>
</xsl:call-template>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<xsl:variable name="new_max_so_far">
<xsl:choose>
<xsl:when test="$num_spaces_this_line &lt; $max_so_far">
<xsl:value-of select="$num_spaces_this_line"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$max_so_far"/>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<!-- now check if we're on the last line, and if not, recurse -->
<xsl:if test="$rest=''">
<xsl:value-of select="$new_max_so_far"/>
</xsl:if>
<xsl:if test="not($rest='')">
<xsl:call-template name="num_leading_spaces">
<xsl:with-param name="text" select="$rest"/>
<xsl:with-param name="max_so_far" select="$new_max_so_far"/>
</xsl:call-template>
</xsl:if>
</xsl:template>
<!-- Given text, determine the starting position of code.
This similar to num_leading_spaces_one_line but treats "Yes:" and "No:"
as spaces. Also, if there is no code on the first line, it searches
subsequent lines until a non-empty line is found.
Used to find the start of code in snippets like:
Yes: if(foo):
No : if(foo):
As well as:
Yes:
if (foo):
-->
<xsl:template name="code_start_index">
<xsl:param name="text"/>
<xsl:param name="current_count"/>
<xsl:choose>
<xsl:when test="starts-with($text, ' ')">
<xsl:call-template name="code_start_index">
<xsl:with-param name="text" select="substring($text, 2)"/>
<xsl:with-param name="current_count" select="$current_count + 1"/>
</xsl:call-template>
</xsl:when>
<xsl:when test="starts-with($text, 'Yes:')">
<xsl:call-template name="code_start_index">
<xsl:with-param name="text" select="substring($text, 5)"/>
<xsl:with-param name="current_count" select="$current_count + 4"/>
</xsl:call-template>
</xsl:when>
<xsl:when test="starts-with($text, 'No:')">
<xsl:call-template name="code_start_index">
<xsl:with-param name="text" select="substring($text, 4)"/>
<xsl:with-param name="current_count" select="$current_count + 3"/>
</xsl:call-template>
</xsl:when>
<!-- This is only reached if the first line is entirely whitespace or
contains nothing but "Yes:" or "No:"-->
<xsl:when test="starts-with($text, '&#xA;')">
<xsl:call-template name="code_start_index">
<xsl:with-param name="text" select="substring($text, 2)"/>
<xsl:with-param name="current_count" select="0"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$current_count"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Helper for ends_with_colon. Determine whether the given line is nothing
but spaces and python-style comments. -->
<xsl:template name="is_blank_or_comment">
<xsl:param name="line"/>
<xsl:choose>
<xsl:when test="$line = ''">
<xsl:value-of select="1"/>
</xsl:when>
<xsl:when test="starts-with($line, '&#xA;')">
<xsl:value-of select="1"/>
</xsl:when>
<xsl:when test="starts-with($line, '#')">
<xsl:value-of select="1"/>
</xsl:when>
<xsl:when test="starts-with($line, ' ')">
<xsl:call-template name="is_blank_or_comment">
<xsl:with-param name="line" select="substring($line, 2)"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="0"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Determine whether the given line ends with a colon. Note that Python
style comments are ignored so the following lines return True:
- def foo():
- def foo(): # Bar
- if(foo):
But some code may confuse this function. For example the following are
also consider to "end_with_colon" even though they don't for Python
- foo(": #")
- foo() # No need for :
-->
<xsl:template name="ends_with_colon">
<xsl:param name="line"/>
<xsl:param name="found_colon"/>
<xsl:choose>
<xsl:when test="$line = ''">
<xsl:value-of select="$found_colon"/>
</xsl:when>
<xsl:when test="starts-with($line, '&#xA;')">
<xsl:value-of select="$found_colon"/>
</xsl:when>
<xsl:when test="starts-with($line, ' ')">
<xsl:call-template name="ends_with_colon">
<xsl:with-param name="line" select="substring($line, 2)"/>
<xsl:with-param name="found_colon" select="$found_colon"/>
</xsl:call-template>
</xsl:when>
<xsl:when test="starts-with($line, ':')">
<xsl:variable name="rest_is_comment">
<xsl:call-template name="is_blank_or_comment">
<xsl:with-param name="line" select="substring($line, 2)"/>
</xsl:call-template>
</xsl:variable>
<xsl:choose>
<xsl:when test="$rest_is_comment = '1'">
<xsl:value-of select="1"/>
</xsl:when>
<xsl:otherwise>
<xsl:call-template name="ends_with_colon">
<xsl:with-param name="line" select="substring($line, 2)"/>
<xsl:with-param name="found_colon" select="0"/>
</xsl:call-template>
</xsl:otherwise>
</xsl:choose>
</xsl:when>
<xsl:otherwise>
<xsl:call-template name="ends_with_colon">
<xsl:with-param name="line" select="substring($line, 2)"/>
<xsl:with-param name="found_colon" select="0"/>
</xsl:call-template>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Prints one line of python code with proper indent and calls itself
recursively for the rest of the text.
This template uses "a", "b", "c" and "d" to refer to four key column
numbers. They are:
- a: the indentation common to all lines in a code snippet. This is
stripped out to allow for cleaner code in the xml.
- b: the indentation of the most out-dented line of code. This is
different from "a" when code is labelled with "Yes:" or "No:"
- c: the indentation of the current python block, in other words, the
indentation of the first line of this block, which is the
indentation of the last line we saw that ended with a colon.
- d: the "total" indentation of the line, ignorng possible "Yes:" or
"No:" text on the line.
For example, for the last line of the following code snippet, the
positions of a, b, c and d are indicated below:
Yes: def Foo():
if bar():
a += 1
baz()
a b c d
The algorithm is:
1) Split the text into first line and the rest. Note that the
substring-before function is supposed to handle the case where the
character is not present in the string but does not so we
automatically ignore the last line of the snippet which is always
empty (the closing snippet tag). This is consistent with the
behavior or print_without_leading_chars.
2) If the current is empty (only whitespace), print newline and call
itself recursively on the rest of the text with the rest of the
parameters unchanged.
3) Otherwise, measure "d"
4) Measure "c" by taking:
- the value of "d" if the previous line ended with a colon or the
current line is outdented compare to the previous line
- the indent of the previous line otherwise
5) Print line[a:c] (Note that we ignore line[0:a])
6) Print line[b:c] in an external span (in order to double the block
indent in external code).
7) Print line[c:<end>] with function names processed to produce both
internal and external names.
8) If there are more lines, recurse.
-->
<xsl:template name="print_python_line_recursively">
<xsl:param name="text"/>
<xsl:param name="a"/>
<xsl:param name="b"/>
<xsl:param name="previous_indent"/>
<xsl:param name="previous_ends_with_colon"/>
<xsl:param name="is_first_line"/>
<xsl:variable name="line" select="substring-before($text, '&#xA;')"/>
<xsl:variable name="rest" select="substring-after($text, '&#xA;')"/>
<xsl:choose>
<xsl:when test="substring($line, $b) = '' and not($rest = '')">
<xsl:if test="not($is_first_line = '1')">
<xsl:text>&#xA;</xsl:text>
</xsl:if>
<xsl:call-template name="print_python_line_recursively">
<xsl:with-param name="text" select="$rest"/>
<xsl:with-param name="a" select="$a"/>
<xsl:with-param name="b" select="$b"/>
<xsl:with-param name="previous_indent" select="$previous_indent"/>
<xsl:with-param name="previous_ends_with_colon"
select="$previous_ends_with_colon"/>
<xsl:with-param name="is_first_line" select="0"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:variable name="indent_after_b">
<xsl:call-template name="num_leading_spaces_one_line">
<xsl:with-param name="text" select="substring($line, $b + 1)"/>
<xsl:with-param name="current_count" select="0"/>
</xsl:call-template>
</xsl:variable>
<xsl:variable name="d" select="$b + $indent_after_b"/>
<xsl:variable name="c">
<xsl:choose>
<xsl:when test="$previous_ends_with_colon = '1' or
$previous_indent > $d">
<xsl:value-of select="$d"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$previous_indent"/>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<xsl:value-of select="substring($line, $a + 1, $c - $a)"/>
<span class="external">
<xsl:value-of select="substring($line, $b + 1, $c - $b)"/>
</span>
<xsl:call-template name="munge_function_names_in_text">
<xsl:with-param name="stripped_line"
select="substring($line, $c + 1)"/>
</xsl:call-template>
<xsl:if test="not(substring($rest, $a) = '')">
<xsl:text>&#xA;</xsl:text>
<xsl:call-template name="print_python_line_recursively">
<xsl:with-param name="text" select="$rest"/>
<xsl:with-param name="a" select="$a"/>
<xsl:with-param name="b" select="$b"/>
<xsl:with-param name="previous_indent" select="$c"/>
<xsl:with-param name="previous_ends_with_colon">
<xsl:call-template name="ends_with_colon">
<xsl:with-param name="line" select="$line"/>
<xsl:with-param name="found_colon" select="0"/>
</xsl:call-template>
</xsl:with-param>
<xsl:with-param name="is_first_line" select="0"/>
</xsl:call-template>
</xsl:if>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Print python code with internal and external styles.
In order to conform with PEP-8 externally, we identify 2-space indents
and an external-only 4-space indent.
Function names that are marked with $$FunctionName/$$ have an external
lower_with_underscore version added. -->
<xsl:template name="print_python_code">
<xsl:param name="text"/>
<xsl:variable name="a">
<xsl:call-template name="num_leading_spaces">
<xsl:with-param name="text" select="."/>
<xsl:with-param name="max_so_far" select="1000"/>
</xsl:call-template>
</xsl:variable>
<xsl:variable name="b">
<xsl:call-template name="code_start_index">
<xsl:with-param name="text" select="$text"/>
<xsl:with-param name="current_count" select="0"/>
</xsl:call-template>
</xsl:variable>
<xsl:call-template name="print_python_line_recursively">
<xsl:with-param name="text" select="$text"/>
<xsl:with-param name="a" select="$a"/>
<xsl:with-param name="b" select="$b"/>
<xsl:with-param name="previous_indent" select="$b"/>
<xsl:with-param name="previous_ends_with_colon" select="0"/>
<xsl:with-param name="is_first_line" select="1"/>
</xsl:call-template>
</xsl:template>
<!-- Given a block of text, each line terminated by \n, and a number n,
emits the text with the first n characters of each line
deleted. If strip==1, then we omit blank lines at the beginning
and end of the text (but not the middle!) -->
<!-- TODO(csilvers): deal well with leading tabs (treat as 8 spaces?) -->
<xsl:template name="print_without_leading_chars">
<xsl:param name="text"/>
<xsl:param name="trim_count"/>
<xsl:param name="strip"/>
<xsl:param name="is_firstline"/>
<!-- TODO(csilvers): deal with case text doesn't end in a newline -->
<xsl:variable name="line" select="substring-before($text, '&#xA;')"/>
<xsl:variable name="rest" select="substring-after($text, '&#xA;')"/>
<xsl:variable name="stripped_line" select="substring($line, $trim_count+1)"/>
<xsl:choose>
<!-- $line (or $rest) is considered empty if we'd trim the entire line -->
<xsl:when test="($strip = '1') and ($is_firstline = '1') and
(string-length($line) &lt;= $trim_count)">
</xsl:when>
<xsl:when test="($strip = '1') and
(string-length($rest) &lt;= $trim_count)">
<xsl:value-of select="$stripped_line"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$stripped_line"/>
<xsl:text>&#xA;</xsl:text>
</xsl:otherwise>
</xsl:choose>
<xsl:if test="not($rest='')">
<xsl:call-template name="print_without_leading_chars">
<xsl:with-param name="text" select="$rest"/>
<xsl:with-param name="trim_count" select="$trim_count"/>
<xsl:with-param name="strip" select="$strip"/>
<xsl:with-param name="is_firstline" select="0"/>
</xsl:call-template>
</xsl:if>
</xsl:template>
<!-- Given a line of code, find function names that are marked with $$ /$$ and
print out the line with the internal and external versions of the
function names.-->
<xsl:template name="munge_function_names_in_text">
<xsl:param name="stripped_line"/>
<xsl:choose>
<xsl:when test="contains($stripped_line, '$$')">
<xsl:value-of select="substring-before($stripped_line, '$$')"/>
<xsl:call-template name="print_function_name">
<xsl:with-param name="text" select="substring-after(substring-before($stripped_line, '/$$'), '$$')"/>
</xsl:call-template>
<xsl:call-template name="munge_function_names_in_text">
<xsl:with-param name="stripped_line" select="substring-after($stripped_line, '/$$')"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$stripped_line"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Given a function name, print out both the internal and external version
of the function name in their respective spans.-->
<xsl:template name="print_function_name">
<xsl:param name="text"/>
<xsl:call-template name="convert_camel_case_to_lowercase_with_under">
<xsl:with-param name="text" select="$text"/>
</xsl:call-template>
</xsl:template>
<!-- Given a single word of text convert it from CamelCase to
lower_with_under.
This means replacing each uppercase character with _ followed by the
lowercase version except for the first character which is replaced
without adding the _.-->
<xsl:template name="convert_camel_case_to_lowercase_with_under">
<xsl:param name="text"/>
<xsl:param name="is_recursive_call"/>
<xsl:variable name="first_char" select="substring($text, 1, 1)"/>
<xsl:variable name="rest" select="substring($text, 2)"/>
<xsl:choose>
<xsl:when test="contains('ABCDEFGHIJKLMNOPQRSTUVWXYZ', $first_char)">
<xsl:if test="$is_recursive_call='1'">
<xsl:text>_</xsl:text>
</xsl:if>
<xsl:value-of select="translate($first_char, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$first_char" />
</xsl:otherwise>
</xsl:choose>
<xsl:if test="not($rest='')">
<xsl:call-template name="convert_camel_case_to_lowercase_with_under">
<xsl:with-param name="text" select="$rest"/>
<xsl:with-param name="is_recursive_call" select="1"/>
</xsl:call-template>
</xsl:if>
</xsl:template>
</xsl:stylesheet>

864
vimscriptfull.asciidoc Normal file
View File

@ -0,0 +1,864 @@
= Google Vimscript Guide
:sectlinks:
Revision 1.1
Nate Soares +
Joshua Hoak +
David Barnett +
Table of Contents
[width="100%",cols="50%,50%",]
|=========================================================================================================================================
a|
link:#portability[Portability]
a|
a|
link:#language-guide[Language Guide]
a|
a|
link:#structure[Structure]
a|
link:#libraries-vs-functionality[Libraries vs. Functionality] link:#configuration[Configuration]
a|
link:#style-guide[Style Guide]
a|
link:#documentation[Documentation] link:#whitespace[Whitespace] link:#variables[Variables] link:#strings[Strings] link:#settings[Settings]
a|
link:#usage-guide[Usage Guide]
a|
link:#commands[Commands] link:#autocommands[Autocommands] link:#functions[Functions] link:#mappings[Mappings]
a|
link:#conventions[Conventions]
a|
link:#dependency-checking[Dependency Checking] link:#statusline-flags[Statusline Flags]
a|
link:#forbidden-commands[Forbidden Commands]
a|
a|
link:#layout[Layout]
a|
a|
link:#recommended-shortcuts[Recommended Shortcuts]
a|
a|
link:#errata[Errata]
a|
link:#compatibility-mode[Compatibility Mode]
|=========================================================================================================================================
[[Background]]
== Background
This is the in-depth vimscript guide. If you're just a casual user looking to write a plugin, the link:vimscriptguide.html[abbreviated style guide] is for you.
This rather rotund guide dives into justifications and clarifications. It provides an idealized set of rules that are rather too draconian to push on casual scripters.
It's for users who want to know why certain decisions were made in the abbreviated guide and who want to learn a thing or two about using vimscript safely.
Fair warning: Vimscript is a maddening abyss. When you gaze into it, it gazes also into you. Proceed with caution.
[[Portability]]
== Portability
Vim is highly configurable. Users can change many of the default settings, including the case sensitivity, the regular expression rules, the substitution rules, and more. In order for your vimscript to work for all users, follow these guidelines:
* Always prefix regular expressions with one of `\m`, `\v`, `\M`, or `\V` (prefer tersity)
** Users can change the global "magic level" of regular expressions. This changes how atoms are parsed in regular expressions, including `.`, `*`, and `{`.
** Even if your regular expression does not contain characters which are affected by the `magic` setting you must prefix it with one of the magic control atoms. This future-proofs your regular expression against other devs modifying it and forgetting to add the control atom.
** If you have no opinion about what type of regular expression to use, prefer the one which makes your regular expression most concise.
* Avoid using `:s[ubstitute]` in scripts.
** `:substitute` moves the cursor.
** `:substitute` outputs an error message when the match does not exist.
** The meaning of the `g` flag depends upon the `gdefault` setting. If you do use `:substitute` you must save `gdefault`, set it to `0` or `1`, perform the substitution, and then restore it.
** Script authors who want a safe way to replace text in the buffer are encouraged to use `maktaba#buffer#Replace`.
* Always use case-explicit operators for strings (`=~#` and `=~?`, never `=~`).
** This also applies to `!~ == != > >= <` and `<=`
** This only applies for strings. `==` and `>=` are fine for numbers, but `==#` and `>=#` must be used for strings.
** The behavior of `=~` and friends is dependant upon the `ignorecase` setting.
** You may break this rule when you explicitly want to obey the user's `ignorecase` setting. Be prepared to justify your reasoning.
* When using regular expressions as arguments to functions, prepend them with `\c` or `\C`.
** This forces case to be either explicitly matched or ignored.
** This is recommended, but not required, when comparing regexes with operators that specify case sensitivity (`=~#`, etc.).
** This rule applies when your regexes are matching syntax, external APIs, external messages, and most other cases.
** It does not apply when matching text in the buffer. When matching text in the buffer you should honor the `ignorecase` setting.
** You may also ignore this rule any time that you explicitly want to honor the `ignorecase` setting. Be prepared to justify your reasoning.
* Always use `normal!` instead of `normal`.
** If you forgo the `!` the command will use the user's key mappings and you have literally no idea what your macro will do.
* Always use the `noremap` family of commands.
** Your plugins generally shouldn't introduce mappings, but if they do, the `map` command respects the users existing mappings and could do anything.
* When using `catch`, match the error code rather than the error text.
** The error text may be locale-dependant.
** See `:help error-messages`.
In general, guard all commands and functions against user settings.
[[Language_Guide]]
== Language Guide
* Line continuations: Yes
** Plugins that support vi compatibility mode must save and restore compatibility options as described in the Errata section so line continuations work properly.
* Exceptions: Yes, with caution
** Always use an error code in thrown exception messages.
** Prefer the `maktaba#error` codes found in `maktaba`.
** Fall back to the vim error codes. See `:help error-messages`.
** Generate custom error messages using `maktaba#error#Message`.
* Global Variables: As configuration only
** See the plugin guide.
* Messaging: As little as possible.
** Loud scripts are annoying.
** Message the user when an error has occured.
** Message the user when an operation which takes a long time has begun work.
** Avoid messaging otherwise.
* Type checking: Use strict and explicit checks where possible.
** Vimscript has unsafe, unintuitive behavior when dealing with some types. For instance, `0 == 'foo'` evaluates to true.
** Use strict comparison operators where possible. When comparing against a string literal, use the `is#` operator. Otherwise, prefer `maktaba#value#IsEqual` or check `type()` explicitly.
** Check variable types explicitly before using them. Use functions from `maktaba#ensure`, or check `maktaba#value` or `type()` and throw your own errors.
** Use `:unlet` for variables that may change types, particularly those assigned inside loops.
* FuncRefs: No in most cases.
** FuncRefs have inconsistently enforced naming restrictions. (Functions can have names that FuncRefs can not.)
** FuncRefs have inconsistent ability to be reassigned (in Vim 7.2 and before you must unlet a FuncRef before assigning it).
** In most instances where a FuncRef is needed a string works just as well: just pass the string that you would use to make the FuncRef.
** Consider using `maktaba#function` instead to create and manipulate handles to functions.
* Python: Sparingly
** Hurts code reuse since python code embedded in python plugins is awkward to share between plugins.
** Using python introduces python language version dependencies, which are likely to get stale.
** Exception: It's reasonable to use python for plugin functionality that needs to do work in the background, as vimscript can not do this.
* Ruby: No
** We can not assume ruby interoperability.
** You shouldn't depend upon the version of the ruby language that the user has installed.
* Lua: No
** For the same reasons an Ruby.
* Dict Functions: Encouraged
** Vimscript can attach functions to dictionaries. Such functions have access to the `self` parameter which access the dict state.
** Use these where you would use a class in python.
** Do not over-use this feature; it is not necessary for helper functions or API functions, only for encapsulated objects.
All other language features are fair game.
[[Structure]]
== Structure
* Provided functionality should be packed into modular plugins.
** Every function in your plugin should be specific to your plugin.
** General utility functions should be abstracted into library plugins.
** Manage dependencies with `maktaba`.
* `plugin-names-like-this`
** Plugin names should be descriptive and concise.
* Each plugin must consist of one directory (or code repository), sharing a name with the plugin (with a "vim-" prefix or ".vim" suffix if desired).
* Plugin metadata should be declared in the addon-info.json format (see the http://goo.gl/CUXJZC[VAM documentation] for details).
* Functions should go in the `autoload/` subdirectory of your plugin.
** This allows them to be late-loaded, which speeds up startup time.
** This helps vim enforce namespacing conventions.
* Each file in the `plugin/` or `instant/` directory should begin with the boilerplate
+
-------------------------------------------------------------------
let [s:plugin, s:enter] = maktaba#plugin#Enter(expand('<sfile>:p'))
if !s:enter
finish
endif
-------------------------------------------------------------------
+
(This prevents re-entry and allows users to selectively disable functionality.)
* User configuration should be via plugin flags defined in `instant/flags.vim`.
** Define flags with `call s:plugin.Flag('FLAGNAME', DEFAULT_VALUE)`.
** Users can configure these flags using the `:Glaive` command (see https://github.com/google/glaive[glaive]).
* Commands, autocommands, mappings, and settings changes should occur either in the `plugin/` or the `ftplugin/` subdirectories.
** All commands should be defined in `plugin/commands.vim` or `ftplugin/` files.
** Autocommands should be defined in `plugin/autocmds.vim`, inside an augroup.
** Mappings should be defined in `plugin/mappings.vim` and will be disabled unless explicitly enabled by users.
** If the plugin configures any standard vim settings, those should be configured in `plugin/settings.vim` or `instant/settings.vim`.
* Avoid using the `after/` subdirectory.
** `after/` should be reserved for the user.
** It is difficult for the user to add their own overrides when plugins use `after/`.
=== Libraries vs. Functionality
Separate library-providing plugins from command-providing plugins.
Many plugins provide either user functionality (commands, autocommands, etc) or an API (of autoloaded functions) but not both. This separation is encouraged, as it allows other plugins to pull in a library without also pulling in commands, setting changes, and other plugin functionality that affects the end user.
=== Configuration
Don't clobber user settings. Provide as much configurability as possible: that's what Vim's all about.
* Use maktaba flags for plugin configuration. Users can configure them using the `:Glaive` command.
* Check if configuration variables exist before setting them.
+
-------------------------------
if !exists('g:myplugin_option')
let g:myplugin_option = 1
endif
-------------------------------
[[Style_Guide]]
== Style Guide
Follow google-wide style conventions. Mimic google python style when in doubt.
=== Documentation
Use https://github.com/google/vimdoc[vimdoc].
Provide help files generated by https://github.com/google/vimdoc[vimdoc]. Write documentation in .vim files in conformance with the vimdoc standards and include fields like "description" and "author" in the addon-info.json file (see the http://goo.gl/CUXJZC[VAM documentation]).
=== Whitespace
Follow google-wide conventions.
* Use two spaces for indents.
* Do not use tabs.
* Use spaces around operators except for arguments to commands.
** Using spaces around operators for commands is often invalid syntax. This is inconsistently enforced by vimscript. To be safe, always omit whitespace around arguments to commands.
--------------------------------------------
let s:variable = "concatenated " . "strings"
command -range=% MyCommand
--------------------------------------------
+
----------------------------------------
let s:variable="concatenated "."strings"
command -range = % MyCommand
----------------------------------------
* Do not introduce trailing whitespace.
** You need not go out of your way to remove it.
* Restrict lines to 80 columns wide.
* Indent continued lines by two tabs (four spaces).
* Do not waste whitespace aligning common segments of similar commands. It is both difficult and expensive to maintain.
-------------------------------------------
command -bang MyCommand call myplugin#foo()
command MyCommand2 call myplugin#bar()
-------------------------------------------
+
--------------------------------------------
command -bang MyCommand call myplugin#foo()
command MyCommand2 call myplugin#bar()
--------------------------------------------
Line Continuations
* Prefer line continuations on semantic boundaries.
--------------------------
command SomeLongCommand
\ call some#function()
--------------------------
+
----------------------------
command SomeLongCommand call
\ some#function()
----------------------------
** Use your best judgement.
* Place one space after the backslash denoting a line continuation.
** When continuing a multi-line command a pipe can be substituted for this space as necessary, as follows:
+
---------------------------------
autocommand BufEnter <buffer>
\ if !empty(s:var)
\| call some#function()
\|else
\| call some#function(s:var)
\|endif
---------------------------------
* Do not continue multi-line commands when you can avoid it. Prefer function calls.
Comments
* Place a space after the `"` before the comment text.
------------------------
" I am a line comment.
call call(s:my_function)
------------------------
* Do not use inline comments.
** Some commands treat them as comments and others as unclosed quotes. There are many edge cases. It's difficult to get right and difficult to maintain.
** Where you would use an inline comment, put a line comment on the line above.
* When leaving blank lines in comments, include the quote in the blank line.
---------------------
" I am one continuous
"
" comment block
---------------------
=== Variables
`plugin-names-like-this`, `FunctionNamesLikeThis`, `CommandNamesLikeThis`, `augroup_names_like_this`, `variable_names_like_this`.
Prefix all variables with their scope.
* `variable_names_like_this`
** FuncRef variables count as functions and should be named like functions.
** This (pathological) convention is enforced by vim itself.
* Prefix global variables with `g:`
** Vimscript allows you to create global variables without prefixing them.
** It is very bad practice to introduce non-prefixed global variables into scope.
** Global variables should only be used for plugin configuration.
** This does not apply to functions defined in `autoload` directories.
* Prefix script-local variables with `s:`
** This prevents namespace collisions between plugins.
** This also applies to script-local functions.
* Prefix function arguments with `a:`
** This is enforced by vim itself.
* Prefix function-local variables with `l:`
** This is not enforced by vimscript but is good practice.
** It helps you remember that all other variables must be prefixed with scope.
** `l:` disambiguates between function-local and vim-predefined variables. For example, `count` refers to `v:count`, not `l:count`.
** It future proofs your scripts against the introduction of new vim-predefined variables.
* Prefix pre-defined vim variables with `v:`
** This is not enforced by vimscript but is good practice.
** It provides context as to where the (undeclared) variable is coming from.
** It reminds you that the variable can not be assigned to.
* Prefix buffer-local variables with `b:`
** This is useful for plugins that keep per-buffer state.
=== Strings
Prefer single quotes.
Prefer single quoted strings. Specifically, in order of precedence:
* Always use single quotes for regular expressions.
** `'\s*'` is not the same as `"\s*"`
** Single quotes will prevent the need for excessive backslashes.
** Double single quotes escape to one single quote in single quoted strings: `'example ('')'` represents the string `example (')`
* If your string requires escape characters (`\n`, `\t`, etc.) use double quotes.
** Escapes can not be expressed in single quoted strings.
** Remember that `'\n'` in a regex does not represent a newline, but rather "\n". You only need to use double quotes when you want to embed the represented character itself (e.g. a newline) in the string.
* If your string contains no escapes nor single quotes, use single quoted strings.
** Most strings in vimscript are regexes, so this provides maximum consistency.
* If your non-regex string contains single quotes but no double quotes, use double quotes.
** Don't bother escaping strings if you don't have to.
** This is similar to the python string rules.
* If your string contains both single and double quotes, use whichever quoting style requires less escaping.
** Break ties in favor of single quotes.
=== Settings
Prefer long names. Set settings locally.
* Prefer long names of built in settings (i.e. `tabstop` over `ts`).
* Set local settings unless you explicitly want to set global settings.
** Use `setlocal` and `&l:` instead of `set` and `&`.
[[Usage_Guide]]
== Usage Guide
Vim plugins should provide any or all of the following: Commands, Autocommands, Functions, Statusline Flags, and Mappings.
=== Commands
* Define in `plugin/commands.vim`.
* CommandNamesLikeThis.
* Prefer semantic names to a unified prefix.
* Do not use `[!]`
* Extract logic into functions.
* `CommandNamesLikeThis`
* Commands should be defined in one block with no whitespace between them.
** Name commands semantically at the expense of a common prefix.
**--------------------------------
command WhitespaceFixTrailing
command WhitespaceFixIndentation
--------------------------------
+
-----------------------------
command FixTrailingWhitespace
command FixIndentation
-----------------------------
* Use `command` without a bang.
** This notifies users to command name conflicts immediately at startup.
** Command name collisions are an error and should not fail silently.
** Plugins are guarded against re-entry, so a single vim session should never attempt to re-define defined commands.
* Do not put logic in commands.
** Delegate to functions instead.
** Pass non-argument command parameters (`<bang>`, `<register>`, etc.) before argument parameters (`<f-args>`, etc.).
** Otherwise variable-length argument functions are difficult to implement.
* Do not autoload commands.
** Autoloaded commands will not be available until after a function in the same file is called.
** Commands intended to be used in the .vimrc should be defined in a `instant/commands.vim` file in plugins using maktaba, or explicitly installed via an autoload function in non-maktaba plugins.
Conventions
* Pass `<bang>` to functions with `'<bang>' == '!'`.
** The function should receive a boolean parameter, not a string.
=== Autocommands
* Define in `plugin/autocmds.vim`.
* Use augroups.
* augroup_names_like_this.
* Clear the augroup first.
* Extract logic into functions.
* All autocommands should be defined in the `plugin/autocmds.vim` file.
** This allows users to disable your autocommands with `Glaive myplugin !plugin[autocmds]`.
* Declare all autocommands in an `augroup` block.
** This allows your autocommands to be cleared with `autocmd!`.
** If your plugin only has one `augroup`, the `augroup` name should be the same as your plugin name, with underscores in place of any hyphens.
** Otherwise `augroup` names should start with your plugin name followed by an underscore.
* Do not put logic in autocommands.
** Delegate to functions instead.
* When creating a new `augroup`, clear it with `autocmd!`
** This allows your plugins to be re-enterable.
=== Functions
* FunctionNamesLikeThis.
* Autoload all functions.
* Prefix script-local functions with `s:`
* Use `[!]`.
* Use `[abort]`.
* `FunctionNamesLikeThis`
* Prefix all script-local functions with `s:`
* Do not provide global functions. Use autoloaded functions instead.
* Place two blank lines between top-level functions.
* Declare all functions with `abort`.
** If you do not do this, the function's behavior depends upon whether it is called within a `try..endtry` block somewhere on the stack.
** The `abort` keyword forces the function to act consistently.
** Without it, the function may (or may not) attempt to continue execution after an error occurs.
* Use `function!` with a bang.
** This allows developers to re-source their scripts and have the functions reloaded without complaint.
** Function names should never collide because functions should always be either script-local or defined in an `autoload` directory.
** Failing to use a bang in any function in an autoload file will lead to cryptic errors if vim tries to re-source the file (e.g., if you refer to an nonexistent autoload function).
* Use `...` for optional arguments, not for lists of arguments.
** Vimscript functions take at most 20 arguments.
** Lists have no such length restriction.
** Your function is likely to break when given too many arguments if you use `...` for a list of arguments.
* Throw exceptions rather than printing errors.
** Printed errors can not be caught.
** Top-level functions expecting errors may catch them and print error messages, but even those should throw their own errors when they choke.
=== Mappings
* Provide opt-in key mappings in `plugin/mappings.vim`.
* `<Plug>` mappings can be defined in `plugin/plugs.vim` (unlike mappings.vim, plugs.vim is opt-out).
* Define key mappings in `plugin/mappings.vim`, using `maktaba#plugin#MapPrefix` to get a prefix.
** Mappings defined in the special `plugin/mappings.vim` file will be disabled by default (by the standard `maktaba#plugin#Enter()` boilerplate).
** Users can enable key mappings with `Glaive myplugin plugin[mappings]`.
* Make all mappings with `<unique>`.
** This will inform the user when they have a mapping conflict instead of silently clobbering their existing mappings.
* You may provide pseudo-mappings using `<Plug>` and your plugin's name in `plugin/plugs.vim` (separate from standard key mappings).
** `<Plug>` is a sequence which can not be typed.
** You can do something like `noremap <Plug>namespace#MappingName some_key_sequence` and then users can do `noremap <leader>x <Plug>namespace#MappingName` to take advantage of your pseudo-mapping.
** Pseudo-mappings should not be in `plugin/mappings.vim` or they will be disabled by default.
** Such pseudo-mappings should be named `<Plug>` followed by your plugin name, a pound sign, and a unique mapping name (CamelCased like a function).
* Always use the `noremap` family of commands. Never use the `map` family.
** `map` depends upon the user's existing mappings, and could do anything.
* Only use `noremap` for commands that both make a motion and take a range.
** `noremap` makes mappings in normal, visual, and operator-pending modes.
** If you don't want all these use `nnoremap` `onoremap` or `vnoremap` explicitly.
* Always use `<SID>` in place of `s:` when accessing script locals in mappings.
** Using `s:` will often fail as the mapping attempts to type a literal s and colon.
[[Conventions]]
== Conventions
=== Dependency Checking
Declare dependencies in addon-info.json and use `maktaba`.
Declaring dependencies in addon-info.json allows conformant plugin managers (like VAM) to ensure dependencies are installed. See the http://goo.gl/CUXJZC[VAM documentation] for details.
Calling `maktaba#library#Require` from dependent code at runtime ensures that dependencies have been installed and that they don't include unsafe non-library files.
=== Statusline Flags
Use `<plugin-name>#status#Status()` or its finer-grained variants to provide statusline flags.
Following is a convention for exposing statusline flags to the user. A plugin should never modify the user's statusline except for when that is the only purpose of the plugin (powerline, etc.).
* Provide the `Info`, `Alert`, `Warning`, and `Error` functions under the `<plugin-name>#status` namespace.
* `Info` should provide information about the state of the buffer.
** Example: The current git branch.
* `Alert` should provide a quiet reminder that the buffer is non-standard.
** Example: The readonly setting is on.
* `Warning` should provide a warning about the current state of the buffer.
** Example: The file has been edited elsewhere.
* `Error` should bring to attention a loud issue with the buffer.
** Example: The file does not pass the syntax checker.
* By following these conventions, users can easily build up their own statusline customizing the verbosity and colors to their tastes.
* All functions should take no arguments and should return either empty strings or strings enclosed by square brackets, e.g. `[Google]`. For example:
** A trailing whitespace plugin might return `[$]` if the file contains trailing whitespace
** A prose writing plugin might return `[write]` if vim is in writing mode.
* Consider providing the `<plugin-name>#status#Status` function.
** It should return the first non-empty of `Error`, `Warning`, `Alert`, or `Info`.
** This is useful for users who want only the most relevant flag and do not have a colored statusline.
[[Forbidden_Commands]]
== Forbidden Commands
These are commands which can only be used by a limited number of plugins, and should not in general be used by yours.
* Do not use `:match :2match` or `:3match`
** These are reserved for the user and for vim itself.
** Use `matchadd()` to create a matchlevel unique to your plugin.
* Do not use `echoerr`.
** `echoerr` does not print the red error message that you might think it does.
** `echoerr` prints an error message as well as context about the code where `echoerr` was called.
** `echoerr` is best suited for debugging.
** Use `echohl` in tandem with `echomsg` if you want the red error bar.
* Use `echomsg` instead of `echo`.
** `echomsg` messages can be reviewed with the `:messages` command.
** `echo` messages disappear permanently on redraw, which can be very annoying to users who failed to read the message in time.
[[Layout]]
== Layout
Lay out `plugin/` files in the following sections, if applicable, separated by two blank lines:
* Declaration of script constants
* Declaration of configuration variables
* Other declarations (commands in `commands.vim` file, autocommands in `autocmds.vim` file, etc.)
Lay out `autoload/` files in the following sections, if applicable, separated by two blank lines:
* `maktaba#library#Require` calls
* Script-local variables
* Script-local functions
* Private autoloaded functions
* Public autoloaded functions
This is recommended convention and is not enforced.
[[Recommended_Shortcuts]]
== Recommended Shortcuts
Use the following shortcuts:
* `catch` over `catch /.*/`
* `return` over `return 0` when the return value has no semantic purpose.
[[Errata]]
== Errata
This section plumbs some of the darker corners of vimscript, explaining the language pathologies that you wish you didn't have to know.
=== Compatibility Mode
If you don't support vi-compatibility mode, fail gracefully.
When `compatible` is set, many vim features are not available. The vim feature which most commonly affects vimscript authors is line continuations.
If you want your plugin to work in vim with vi compatibility on, you will need to save the compatibility options at the beginning of each plugin file, clear them, and restore them at the end of each plugin file. See `:help use-cpo-save` for details.
Plugins that depend on maktaba generally don't need to worry about compatible mode since maktaba currently just disables it, printing a warning.
Revision 1.1
Nate Soares +
Joshua Hoak +
David Barnett +

1534
vimscriptfull.xml
View File

File diff suppressed because it is too large Load Diff

333
vimscriptguide.asciidoc Normal file
View File

@ -0,0 +1,333 @@
= Google Vimscript Style Guide
:sectlinks:
Revision 1.1
Nate Soares +
Joshua Hoak +
David Barnett +
Table of Contents
[width="100%",cols="50%,50%",]
|=================================================================================================================================================================================================================================================================================================================================
a|
link:#portability[Portability]
a|
link:#strings[Strings] link:#matching-strings[Matching Strings] link:#regular-expressions[Regular Expressions] link:#dangerous-commands[Dangerous commands] link:#fragile-commands[Fragile commands] link:#catching-exceptions[Catching Exceptions]
a|
link:#general-guidelines[General Guidelines]
a|
link:#messaging[Messaging] link:#type-checking[Type checking] link:#python[Python] link:#other-languages[Other Languages] link:#boilerplate[Boilerplate] link:#plugin-layout[Plugin layout] link:#functions[Functions] link:#commands[Commands] link:#autocommands[Autocommands] link:#mappings[Mappings] link:#settings[Settings]
a|
link:#style[Style]
a|
link:#whitespace[Whitespace] link:#naming[Naming]
|=================================================================================================================================================================================================================================================================================================================================
[[Background]]
== Background
This is a casual version of the vimscript style guide, because vimscript is a casual language. When submitting vim plugin code, you must adhere to these rules. For clarifications, justifications, and explanations about the finer points of vimscript, please refer to the link:vimscriptfull.xml[heavy guide].
[[Portability]]
== Portability
It's hard to get vimscript right. Many commands depend upon the user's settings. By following these guidelines, you can hope to make your scripts portable.
=== Strings
Prefer single quoted strings
Double quoted strings are semantically different in vimscript, and you probably don't want them (they break regexes).
Use double quoted strings when you need an escape sequence (such as `"\n"`) or if you know it doesn't matter and you need to embed single quotes.
=== Matching Strings
Use the `=~#` or `=~?` operator families over the `=~` family.
The matching behavior depends upon the user's ignorecase and smartcase settings and on whether you compare them with the `=~`, `=~#`, or `=~?` family of operators. Use the `=~#` and `=~?` operator families explicitly when comparing strings unless you explicitly need to honor the user's case sensitivity settings.
=== Regular Expressions
Prefix all regexes with `\m\C`.
In addition to the case sensitivity settings, regex behavior depends upon the user's nomagic setting. To make regexes act like nomagic and noignorecase are set, prepend all regexes with `\m\C`.
You are welcome to use other magic levels (`\v`) and case sensitivities (`\c`) so long as they are intentional and explicit.
=== Dangerous commands
Avoid commands with unintended side effects.
Avoid using `:s[ubstitute]` as it moves the cursor and prints error messages. Prefer functions (such as `search()`) better suited to scripts.
For many vim commands, functions exist that do the same thing with fewer side effects. See `:help functions()` for a list of built-in functions.
=== Fragile commands
Avoid commands that rely on user settings.
Always use `normal!` instead of `normal`. The latter depends upon the user's key mappings and could do anything.
Avoid `:s[ubstitute]`, as its behavior depends upon a number of local settings.
The same applies to other commands not listed here.
=== Catching Exceptions
Match error codes, not error text.
Error text may be locale dependant.
[[General_Guidelines]]
== General Guidelines
=== Messaging
Message the user infrequently.
Loud scripts are annoying. Message the user only when:
* A long-running process has kicked off.
* An error has occurred.
=== Type checking
Use strict and explicit checks where possible.
Vimscript has unsafe, unintuitive behavior when dealing with some types. For instance, `0 == 'foo'` evaluates to true.
Use strict comparison operators where possible. When comparing against a string literal, use the `is#` operator. Otherwise, prefer `maktaba#value#IsEqual` or check `type()` explicitly.
Check variable types explicitly before using them. Use functions from `maktaba#ensure`, or check `maktaba#value` or `type()` and throw your own errors.
Use `:unlet` for variables that may change types, particularly those assigned inside loops.
=== Python
Use sparingly.
Use python only when it provides critical functionality, for example when writing threaded code.
=== Other Languages
Use vimscript instead.
Avoid using other scripting languages such as ruby and lua. We can not guarantee that the end user's vim has been compiled with support for non-vimscript languages.
=== Boilerplate
Use https://github.com/google/maktaba[maktaba].
maktaba removes boilerplate, including:
* Plugin creation
* Error handling
* Dependency checking
=== Plugin layout
Organize functionality into modular plugins
Group your functionality as a plugin, unified in one directory (or code repository) which shares your plugin's name (with a "vim-" prefix or ".vim" suffix if desired). It should be split into plugin/, autoload/, etc. subdirectories as necessary, and it should declare metadata in the addon-info.json format (see the http://goo.gl/CUXJZC[VAM documentation] for details).
=== Functions
In the autoload/ directory, defined with `[!]` and `[abort]`.
Autoloading allows functions to be loaded on demand, which makes startuptime faster and enforces function namespacing.
Script-local functions are welcome, but should also live in autoload/ and be called by autoloaded functions.
Non-library plugins should expose commands instead of functions. Command logic should be extracted into functions and autoloaded.
`[!]` allows developers to reload their functions without complaint.
`[abort]` forces the function to halt when it encounters an error.
=== Commands
In the plugin/commands.vim or under the ftplugin/ directory, defined without `[!]`.
General commands go in `plugin/commands.vim`. Filetype-specific commands go in `ftplugin/`.
Excluding `[!]` prevents your plugin from silently clobbering existing commands. Command conflicts should be resolved by the user.
=== Autocommands
Place them in plugin/autocmds.vim, within augroups.
Place all autocommands in augroups.
The augroup name should be unique. It should either be, or be prefixed with, the plugin name.
Clear the augroup with `autocmd!` before defining new autocommands in the augroup. This makes your plugin re-entrable.
=== Mappings
Place them in `plugin/mappings.vim`, using `maktaba#plugin#MapPrefix` to get a prefix.
All key mappings should be defined in `plugin/mappings.vim`.
Partial mappings (see :help using-<Plug>.) should be defined in `plugin/plugs.vim`.
=== Settings
Change settings locally
Use `:setlocal` and `&l:` instead of `:set` and `&` unless you have explicit reason to do otherwise.
[[Style]]
== Style
Follow google style conventions. When in doubt, treat vimscript style like python style.
=== Whitespace
Similar to python. +
+
* Use two spaces for indents
* Do not use tabs
* Use spaces around operators
+
This does not apply to arguments to commands.
+
--------------------------------------------
let s:variable = "concatenated " . "strings"
command -range=% MyCommand
--------------------------------------------
* Do not introduce trailing whitespace
+
You need not go out of your way to remove it.
+
Trailing whitespace is allowed in mappings which prep commands for user input, such as "`noremap <leader>gf :grep -f `".
* Restrict lines to 80 columns wide
* Indent continued lines by four spaces
* Do not align arguments of commands
+
--------------------------------------------
command -bang MyCommand call myplugin#foo()
command MyCommand2 call myplugin#bar()
--------------------------------------------
+
-------------------------------------------
command -bang MyCommand call myplugin#foo()
command MyCommand2 call myplugin#bar()
-------------------------------------------
=== Naming
In general, use `plugin-names-like-this`, `FunctionNamesLikeThis`, `CommandNamesLikeThis`, `augroup_names_like_this`, `variable_names_like_this`.
Always prefix variables with their scope.
plugin-names-like-this
Keep them short and sweet.
FunctionNamesLikeThis
Prefix script-local functions with `s:`
Autoloaded functions may not have a scope prefix.
Do not create global functions. Use autoloaded functions instead.
CommandNamesLikeThis
Prefer succinct command names over common command prefixes.
variable_names_like_this
Augroup names count as variables for naming purposes.
Prefix all variables with their scope.
* Global variables with `g:`
* Script-local variables with `s:`
* Function arguments with `a:`
* Function-local variables with `l:`
* Vim-predefined variables with `v:`
* Buffer-local variables with `b:`
`g:`, `s:`, and `a:` must always be used.
`b:` changes the variable semantics; use it when you want buffer-local semantics.
`l:` and `v:` should be used for consistency, future proofing, and to avoid subtle bugs. They are not strictly required. Add them in new code but don’t go out of your way to add them elsewhere.
Revision 1.1
Nate Soares +
Joshua Hoak +
David Barnett +

412
vimscriptguide.xml
View File

@ -1,412 +0,0 @@
<?xml version = '1.0'?>
<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
<GUIDE title="Google Vimscript Style Guide">
<p class="revision">
Revision 1.1
</p>
<address>
Nate Soares<br/>
Joshua Hoak<br/>
David Barnett<br/>
</address>
<OVERVIEW>
<CATEGORY title="Background">
<p>
This is a casual version of the vimscript style guide, because
vimscript is a casual language. When submitting vim plugin code, you
must adhere to these rules. For clarifications, justifications, and
explanations about the finer points of vimscript, please refer to the
<a href="vimscriptfull.xml">heavy guide</a>.
</p>
</CATEGORY>
</OVERVIEW>
<CATEGORY title="Portability">
<p>
It's hard to get vimscript right. Many commands depend upon the user's
settings. By following these guidelines, you can hope to make your
scripts portable.
</p>
<STYLEPOINT title="Strings">
<SUMMARY>Prefer single quoted strings</SUMMARY>
<BODY>
<p>
Double quoted strings are semantically different in vimscript, and
you probably don't want them (they break regexes).
</p>
<p>
Use double quoted strings when you need an escape sequence (such as
<code>"\n"</code>) or if you know it doesn't matter and you need to
embed single quotes.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Matching Strings">
<SUMMARY>
Use the <code>=~#</code> or <code>=~?</code> operator families over the
<code>=~</code> family.
</SUMMARY>
<BODY>
<p>
The matching behavior depends upon the user's ignorecase and smartcase
settings and on whether you compare them with the <code>=~</code>,
<code>=~#</code>, or <code>=~?</code> family of operators. Use the
<code>=~#</code> and <code>=~?</code> operator families explicitly
when comparing strings unless you explicitly need to honor the user's
case sensitivity settings.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Regular Expressions">
<SUMMARY>Prefix all regexes with <code>\m\C</code>.</SUMMARY>
<BODY>
<p>
In addition to the case sensitivity settings, regex behavior depends
upon the user's nomagic setting. To make regexes act like nomagic and
noignorecase are set, prepend all regexes with <code>\m\C</code>.
</p>
<p>
You are welcome to use other magic levels (<code>\v</code>) and case
sensitivities (<code>\c</code>) so long as they are intentional and
explicit.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Dangerous commands">
<SUMMARY>Avoid commands with unintended side effects.</SUMMARY>
<BODY>
<p>
Avoid using <code>:s[ubstitute]</code> as it moves the cursor and
prints error messages. Prefer functions (such as
<code>search()</code>) better suited to scripts.
</p>
<p>
For many vim commands, functions exist that do the same thing with
fewer side effects. See <code>:help functions()</code> for a list of
built-in functions.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Fragile commands">
<SUMMARY>Avoid commands that rely on user settings.</SUMMARY>
<BODY>
<p>
Always use <code>normal!</code> instead of <code>normal</code>. The
latter depends upon the user's key mappings and could do anything.
</p>
<p>
Avoid <code>:s[ubstitute]</code>, as its behavior depends upon a
number of local settings.
</p>
<p>
The same applies to other commands not listed here.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Catching Exceptions">
<SUMMARY>Match error codes, not error text.</SUMMARY>
<BODY>
<p>Error text may be locale dependant.</p>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="General Guidelines">
<STYLEPOINT title="Messaging">
<SUMMARY>Message the user infrequently.</SUMMARY>
<BODY>
<p>
Loud scripts are annoying. Message the user only when:
<ul>
<li>A long-running process has kicked off.</li>
<li>An error has occurred.</li>
</ul>
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Type checking">
<SUMMARY>Use strict and explicit checks where possible.</SUMMARY>
<BODY>
<p>
Vimscript has unsafe, unintuitive behavior when dealing with some
types. For instance, <code>0 == 'foo'</code> evaluates to true.
</p>
<p>
Use strict comparison operators where possible. When comparing against
a string literal, use the <code>is#</code> operator. Otherwise, prefer
<code>maktaba#value#IsEqual</code> or check <code>type()</code>
explicitly.
</p>
<p>
Check variable types explicitly before using them. Use functions from
<code>maktaba#ensure</code>, or check <code>maktaba#value</code> or
<code>type()</code> and throw your own errors.
</p>
<p>
Use <code>:unlet</code> for variables that may change types,
particularly those assigned inside loops.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Python">
<SUMMARY>Use sparingly.</SUMMARY>
<BODY>
<p>
Use python only when it provides critical functionality, for example
when writing threaded code.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Other Languages">
<SUMMARY>Use vimscript instead.</SUMMARY>
<BODY>
<p>
Avoid using other scripting languages such as ruby and lua. We can
not guarantee that the end user's vim has been compiled with support
for non-vimscript languages.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Boilerplate">
<SUMMARY>
Use <a href="https://github.com/google/maktaba">maktaba</a>.
</SUMMARY>
<BODY>
<p>
maktaba removes boilerplate, including:
<ul>
<li>Plugin creation</li>
<li>Error handling</li>
<li>Dependency checking</li>
</ul>
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Plugin layout">
<SUMMARY>Organize functionality into modular plugins</SUMMARY>
<BODY>
<p>
Group your functionality as a plugin, unified in one directory (or
code repository) which shares your plugin's name (with a "vim-" prefix
or ".vim" suffix if desired). It should be split into plugin/,
autoload/, etc. subdirectories as necessary, and it should declare
metadata in the addon-info.json format (see the
<a href="http://goo.gl/CUXJZC">VAM documentation</a> for details).
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Functions">
<SUMMARY>
In the autoload/ directory, defined with <code>[!]</code> and
<code>[abort]</code>.
</SUMMARY>
<BODY>
<p>
Autoloading allows functions to be loaded on demand, which makes
startuptime faster and enforces function namespacing.
</p>
<p>
Script-local functions are welcome, but should also live in autoload/
and be called by autoloaded functions.
</p>
<p>
Non-library plugins should expose commands instead of functions.
Command logic should be extracted into functions and autoloaded.
</p>
<p>
<code>[!]</code> allows developers to reload their functions
without complaint.
</p>
<p>
<code>[abort]</code> forces the function to halt when it encounters
an error.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Commands">
<SUMMARY>
In the plugin/commands.vim or under the ftplugin/ directory, defined
without <code>[!]</code>.
</SUMMARY>
<BODY>
<p>
General commands go in <code>plugin/commands.vim</code>.
Filetype-specific commands go in <code>ftplugin/</code>.
</p>
<p>
Excluding <code>[!]</code> prevents your plugin from silently
clobbering existing commands. Command conflicts should be resolved by
the user.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Autocommands">
<SUMMARY>
Place them in plugin/autocmds.vim, within augroups.
</SUMMARY>
<BODY>
<p>
Place all autocommands in augroups.
</p>
<p>
The augroup name should be unique. It should either be, or be prefixed
with, the plugin name.
</p>
<p>
Clear the augroup with <code>autocmd!</code> before defining new
autocommands in the augroup. This makes your plugin re-entrable.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Mappings">
<SUMMARY>
Place them in <code>plugin/mappings.vim</code>, using
<code>maktaba#plugin#MapPrefix</code> to get a prefix.
</SUMMARY>
<BODY>
<p>
All key mappings should be defined in
<code>plugin/mappings.vim</code>.
</p>
<p>
Partial mappings (see :help using-&lt;Plug&gt;.) should be defined in
<code>plugin/plugs.vim</code>.
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Settings">
<SUMMARY>Change settings locally</SUMMARY>
<BODY>
<p>
Use <code>:setlocal</code> and <code>&amp;l:</code> instead of
<code>:set</code> and <code>&amp;</code> unless you have explicit
reason to do otherwise.
</p>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="Style">
<p>
Follow google style conventions. When in doubt, treat vimscript style
like python style.
</p>
<STYLEPOINT title="Whitespace">
<SUMMARY>
Similar to python.
<br/>
<br/>
</SUMMARY>
<BODY>
<ul>
<li>Use two spaces for indents</li>
<li>Do not use tabs</li>
<li>Use spaces around operators
<p>This does not apply to arguments to commands.</p>
<CODE_SNIPPET>
let s:variable = "concatenated " . "strings"
command -range=% MyCommand
</CODE_SNIPPET>
</li>
<li>Do not introduce trailing whitespace
<p>You need not go out of your way to remove it.</p>
<p>
Trailing whitespace is allowed in mappings which prep commands
for user input, such as
"<code>noremap &lt;leader&gt;gf :grep -f </code>".
</p>
</li>
<li>Restrict lines to 80 columns wide</li>
<li>Indent continued lines by four spaces</li>
<li>Do not align arguments of commands
<BAD_CODE_SNIPPET>
command -bang MyCommand call myplugin#foo()
command MyCommand2 call myplugin#bar()
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
command -bang MyCommand call myplugin#foo()
command MyCommand2 call myplugin#bar()
</CODE_SNIPPET>
</li>
</ul>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Naming">
<SUMMARY>
<p>
In general, use
<code>plugin-names-like-this</code>,
<code>FunctionNamesLikeThis</code>,
<code>CommandNamesLikeThis</code>,
<code>augroup_names_like_this</code>,
<code>variable_names_like_this</code>.
</p>
<p>Always prefix variables with their scope.</p>
</SUMMARY>
<BODY>
<SUBSECTION title="plugin-names-like-this">
<p>Keep them short and sweet.</p>
</SUBSECTION>
<SUBSECTION title="FunctionNamesLikeThis">
<p>Prefix script-local functions with <code>s:</code></p>
<p>Autoloaded functions may not have a scope prefix.</p>
<p>
Do not create global functions. Use autoloaded functions
instead.
</p>
</SUBSECTION>
<SUBSECTION title="CommandNamesLikeThis">
<p>Prefer succinct command names over common command prefixes.</p>
</SUBSECTION>
<SUBSECTION title="variable_names_like_this">
<p>Augroup names count as variables for naming purposes.</p>
</SUBSECTION>
<SUBSECTION title="Prefix all variables with their scope.">
<ul>
<li>Global variables with <code>g:</code></li>
<li>Script-local variables with <code>s:</code></li>
<li>Function arguments with <code>a:</code></li>
<li>Function-local variables with <code>l:</code></li>
<li>Vim-predefined variables with <code>v:</code></li>
<li>Buffer-local variables with <code>b:</code></li>
</ul>
<p>
<code>g:</code>, <code>s:</code>, and <code>a:</code> must always
be used.
</p>
<p>
<code>b:</code> changes the variable semantics; use it when you
want buffer-local semantics.
</p>
<p>
<code>l:</code> and <code>v:</code> should be used for consistency,
future proofing, and to avoid subtle bugs. They are not strictly
required. Add them in new code but don’t go out of your way to add
them elsewhere.
</p>
</SUBSECTION>
</BODY>
</STYLEPOINT>
</CATEGORY>
<p align="right">
Revision 1.1
</p>
<address>
Nate Soares<br/>
Joshua Hoak<br/>
David Barnett<br/>
</address>
</GUIDE>

174
xmlstyle.asciidoc Normal file
View File

@ -0,0 +1,174 @@
= Google XML Document Format Style Guide
:sectlinks:
Version 1.0 Copyright Google 2008
== Introduction
This document provides a set of guidelines for general use when designing new XML document formats (and to some extent XML documents as well; see Section 11). Document formats usually include both formal parts (DTDs, schemas) and parts expressed in normative English prose. These guidelines apply to new designs, and are not intended to force retroactive changes in existing designs. When participating in the creation of public or private document format designs, the guidelines may be helpful but should not control the group consensus. This guide is meant for the design of XML that is to be generated and consumed by machines rather than human beings. Its rules are _not applicable_ to formats such as XHTML (which should be formatted as much like HTML as possible) or ODF which are meant to express rich text. A document that includes embedded content in XHTML or some other rich-text format, but also contains purely machine-interpretable portions, SHOULD follow this style guide for the machine-interpretable portions. It also does not affect XML document formats that are created by translations from proto buffers or through some other type of format. Brief rationales have been added to most of the guidelines. They are maintained in the same document in hopes that they won't get out of date, but they are not considered normative. The terms MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are used in this document in the sense of http://www.ietf.org/rfc/rfc2119.txt[RFC 2119.]
== To design or not to design, that is the question
1. Attempt to reuse existing XML formats whenever possible, especially those which allow extensions. Creating an entirely new format should be done only with care and consideration; read http://www.tbray.org/ongoing/When/200x/2006/01/08/No-New-XML-Languages[Tim Bray's warnings] first. Try to get wide review of your format, from outside your organization as well, if possible. [__Rationale:__ New document formats have a cost: they must be reviewed, documented, and learned by users.]
2. If you are reusing or extending an existing format, make _sensible_ use of the prescribed elements and attributes, especially any that are required. Don't completely repurpose them, but do try to see how they might be used in creative ways if the vanilla semantics aren't suitable. As a last resort when an element or attribute is required by the format but is not appropriate for your use case, use some fixed string as its value. [__Rationale:__ Markup reuse is good, markup abuse is bad.]
3. When extending formats, use the implicit style of the existing format, even if it contradicts this guide. [__Rationale:__ Consistency.]
== Schemas
1. Document formats SHOULD be expressed using a schema language. [__Rationale:__ Clarity and machine-checkability.]
2. The schema language SHOULD be http://www.relaxng.org/[RELAX NG] http://www.relaxng.org/compact-tutorial-20030326.html[compact syntax]. Embedded http://www.schematron.com/[Schematron] rules MAY be added to the schema for additional fine control. [__Rationale:__ RELAX NG is the most flexible schema language, with very few arbitrary restrictions on designs. The compact syntax is quite easy to read and learn, and can be converted one-to-one to and from the XML syntax when necessary. Schematron handles arbitrary cross-element and cross-attribute constraints nicely.]
3. Schemas SHOULD use the http://www.xfront.com/GlobalVersusLocal.html#SecondDesign["Salami Slice" style] (one rule per element). Schemas MAY use the http://www.xfront.com/GlobalVersusLocal.html#FirstDesign["Russian Doll" style] (schema resembles document) if they are short and simple. The http://www.xfront.com/GlobalVersusLocal.html#ThirdDesign["Venetian Blind" style] (one rule per element type) is unsuited to RELAX NG and SHOULD NOT be used.
4. Regular expressions SHOULD be provided to assist in validating complex values.
5. DTDs and/or W3C XML Schemas MAY be provided for compatibility with existing products, tools, or users. [__Rationale:__ We can't change the world all at once.]
== Namespaces
1. Element names MUST be in a namespace, except when extending pre-existing document types that do not use namespaces. A default namespace SHOULD be used. [__Rationale:__ Namespace-free documents are obsolete; every set of names should be in some namespace. Using a default namespace improves readability.]
2. Attribute names SHOULD NOT be in a namespace unless they are drawn from a foreign document type or are meant to be used in foreign document types. [__Rationale:__ Attribute names in a namespace must always have a prefix, which is annoying to type and hard to read.]
3. Namespace names are HTTP URIs. Namespace names SHOULD take the form http://example.com/__whatever__/__year,__ where _whatever_ is a unique value based on the name of the document type, and _year_ is the year the namespace was created. There may be additional URI-path parts before the _year._ [__Rationale:__ Existing convention. Providing the year allows for the possible recycling of code names.]
4. Namespaces MUST NOT be changed unless the semantics of particular elements or attributes has changed in drastically incompatible ways. [__Rationale:__ Changing the namespace requires changing all client code.]
5. Namespace prefixes SHOULD be short (but not so short that they are likely to be conflict with another project). Single-letter prefixes MUST NOT be usedPrefixes SHOULD contain only lower-case ASCII letters. [__Rationale:__ Ease of typing and absence of encoding compatibility problems.]
== Names and enumerated values
*Note:* "Names" refers to the names of elements, attributes, and enumerated values.
1. All names MUST use lowerCamelCaseThat is, they start with an initial lower-case letter, then each new word within the name starts with an initial capital letter[__Rationale:__ Adopting a single style provides consistency, which helps when referring to names since the capitalization is known and so does not have to be remembered. It matches Java style, and other languages can be dealt with using automated name conversion.]
2. Names MUST contain only ASCII letters and digits. [__Rationale:__ Ease of typing and absence of encoding compatibility problems.]
3. Names SHOULD NOT exceed 25 charactersLonger names SHOULD be avoided by devising concise and informative names. If a name can only remain within this limit by becoming obscure, the limit SHOULD be ignored. [__Rationale:__ Longer names are awkward to use and require additional bandwidth.]
4. Published standard abbreviations, if sufficiently well-known, MAY be employed in constructing namesAd hoc abbreviations MUST NOT be used. Acronyms MUST be treated as words for camel-casing purposes: informationUri, not informationURI[__Rationale:__ An abbreviation that is well known to one community is often incomprehensible to others who need to use the same document format (and who do understand the full name); treating an acronym as a word makes it easier to see where the word boundaries are.]
== Elements
1. All elements MUST contain either nothing, character content, or child elements. Mixed content MUST NOT be used. [__Rationale:__ Many XML data models don't handle mixed content properly, and its use makes the element order-dependent. As always, textual formats are not covered by this rule.]
2. XML elements that merely wrap repeating child elements SHOULD NOT be used. [__Rationale:__ They are not used in Atom and add nothing.]
== Attributes
1. Document formats MUST NOT depend on the order of attributes in a start-tag. [__Rationale:__ Few XML parsers report the order, and it is not part of the XML Infoset.]
2. Elements SHOULD NOT be overloaded with too many attributes (no more than 10 as a rule of thumb). Instead, use child elements to encapsulate closely related attributes. [__Rationale:__ This approach maintains the built-in extensibility that XML provides with elements, and is useful for providing forward compatibility as a specification evolves.]
3. Attributes MUST NOT be used to hold values in which line breaks are significant. [__Rationale:__ Such line breaks are converted to spaces by conformant XML parsers.]
4. Document formats MUST allow either single or double quotation marks around attribute values. [__Rationale:__ XML parsers don't report the difference.]
== Values
1. Numeric values SHOULD be 32-bit signed integers, 64-bit signed integers, or 64-bit IEEE doubles, all expressed in base 10. These correspond to the XML Schema types xsd:int, xsd:long, and xsd:double respectively. If required in particular cases, xsd:integer (unlimited-precision integer) values MAY also be used. [__Rationale:__ There are far too many numeric types in XML Schema: these provide a reasonable subset.]
2. Boolean values SHOULD NOT be used (use enumerations instead). If they must be used, they MUST be expressed as true or false, corresponding to a subset of the XML Schema type xsd:boolean. The alternative xsd:boolean values 1 and 0 MUST NOT be used. [__Rationale:__ Boolean arguments are not extensible. The additional flexibility of allowing numeric values is not abstracted away by any parser.]
3. Dates should be represented using http://www.ietf.org/rfc/rfc3339.txt[RFC 3339] format, a subset of both ISO 8601 format and XML Schema xsd:dateTime format. UTC times SHOULD be used rather than local times. [__Rationale:__ There are far too many date formats and time zones, although it is recognized that sometimes local time preserves important information.]
4. Embedded syntax in character content and attribute values SHOULD NOT be used. Syntax in values means XML tools are largely useless. Syntaxes such as dates, URIs, and XPath expressions are exceptions. [__Rationale:__ Users should be able to process XML documents using only an XML parser without requiring additional special-purpose parsers, which are easy to get wrong.]
5. Be careful with whitespace in values. XML parsers don't strip whitespace in elements, but do convert newlines to spaces in attributes. However, application frameworks may do more aggressive whitespace stripping. Your document format SHOULD give rules for whitespace stripping.
== Key-value pairs
1. Simple key-value pairs SHOULD be represented with an empty element whose name represents the key, with the value attribute containing the valueElements that have a value attribute MAY also have a unit attribute to specify the unit of a measured value. For physical measurements, the http://en.wikipedia.org/wiki/International_System_of_Units[SI system] SHOULD be used. [__Rationale:__ Simplicity and design consistency. Keeping the value in an attribute hides it from the user, since displaying just the value without the key is not useful.]
2. If the number of possible keys is very large or unbounded, key-value pairs MAY be represented by a single generic element with key, value, and optional unit and scheme attributes (which serve to discriminate keys from different domains). In that case, also provide (not necessarily in the same document) a list of keys with human-readable explanations.
== Binary data
*Note:* There are no hard and fast rules about whether binary data should be included as part of an XML document or not. If it's too large, it's probably better to link to it.
1. Binary data MUST NOT be included directly as-is in XML documents, but MUST be encoded using Base64 encoding. [__Rationale:__ XML does not allow arbitrary binary bytes.]
2. The line breaks required by Base64 MAY be omitted. [__Rationale:__ The line breaks are meant to keep plain text lines short, but XML is not really plain text.]
3. An attribute named xsi:type with value xs:base64Binary MAY be attached to this element to signal that the Base64 format is in use. [Rationale: Opaque blobs should have decoding instructions attached.]
== Processing instructions
1. New processing instructions MUST NOT be created except in order to specify purely local processing conventions, and SHOULD be avoided altogether. Existing standardized processing instructions MAY be used. [__Rationale:__ Processing instructions fit awkwardly into XML data models and can always be replaced by elements; they exist primarily to avoid breaking backward compatibility.]
== Representation of XML document instances
*Note:* These points are only guidelines, as the format of program-created instances will often be outside the programmer's control (for example, when an XML serialization library is being used). _In no case_ should XML parsers rely on these guidelines being followed. Use standard XML parsers, not hand-rolled hacks.
1. The character encoding used SHOULD be UTF-8. Exceptions should require extremely compelling circumstances. [__Rationale:__ UTF-8 is universal and in common use.]
2. Namespaces SHOULD be declared in the root element of a document wherever possible. [__Rationale:__ Clarity and consistency.]
3. The mapping of namespace URIs to prefixes SHOULD remain constant throughout the document, and SHOULD also be used in documentation of the design. [__Rationale:__ Clarity and consistency.]
4. Well-known prefixes such as html: (for XHTML), dc: (for Dublin Core metadata), and xs: (for XML Schema) should be used for standard namespaces. [__Rationale:__ Human readability.]
5. Redundant whitespace in a tag SHOULD NOT be used. Use one space before each attribute in a start-tag; if the start tag is too long, the space MAY be replaced by a newline. [__Rationale:__ Consistency and conciseness.]
6. Empty elements MAY be expressed as empty tags or a start-tag immediately followed by an end-tagNo distinction should be made between these two formats by any application. [__Rationale:__ They are not distinguished by XML parsers.]
7. Documents MAY be pretty-printed using 2-space indentation for child elements. Elements that contain character content SHOULD NOT be wrapped. Long start-tags MAY be broken using newlines (possibly with extra indentation) after any attribute value except the last. [__Rationale:__ General compatibility with our style. Wrapping character content affects its value.]
8. Attribute values MAY be surrounded with either quotation marks or apostrophes. Specifications MUST NOT require or forbid the use of either form. &apos; and &quot; may be freely used to escape each type of quote. [__Rationale:__ No XML parsers report the distinction.]
9. Comments MUST NOT be used to carry real data. Comments MAY be used to contain TODOs in hand-written XML. Comments SHOULD NOT be used at all in publicly transmitted documents[__Rationale:__ Comments are often discarded by parsers.]
10. If comments are nevertheless used, they SHOULD appear only in the document prolog or in elements that contain child elements. If pretty-printing is required, pretty-print comments like elements, but with line wrapping. Comments SHOULD NOT appear in elements that contain character content. [__Rationale:__ Whitespace in and around comments improves readability, but embedding a comment in character content can lead to confusion about what whitespace is or is not in the content.]
11. Comments SHOULD have whitespace following <!-- and preceding -->. [__Rationale:__ Readability.]
12. CDATA sections MAY be used; they are equivalent to the use of &amp; and &lt;. Specifications MUST NOT require or forbid the use of CDATA sections. [__Rationale:__ Few XML parsers report the distinction, and combinations of CDATA and text are often reported as single objects anyway.]
13. Entity references other than the XML standard entity references &amp;, &lt;, &gt;, &quot;, and &apos; MUST NOT be used. Character references MAY be used, but actual characters are preferred, unless the character encoding is not UTF-8. As usual, textual formats are exempt from this rule.
== Elements vsAttributes
*Note:* There are no hard and fast rules for deciding when to use attributes and when to use elements. Here are some of the considerations that designers should take into account; no rationales are given.
=== 12.General points:
1. Attributes are more restrictive than elements, and all designs have some elements, so an all-element design is simplest -- which is not the same as best.
+
2. In a tree-style data model, elements are typically represented internally as nodes, which use more memory than the strings used to represent attributes. Sometimes the nodes are of different application-specific classes, which in many languages also takes up memory to represent the classes.
+
3. When streaming, elements are processed one at a time (possibly even piece by piece, depending on the XML parser you are using), whereas all the attributes of an element and their values are reported at once, which costs memory, particularly if some attribute values are very long.
+
4. Both element content and attribute values need to be escaped appropriately, so escaping should not be a consideration in the design.
+
5. In some programming languages and libraries, processing elements is easier; in others, processing attributes is easier. Beware of using ease of processing as a criterion. In particular, XSLT can handle either with equal facility.
+
6. If a piece of data should usually be shown to the user, consider using an element; if not, consider using an attribute. (This rule is often violated for one reason or another.)
+
7. If you are extending an existing schema, do things by analogy to how things are done in that schema.
+
8. Sensible schema languages, meaning RELAX NG and Schematron, treat elements and attributes symmetrically. Older and cruderhttp://www.w3.org/TR/2004/REC-xmlschema-0-20041028/[]schema languages such as DTDs and XML Schema, tend to have better support for elements.
=== 12.2 Using elements
1. If something might appear more than once in a data model, use an element rather than introducing attributes with names like foo1, foo2, foo3 ....
+
2. Use elements to represent a piece of information that can be considered an independent object and when the information is related via a parent/child relationship to another piece of information.
+
3. Use elements when data incorporates strict typing or relationship rules.
+
4. If order matters between two pieces of data, use elements for them: attributes are inherently unordered.
+
5. If a piece of data has, or might have, its own substructure, use it in an element: getting substructure into an attribute is always messy. Similarly, if the data is a constituent part of some larger piece of data, put it in an element.
+
6. An exception to the previous rule: multiple whitespace-separated tokens can safely be put in an attribute. In principle, the separator can be anything, but schema-language validators are currently only able to handle whitespace, so it's best to stick with that.
+
7. If a piece of data extends across multiple lines, use an element: XML parsers will change newlines in attribute values into spaces.
8. If a piece of data is very large, use an element so that its content can be streamed.
9. If a piece of data is in a natural language, put it in an element so you can use the xml:lang attribute to label the language being used. Some kinds of natural-language text, like Japanese, often make use http://www.w3.org/TR/2001/REC-ruby-20010531[annotations] that are conventionally represented using child elements; right-to-left languages like Hebrew and Arabic may similarly require child elements to manage http://www.w3.org/TR/2001/REC-ruby-20010531[bidirectionality] properly.
+
=== 12.3 Using attributes
1. If the data is a code from an enumeration, code list, or controlled vocabulary, put it in an attribute if possible. For example, language tags, currency codes, medical diagnostic codes, etcare best handled as attributes.
+
2. If a piece of data is really metadata on some other piece of data (for example, representing a class or role that the main data serves, or specifying a method of processing it), put it in an attribute if possible.
+
3. In particular, if a piece of data is an ID for some other piece of data, or a reference to such an ID, put the identifying piece in an attribute. When it's an ID, use the name xml:id for the attribute.
+
4. Hypertext references are conventionally put in href attributes.
+
5. If a piece of data is applicable to an element and any descendant elements unless it is overridden in some of them, it is conventional to put it in an attribute. Well-known examples are xml:lang, xml:space, xml:base, and namespace declarations.
+
6. If terseness is really the _most_ important thing, use attributes, but consider gzip compression instead -- it works very well on documents with highly repetitive structures.
== Parting words
Use common sense and __BE CONSISTENT__. Design for extensibility. You _are_ gonna need it. [__Rationale:__ Long and painful experience.]
When designing XML formats, take a few minutes to look at other formats and determine their style. The point of having style guidelines is so that people can concentrate on what you are saying, rather than on how you are saying it
Break _ANY OR ALL_ of these rules (yes, even the ones that say MUST) rather than create a crude, arbitrary, disgusting mess of a design if that's what following them slavishly would give you. In particular, random mixtures of attributes and child elements are hard to follow and hard to use, though it often makes good sense to use both when the data clearly fall into two different groups such as simple/complex or metadata/data.
Newbies always ask:
"Elements or attributes?
Which will serve me best?"
Those who know roar like lions;
Wise hackers smile like tigers.
--a http://en.wikipedia.org/wiki/Waka_%28poetry%29#Tanka[tanka], or extended haiku
[TODO: if a registry of schemas is set up, add a link to it]
+

681
xmlstyle.html
View File

@ -1,681 +0,0 @@
<style type="text/css">
/* default css */
table {
font-size: 1em;
line-height: inherit;
}
tr {
text-align: left;
}
div, address, ol, ul, li, option, select {
margin-top: 0px;
margin-bottom: 0px;
}
p {
margin: 0px;
}
body {
margin: 6px;
padding: 0px;
font-family: Verdana, sans-serif;
font-size: 10pt;
background-color: #ffffff;
}
img {
-moz-force-broken-image-icon: 1;
}
@media screen {
html.pageview {
background-color: #f3f3f3 !important;
}
body {
min-height: 1100px;
counter-reset: __goog_page__;
}
* html body {
height: 1100px;
}
.pageview body {
border-top: 1px solid #ccc;
border-left: 1px solid #ccc;
border-right: 2px solid #bbb;
border-bottom: 2px solid #bbb;
width: 648px !important;
margin: 15px auto 25px;
padding: 40px 50px;
}
/* IE6 */
* html {
overflow-y: scroll;
}
* html.pageview body {
overflow-x: auto;
}
/* Prevent repaint errors when scrolling in Safari. This "Star-7" css hack
targets Safari 3.1, but not WebKit nightlies and presumably Safari 4.
That's OK because this bug is fixed in WebKit nightlies/Safari 4 :-). */
html*#wys_frame::before {
content: '\A0';
position: fixed;
overflow: hidden;
width: 0;
height: 0;
top: 0;
left: 0;
}
.writely-callout-data {
display: none;
*display: inline-block;
*width: 0;
*height: 0;
*overflow: hidden;
}
.writely-footnote-marker {
background-image: url('images/footnote_doc_icon.gif');
background-color: transparent;
background-repeat: no-repeat;
width: 7px;
overflow: hidden;
height: 16px;
vertical-align: top;
-moz-user-select: none;
}
.editor .writely-footnote-marker {
cursor: move;
}
.writely-footnote-marker-highlight {
background-position: -15px 0;
-moz-user-select: text;
}
.writely-footnote-hide-selection ::-moz-selection, .writely-footnote-hide-selection::-moz-selection {
background: transparent;
}
.writely-footnote-hide-selection ::selection, .writely-footnote-hide-selection::selection {
background: transparent;
}
.writely-footnote-hide-selection {
cursor: move;
}
.editor .writely-comment-yellow {
background-color: #FF9;
background-position: -240px 0;
}
.editor .writely-comment-yellow-hover {
background-color: #FF0;
background-position: -224px 0;
}
.editor .writely-comment-blue {
background-color: #C0D3FF;
background-position: -16px 0;
}
.editor .writely-comment-blue-hover {
background-color: #6292FE;
background-position: 0 0;
}
.editor .writely-comment-orange {
background-color: #FFDEAD;
background-position: -80px 0;
}
.editor .writely-comment-orange-hover {
background-color: #F90;
background-position: -64px 0;
}
.editor .writely-comment-green {
background-color: #99FBB3;
background-position: -48px 0;
}
.editor .writely-comment-green-hover {
background-color: #00F442;
background-position: -32px 0;
}
.editor .writely-comment-cyan {
background-color: #CFF;
background-position: -208px 0;
}
.editor .writely-comment-cyan-hover {
background-color: #0FF;
background-position: -192px 0;
}
.editor .writely-comment-purple {
background-color: #EBCCFF;
background-position: -144px 0;
}
.editor .writely-comment-purple-hover {
background-color: #90F;
background-position: -128px 0;
}
.editor .writely-comment-magenta {
background-color: #FCF;
background-position: -112px 0;
}
.editor .writely-comment-magenta-hover {
background-color: #F0F;
background-position: -96px 0;
}
.editor .writely-comment-red {
background-color: #FFCACA;
background-position: -176px 0;
}
.editor .writely-comment-red-hover {
background-color: #FF7A7A;
background-position: -160px 0;
}
.editor .writely-comment-marker {
background-image: url('images/markericons_horiz.gif');
background-color: transparent;
padding-right: 11px;
background-repeat: no-repeat;
width: 16px;
height: 16px;
-moz-user-select: none;
}
.editor .writely-comment-hidden {
padding: 0;
background: none;
}
.editor .writely-comment-marker-hidden {
background: none;
padding: 0;
width: 0;
}
.editor .writely-comment-none {
opacity: .2;
filter:progid:DXImageTransform.Microsoft.Alpha(opacity=20);
-moz-opacity: .2;
}
.editor .writely-comment-none-hover {
opacity: .2;
filter:progid:DXImageTransform.Microsoft.Alpha(opacity=20);
-moz-opacity: .2;
}
.br_fix br:not(:-moz-last-node):not(:-moz-first-node) {
position:relative;
left: -1ex
}
.br_fix br+br {
position: static !important
}
}
h6 { font-size: 8pt }
h5 { font-size: 8pt }
h4 { font-size: 10pt }
h3 { font-size: 12pt }
h2 { font-size: 14pt }
h1 { font-size: 18pt }
blockquote {padding: 10px; border: 1px #DDD dashed }
a img {border: 0}
.pb {
border-width: 0;
page-break-after: always;
/* We don't want this to be resizeable, so enforce a width and height
using !important */
height: 1px !important;
width: 100% !important;
}
.editor .pb {
border-top: 1px dashed #C0C0C0;
border-bottom: 1px dashed #C0C0C0;
}
div.google_header, div.google_footer {
position: relative;
margin-top: 1em;
margin-bottom: 1em;
}
/* Table of contents */
.editor div.writely-toc {
background-color: #f3f3f3;
border: 1px solid #ccc;
}
.writely-toc > ol {
padding-left: 3em;
font-weight: bold;
}
ol.writely-toc-subheading {
padding-left: 1em;
font-weight: normal;
}
/* IE6 only */
* html writely-toc ol {
list-style-position: inside;
}
.writely-toc-none {
list-style-type: none;
}
.writely-toc-decimal {
list-style-type: decimal;
}
.writely-toc-upper-alpha {
list-style-type: upper-alpha;
}
.writely-toc-lower-alpha {
list-style-type: lower-alpha;
}
.writely-toc-upper-roman {
list-style-type: upper-roman;
}
.writely-toc-lower-roman {
list-style-type: lower-roman;
}
.writely-toc-disc {
list-style-type: disc;
}
/* Ordered lists converted to numbered lists can preserve ordered types, and
vice versa. This is confusing, so disallow it */
ul[type="i"], ul[type="I"], ul[type="1"], ul[type="a"], ul[type="A"] {
list-style-type: disc;
}
ol[type="disc"], ol[type="circle"], ol[type="square"] {
list-style-type: decimal;
}
/* end default css */
/* custom css */
/* end custom css */
/* ui edited css */
body {
font-family: Verdana;
font-size: 10.0pt;
line-height: normal;
background-color: #ffffff;
}
/* end ui edited css */
/* editor CSS */
.editor a:visited {color: #551A8B}
.editor table.zeroBorder {border: 1px dotted gray}
.editor table.zeroBorder td {border: 1px dotted gray}
.editor table.zeroBorder th {border: 1px dotted gray}
.editor div.google_header, .editor div.google_footer {
border: 2px #DDDDDD dashed;
position: static;
width: 100%;
min-height: 2em;
}
.editor .misspell {background-color: yellow}
.editor .writely-comment {
font-size: 9pt;
line-height: 1.4;
padding: 1px;
border: 1px dashed #C0C0C0
}
/* end editor CSS */
</style>
<style>
body {
margin: 0px;
}
#doc-contents {
margin: 6px;
}
#google-view-footer {
clear: both;
border-top: thin solid;
padding-top: 0.3em;
padding-bottom: 0.3em;
}
a.google-small-link:link, a.google-small-link:visited {
color:#112ABB;
font-family:Arial,Sans-serif;
font-size:11px !important;
}
body, p, div, td {
direction: inherit;
}
@media print {
#google-view-footer {
display: none;
}
}
</style>
<script>
function viewOnLoad() {
if (document.location.href.indexOf('spi=1') != -1) {
if (navigator.userAgent.toLowerCase().indexOf('msie') != -1) {
window.print();
} else {
window.setTimeout(window.print, 10);
}
}
if (document.location.href.indexOf('hgd=1') != -1) {
var footer = document.getElementById("google-view-footer");
if (footer) {
footer.style.display = 'none';
}
}
}
</script>
</head>
<body>
<div id="doc-contents">
<div>
<h1 style="text-align: center;">
Google XML Document Format Style Guide</h1><div style="text-align: center;">Version 1.0<br>Copyright Google 2008<br><br></div><h2>Introduction</h2>This document provides a set of guidelines for general use when designing new XML document formats (and to some extent XML documents as well; see Section 11).&nbsp; Document formats usually include both formal parts (DTDs, schemas) and parts expressed in normative English prose.<br><br>These guidelines apply to new designs, and are not intended to force retroactive changes in existing designs.&nbsp; When participating in the creation of public or private document format designs, the guidelines may be helpful but should not control the group consensus.<br><br>This guide is meant for the design of XML that is to be generated and consumed by machines rather than human beings.&nbsp; Its rules are <i>not applicable</i> to formats such as XHTML (which should be formatted as much like HTML as possible) or ODF which are meant to express rich text.&nbsp; A document that includes embedded content in XHTML or some other rich-text format, but also contains purely machine-interpretable portions, SHOULD follow this style guide for the machine-interpretable portions.&nbsp; It also does not affect XML document formats that are created by translations from proto buffers or through some other type of format.<br><br>Brief rationales have been added to most of the guidelines.&nbsp; They are maintained in the same document in hopes that they won't get out of date, but they are not considered normative.<br><br>The terms MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are used in this document in the sense of <a title="RFC 2119" href="http://www.ietf.org/rfc/rfc2119.txt" id="iecm">RFC 2119.</a><br>&nbsp;<br><h2>1. To design or not to design, that is the question<br></h2><ol><li>Attempt to reuse existing XML formats whenever possible, especially those which allow extensions.&nbsp; Creating an entirely new format should be done only with care and consideration; read <a title="Tim Bray's warnings" href="http://www.tbray.org/ongoing/When/200x/2006/01/08/No-New-XML-Languages" id="d3cy">Tim Bray's warnings</a> first.&nbsp; Try to get wide review of your format, from outside your organization as well, if possible.&nbsp; [<i>Rationale:</i> New document formats have a cost: they must be reviewed, documented, and learned by users.]<br><br></li><li>If you are reusing or extending an existing format, make <i>sensible</i>
use of the prescribed elements and attributes, especially any that are
required.&nbsp; Don't completely repurpose them, but do try to see how they
might be used in creative ways if the vanilla semantics aren't
suitable.&nbsp; As a last resort when an element or attribute is required by the format but is not appropriate for your use case, use some
fixed string as its value.&nbsp; [<i>Rationale:</i>&nbsp; Markup reuse is good, markup abuse is bad.]<br><br></li><li>When extending formats, use the implicit style of the existing format, even if it contradicts this guide.&nbsp; [<i>Rationale: </i>Consistency.]<br></li></ol><br><h2>2. Schemas</h2><ol><li>Document formats SHOULD be expressed using a schema language.&nbsp; [<i>Rationale: </i>Clarity and machine-checkability.]<br><br></li><li>The schema language SHOULD be <a title="RELAX NG" href="http://www.relaxng.org/" id="p1s7">RELAX NG</a> <a title="compact syntax" href="http://www.relaxng.org/compact-tutorial-20030326.html" id="ulci">compact syntax</a>.&nbsp; Embedded <a title="Schematron" href="http://www.schematron.com/" id="ymh-">Schematron</a> rules MAY be added to the schema for additional fine control.&nbsp; [<i>Rationale:</i>
RELAX NG is the most flexible schema language, with very few arbitrary
restrictions on designs.&nbsp; The compact syntax is quite easy to read and
learn, and can be converted one-to-one to and from the XML syntax when
necessary.&nbsp; Schematron handles arbitrary cross-element and
cross-attribute constraints nicely.]<br><br></li><li>Schemas SHOULD use the <a title="&quot;Salami Slice&quot; style" href="http://www.xfront.com/GlobalVersusLocal.html#SecondDesign" id="r:fj">"Salami Slice" style</a> (one rule per element).&nbsp; Schemas MAY use the <a title="&quot;Russian Doll&quot; style" href="http://www.xfront.com/GlobalVersusLocal.html#FirstDesign" id="h14y">"Russian Doll" style</a> (schema resembles document) if they are short and simple.&nbsp; The <a title="&quot;Venetian Blind&quot; style" href="http://www.xfront.com/GlobalVersusLocal.html#ThirdDesign" id="dr_g">"Venetian Blind" style</a> (one rule per element type) is unsuited to RELAX NG and SHOULD NOT be used.<br><br></li><li>Regular expressions SHOULD be provided to assist in validating complex values.<br><br></li><li>DTDs and/or W3C XML Schemas MAY be provided for compatibility with existing products, tools, or users.&nbsp; [<i>Rationale:</i> We can't change the world all at once.]<br></li></ol></div><div><br><h2>3. Namespaces</h2><ol><li>Element names MUST be in a namespace, except
when extending pre-existing document types that do not use namespaces.&nbsp;
A default namespace SHOULD be used.&nbsp; [<i>Rationale:</i> Namespace-free
documents are obsolete; every set of names should be in some
namespace.&nbsp; Using a default namespace improves readability.]<br><br></li><li>Attribute
names SHOULD NOT be in a namespace unless they are drawn from a foreign
document type or are meant to be used in foreign document types.&nbsp; [<i>Rationale:</i> Attribute names in a namespace must always have a prefix, which is annoying to type and hard to read.]<br><br>
</li><li>Namespace names are HTTP URIs.&nbsp; Namespace names SHOULD take the form <span style="font-family: Courier New;">http://example.com/</span><i style="font-family: Courier New;">whatever</i><span style="font-family: Courier New;">/</span><i><span style="font-family: Courier New;">year</span>, </i>where <i>whatever</i> is a unique value based on the name of the document type, and <i>year</i>
is the year the namespace was created.&nbsp; There may be additional URI-path parts
before the <i>year.</i>&nbsp; [<i>Rationale:</i> Existing convention.&nbsp; Providing the year allows for the possible recycling of code names.]<br><br></li><li>Namespaces MUST NOT be changed unless the semantics of particular elements or attributes has changed in drastically incompatible ways.&nbsp; [<i>Rationale:</i> Changing the namespace requires changing all client code.]<br><br></li><li>Namespace prefixes SHOULD be short (but not so short that they are likely to be conflict with another project).&nbsp; Single-letter prefixes MUST NOT be used. Prefixes SHOULD contain only lower-case ASCII letters.&nbsp; [<i>Rationale:</i> Ease of typing and absence of encoding compatibility problems.]</li></ol><br>
<h2>4. Names and enumerated values</h2><b>Note: </b>"Names" refers to the names of elements, attributes, and enumerated values.<br><br><ol><li>All names MUST use lowerCamelCase. That is, they start with an initial lower-case letter, then each new word within the name starts with an initial capital letter. [<i>Rationale:</i> Adopting a single style provides consistency, which helps when referring to names since the capitalization is known and so does not have to be remembered.&nbsp; It matches Java style, and other languages can be dealt with using automated name conversion.]<br><br></li><li>Names MUST contain only ASCII letters and digits.&nbsp;
[<i>Rationale:</i> Ease of typing and absence of encoding compatibility problems.]<br> <br></li><li>Names SHOULD NOT exceed 25 characters. Longer names SHOULD be
avoided by devising concise and informative names.&nbsp; If a name can only remain within this limit by becoming obscure, the limit SHOULD be ignored.&nbsp; [<i>Rationale: </i>Longer names are awkward to use and require additional bandwidth.]<br><br></li><li>Published standard abbreviations, if sufficiently well-known, MAY be employed in constructing names. Ad hoc abbreviations MUST NOT be used.&nbsp; Acronyms MUST be treated as words for camel-casing purposes: informationUri, not informationURI. [<i>Rationale:</i>&nbsp; An abbreviation that is well known
to one community is often incomprehensible to others who need to use
the same document format (and who do understand the full name); treating an acronym as a word makes it easier to see where the word boundaries are.] <br></li></ol><p><br></p><p>
</p><h2>
5. Elements</h2><ol><li>All elements MUST contain either nothing, character content, or child elements.&nbsp; Mixed content MUST NOT be used.&nbsp; [<i>Rationale:</i> Many XML data models don't handle mixed content properly, and its use makes the element order-dependent.&nbsp; As always, textual formats are not covered by this rule.]<br><br></li><li>XML elements that merely wrap repeating child elements SHOULD NOT be used.&nbsp; [<i>Rationale:</i> They are not used in Atom and add nothing.]</li></ol>
<p><br></p><h2>6. Attributes</h2><ol><li>Document formats MUST NOT depend on the order of attributes in a start-tag.&nbsp; [<i>Rationale:</i> Few XML parsers report the order, and it is not part of the XML Infoset.]<br><br></li><li>Elements SHOULD NOT be overloaded with too many attributes (no more
than 10 as a rule of thumb).&nbsp; Instead, use child elements to
encapsulate closely related attributes.&nbsp; [<i>Rationale:</i> This
approach maintains the built-in extensibility that XML provides with
elements, and is useful for providing forward compatibility as a
specification evolves.]<br><br></li><li>Attributes MUST NOT be used to hold values in which line breaks are significant.&nbsp; [<i>Rationale:</i> Such line breaks are converted to spaces by conformant XML parsers.]<br><br></li><li>Document formats MUST allow either single or double quotation marks around attribute values.&nbsp; [<i>Rationale:</i>&nbsp; XML parsers don't report the difference.]<br></li></ol>
<p><br></p>
<p>
</p><h2>
7. Values</h2><ol><li>Numeric values SHOULD be 32-bit signed integers, 64-bit signed integers, or 64-bit IEEE doubles, all expressed in base 10.&nbsp; These correspond to the XML Schema types <span style="font-family: Courier New;">xsd:int</span>, <span style="font-family: Courier New;">xsd:long</span>, and <span style="font-family: Courier New;">xsd:double</span> respectively.&nbsp; If required in particular cases, <span style="font-family: Courier New;">xsd:integer</span> (unlimited-precision integer) values MAY also be used.&nbsp; [<i>Rationale:</i> There are far too many numeric types in XML Schema: these provide a reasonable subset.]&nbsp; <br><br></li><li>
Boolean values SHOULD NOT be used (use enumerations instead).&nbsp; If they must be used, they MUST be expressed as <span style="font-family: Courier New;">true</span> or <span style="font-family: Courier New;">false</span>, corresponding to a subset of the XML Schema type <span style="font-family: Courier New;">xsd:boolean</span>.&nbsp; The alternative <span style="font-family: Courier New;">xsd:boolean</span> values <span style="font-family: Courier New;">1</span> and <span style="font-family: Courier New;">0</span> MUST NOT be used.&nbsp; [<i>Rationale:</i> Boolean arguments are not extensible.&nbsp; The additional flexibility of allowing numeric values is not abstracted away by any parser.]<br><br></li><li>Dates should be represented using <a title="RFC 3339" href="http://www.ietf.org/rfc/rfc3339.txt" id="sk98">RFC 3339</a> format, a subset of both
ISO 8601 format and XML Schema <span style="font-family: Courier New;">xsd:dateTime</span> format.&nbsp; UTC times SHOULD be used rather than local times.&nbsp;
[<i>Rationale:</i> There are far too many date formats and time zones, although it is recognized that sometimes local time preserves important information.]<br><br></li><li>Embedded syntax in character content and attribute values SHOULD NOT be
used.&nbsp; Syntax in values means XML tools are largely useless.&nbsp; Syntaxes such as&nbsp; dates, URIs, and
XPath expressions are exceptions.&nbsp; [<i>Rationale:</i>&nbsp;
Users should be able to process XML documents using only an XML parser
without requiring additional special-purpose parsers, which are easy to
get wrong.]<br><br></li><li>Be careful with whitespace in values.&nbsp; XML parsers don't strip whitespace in elements, but do convert newlines to spaces in attributes.&nbsp; However, application frameworks may do more aggressive whitespace stripping.&nbsp; Your document format SHOULD give rules for whitespace stripping.<br></li></ol>
<p><br>
</p>
<p>
</p><h2>8. Key-value pairs<br></h2><ol><li>
Simple key-value pairs SHOULD be represented with an empty element whose name represents the key, with the <span style="font-family: Courier New;">value</span> attribute containing the value. Elements that have a <span style="font-family: Courier New;">value</span> attribute MAY also have a <span style="font-family: Courier New;">unit</span> attribute to specify the unit of a measured value.&nbsp; For physical measurements, the <a title="SI system" href="http://en.wikipedia.org/wiki/International_System_of_Units" id="rhxg">SI system</a> SHOULD be used.&nbsp; [<i>Rationale:</i>
Simplicity and design consistency.&nbsp; Keeping the value in an attribute
hides it from the user, since displaying just the value without the key is not useful.]<br><br></li><li>If the number of possible keys is very large or unbounded, key-value pairs MAY be represented by a single generic element with <span style="font-family: Courier New;">key</span>, <span style="font-family: Courier New;">value</span>, and optional <span style="font-family: Courier New;">unit</span> and <span style="font-family: Courier New;">scheme</span>
attributes (which serve to discriminate keys from different domains).&nbsp;
In that case, also provide (not necessarily in the same document) a
list of keys with human-readable explanations.</li></ol><br><h2>9. Binary data</h2><p><b>Note: </b>There are no hard and fast rules about whether binary data should be included as part of an XML document or not.&nbsp; If it's too large, it's probably better to link to it.</p><p><br></p><ol><li>Binary data MUST NOT be included directly as-is in XML documents, but MUST be encoded using Base64 encoding.&nbsp; [<i>Rationale:</i> XML does not allow arbitrary binary bytes.]<br><br></li><li>
The line breaks required by Base64 MAY be omitted.&nbsp; [<i>Rationale:</i> The line breaks are meant to keep plain text lines short, but XML is not really plain text.]<br><br></li><li>An attribute named <span style="font-family: Courier New;">xsi:type</span> with value <span style="font-family: Courier New;">xs:base64Binary</span> MAY be attached to this element to signal that the Base64 format is in use.&nbsp; [Rationale: Opaque blobs should have decoding instructions attached.]<br><br></li></ol>
<h2>10. Processing instructions</h2><ol><li>New processing instructions MUST NOT be created except in order to specify purely local processing conventions, and SHOULD be avoided altogether.&nbsp; Existing standardized processing instructions MAY be used.&nbsp; [<i>Rationale:</i> Processing instructions fit awkwardly into XML data models and can always be replaced by elements; they exist primarily to avoid breaking backward compatibility.]</li></ol><p>&nbsp;</p>
<p>
</p><p>&nbsp;</p><h2>11. Representation of XML document instances<br></h2><p><b>Note:</b>&nbsp; These points are only guidelines, as the format of program-created instances will often be outside the programmer's control (for example, when an XML serialization library is being used).&nbsp; <i>In no case</i> should XML parsers rely on these guidelines being followed.&nbsp; Use standard XML parsers, not hand-rolled hacks.<br></p><p><br></p><ol><li>The character encoding used SHOULD be UTF-8.&nbsp; Exceptions should require extremely compelling circumstances.&nbsp; [<i>Rationale:</i> UTF-8 is universal and in common use.]<br><br></li><li>Namespaces SHOULD be declared in the root element of a document wherever possible.&nbsp; [<i>Rationale: </i>Clarity and consistency.]<br><br></li><li>The mapping of namespace URIs to prefixes SHOULD remain constant throughout the document, and SHOULD also be used in documentation of the design.&nbsp; [<i>Rationale: </i>Clarity and consistency.]<br><br></li><li>Well-known prefixes such as html: (for XHTML), dc: (for Dublin Core metadata), and xs: (for XML Schema) should be used for standard namespaces.&nbsp; [<i>Rationale:</i> Human readability.]<br><br></li><li>Redundant whitespace in a tag SHOULD NOT be
used.&nbsp; Use one space before each attribute in a start-tag; if the start
tag is too long, the space MAY be replaced by a newline.&nbsp; [<i>Rationale:</i> Consistency and conciseness.]<br><br></li><li>Empty elements MAY be expressed as empty tags or a start-tag
immediately followed by an end-tag. No distinction should be made
between these two formats by any application.&nbsp; [<i>Rationale:</i> They are not distinguished by XML parsers.]<br><br></li><li>Documents MAY be pretty-printed using 2-space indentation for child
elements.&nbsp; Elements that contain character content SHOULD NOT be
wrapped.&nbsp; Long start-tags MAY be broken using newlines (possibly with extra indentation) after any attribute value except the last.&nbsp; [<i>Rationale:</i> General compatibility with our style.&nbsp; Wrapping character content affects its value.]<br><br></li><li>Attribute values MAY be surrounded with either quotation marks or apostrophes.
Specifications MUST NOT require or forbid the use of either form.&nbsp; <span style="font-family: Courier New;">&amp;apos;</span> and <span style="font-family: Courier New;">&amp;quot;</span> may be freely used to escape each type of quote.&nbsp; [<i>Rationale:</i> No XML parsers report the distinction.]<br><br>
</li><li>Comments MUST NOT be used to carry real data.&nbsp; Comments MAY be used to contain TODOs in hand-written XML.&nbsp; Comments SHOULD NOT be used at all in publicly transmitted documents. [<i>Rationale:&nbsp; </i>Comments are often discarded by parsers.]<br><br></li><li>If comments are nevertheless used, they SHOULD appear only in the document prolog or in elements that
contain child elements.&nbsp; If pretty-printing is required, pretty-print
comments like elements, but with line wrapping.&nbsp; Comments SHOULD NOT
appear in elements that contain character content.&nbsp; [<i>Rationale:&nbsp; </i>Whitespace in and around comments improves readability, but embedding a
comment in character content can lead to confusion about what
whitespace is or is not in the content.]<br><br></li><li>Comments SHOULD have whitespace following <span style="font-family: Courier New;">&lt;!--</span> and preceding <span style="font-family: Courier New;">--&gt;</span>.&nbsp; [<i>Rationale:</i> Readability.]<br><br></li><li>CDATA sections MAY be used; they are equivalent to the use of <span style="font-family: Courier New;">&amp;amp;</span> and <span style="font-family: Courier New;">&amp;lt;</span>.&nbsp; Specifications MUST NOT require or forbid the use of CDATA sections.&nbsp; [<i>Rationale:</i> Few XML parsers report the distinction, and combinations of CDATA and text are often reported as single objects anyway.]<br><br></li><li>Entity references other than the XML standard entity references <span style="font-family: Courier New;">&amp;amp;</span>, <span style="font-family: Courier New;">&amp;lt;</span>, <span style="font-family: Courier New;">&amp;gt;</span>, <span style="font-family: Courier New;">&amp;quot;</span>, and <span style="font-family: Courier New;">&amp;apos;</span> MUST NOT be used.&nbsp; Character references MAY be used, but actual characters are preferred, unless the character encoding is not UTF-8.&nbsp; As usual, textual formats are exempt from this rule.<br></li></ol>
<br><p>&nbsp;</p><p>
</p>
<p>
</p><br><br><h2>
12. Elements vs. Attributes
</h2>
<p>
<b>Note:</b>&nbsp; There are no hard and fast rules for deciding when to use attributes and when to use elements.&nbsp; Here are some of the considerations that designers should take into account; no rationales are given.
</p>
<h3>
12.1. General points:<br>
</h3>
<ol>
<li>
<p>
Attributes are more restrictive than elements, and all designs have some elements, so an all-element design is simplest -- which is not the same as best.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
In a tree-style data model, elements are typically represented internally as nodes, which use more memory than the strings used to represent attributes.&nbsp; Sometimes the nodes are of different application-specific classes, which in many languages also takes up memory to represent the classes.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
When streaming, elements are processed one at a time (possibly even piece by piece, depending on the XML parser you are using), whereas all the attributes of an element and their values are reported at once, which costs memory, particularly if some attribute values are very long.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
Both element content and attribute values need to be escaped appropriately, so escaping should not be a consideration in the design.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
In some programming languages and libraries, processing elements is easier; in others, processing attributes is easier.&nbsp; Beware of using ease of processing as a criterion.&nbsp; In particular, XSLT can handle either with equal facility.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If a piece of data should usually be shown to the user, consider using an element; if not, consider using an attribute.&nbsp; (This rule is often violated for one reason or another.)
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If you are extending an existing schema, do things by analogy to how things are done in that schema.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
Sensible schema languages, meaning RELAX NG and Schematron, treat elements and attributes symmetrically.&nbsp; Older and cruder<a href="http://www.w3.org/TR/2004/REC-xmlschema-0-20041028/" id="h2c3" title="XML Schema"> </a>schema languages such as DTDs and XML Schema, tend to have better support for elements.
</p>
</li>
</ol>
<p>
</p>
<h3>
12.2 Using elements<br>
</h3>
<ol>
<li>
<p>
If something might appear more than once in a data model, use an element rather than introducing attributes with names like <span style="font-family: Courier New;">foo1, foo2, foo3</span> ....
</p>
<p>
<br>
</p>
</li>
<li>
<p>
Use elements to represent a piece of information that can be considered an independent object and when the information is related via a parent/child relationship to another piece of information.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
Use elements when data incorporates strict typing or relationship rules.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If order matters between two pieces of data, use elements for them: attributes are inherently unordered.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If a piece of data has, or might have, its own substructure, use it in an element: getting substructure into an attribute is always messy.&nbsp; Similarly, if the data is a constituent part of some larger piece of data, put it in an element.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
An exception to the previous rule: multiple whitespace-separated tokens can safely be put in an attribute.&nbsp; In principle, the separator can be anything, but schema-language validators are currently only able to handle whitespace, so it's best to stick with that.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If a piece of data extends across multiple lines, use an element: XML parsers will change newlines in attribute values into spaces.
<br><br></p></li><li>If a piece of data is very large, use an element so that its content can be streamed.<br><br></li>
<li>
<p>
If a piece of data is in a natural language, put it in an element so you can use the <span style="font-family: Courier New;">xml:lang</span> attribute to label the language being used.&nbsp; Some kinds of natural-language text, like Japanese, often make use <a href="http://www.w3.org/TR/2001/REC-ruby-20010531" id="pa2f" title="annotations">annotations</a> that are conventionally represented using child elements; right-to-left languages like Hebrew and Arabic may similarly require child elements to manage <a href="http://www.w3.org/TR/2001/REC-ruby-20010531" id="ehyv" title="bidirectionality">bidirectionality</a> properly.
</p>
<p>
</p>
</li>
</ol>
<h3>
12.3 Using attributes<br>
</h3>
<ol>
<li>
<p>
If the data is a code from an enumeration, code list, or controlled vocabulary, put it in an attribute if possible.&nbsp; For example, language tags, currency codes, medical diagnostic codes, etc. are best handled as attributes.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If a piece of data is really metadata on some other piece of data (for example, representing a class or role that the main data serves,&nbsp; or specifying a method of processing it), put it in an attribute if possible.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
In particular, if a piece of data is an ID for some other piece of data, or a reference to such an ID, put the identifying piece in an attribute.&nbsp; When it's an ID, use the name <span style="font-family: Courier New;">xml:id</span> for the attribute.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
Hypertext references are conventionally put in <span style="font-family: Courier New;">href</span> attributes.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If a piece of data is applicable to an element and any descendant elements unless it is overridden in some of them, it is conventional to put it in an attribute.&nbsp; Well-known examples are <span style="font-family: Courier New;">xml:lang</span>, <span style="font-family: Courier New;">xml:space</span>, <span style="font-family: Courier New;">xml:base</span>, and namespace declarations.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If terseness is really the <i>most</i> important thing, use attributes, but consider <span style="font-family: Courier New;">gzip</span> compression instead -- it works very well on documents with highly repetitive structures.</p></li>
</ol></div><br><div><div><div><div><div>
<br><h2>13. Parting words
</h2>
<p>
</p><p>
Use common sense and <i>BE CONSISTENT</i>.&nbsp;&nbsp; Design for extensibility.&nbsp; You <i>are</i> gonna need it.&nbsp; [<i>Rationale:</i> Long and painful experience.]<br></p><p><br> </p>
<p>
When designing XML formats, take a few minutes to look at other formats and determine their style.&nbsp; The point of having style guidelines is so that people can concentrate on what you are
saying, rather than on how you are saying it. <br></p><p>
<br>
Break <i>ANY OR ALL</i> of these rules (yes, even the ones that say MUST) rather than create a crude, arbitrary, disgusting mess of a design if that's what following them slavishly would give you.&nbsp; In particular, random mixtures of attributes and child elements are hard to follow and hard to use, though it often makes good sense to use both when the data clearly fall into two different groups such as simple/complex or metadata/data.
</p>
<div><p>
<br>
Newbies always ask:
</p>
<p>
&nbsp;&nbsp;&nbsp; "Elements or attributes?
</p>
<p>
Which will serve me best?"
</p>
<p>
&nbsp;&nbsp;&nbsp; Those who know roar like lions;
</p>
<p>
&nbsp;&nbsp;&nbsp; Wise hackers smile like tigers.
</p>
<p>
&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; --a <a href="http://en.wikipedia.org/wiki/Waka_%28poetry%29#Tanka" id="s3k3" title="tanka">tanka</a>, or extended haiku
</p>
</div>
<p>
<br>
</p>
<br>[TODO: if a registry of schemas is set up, add a link to it]<br><br></div><br></div><br></div></div></div><br>
<br clear="all"/>
</div>