mirror of
https://github.com/google/styleguide.git
synced 2024-03-22 13:11:43 +08:00
first clean fork on cpplint
This commit is contained in:
unknown
parent
e1333014b5
commit
9d1438f507
447
Rguide.xml
447
Rguide.xml
|
|
@ -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><-</code>, not
|
||||
<code>=</code></li>
|
||||
<li><a href="#semicolons">Semicolons</a>: don't use them</li>
|
||||
<li><a href="#generallayout"> General Layout and Ordering</a></li>
|
||||
<li><a href="#comments"> Commenting Guidelines</a>: all comments begin
|
||||
with <code>#</code> followed by a space; inline comments need two
|
||||
spaces before the <code>#</code></li>
|
||||
<li><a href="#functiondefinition">Function Definitions and Calls</a></li>
|
||||
<li><a href="#functiondocumentation"> Function Documentation</a></li>
|
||||
<li><a href="#examplefunction"> Example Function</a></li>
|
||||
<li><a href="#todo"> TODO Style</a>: <code>TODO(username)</code></li>
|
||||
</ol>
|
||||
|
||||
<h2>Summary: R Language Rules</h2>
|
||||
<ol>
|
||||
<li><a href="#attach"> <code>attach</code></a>: avoid using it</li>
|
||||
<li><a href="#functionlanguage"> Functions</a>:
|
||||
errors should be raised using <code>stop()</code></li>
|
||||
<li><a href="#object"> Objects and Methods</a>: avoid S4 objects and
|
||||
methods when possible; never mix S3 and S4 </li>
|
||||
</ol>
|
||||
|
||||
<h3>Notation and Naming</h3>
|
||||
|
||||
<h4 id="filenames">File Names</h4>
|
||||
<p>
|
||||
File names should end in <code>.R</code> and, of course, be
|
||||
meaningful.
|
||||
<br/> GOOD: <code>predict_ad_revenue.R</code>
|
||||
<br/> BAD: <code><span style="color:red">foo.R</span></code>
|
||||
</p>
|
||||
|
||||
<h4 id="identifiers">Identifiers</h4>
|
||||
<p>
|
||||
Don't use underscores ( <code>_</code> ) or hyphens
|
||||
( <code>-</code> ) in identifiers.
|
||||
Identifiers should be named according to the following conventions.
|
||||
The preferred form for variable names is all lower case
|
||||
letters and words separated with dots
|
||||
(<code>variable.name</code>), but <code>variableName</code>
|
||||
is also accepted;
|
||||
function names have initial capital letters and no dots
|
||||
(<code>FunctionName</code>);
|
||||
constants are named like functions but with an initial
|
||||
<code>k</code>.
|
||||
</p>
|
||||
<ul>
|
||||
<li><code>variable.name</code> is preferred, <code>variableName</code> is accepted
|
||||
<br/> GOOD: <code>avg.clicks</code>
|
||||
<br/> OK: <code>avgClicks</code>
|
||||
<br/> BAD: <code><span style="color:red">avg_Clicks</span></code>
|
||||
</li>
|
||||
<li><code>FunctionName </code>
|
||||
<br/> GOOD: <code>CalculateAvgClicks</code>
|
||||
<br/> BAD: <code><span style="color:red">calculate_avg_clicks
|
||||
</span></code>,
|
||||
<code><span style="color:red">calculateAvgClicks</span></code>
|
||||
<br/> Make function names verbs.
|
||||
<br/><em>Exception: When creating a classed object, the function
|
||||
name (constructor) and class should match (e.g., lm).</em></li>
|
||||
<li><code>kConstantName </code></li>
|
||||
</ul>
|
||||
|
||||
|
||||
<h3>Syntax</h3>
|
||||
|
||||
<h4 id="linelength">Line Length</h4>
|
||||
<p>
|
||||
The maximum line length is 80 characters.
|
||||
</p>
|
||||
|
||||
<h4 id="indentation">Indentation</h4>
|
||||
<p>
|
||||
When indenting your code, use two spaces. Never use tabs or mix
|
||||
tabs and spaces.
|
||||
<br/><em>Exception: When a line break occurs inside parentheses,
|
||||
align the wrapped line with the first character inside the
|
||||
parenthesis.</em>
|
||||
</p>
|
||||
|
||||
<h4 id="spacing">Spacing</h4>
|
||||
<p>
|
||||
Place spaces around all binary operators (<code>=</code>,
|
||||
<code>+</code>, <code>-</code>, <code><-</code>, etc.).
|
||||
<br/><em> Exception: Spaces around <code>=</code>'s are
|
||||
optional when passing parameters in a function call.</em>
|
||||
</p>
|
||||
<p>
|
||||
Do not place a space before a comma, but always place one after a
|
||||
comma.
|
||||
<br/><br/> GOOD:
|
||||
</p>
|
||||
<pre>tab.prior <- table(df[df$days.from.opt < 0, "campaign.id"])
|
||||
total <- sum(x[, 1])
|
||||
total <- sum(x[1, ])</pre>
|
||||
<p>
|
||||
BAD:
|
||||
</p>
|
||||
<pre><span style="color:red">tab.prior <- table(df[df$days.from.opt<0, "campaign.id"]) # Needs spaces around '<'
|
||||
tab.prior <- table(df[df$days.from.opt < 0,"campaign.id"]) # Needs a space after the comma
|
||||
tab.prior<- table(df[df$days.from.opt < 0, "campaign.id"]) # Needs a space before <-
|
||||
tab.prior<-table(df[df$days.from.opt < 0, "campaign.id"]) # Needs spaces around <-
|
||||
total <- sum(x[,1]) # Needs a space after the comma
|
||||
total <- sum(x[ ,1]) # Needs a space after the comma, not before</span>
|
||||
</pre>
|
||||
<p>
|
||||
Place a space before left parenthesis, except in a function call.
|
||||
</p>
|
||||
<p>
|
||||
GOOD:
|
||||
<br/><code>if (debug)</code>
|
||||
</p>
|
||||
<p>
|
||||
BAD:
|
||||
<br/><code><span style="color:red">if(debug)</span></code>
|
||||
</p>
|
||||
<p>
|
||||
Extra spacing (i.e., more than one space in a row) is okay if it
|
||||
improves alignment of equals signs or arrows (<code><-</code>).
|
||||
</p>
|
||||
<pre>plot(x = x.coord,
|
||||
y = data.mat[, MakeColName(metric, ptiles[1], "roiOpt")],
|
||||
ylim = ylim,
|
||||
xlab = "dates",
|
||||
ylab = metric,
|
||||
main = (paste(metric, " for 3 samples ", sep = "")))
|
||||
</pre>
|
||||
<p>
|
||||
Do not place spaces around code in parentheses or square brackets.
|
||||
<br/><em> Exception: Always place a space after a comma.</em>
|
||||
</p>
|
||||
<p>
|
||||
GOOD:</p><pre>if (debug)
|
||||
x[1, ]</pre>
|
||||
<p>
|
||||
BAD:</p><pre><span style="color:red">if ( debug ) # No spaces around debug
|
||||
x[1,] # Needs a space after the comma </span></pre>
|
||||
|
||||
<h4 id="curlybraces">Curly Braces</h4>
|
||||
<p>
|
||||
An opening curly brace should never go on its own line; a closing
|
||||
curly brace should always go on its own line. You may omit curly
|
||||
braces when a block consists of a single statement; however, you
|
||||
must <em>consistently</em> either use or not use curly braces for
|
||||
single statement blocks.
|
||||
</p>
|
||||
<pre>
|
||||
if (is.null(ylim)) {
|
||||
ylim <- c(0, 0.06)
|
||||
}</pre>
|
||||
<p>
|
||||
xor (but not both)
|
||||
</p>
|
||||
<pre>
|
||||
if (is.null(ylim))
|
||||
ylim <- c(0, 0.06)</pre>
|
||||
<p>
|
||||
Always begin the body of a block on a new line.
|
||||
</p>
|
||||
<p>
|
||||
BAD:
|
||||
<br/><code><span style="color:red"> if (is.null(ylim))
|
||||
ylim <- c(0, 0.06)</span></code>
|
||||
<br/><code><span style="color:red"> if (is.null(ylim))
|
||||
{ylim <- c(0, 0.06)} </span></code>
|
||||
</p>
|
||||
|
||||
<h4 id="else">Surround else with braces</h4>
|
||||
<p>
|
||||
An <code>else</code> statement should always be surrounded on the
|
||||
same line by curly braces.</p>
|
||||
<pre>
|
||||
if (condition) {
|
||||
one or more lines
|
||||
} else {
|
||||
one or more lines
|
||||
}
|
||||
</pre>
|
||||
<p>
|
||||
BAD:<br/>
|
||||
</p>
|
||||
<pre style="color:red">
|
||||
if (condition) {
|
||||
one or more lines
|
||||
}
|
||||
else {
|
||||
one or more lines
|
||||
}
|
||||
</pre>
|
||||
<p>
|
||||
BAD:<br/>
|
||||
</p>
|
||||
<pre style="color:red">
|
||||
if (condition)
|
||||
one line
|
||||
else
|
||||
one line
|
||||
</pre>
|
||||
|
||||
<h4 id="assignment">Assignment</h4>
|
||||
<p>
|
||||
Use <code><-</code>, not <code>=</code>, for assignment.
|
||||
</p>
|
||||
<p>
|
||||
GOOD:
|
||||
<br/><code> x <- 5 </code>
|
||||
</p>
|
||||
<p>
|
||||
BAD:
|
||||
<br/><code><span style="color:red"> x = 5</span></code>
|
||||
</p>
|
||||
<h4 id="semicolons">Semicolons</h4>
|
||||
<p>
|
||||
Do not terminate your lines with semicolons or use semicolons to
|
||||
put more than one command on the same line. (Semicolons are not
|
||||
necessary, and are omitted for consistency with other Google style
|
||||
guides.)
|
||||
</p>
|
||||
|
||||
|
||||
<h3> Organization </h3>
|
||||
<h4 id="generallayout">General Layout and Ordering</h4>
|
||||
<p>
|
||||
If everyone uses the same general ordering, we'll be able to
|
||||
read and understand each other's scripts faster and more easily.
|
||||
</p>
|
||||
<ol>
|
||||
<li>Copyright statement comment </li>
|
||||
<li>Author comment</li>
|
||||
<li>File description comment, including purpose of
|
||||
program, inputs, and outputs</li>
|
||||
<li><code>source()</code> and <code>library()</code> statements</li>
|
||||
<li>Function definitions</li>
|
||||
<li>Executed statements, if applicable (e.g.,
|
||||
<code> print</code>, <code>plot</code>)</li>
|
||||
</ol>
|
||||
<p>
|
||||
Unit tests should go in a separate file named
|
||||
<code>originalfilename_test.R</code>.
|
||||
</p>
|
||||
<h4 id="comments">Commenting Guidelines</h4>
|
||||
<p>
|
||||
Comment your code. Entire commented lines should begin with
|
||||
<code>#</code> and one space.
|
||||
</p>
|
||||
<p>
|
||||
Short comments can be placed after code preceded by two spaces,
|
||||
<code>#</code>, and then one space.
|
||||
</p>
|
||||
<pre># Create histogram of frequency of campaigns by pct budget spent.
|
||||
hist(df$pct.spent,
|
||||
breaks = "scott", # method for choosing number of buckets
|
||||
main = "Histogram: fraction budget spent by campaignid",
|
||||
xlab = "Fraction of budget spent",
|
||||
ylab = "Frequency (count of campaignids)")
|
||||
</pre>
|
||||
<h4 id="functiondefinition">Function Definitions and
|
||||
Calls</h4>
|
||||
<p>
|
||||
Function definitions should first list arguments without default
|
||||
values, followed by those with default values.
|
||||
</p>
|
||||
<p>
|
||||
In both function definitions and function calls, multiple
|
||||
arguments per line are allowed; line breaks are only allowed
|
||||
between assignments.
|
||||
<br/>GOOD:
|
||||
</p>
|
||||
<pre>PredictCTR <- function(query, property, num.days,
|
||||
show.plot = TRUE)
|
||||
</pre>
|
||||
BAD:
|
||||
<pre><span style="color:red">PredictCTR <- function(query, property, num.days, show.plot =
|
||||
TRUE)
|
||||
</span></pre>
|
||||
<p> Ideally, unit tests should serve as sample function calls (for
|
||||
shared library routines).
|
||||
</p>
|
||||
<h4 id="functiondocumentation">Function Documentation</h4>
|
||||
<p> Functions should contain a comments section immediately below
|
||||
the function definition line. These comments should consist of a
|
||||
one-sentence description of the function; a list of the function's
|
||||
arguments, denoted by <code>Args:</code>, with a description of
|
||||
each (including the data type); and a description of the return
|
||||
value, denoted by <code>Returns:</code>. The comments should be
|
||||
descriptive enough that a caller can use the function without
|
||||
reading any of the function's code.
|
||||
</p>
|
||||
|
||||
<h4 id="examplefunction">Example Function</h4>
|
||||
<pre>
|
||||
CalculateSampleCovariance <- function(x, y, verbose = TRUE) {
|
||||
# Computes the sample covariance between two vectors.
|
||||
#
|
||||
# Args:
|
||||
# x: One of two vectors whose sample covariance is to be calculated.
|
||||
# y: The other vector. x and y must have the same length, greater than one,
|
||||
# with no missing values.
|
||||
# verbose: If TRUE, prints sample covariance; if not, not. Default is TRUE.
|
||||
#
|
||||
# Returns:
|
||||
# The sample covariance between x and y.
|
||||
n <- length(x)
|
||||
# Error handling
|
||||
if (n <= 1 || n != length(y)) {
|
||||
stop("Arguments x and y have different lengths: ",
|
||||
length(x), " and ", length(y), ".")
|
||||
}
|
||||
if (TRUE %in% is.na(x) || TRUE %in% is.na(y)) {
|
||||
stop(" Arguments x and y must not have missing values.")
|
||||
}
|
||||
covariance <- var(x, y)
|
||||
if (verbose)
|
||||
cat("Covariance = ", round(covariance, 4), ".\n", sep = "")
|
||||
return(covariance)
|
||||
}
|
||||
</pre>
|
||||
|
||||
<h4 id="todo">TODO Style</h4>
|
||||
|
||||
<p>
|
||||
Use a consistent style for TODOs throughout your code.
|
||||
<br/><code>TODO(username): Explicit description of action to
|
||||
be taken</code>
|
||||
</p>
|
||||
|
||||
|
||||
<h3> Language </h3>
|
||||
|
||||
<h4 id="attach">Attach</h4>
|
||||
<p> The possibilities for creating errors when using
|
||||
<code>attach</code> are numerous. Avoid it.</p>
|
||||
<h4 id="functionlanguage">Functions</h4>
|
||||
<p> Errors should be raised using <code>stop()</code>.</p>
|
||||
<h4 id="object">Objects and Methods</h4>
|
||||
<p> The S language has two object systems, S3 and S4, both of which
|
||||
are available in R. S3 methods are more interactive and flexible,
|
||||
whereas S4 methods are more formal and rigorous. (For an illustration
|
||||
of the two systems, see Thomas Lumley's
|
||||
"Programmer's Niche: A Simple
|
||||
Class, in S3 and S4" in R News 4/1, 2004, pgs. 33 - 36:
|
||||
<a href="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>
|
||||
|
|
@ -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>
|
||||
<div ng-controller="hello.mainpage.HomeCtrl"/>
|
||||
<span ng-class="homeCtrl.myColor">I'm in a color!</span>
|
||||
<span>{{homeCtrl.add(5, 6)}}</span>
|
||||
</div>
|
||||
</pre>
|
||||
|
||||
<p>After Angular 1.2, this looks like:</p>
|
||||
|
||||
<pre class="prettyprint lang-js">
|
||||
/**
|
||||
* Home controller.
|
||||
*
|
||||
* @constructor
|
||||
* @ngInject
|
||||
* @export
|
||||
*/
|
||||
hello.mainpage.HomeCtrl = function() {
|
||||
/**
|
||||
* @type {string}
|
||||
* @export
|
||||
*/
|
||||
this.myColor = 'blue';
|
||||
};
|
||||
|
||||
|
||||
/**
|
||||
* @param {number} a
|
||||
* @param {number} b
|
||||
* @export
|
||||
*/
|
||||
hello.mainpage.HomeCtrl.prototype.add = function(a, b) {
|
||||
return a + b;
|
||||
};
|
||||
</pre>
|
||||
|
||||
<p>If you are compiling with property renaming, expose properties and methods using the @export
|
||||
annotation. Remember to @export the constructor as well.</p>
|
||||
|
||||
<p>And in the template:</p>
|
||||
|
||||
<pre>
|
||||
<div ng-controller="hello.mainpage.HomeCtrl as homeCtrl"/>
|
||||
<span ng-class="homeCtrl.myColor">I'm in a color!</span>
|
||||
<span>{{homeCtrl.add(5, 6)}}</span>
|
||||
</div>
|
||||
</pre>
|
||||
|
||||
<p><b>Why?</b>
|
||||
Putting methods and properties directly onto the controller, instead of building up a scope
|
||||
object, fits better with the Google Closure class style. Additionally, using 'controller as'
|
||||
makes it obvious which controller you are accessing when multiple controllers apply to an element.
|
||||
Since there is always a '.' in the bindings, you don't have to worry about prototypal inheritance
|
||||
masking primitives.</p>
|
||||
|
||||
<h3 id="directives">Directives</h3>
|
||||
|
||||
<p>All DOM manipulation should be done inside directives. Directives should be kept small and use
|
||||
composition. Files defining directives should goog.provide a static function which returns the
|
||||
directive definition object.</p>
|
||||
|
||||
<pre class="prettyprint lang-js">
|
||||
goog.provide('hello.pane.paneDirective');
|
||||
|
||||
/**
|
||||
* Description and usage
|
||||
* @return {angular.Directive} Directive definition object.
|
||||
*/
|
||||
hello.pane.paneDirective = function() {
|
||||
// ...
|
||||
};
|
||||
</pre>
|
||||
|
||||
<p><b>Exception</b>: DOM manipulation may occur in services for DOM elements disconnected from the
|
||||
rest of the view, e.g. dialogs or keyboard shortcuts.</p>
|
||||
|
||||
<h3 id="services">Services</h3>
|
||||
|
||||
<p>Services registered on the module with <code>module.service</code> are classes.
|
||||
Use <code>module.service</code> instead of <code>module.provider</code> or
|
||||
<code>module.factory</code> unless you need to do initialization beyond just creating a
|
||||
new instance of the class.</p>
|
||||
|
||||
<pre class="prettyprint lang-js">
|
||||
/**
|
||||
* @param {!angular.$http} $http The Angular http service.
|
||||
* @constructor
|
||||
*/
|
||||
hello.request.Request = function($http) {
|
||||
/** @type {!angular.$http} */
|
||||
this.http_ = $http;
|
||||
};
|
||||
|
||||
hello.request.Request.prototype.get = function() {/*...*/};
|
||||
</pre>
|
||||
|
||||
<p>In the module:</p>
|
||||
|
||||
<pre class="prettyprint lang-js">
|
||||
module.service('request', hello.request.Request);
|
||||
</pre>
|
||||
|
||||
|
||||
<h2>2 Angular Style Rules</h2>
|
||||
|
||||
<h3 id="dollarsign">Reserve $ for Angular properties and services</h3>
|
||||
<p>Do not use $ to prepend your own object properties and service identifiers. Consider this style
|
||||
of naming reserved by AngularJS and jQuery.</p>
|
||||
|
||||
<p>Yes:</p>
|
||||
<pre class="prettyprint lang-js">
|
||||
$scope.myModel = { value: 'foo' }
|
||||
myModule.service('myService', function() { /*...*/ });
|
||||
var MyCtrl = function($http) {this.http_ = $http;};
|
||||
</pre>
|
||||
|
||||
<p><font color="red">No:</font></p>
|
||||
<pre class="prettyprint">
|
||||
$scope.$myModel = { value: 'foo' } // BAD
|
||||
$scope.myModel = { $value: 'foo' } // BAD
|
||||
myModule.service('$myService', function() { ... }); // BAD
|
||||
var MyCtrl = function($http) {this.$http_ = $http;}; // BAD
|
||||
</pre>
|
||||
|
||||
<p><b>Why?</b>
|
||||
It's useful to distinguish between Angular / jQuery builtins and things you add yourself.
|
||||
In addition, $ is not an acceptable character for variables names in the JS style guide.
|
||||
</p>
|
||||
|
||||
<h3 id="customelements">Custom elements</h3>
|
||||
|
||||
<p>For custom elements (e.g. <code><ng-include src="template"></ng-include></code>), IE8
|
||||
requires special support (html5shiv-like hacks) to enable css styling. Be aware of this
|
||||
restriction in apps targeting old versions of IE.</p>
|
||||
|
||||
<h2>3 Angular Tips, Tricks, and Best Practices</h2>
|
||||
|
||||
<p>These are not strict style guide rules, but are placed here as reference for folks getting
|
||||
started with Angular at Google.</p>
|
||||
|
||||
<h3 id="testing">Testing</h3>
|
||||
|
||||
<p>Angular is designed for test-driven development.</p>
|
||||
|
||||
<p>The recommended unit testing setup is Jasmine + Karma (though you could use closure tests
|
||||
or js_test)</p>
|
||||
|
||||
<p>Angular provides easy adapters to load modules and use the injector in Jasmine tests.
|
||||
<ul>
|
||||
<li><a href = "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>
|
||||
6117
cppguide.html
6117
cppguide.html
File diff suppressed because it is too large
Load Diff
18
cppguide.xml
18
cppguide.xml
|
|
@ -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>
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
# Google documentation guide
|
||||
|
||||
* [Markdown styleguide](style.md)
|
||||
* [Best practices](best_practices.md)
|
||||
* [README files](READMEs.md)
|
||||
* [Philosophy](philosophy.md)
|
||||
|
||||
## See also
|
||||
|
||||
* [How to update this guide](https://goto.google.com/doc-guide), for Googlers.
|
||||
|
|
@ -1,69 +0,0 @@
|
|||
# README.md files
|
||||
|
||||
About README.md files.
|
||||
|
||||
1. [Overview](#overview)
|
||||
1. [Guidelines](#guidelines)
|
||||
1. [Filename](#filename)
|
||||
1. [Contents](#contents)
|
||||
1. [Example](#example)
|
||||
|
||||
## Overview
|
||||
|
||||
`README.md` files are Markdown files that describe a directory.
|
||||
GitHub and Gitiles renders it when you browse the directory.
|
||||
|
||||
For example, the file /README.md is rendered when you view the contents of the
|
||||
containing directory:
|
||||
|
||||
https://github.com/google/styleguide/tree/gh-pages
|
||||
|
||||
Also `README.md` at `HEAD` ref is rendered by Gitiles when displaying repository
|
||||
index:
|
||||
|
||||
https://gerrit.googlesource.com/gitiles/
|
||||
|
||||
## Guidelines
|
||||
|
||||
**`README.md` files are intended to provide orientation for engineers browsing
|
||||
your code, especially first-time users.** The `README.md` is likely the first
|
||||
file a reader encounters when they browse a directory that
|
||||
contains your code. In this way, it acts as a landing page for the directory.
|
||||
|
||||
We recommend that top-level directories for your code have an up-to-date
|
||||
`README.md` file. This is especially important for package directories that
|
||||
provide interfaces for other teams.
|
||||
|
||||
### Filename
|
||||
|
||||
Use `README.md`.
|
||||
|
||||
Files named `README` are not displayed in the directory view in Gitiles.
|
||||
|
||||
### Contents
|
||||
|
||||
At minimum, every package-level `README.md` should include or point to the
|
||||
following information:
|
||||
|
||||
1. **What** is in this package/library and what's it used for.
|
||||
2. **Who** to contact.
|
||||
3. **Status**: whether this package/library is deprecated, or not for general
|
||||
release, etc.
|
||||
4. **More info**: where to go for more detailed documentation, such as:
|
||||
* An overview.md file for more detailed conceptual information.
|
||||
* Any API documentation for using this package/library.
|
||||
|
||||
## Example
|
||||
|
||||
```markdown
|
||||
# APIs
|
||||
|
||||
This is the top-level directory for all externally-visible APIs, plus some
|
||||
private APIs under `internal/` directories.
|
||||
See [API Style Guide](docs/apistyle.md) for more information.
|
||||
|
||||
*TL;DR*: API definitions and configurations should be defined in `.proto` files,
|
||||
checked into `apis/`.
|
||||
|
||||
...
|
||||
```
|
||||
|
|
@ -1 +0,0 @@
|
|||
1.0
|
||||
|
|
@ -1,115 +0,0 @@
|
|||
# Documentation Best Practices
|
||||
|
||||
"Say what you mean, simply and directly." - [Brian Kernighan]
|
||||
(http://en.wikipedia.org/wiki/The_Elements_of_Programming_Style)
|
||||
|
||||
Contents:
|
||||
|
||||
1. [Minimum viable documentation](#minimum-viable-documentation)
|
||||
1. [Update docs with code](#update-docs-with-code)
|
||||
1. [Delete dead documentation](#delete-dead-documentation)
|
||||
1. [Documentation is the story of your code](#documentation-is-the-story-of-your-code)
|
||||
|
||||
## Minimum viable documentation
|
||||
|
||||
A small set of fresh and accurate docs are better than a sprawling, loose
|
||||
assembly of "documentation" in various states of disrepair.
|
||||
|
||||
Write short and useful documents. Cut out everything unnecessary, while also
|
||||
making a habit of continually massaging and improving every doc to suit your
|
||||
changing needs. **Docs work best when they are alive but frequently trimmed,
|
||||
like a bonsai tree**.
|
||||
|
||||
This guide encourages engineers to take ownership of their docs and keep
|
||||
them up to date with the same zeal we keep our tests in good order. Strive for
|
||||
this.
|
||||
|
||||
* Identify what you really need: release docs, API docs, testing guidelines.
|
||||
* Delete cruft frequently and in small batches.
|
||||
|
||||
## Update docs with code
|
||||
|
||||
**Change your documentation in the same CL as the code change**. This keeps your
|
||||
docs fresh, and is also a good place to explain to your reviewer what you're
|
||||
doing.
|
||||
|
||||
A good reviewer can at least insist that docstrings, header files, README.md
|
||||
files, and any other docs get updated alongside the CL.
|
||||
|
||||
## Delete dead documentation
|
||||
|
||||
Dead docs are bad. They misinform, they slow down, they incite despair in
|
||||
engineers and laziness in team leads. They set a precedent for leaving behind
|
||||
messes in a code base. If your home is clean, most guests will be clean without
|
||||
being asked.
|
||||
|
||||
Just like any big cleaning project, **it's easy to be overwhelmed**. If your
|
||||
docs are in bad shape:
|
||||
|
||||
* Take it slow, doc health is a gradual accumulation.
|
||||
* First delete what you're certain is wrong, ignore what's unclear.
|
||||
* Get your whole team involved. Devote time to quickly scan every doc and make
|
||||
a simple decision: Keep or delete?
|
||||
* Default to delete or leave behind if migrating. Stragglers can always be
|
||||
recovered.
|
||||
* Iterate.
|
||||
|
||||
## Prefer the good over the perfect
|
||||
|
||||
Your documentation should be as good as possible within a reasonable time frame.
|
||||
The standards for an documentation review are different from the
|
||||
standards for code reviews. Reviewers can and should ask for improvements, but
|
||||
in general, the author should always be able to invoke the "Good Over Perfect
|
||||
Rule". It's preferable to allow authors to quickly submit changes that improve
|
||||
the document, instead of forcing rounds of review until it's "perfect". Docs are
|
||||
never perfect, and tend to gradually improve as the team learns what they really
|
||||
need to write down.
|
||||
|
||||
## Documentation is the story of your code
|
||||
|
||||
Writing excellent code doesn't end when your code compiles or even if your
|
||||
test coverage reaches 100%. It's easy to write something a computer understands,
|
||||
it's much harder to write something both a human and a computer understand. Your
|
||||
mission as a Code Health-conscious engineer is to **write for humans first,
|
||||
computers second.** Documentation is an important part of this skill.
|
||||
|
||||
There's a spectrum of engineering documentation that ranges from terse comments
|
||||
to detailed prose:
|
||||
|
||||
1. **Inline comments**: The primary purpose of inline comments is to provide
|
||||
information that the code itself cannot contain, such as why the code is
|
||||
there.
|
||||
|
||||
2. **Method and class comments**:
|
||||
|
||||
* **Method API documentation**: The header / Javadoc / docstring
|
||||
comments that say what methods do and how to use them. This
|
||||
documentation is **the contract of how your code must behave**. The
|
||||
intended audience is future programmers who will use and modify your
|
||||
code.
|
||||
|
||||
It is often reasonable to say that any behavior documented here should
|
||||
have a test verifying it. This documentation details what arguments the
|
||||
method takes, what it returns, any "gotchas" or restrictions, and what
|
||||
exceptions it can throw or errors it can return. It does not usually
|
||||
explain why code behaves a particular way unless that's relevant to a
|
||||
developer's understanding of how to use the method. "Why" explanations
|
||||
are for inline comments. Think in practical terms when writing method
|
||||
documentation: "This is a hammer. You use it to pound nails."
|
||||
|
||||
* **Class / Module API documentation**: The header / Javadoc / docstring
|
||||
comments for a class or a whole file. This documentation gives a brief
|
||||
overview of what the class / file does and often gives a few short
|
||||
examples of how you might use the class / file.
|
||||
|
||||
Examples are particularly relevant when there's several distinct ways to
|
||||
use the class (some advanced, some simple). Always list the simplest
|
||||
use case first.
|
||||
|
||||
3. **README.md**: A good README.md orients the new user to the directory and
|
||||
points to more detailed explanation and user guides:
|
||||
* What is this directory intended to hold?
|
||||
* Which files should the developer look at first? Are some files an API?
|
||||
* Who maintains this directory and where I can learn more?
|
||||
|
||||
See the [README.md guidelines](READMEs.md).
|
||||
|
|
@ -1,71 +0,0 @@
|
|||
# Philosophy
|
||||
|
||||
埏埴以為器，當其無，有器之用.
|
||||
|
||||
*Clay becomes pottery through craft, but it's the emptiness that makes a pot
|
||||
useful.*
|
||||
|
||||
\- [Laozi](http://ctext.org/dictionary.pl?if=en&id=11602)
|
||||
|
||||
Contents:
|
||||
|
||||
1. [Radical simplicity](#radical-simplicity)
|
||||
1. [Readable source text](#readable-source-text)
|
||||
1. [Minimum viable documentation](#minimum-viable-documentation)
|
||||
1. [Better is better than perfect](#better-is-better-than-perfect)
|
||||
|
||||
## Radical simplicity
|
||||
|
||||
* **Scalability and interoperability** are more important than a menagerie of
|
||||
unessential features. Scale comes from simplicity, speed, and ease.
|
||||
Interoperability comes from unadorned, digestable content.
|
||||
|
||||
* **Fewer distractions** make for better writing and more productive reading.
|
||||
|
||||
* **New features should never interfere with the simplest use case** and should
|
||||
remain invisible to users who don't need them.
|
||||
|
||||
* **This guide is designed for the average engineer** -- the busy,
|
||||
just-want-to-go-back-to-coding engineer. Large and complex documentation is
|
||||
possible but not the primary focus.
|
||||
|
||||
* **Minimizing context switching makes people happier.** Engineers should be
|
||||
able to interact with documentation using the same tools they use to read and
|
||||
write code.
|
||||
|
||||
## Readable source text
|
||||
|
||||
* **Plain text not only suffices, it is superior**. Markdown itself is not
|
||||
essential to this formula, but it is the best and most widely supported
|
||||
solution right now. HTML is generally not encouraged.
|
||||
|
||||
* **Content and presentation should not mingle**. It should always be possible
|
||||
to ditch the renderer and read the essential information at source. Users
|
||||
should never have to touch the presentation layer if they don't want to.
|
||||
|
||||
* **Portability and future-proofing leave room for the unimagined integrations
|
||||
to come**, and are best achieved by keeping the source as human-readable as
|
||||
possible.
|
||||
|
||||
* **Static content is better than dynamic**, because content should not depend
|
||||
on the features of any one server. However, **fresh is better than stale**. We
|
||||
strive to balance these needs.
|
||||
|
||||
## Minimum viable documentation
|
||||
|
||||
* **Docs thrive when they're treated like tests**: a necessary chore one learns
|
||||
to savor because it rewards over time.
|
||||
See [Best Practices](best_practices.md).
|
||||
|
||||
* **Brief and utilitarian is better than long and exhaustive**. The vast
|
||||
majority of users need only a small fraction of the author's total knowledge,
|
||||
but they need it quickly and often.
|
||||
|
||||
## Better is better than perfect
|
||||
|
||||
* **Incremental improvement is better than prolonged debate**. Patience and
|
||||
tolerance of imperfection allow projects to evolve organically.
|
||||
|
||||
* **Don't lick the cookie, pass the plate**. We're drowning in potentially
|
||||
impactful projects. Choose only those you can really handle and release those
|
||||
you can't.
|
||||
|
|
@ -1,420 +0,0 @@
|
|||
# Markdown style guide
|
||||
|
||||
Much of what makes Markdown great is the ability to write plain text, and get
|
||||
great formatted output as a result. To keep the slate clean for the next author,
|
||||
your Markdown should be simple and consistent with the whole corpus wherever
|
||||
possible.
|
||||
|
||||
We seek to balance three goals:
|
||||
|
||||
1. *Source text is readable and portable.*
|
||||
2. *Markdown files are maintainable over time and across teams.*
|
||||
3. *The syntax is simple and easy to remember.*
|
||||
|
||||
Contents:
|
||||
|
||||
1. [Document layout](#document-layout)
|
||||
1. [Character line limit](#character-line-limit)
|
||||
1. [Trailing whitespace](#trailing-whitespace)
|
||||
1. [Headings](#headings)
|
||||
1. [ATX-style headings](#atx-style-headings)
|
||||
1. [Add spacing to headings](#add-spacing-to-headings)
|
||||
1. [Lists](#lists)
|
||||
1. [Use lazy numbering for long lists](#use-lazy-numbering-for-long-lists)
|
||||
1. [Nested list spacing](#nested-list-spacing)
|
||||
1. [Code](#code)
|
||||
1. [Inline](#inline)
|
||||
1. [Codeblocks](#codeblocks)
|
||||
1. [Declare the language](#declare-the-language)
|
||||
1. [Escape newlines](#escape-newlines)
|
||||
1. [Nest codeblocks within lists](#nest-codeblocks-within-lists)
|
||||
1. [Links](#links)
|
||||
1. [Use informative Markdown link titles](#use-informative-markdown-link-titles)
|
||||
1. [Images](#images)
|
||||
1. [Prefer lists to tables](#prefer-lists-to-tables)
|
||||
1. [Strongly prefer Markdown to HTML](#strongly-prefer-markdown-to-html)
|
||||
|
||||
## Document layout
|
||||
|
||||
In general, most documents benefit from some variation of the following layout:
|
||||
|
||||
```markdown
|
||||
# Document Title
|
||||
|
||||
Short introduction.
|
||||
|
||||
[TOC]
|
||||
|
||||
## Topic
|
||||
|
||||
Content.
|
||||
|
||||
## See also
|
||||
|
||||
* https://link-to-more-info
|
||||
```
|
||||
|
||||
1. `# Document Title`: The first heading should be a level one heading, and
|
||||
should ideally be the same or nearly the same as the filename. The first
|
||||
level one heading is used as the page `<title>`.
|
||||
|
||||
1. `author`: *Optional*. If you'd like to claim ownership of the document or
|
||||
if you are very proud of it, add yourself under the title. However,
|
||||
revision history generally suffices.
|
||||
|
||||
1. `Short introduction.` 1-3 sentences providing a high-level overview of the
|
||||
topic. Imagine yourself as a complete newbie, who landed on your "Extending
|
||||
Foo" doc and needs to know the most basic assumptions you take for granted.
|
||||
"What is Foo? Why would I extend it?"
|
||||
|
||||
1. `[TOC]`: if you use hosting that supports table of contents, such as Gitiles,
|
||||
put `[TOC]` after the short introduction. See
|
||||
[`[TOC]` documentation](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Table-of-contents).
|
||||
|
||||
1. `## Topic`: The rest of your headings should start from level 2.
|
||||
|
||||
1. `## See also`: Put miscellaneous links at the bottom for the user who wants
|
||||
to know more or didn't find what she needed.
|
||||
|
||||
## Character line limit
|
||||
|
||||
Obey projects' character line limit wherever possible. Long URLs and tables are
|
||||
the usual suspects when breaking the rule. (Headings also can't be wrapped, but
|
||||
we encourage keeping them short). Otherwise, wrap your text:
|
||||
|
||||
```markdown
|
||||
Lorem ipsum dolor sit amet, nec eius volumus patrioque cu, nec et commodo
|
||||
hendrerit, id nobis saperet fuisset ius.
|
||||
|
||||
* Malorum moderatius vim eu. In vix dico persecuti. Te nam saperet percipitur
|
||||
interesset. See the [foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md).
|
||||
```
|
||||
|
||||
Often, inserting a newline before a long link preserves readability while
|
||||
minimizing the overflow:
|
||||
|
||||
```markdown
|
||||
Lorem ipsum dolor sit amet. See the
|
||||
[foo docs](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md)
|
||||
for details.
|
||||
```
|
||||
|
||||
## Trailing whitespace
|
||||
|
||||
Don't use trailing whitespace, use a trailing backslash.
|
||||
|
||||
The [CommonMark spec](http://spec.commonmark.org/0.20/#hard-line-breaks) decrees
|
||||
that two spaces at the end of a line should insert a `<br />` tag. However, many
|
||||
directories have a trailing whitespace presubmit check in place, and many IDEs
|
||||
will clean it up anyway.
|
||||
|
||||
Best practice is to avoid the need for a `<br />` altogether. Markdown creates
|
||||
paragraph tags for you simply with newlines: get used to that.
|
||||
|
||||
## Headings
|
||||
|
||||
### ATX-style headings
|
||||
|
||||
```markdown
|
||||
## Heading 2
|
||||
```
|
||||
|
||||
Headings with `=` or `-` underlines can be annoying to maintain and don't fit
|
||||
with the rest of the heading syntax. The user has to ask: Does `---` mean H1 or
|
||||
H2?
|
||||
|
||||
```markdown
|
||||
Heading - do you remember what level? DO NOT DO THIS.
|
||||
---------
|
||||
```
|
||||
|
||||
### Add spacing to headings
|
||||
|
||||
Prefer spacing after `#` and newlines before and after:
|
||||
|
||||
```markdown
|
||||
...text before.
|
||||
|
||||
# Heading 1
|
||||
|
||||
Text after...
|
||||
```
|
||||
|
||||
Lack of spacing makes it a little harder to read in source:
|
||||
|
||||
```markdown
|
||||
...text before.
|
||||
|
||||
#Heading 1
|
||||
Text after... DO NOT DO THIS.
|
||||
```
|
||||
|
||||
## Lists
|
||||
|
||||
### Use lazy numbering for long lists
|
||||
|
||||
Markdown is smart enough to let the resulting HTML render your numbered lists
|
||||
correctly. For longer lists that may change, especially long nested lists, use
|
||||
"lazy" numbering:
|
||||
|
||||
```markdown
|
||||
1. Foo.
|
||||
1. Bar.
|
||||
1. Foofoo.
|
||||
1. Barbar.
|
||||
1. Baz.
|
||||
```
|
||||
|
||||
However, if the list is small and you don't anticipate changing it, prefer fully
|
||||
numbered lists, because it's nicer to read in source:
|
||||
|
||||
```markdown
|
||||
1. Foo.
|
||||
2. Bar.
|
||||
3. Baz.
|
||||
```
|
||||
|
||||
### Nested list spacing
|
||||
|
||||
When nesting lists, use a 4 space indent for both numbered and bulleted lists:
|
||||
|
||||
```markdown
|
||||
1. 2 spaces after a numbered list.
|
||||
4 space indent for wrapped text.
|
||||
2. 2 spaces again.
|
||||
|
||||
* 3 spaces after a bullet.
|
||||
4 space indent for wrapped text.
|
||||
1. 2 spaces after a numbered list.
|
||||
8 space indent for the wrapped text of a nested list.
|
||||
2. Looks nice, don't it?
|
||||
* 3 spaces after a bullet.
|
||||
```
|
||||
|
||||
The following works, but it's very messy:
|
||||
|
||||
```markdown
|
||||
* One space,
|
||||
with no indent for wrapped text.
|
||||
1. Irregular nesting... DO NOT DO THIS.
|
||||
```
|
||||
|
||||
Even when there's no nesting, using the 4 space indent makes layout consistent
|
||||
for wrapped text:
|
||||
|
||||
```markdown
|
||||
* Foo,
|
||||
wrapped.
|
||||
|
||||
1. 2 spaces
|
||||
and 4 space indenting.
|
||||
2. 2 spaces again.
|
||||
```
|
||||
|
||||
However, when lists are small, not nested, and a single line, one space can
|
||||
suffice for both kinds of lists:
|
||||
|
||||
```markdown
|
||||
* Foo
|
||||
* Bar
|
||||
* Baz.
|
||||
|
||||
1. Foo.
|
||||
2. Bar.
|
||||
```
|
||||
|
||||
## Code
|
||||
|
||||
### Inline
|
||||
|
||||
`Backticks` designate `inline code`, and will render all wrapped content
|
||||
literally. Use them for short code quotations and field names:
|
||||
|
||||
```markdown
|
||||
You'll want to run `really_cool_script.sh arg`.
|
||||
|
||||
Pay attention to the `foo_bar_whammy` field in that table.
|
||||
```
|
||||
|
||||
Use inline code when referring to file types in an abstract sense, rather than a
|
||||
specific file:
|
||||
|
||||
```markdown
|
||||
Be sure to update your `README.md`!
|
||||
```
|
||||
|
||||
Backticks are the most common approach for "escaping" Markdown metacharacters;
|
||||
in most situations where escaping would be needed, code font just makes sense
|
||||
anyway.
|
||||
|
||||
### Codeblocks
|
||||
|
||||
For code quotations longer than a single line, use a codeblock:
|
||||
|
||||
<pre>
|
||||
```python
|
||||
def Foo(self, bar):
|
||||
self.bar = bar
|
||||
```
|
||||
</pre>
|
||||
|
||||
#### Declare the language
|
||||
|
||||
It is best practice to explicitly declare the language, so that neither the
|
||||
syntax highlighter nor the next editor must guess.
|
||||
|
||||
#### Indented codeblocks are sometimes cleaner
|
||||
|
||||
Four-space indenting is also interpreted as a codeblock. These can look
|
||||
cleaner and be easier to read in source, but there is no way to specify the
|
||||
language. We encourage their use when writing many short snippets:
|
||||
|
||||
```markdown
|
||||
You'll need to run:
|
||||
|
||||
bazel run :thing -- --foo
|
||||
|
||||
And then:
|
||||
|
||||
bazel run :another_thing -- --bar
|
||||
|
||||
And again:
|
||||
|
||||
bazel run :yet_again -- --baz
|
||||
```
|
||||
|
||||
#### Escape newlines
|
||||
|
||||
Because most commandline snippets are intended to be copied and pasted directly
|
||||
into a terminal, it's best practice to escape any newlines. Use a single
|
||||
backslash at the end of the line:
|
||||
|
||||
<pre>
|
||||
```shell
|
||||
bazel run :target -- --flag --foo=longlonglonglonglongvalue \
|
||||
--bar=anotherlonglonglonglonglonglonglonglonglonglongvalue
|
||||
```
|
||||
</pre>
|
||||
|
||||
#### Nest codeblocks within lists
|
||||
|
||||
If you need a codeblock within a list, make sure to indent it so as to not break
|
||||
the list:
|
||||
|
||||
```markdown
|
||||
* Bullet.
|
||||
|
||||
```c++
|
||||
int foo;
|
||||
```
|
||||
|
||||
* Next bullet.
|
||||
```
|
||||
|
||||
You can also create a nested code block with 4 spaces. Simply indent 4
|
||||
additional spaces from the list indentation:
|
||||
|
||||
```markdown
|
||||
* Bullet.
|
||||
|
||||
int foo;
|
||||
|
||||
* Next bullet.
|
||||
```
|
||||
|
||||
## Links
|
||||
|
||||
Long links make source Markdown difficult to read and break the 80 character
|
||||
wrapping. **Wherever possible, shorten your links**.
|
||||
|
||||
### Use informative Markdown link titles
|
||||
|
||||
Markdown link syntax allows you to set a link title, just as HTML does. Use it
|
||||
wisely.
|
||||
|
||||
Titling your links as "link" or "here" tells the reader precisely nothing when
|
||||
quickly scanning your doc and is a waste of space:
|
||||
|
||||
```markdown
|
||||
See the syntax guide for more info: [link](syntax_guide.md).
|
||||
Or, check out the style guide [here](style_guide.md).
|
||||
DO NOT DO THIS.
|
||||
```
|
||||
|
||||
Instead, write the sentence naturally, then go back and wrap the most
|
||||
appropriate phrase with the link:
|
||||
|
||||
```markdown
|
||||
See the [syntax guide](syntax_guide.md) for more info.
|
||||
Or, check out the [style guide](style_guide.md).
|
||||
```
|
||||
|
||||
## Images
|
||||
|
||||
Use images sparingly, and prefer simple screenshots. This guide is designed
|
||||
around the idea that plain text gets users down to the business of communication
|
||||
faster with less reader distraction and author procrastination. However, it's
|
||||
sometimes very helpful to show what you mean.
|
||||
|
||||
See [image syntax](https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Images).
|
||||
|
||||
## Prefer lists to tables
|
||||
|
||||
Any tables in your Markdown should be small. Complex, large tables are difficult
|
||||
to read in source and most importantly, **a pain to modify later**.
|
||||
|
||||
```markdown
|
||||
Fruit | Attribute | Notes
|
||||
--- | --- | --- | ---
|
||||
Apple | [Juicy](http://example.com/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Firm, Sweet | Apples keep doctors away.
|
||||
Banana | [Convenient](http://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Soft, Sweet | Contrary to popular belief, most apes prefer mangoes.
|
||||
|
||||
DO NOT DO THIS
|
||||
```
|
||||
|
||||
[Lists](#lists) and subheadings usually suffice to present the same information
|
||||
in a slightly less compact, though much more edit-friendly way:
|
||||
|
||||
```markdown
|
||||
## Fruits
|
||||
|
||||
### Apple
|
||||
|
||||
* [Juicy](http://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)
|
||||
* Firm
|
||||
* Sweet
|
||||
|
||||
Apples keep doctors away.
|
||||
|
||||
### Banana
|
||||
|
||||
* [Convenient](http://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery)
|
||||
* Soft
|
||||
* Sweet
|
||||
|
||||
Contrary to popular belief, most apes prefer mangoes.
|
||||
```
|
||||
|
||||
However, there are times when a small table is called for:
|
||||
|
||||
```markdown
|
||||
Transport | Favored by | Advantages
|
||||
--- | --- | ---
|
||||
Swallow | Coconuts | Otherwise unladen
|
||||
Bicycle | Miss Gulch | Weatherproof
|
||||
X-34 landspeeder | Whiny farmboys | Cheap since the X-38 came out
|
||||
```
|
||||
|
||||
## Strongly prefer Markdown to HTML
|
||||
|
||||
Please prefer standard Markdown syntax wherever possible and avoid HTML hacks.
|
||||
If you can't seem to accomplish what you want, reconsider whether you really
|
||||
need it. Except for [big tables](#prefer-lists-to-tables), Markdown meets almost
|
||||
all needs already.
|
||||
|
||||
Every bit of HTML or Javascript hacking reduces the readability and portability.
|
||||
This in turn limits the usefulness of integrations with
|
||||
other tools, which may either present the source as plain text or render it. See
|
||||
[Philosophy](philosophy.md).
|
||||
|
||||
Gitiles does not render HTML.
|
||||
|
|
@ -1,167 +0,0 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<profiles version="1">
|
||||
<profile kind="CodeFormatterProfile" name="Google C++" version="1">
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_method_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_for" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_in_empty_block" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.lineSplit" value="80"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.alignment_for_member_access" value="16"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_base_types" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.keep_else_statement_on_same_line" value="false"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.indent_switchstatements_compare_to_switch" value="true"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.alignment_for_constructor_initializer_list" value="83"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_brace_in_array_initializer" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_method_declaration_parameters" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_if" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_parenthesized_expression" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_exception_specification" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_base_types" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.indent_body_declarations_compare_to_access_specifier" value="true"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_exception_specification" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_template_arguments" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_block" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_method_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.use_tabs_only_for_leading_indentations" value="false"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_labeled_statement" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_colon_in_case" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.comment.min_distance_between_code_and_line_comment" value="2"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_array_initializer" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_enum_declarations" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.alignment_for_expressions_in_array_initializer" value="16"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_declarator_list" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_bracket" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_for" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_prefix_operator" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.tabulation.size" value="2"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_else_in_if_statement" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.alignment_for_enumerator_list" value="51"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_parenthesized_expression" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_parens_in_method_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_switch" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.alignment_for_declarator_list" value="16"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_parenthesized_expression" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.indent_empty_lines" value="false"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.indent_switchstatements_compare_to_cases" value="true"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.keep_empty_array_initializer_on_one_line" value="false"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_method_declaration" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.put_empty_statement_on_new_line" value="true"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_switch" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_cast" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_braces_in_array_initializer" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.brace_position_for_method_declaration" value="end_of_line"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_while" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_question_in_conditional" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_semicolon" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_closing_angle_bracket_in_template_arguments" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_base_clause" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.indent_breaks_compare_to_cases" value="true"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_unary_operator" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.join_wrapped_lines" value="true"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_declarator_list" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.alignment_for_arguments_in_method_invocation" value="18"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.comment.never_indent_line_comments_on_first_column" value="true"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_while" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_brackets" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_bracket" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.alignment_for_parameters_in_method_declaration" value="18"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_closing_brace_in_array_initializer" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.number_of_empty_lines_to_preserve" value="1"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_method_invocation" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_brace_in_array_initializer" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_semicolon_in_for" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_conditional" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.brace_position_for_block" value="end_of_line"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.comment.preserve_white_space_between_code_and_line_comments" value="true"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.brace_position_for_type_declaration" value="end_of_line"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_assignment_operator" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_angle_bracket_in_template_arguments" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_expression_list" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_angle_bracket_in_template_parameters" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.continuation_indentation" value="2"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.alignment_for_expression_list" value="0"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_method_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_template_parameters" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_default" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_binary_operator" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.alignment_for_conditional_expression" value="34"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_parens_in_method_invocation" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_array_initializer" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_if" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.format_guardian_clause_on_one_line" value="false"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.indent_access_specifier_extra_spaces" value="1"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_cast" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.indent_access_specifier_compare_to_type_header" value="false"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_type_declaration" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.continuation_indentation_for_array_initializer" value="2"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_colon_in_labeled_statement" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_method_declaration_parameters" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_semicolon_in_for" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_method_invocation" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.indent_body_declarations_compare_to_namespace_header" value="false"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.alignment_for_compact_if" value="0"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_assignment_operator" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_closing_brace_in_block" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_array_initializer" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_at_end_of_file_if_missing" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.alignment_for_assignment" value="16"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.alignment_for_conditional_expression_chain" value="18"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_template_parameters" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_expression_list" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_question_in_conditional" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_exception_specification" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_binary_operator" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_identifier_in_function_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.alignment_for_base_clause_in_type_declaration" value="16"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_method_declaration_throws" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_between_empty_parens_in_exception_specification" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_method_invocation_arguments" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.indent_declaration_compare_to_template_header" value="false"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_unary_operator" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_switch" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.indent_statements_compare_to_body" value="true"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_method_declaration_throws" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.alignment_for_binary_expression" value="16"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.indent_statements_compare_to_block" value="true"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_template_arguments" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_catch_in_try_statement" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.alignment_for_throws_clause_in_method_declaration" value="16"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_method_invocation" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_closing_paren_in_cast" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_paren_in_catch" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_angle_bracket_in_template_parameters" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.tabulation.char" value="space"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_angle_bracket_in_template_parameters" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_colon_in_constructor_initializer_list" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_while" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_comma_in_method_invocation_arguments" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.brace_position_for_block_in_case" value="end_of_line"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.compact_else_if" value="true"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_postfix_operator" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_after_template_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_colon_in_base_clause" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_catch" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.keep_then_statement_on_same_line" value="false"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.brace_position_for_switch" value="end_of_line"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.alignment_for_overloaded_left_shift_chain" value="18"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_if" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_paren_in_switch" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.keep_imple_if_on_one_line" value="false"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_after_opening_brace_in_array_initializer" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.indentation.size" value="2"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.brace_position_for_namespace_declaration" value="end_of_line"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_colon_in_conditional" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_comma_in_enum_declarations" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_prefix_operator" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_angle_bracket_in_template_arguments" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.brace_position_for_array_initializer" value="end_of_line"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_colon_in_case" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_catch" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_brace_in_namespace_declaration" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_postfix_operator" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_closing_bracket" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_new_line_before_while_in_do_statement" value="do not insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_before_opening_paren_in_for" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_closing_angle_bracket_in_template_parameters" value="insert"/>
|
||||
<setting id="org.eclipse.cdt.core.formatter.insert_space_after_opening_angle_bracket_in_template_arguments" value="do not insert"/>
|
||||
</profile>
|
||||
</profiles>
|
||||
|
|
@ -1,337 +0,0 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<profiles version="13">
|
||||
<profile kind="CodeFormatterProfile" name="GoogleStyle" version="13">
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment.insert_new_line_before_root_tags" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.disabling_tag" value="@formatter:off"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_annotation" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_type_parameters" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_type_declaration" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_type_arguments" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_anonymous_type_declaration" value="end_of_line"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_case" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_brace_in_array_initializer" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment.new_lines_at_block_boundaries" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_cascading_method_invocation_with_arguments.count_dependent" value="16|-1|16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_annotation_declaration" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_annotation" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_field" value="0"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_while" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.use_on_off_tags" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.wrap_prefer_two_fragments" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_annotation_type_member_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_else_in_if_statement" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_prefix_operator" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.keep_else_statement_on_same_line" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_ellipsis" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment.insert_new_line_for_parameter" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.wrap_comment_inline_tags" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_annotation_type_declaration" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.indent_breaks_compare_to_cases" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_at_in_annotation" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_local_variable_declaration" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_multiple_fields" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_parameter" value="1040"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_expressions_in_array_initializer" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_type.count_dependent" value="1585|-1|1585"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_conditional_expression" value="80"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_for" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_multiple_fields.count_dependent" value="16|-1|16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_binary_operator" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_question_in_wildcard" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_array_initializer" value="end_of_line"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_enum_constant" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_finally_in_try_statement" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_local_variable" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_catch_in_try_statement" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_while" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.blank_lines_after_package" value="1"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_qualified_allocation_expression.count_dependent" value="16|4|80"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_throws_clause_in_method_declaration.count_dependent" value="16|4|48"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_type_parameters" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.continuation_indentation" value="2"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_superinterfaces_in_enum_declaration.count_dependent" value="16|4|49"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_postfix_operator" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_method_invocation" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_angle_bracket_in_type_arguments" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_superinterfaces" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_new_chunk" value="1"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_binary_operator" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_package" value="0"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_cascading_method_invocation_with_arguments" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.compiler.source" value="1.7"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_throws_clause_in_constructor_declaration.count_dependent" value="16|4|48"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_enum_constant_arguments" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_constructor_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment.format_line_comments" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_closing_angle_bracket_in_type_arguments" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_enum_declarations" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.join_wrapped_lines" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_block" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_explicit_constructor_call" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.wrap_non_simple_local_variable_annotation" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_method_invocation_arguments" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.align_type_members_on_columns" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_member_type" value="0"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_enum_constant" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_enum_constants.count_dependent" value="16|5|48"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_for" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_method_declaration" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_selector_in_method_invocation" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_switch" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_unary_operator" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_case" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment.indent_parameter_description" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_method_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_switch" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_enum_declaration" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_angle_bracket_in_type_parameters" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment.clear_blank_lines_in_block_comment" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_type_declaration" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.lineSplit" value="100"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_if" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_selector_in_method_invocation.count_dependent" value="16|4|48"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_brackets_in_array_type_reference" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_parenthesized_expression" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_explicitconstructorcall_arguments" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_constructor_declaration" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_first_class_body_declaration" value="0"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_method" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.indentation.size" value="4"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_method_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.enabling_tag" value="@formatter:on"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_enum_constant" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_package" value="1585"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_superclass_in_type_declaration" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_assignment" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.compiler.problem.assertIdentifier" value="error"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.tabulation.char" value="space"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_semicolon_in_try_resources" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_constructor_declaration_parameters" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_prefix_operator" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.indent_statements_compare_to_body" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_method" value="1"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.wrap_outer_expressions_when_nested" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.wrap_non_simple_type_annotation" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.format_guardian_clause_on_one_line" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_for" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_field_declaration" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_cast" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_parameters_in_constructor_declaration" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_labeled_statement" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_annotation_type_declaration" value="end_of_line"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_method_body" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_method_declaration" value="0"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_try" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_method_invocation" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_bracket_in_array_allocation_expression" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_enum_constant" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_annotation" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_at_in_annotation_type_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_method_declaration_throws" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_if" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_switch" value="end_of_line"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_method_declaration_throws" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_parenthesized_expression_in_return" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_annotation" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_question_in_conditional" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_question_in_wildcard" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_try" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_bracket_in_array_allocation_expression" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment.preserve_white_space_between_code_and_line_comments" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_parenthesized_expression_in_throw" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_type_arguments" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.compiler.problem.enumIdentifier" value="error"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_generic_type_arguments" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.indent_switchstatements_compare_to_switch" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment_new_line_at_start_of_html_paragraph" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_ellipsis" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_block" value="end_of_line"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comment_prefix" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_for_inits" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_method_declaration" value="end_of_line"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.compact_else_if" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.wrap_non_simple_parameter_annotation" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.wrap_before_or_operator_multicatch" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_array_initializer" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_for_increments" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_method" value="1585"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.format_line_comment_starting_on_first_column" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_bracket_in_array_reference" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_field" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment.indent_root_tags" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_enum_constant" value="end_of_line"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_enum_declarations" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_union_type_in_multicatch" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_explicitconstructorcall_arguments" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_switch" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_method_declaration_parameters" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_superinterfaces" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_allocation_expression" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.tabulation.size" value="2"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_bracket_in_array_type_reference" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_opening_brace_in_array_initializer" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_closing_brace_in_block" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_bracket_in_array_reference" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_enum_constant" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_angle_bracket_in_type_arguments" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_constructor_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_constructor_declaration_throws" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_if" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_method_invocation.count_dependent" value="16|5|80"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment.clear_blank_lines_in_javadoc_comment" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_parameter.count_dependent" value="1040|-1|1040"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_throws_clause_in_constructor_declaration" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_assignment_operator" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_assignment_operator" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_package.count_dependent" value="1585|-1|1585"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.indent_empty_lines" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_synchronized" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_closing_paren_in_cast" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_method_declaration_parameters" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.force_if_else_statement_brace" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_block_in_case" value="end_of_line"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.number_of_empty_lines_to_preserve" value="3"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.wrap_non_simple_package_annotation" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_method_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_catch" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_constructor_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_method_invocation" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_bracket_in_array_reference" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_qualified_allocation_expression" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_annotation.count_dependent" value="16|-1|16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_and_in_type_parameter" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_type" value="1585"/>
|
||||
<setting id="org.eclipse.jdt.core.compiler.compliance" value="1.7"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.continuation_indentation_for_array_initializer" value="2"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_brackets_in_array_allocation_expression" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_at_in_annotation_type_declaration" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_allocation_expression" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_cast" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_unary_operator" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_new_anonymous_class" value="20"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_angle_bracket_in_parameterized_type_reference" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_local_variable.count_dependent" value="1585|-1|1585"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_anonymous_type_declaration" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.keep_empty_array_initializer_on_one_line" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_enum_declaration" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_field.count_dependent" value="1585|-1|1585"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.keep_imple_if_on_one_line" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_constructor_declaration_parameters" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_closing_angle_bracket_in_type_parameters" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_labeled_statement" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_at_end_of_file_if_missing" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_for" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_parameterized_type_reference" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_parameters_in_constructor_declaration.count_dependent" value="16|5|80"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_superinterfaces_in_type_declaration" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_enum_declaration" value="end_of_line"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_binary_expression" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_while" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_type" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode" value="enabled"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_try" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.put_empty_statement_on_new_line" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_label" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_parameter" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_angle_bracket_in_type_parameters" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_method_invocation" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment.format_javadoc_comments" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_enum_constant" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_before_while_in_do_statement" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_enum_constant.count_dependent" value="16|-1|16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment.line_length" value="100"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_after_annotation_on_package" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.blank_lines_between_import_groups" value="1"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_enum_constant_arguments" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_semicolon" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_constructor_declaration" value="end_of_line"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.number_of_blank_lines_at_beginning_of_method_body" value="0"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_conditional" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.indent_body_declarations_compare_to_type_header" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_annotation_type_member_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.wrap_before_binary_operator" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.blank_lines_between_type_declarations" value="2"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.indent_body_declarations_compare_to_enum_declaration_header" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_synchronized" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_superinterfaces_in_enum_declaration" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.indent_statements_compare_to_block" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.join_lines_in_comments" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_question_in_conditional" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_multiple_field_declarations" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_compact_if" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_for_inits" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.indent_switchstatements_compare_to_cases" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_array_initializer" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_default" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_and_in_type_parameter" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_parens_in_constructor_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.blank_lines_before_imports" value="0"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_assert" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_field" value="1585"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment.format_html" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_throws_clause_in_method_declaration" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_angle_bracket_in_type_parameters" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_bracket_in_array_allocation_expression" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_anonymous_type_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_colon_in_conditional" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_angle_bracket_in_parameterized_type_reference" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_for" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_expressions_in_array_initializer.count_dependent" value="16|5|80"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_postfix_operator" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment.format_source_code" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_synchronized" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_allocation_expression" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_constructor_declaration_throws" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_parameters_in_method_declaration" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_brace_in_array_initializer" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.compiler.codegen.targetPlatform" value="1.7"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_resources_in_try" value="80"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.use_tabs_only_for_leading_indentations" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_annotation" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment.format_header" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment.format_block_comments" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_enum_constant" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_enum_constants" value="0"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_parenthesized_expression" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.indent_body_declarations_compare_to_annotation_declaration_header" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_new_line_in_empty_block" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_parenthesized_expression" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_catch" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_multiple_local_declarations" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_superinterfaces_in_type_declaration.count_dependent" value="16|4|48"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_switch" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_comma_in_for_increments" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_method.count_dependent" value="1585|-1|1585"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_method_invocation" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_colon_in_assert" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.brace_position_for_type_declaration" value="end_of_line"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_brace_in_array_initializer" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_between_empty_braces_in_array_initializer" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_binary_expression.count_dependent" value="16|-1|16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.wrap_non_simple_member_annotation" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_annotations_on_local_variable" value="1585"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_opening_paren_in_method_declaration" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_semicolon_in_for" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_explicit_constructor_call.count_dependent" value="16|5|80"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_paren_in_catch" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_angle_bracket_in_parameterized_type_reference" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_multiple_field_declarations" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_closing_paren_in_annotation" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_generic_type_arguments.count_dependent" value="16|-1|16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_parameterized_type_reference" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_arguments_in_allocation_expression.count_dependent" value="16|5|80"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_method_invocation_arguments" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_parameters_in_method_declaration.count_dependent" value="16|5|80"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.comment.new_lines_at_javadoc_boundaries" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.blank_lines_after_imports" value="1"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_comma_in_multiple_local_declarations" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.indent_body_declarations_compare_to_enum_constant_header" value="true"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_after_semicolon_in_for" value="insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.never_indent_line_comments_on_first_column" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_semicolon_in_try_resources" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.alignment_for_for_statement" value="16"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.insert_space_before_opening_angle_bracket_in_type_arguments" value="do not insert"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.never_indent_block_comments_on_first_column" value="false"/>
|
||||
<setting id="org.eclipse.jdt.core.formatter.keep_then_statement_on_same_line" value="false"/>
|
||||
</profile>
|
||||
</profiles>
|
||||
|
|
@ -1,151 +0,0 @@
|
|||
;;; google-c-style.el --- Google's C/C++ style for c-mode
|
||||
|
||||
;; Keywords: c, tools
|
||||
|
||||
;; google-c-style.el is Copyright (C) 2008 Google Inc. All Rights Reserved.
|
||||
;;
|
||||
;; It is free software; you can redistribute it and/or modify it under the
|
||||
;; terms of either:
|
||||
;;
|
||||
;; a) the GNU General Public License as published by the Free Software
|
||||
;; Foundation; either version 1, or (at your option) any later version, or
|
||||
;;
|
||||
;; b) the "Artistic License".
|
||||
|
||||
;;; Commentary:
|
||||
|
||||
;; Provides the google C/C++ coding style. You may wish to add
|
||||
;; `google-set-c-style' to your `c-mode-common-hook' after requiring this
|
||||
;; file. For example:
|
||||
;;
|
||||
;; (add-hook 'c-mode-common-hook 'google-set-c-style)
|
||||
;;
|
||||
;; If you want the RETURN key to go to the next line and space over
|
||||
;; to the right place, add this to your .emacs right after the load-file:
|
||||
;;
|
||||
;; (add-hook 'c-mode-common-hook 'google-make-newline-indent)
|
||||
|
||||
;;; Code:
|
||||
|
||||
;; For some reason 1) c-backward-syntactic-ws is a macro and 2) under Emacs 22
|
||||
;; bytecode cannot call (unexpanded) macros at run time:
|
||||
(eval-when-compile (require 'cc-defs))
|
||||
|
||||
;; Wrapper function needed for Emacs 21 and XEmacs (Emacs 22 offers the more
|
||||
;; elegant solution of composing a list of lineup functions or quantities with
|
||||
;; operators such as "add")
|
||||
(defun google-c-lineup-expression-plus-4 (langelem)
|
||||
"Indents to the beginning of the current C expression plus 4 spaces.
|
||||
|
||||
This implements title \"Function Declarations and Definitions\"
|
||||
of the Google C++ Style Guide for the case where the previous
|
||||
line ends with an open parenthese.
|
||||
|
||||
\"Current C expression\", as per the Google Style Guide and as
|
||||
clarified by subsequent discussions, means the whole expression
|
||||
regardless of the number of nested parentheses, but excluding
|
||||
non-expression material such as \"if(\" and \"for(\" control
|
||||
structures.
|
||||
|
||||
Suitable for inclusion in `c-offsets-alist'."
|
||||
(save-excursion
|
||||
(back-to-indentation)
|
||||
;; Go to beginning of *previous* line:
|
||||
(c-backward-syntactic-ws)
|
||||
(back-to-indentation)
|
||||
(cond
|
||||
;; We are making a reasonable assumption that if there is a control
|
||||
;; structure to indent past, it has to be at the beginning of the line.
|
||||
((looking-at "\\(\\(if\\|for\\|while\\)\\s *(\\)")
|
||||
(goto-char (match-end 1)))
|
||||
;; For constructor initializer lists, the reference point for line-up is
|
||||
;; the token after the initial colon.
|
||||
((looking-at ":\\s *")
|
||||
(goto-char (match-end 0))))
|
||||
(vector (+ 4 (current-column)))))
|
||||
|
||||
;;;###autoload
|
||||
(defconst google-c-style
|
||||
`((c-recognize-knr-p . nil)
|
||||
(c-enable-xemacs-performance-kludge-p . t) ; speed up indentation in XEmacs
|
||||
(c-basic-offset . 2)
|
||||
(indent-tabs-mode . nil)
|
||||
(c-comment-only-line-offset . 0)
|
||||
(c-hanging-braces-alist . ((defun-open after)
|
||||
(defun-close before after)
|
||||
(class-open after)
|
||||
(class-close before after)
|
||||
(inexpr-class-open after)
|
||||
(inexpr-class-close before)
|
||||
(namespace-open after)
|
||||
(inline-open after)
|
||||
(inline-close before after)
|
||||
(block-open after)
|
||||
(block-close . c-snug-do-while)
|
||||
(extern-lang-open after)
|
||||
(extern-lang-close after)
|
||||
(statement-case-open after)
|
||||
(substatement-open after)))
|
||||
(c-hanging-colons-alist . ((case-label)
|
||||
(label after)
|
||||
(access-label after)
|
||||
(member-init-intro before)
|
||||
(inher-intro)))
|
||||
(c-hanging-semi&comma-criteria
|
||||
. (c-semi&comma-no-newlines-for-oneline-inliners
|
||||
c-semi&comma-inside-parenlist
|
||||
c-semi&comma-no-newlines-before-nonblanks))
|
||||
(c-indent-comments-syntactically-p . t)
|
||||
(comment-column . 40)
|
||||
(c-indent-comment-alist . ((other . (space . 2))))
|
||||
(c-cleanup-list . (brace-else-brace
|
||||
brace-elseif-brace
|
||||
brace-catch-brace
|
||||
empty-defun-braces
|
||||
defun-close-semi
|
||||
list-close-comma
|
||||
scope-operator))
|
||||
(c-offsets-alist . ((arglist-intro google-c-lineup-expression-plus-4)
|
||||
(func-decl-cont . ++)
|
||||
(member-init-intro . ++)
|
||||
(inher-intro . ++)
|
||||
(comment-intro . 0)
|
||||
(arglist-close . c-lineup-arglist)
|
||||
(topmost-intro . 0)
|
||||
(block-open . 0)
|
||||
(inline-open . 0)
|
||||
(substatement-open . 0)
|
||||
(statement-cont
|
||||
.
|
||||
(,(when (fboundp 'c-no-indent-after-java-annotations)
|
||||
'c-no-indent-after-java-annotations)
|
||||
,(when (fboundp 'c-lineup-assignments)
|
||||
'c-lineup-assignments)
|
||||
++))
|
||||
(label . /)
|
||||
(case-label . +)
|
||||
(statement-case-open . +)
|
||||
(statement-case-intro . +) ; case w/o {
|
||||
(access-label . /)
|
||||
(innamespace . 0))))
|
||||
"Google C/C++ Programming Style.")
|
||||
|
||||
;;;###autoload
|
||||
(defun google-set-c-style ()
|
||||
"Set the current buffer's c-style to Google C/C++ Programming
|
||||
Style. Meant to be added to `c-mode-common-hook'."
|
||||
(interactive)
|
||||
(make-local-variable 'c-tab-always-indent)
|
||||
(setq c-tab-always-indent t)
|
||||
(c-add-style "Google" google-c-style t))
|
||||
|
||||
;;;###autoload
|
||||
(defun google-make-newline-indent ()
|
||||
"Sets up preferred newline behavior. Not set by default. Meant
|
||||
to be added to `c-mode-common-hook'."
|
||||
(interactive)
|
||||
(define-key c-mode-base-map "\C-m" 'newline-and-indent)
|
||||
(define-key c-mode-base-map [ret] 'newline-and-indent))
|
||||
|
||||
(provide 'google-c-style)
|
||||
;;; google-c-style.el ends here
|
||||
|
|
@ -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>
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
" Indent Python in the Google way.
|
||||
|
||||
setlocal indentexpr=GetGooglePythonIndent(v:lnum)
|
||||
|
||||
let s:maxoff = 50 " maximum number of lines to look backwards.
|
||||
|
||||
function GetGooglePythonIndent(lnum)
|
||||
|
||||
" Indent inside parens.
|
||||
" Align with the open paren unless it is at the end of the line.
|
||||
" E.g.
|
||||
" open_paren_not_at_EOL(100,
|
||||
" (200,
|
||||
" 300),
|
||||
" 400)
|
||||
" open_paren_at_EOL(
|
||||
" 100, 200, 300, 400)
|
||||
call cursor(a:lnum, 1)
|
||||
let [par_line, par_col] = searchpairpos('(\|{\|\[', '', ')\|}\|\]', 'bW',
|
||||
\ "line('.') < " . (a:lnum - s:maxoff) . " ? dummy :"
|
||||
\ . " synIDattr(synID(line('.'), col('.'), 1), 'name')"
|
||||
\ . " =~ '\\(Comment\\|String\\)$'")
|
||||
if par_line > 0
|
||||
call cursor(par_line, 1)
|
||||
if par_col != col("$") - 1
|
||||
return par_col
|
||||
endif
|
||||
endif
|
||||
|
||||
" Delegate the rest to the original function.
|
||||
return GetPythonIndent(a:lnum)
|
||||
|
||||
endfunction
|
||||
|
||||
let pyindent_nested_paren="&sw*2"
|
||||
let pyindent_open_paren="&sw*2"
|
||||
1117
htmlcssguide.xml
1117
htmlcssguide.xml
File diff suppressed because it is too large
Load Diff
BIN
include/link.png
BIN
include/link.png
Binary file not shown.
|
Before Width: | Height: | Size: 189 B |
|
|
@ -1,261 +0,0 @@
|
|||
/* General CSS */
|
||||
|
||||
body {
|
||||
background-color: #fff;
|
||||
color: #333;
|
||||
font-family: sans-serif;
|
||||
font-size: 10pt;
|
||||
margin-right: 100px;
|
||||
margin-left: 100px;
|
||||
}
|
||||
|
||||
h1 {
|
||||
text-align: center;
|
||||
font-size: 18pt;
|
||||
}
|
||||
|
||||
h1, h2, h3, h4, h5, h6 {
|
||||
color: #06c;
|
||||
margin-top: 2em;
|
||||
margin-bottom: 1em;
|
||||
padding: 25px;
|
||||
font-weight:bold;
|
||||
}
|
||||
|
||||
h2,
|
||||
h3,
|
||||
h4,
|
||||
h5,
|
||||
h6 {
|
||||
margin-top:1.5em;
|
||||
margin-bottom:.75em;
|
||||
}
|
||||
|
||||
h1 {font-size:200%;}
|
||||
h2 {font-size:167%;}
|
||||
h3 {font-size:133%;}
|
||||
h4 {font-size:120%;}
|
||||
h5 {font-size:110%;}
|
||||
|
||||
|
||||
table {
|
||||
border: 1px solid #bbb;
|
||||
border-spacing: 0;
|
||||
border-collapse: collapse;
|
||||
margin: 0 0 1.5em;
|
||||
vertical-align: middle;
|
||||
width: 100%
|
||||
}
|
||||
|
||||
td, th {
|
||||
border: 1px solid #ccc;
|
||||
padding: 2px 12px;
|
||||
font-size: 10pt;
|
||||
}
|
||||
|
||||
code, samp, var {
|
||||
background-color:#FAFAFA;
|
||||
white-space: nowrap
|
||||
}
|
||||
|
||||
pre {
|
||||
padding:6px 10px;
|
||||
background-color:#FAFAFA;
|
||||
border:1px solid #bbb;
|
||||
overflow:auto;
|
||||
}
|
||||
|
||||
pre.prettyprint {
|
||||
padding:6px 10px !important;
|
||||
border:1px solid #bbb !important;
|
||||
}
|
||||
|
||||
code.bad, code.badcode {
|
||||
color: magenta;
|
||||
}
|
||||
|
||||
pre.bad, pre.badcode {
|
||||
background-color:#ffe6d8;
|
||||
border-top:1px inset #a03;
|
||||
border-left:1px inset #a03;
|
||||
}
|
||||
|
||||
hr {
|
||||
margin-top: 3.5em;
|
||||
border-width: 1px;
|
||||
color: #fff;
|
||||
}
|
||||
|
||||
/* TOC CSS */
|
||||
|
||||
table.columns {
|
||||
border: none;
|
||||
}
|
||||
|
||||
td.two_columns {
|
||||
-webkit-column-count: 2;
|
||||
column-count: 2;
|
||||
}
|
||||
|
||||
.toc_category {
|
||||
font-size: 10pt;
|
||||
padding-top: 1em;
|
||||
padding-bottom: 1em;
|
||||
border-left-width: 2px;
|
||||
border-right-width: 2px;
|
||||
border-color: grey;
|
||||
}
|
||||
|
||||
.toc_stylepoint {
|
||||
font-size: 10pt;
|
||||
padding-top: 1em;
|
||||
padding-bottom: 1em;
|
||||
}
|
||||
|
||||
li.toc_entry {
|
||||
padding-right: 1em;
|
||||
display: inline;
|
||||
list-style-type: none;
|
||||
}
|
||||
|
||||
/*
|
||||
* This space is required to trigger the linewrap on the links
|
||||
* at href boundaries
|
||||
*/
|
||||
li.toc_entry::after {
|
||||
content: " ";
|
||||
}
|
||||
|
||||
li.toc_entry a {
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
/* Horizontal TOC */
|
||||
.toc td, .toc th {
|
||||
border-width: 1px 5px;
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
/* Vertical TOC */
|
||||
|
||||
.toc td.two_columns {
|
||||
border-width: 0px;
|
||||
}
|
||||
|
||||
/* Special Sections */
|
||||
|
||||
address {
|
||||
text-align: right;
|
||||
}
|
||||
|
||||
.revision {
|
||||
text-align: right;
|
||||
}
|
||||
|
||||
.headerbox {
|
||||
margin-left: 50%;
|
||||
font-size: 75%;
|
||||
}
|
||||
|
||||
.legend {
|
||||
padding-top: 1em;
|
||||
margin-left: 50%;
|
||||
font-size: 10pt;
|
||||
}
|
||||
|
||||
.link_button {
|
||||
float: left;
|
||||
display: none;
|
||||
background-color: #f8f8ff;
|
||||
border-color: #f0f0ff;
|
||||
border-style: solid;
|
||||
border-width: 1px;
|
||||
font-size: 75%;
|
||||
margin-top: 0;
|
||||
margin-left: -50px;
|
||||
padding: 24px;
|
||||
border-radius: 3px;
|
||||
-webkit-border-radius: 3px;
|
||||
-moz-border-radius: 3px;
|
||||
}
|
||||
|
||||
.ignoreLink {
|
||||
padding: 0px;
|
||||
}
|
||||
|
||||
.divider{
|
||||
width:5px;
|
||||
height:auto;
|
||||
display:inline-block;
|
||||
}
|
||||
|
||||
/* Style Guide semantic CSS */
|
||||
|
||||
.summary {
|
||||
margin-top: 1em;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
||||
.stylebody {
|
||||
margin-top: 1em;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
||||
.stylepoint_section {
|
||||
display: block;
|
||||
margin-bottom: 1em;
|
||||
font-family: sans-serif;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.stylepoint_subsection {
|
||||
display: block;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
||||
.stylepoint_subsubsection {
|
||||
display: block;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
||||
.definition:before {
|
||||
content: "Definition: ";
|
||||
font-weight: bold;
|
||||
display: block;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
||||
.pros:before {
|
||||
content: "Pros: ";
|
||||
font-weight: bold;
|
||||
display: block;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
||||
.cons:before {
|
||||
content: "Cons: ";
|
||||
font-weight: bold;
|
||||
display: block;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
||||
.decision:before {
|
||||
content: "Decision: ";
|
||||
font-weight: bold;
|
||||
display: block;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
||||
.exception:before {
|
||||
content: "Exception: ";
|
||||
font-weight: bold;
|
||||
display: block;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
||||
.note:before {
|
||||
content: "Note: ";
|
||||
font-weight: bold;
|
||||
display: block;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
|
@ -1,289 +0,0 @@
|
|||
TocTypeEnum = {
|
||||
VERTICAL: 1,
|
||||
HORIZONTAL: 2
|
||||
};
|
||||
|
||||
function CreateTOC(tocElement) {
|
||||
|
||||
// Find the toc element DIV. We'll place our TOC there.
|
||||
var toc = document.getElementById(tocElement);
|
||||
|
||||
var tocTypeClass = toc.className;
|
||||
var tocType;
|
||||
|
||||
switch (tocTypeClass) {
|
||||
case 'horizontal_toc':
|
||||
tocType = TocTypeEnum.HORIZONTAL;
|
||||
break;
|
||||
case 'vertical_toc':
|
||||
tocType = TocTypeEnum.VERTICAL;
|
||||
break;
|
||||
default:
|
||||
tocType = TocTypeEnum.VERTICAL;
|
||||
break;
|
||||
}
|
||||
|
||||
// If toc_levels is defined, set headingLevels to it.
|
||||
// Otherwise, use default value of "h2,h3"
|
||||
var headingLevels;
|
||||
if (typeof toc_levels === 'undefined') {
|
||||
headingLevels = 'h2,h3';
|
||||
} else {
|
||||
|
||||
}
|
||||
|
||||
// Collect all section heading elements in an array
|
||||
var headings = document.querySelectorAll(headingLevels);
|
||||
|
||||
// Add TOC title elements
|
||||
var tocHeadingDiv = document.createElement('div');
|
||||
toc.appendChild(tocHeadingDiv);
|
||||
tocHeadingDiv.className = 'toc_title';
|
||||
var tocHeading = document.createElement('h3');
|
||||
toc.appendChild(tocHeading);
|
||||
tocHeading.className = 'ignoreLink';
|
||||
tocHeading.id = 'toc';
|
||||
var tocText = document.createTextNode('Table of Contents');
|
||||
tocHeading.appendChild(tocText);
|
||||
|
||||
// Add table and tbody
|
||||
var tocTable = document.createElement('table');
|
||||
if (tocType == TocTypeEnum.VERTICAL) {
|
||||
tocTable.className = 'columns';
|
||||
}
|
||||
toc.appendChild(tocTable);
|
||||
|
||||
var tbody_element = document.createElement('tbody');
|
||||
tbody_element.setAttribute('valign', 'top');
|
||||
tbody_element.className = 'toc';
|
||||
tocTable.appendChild(tbody_element);
|
||||
|
||||
// Get the highest level heading
|
||||
var firstHeading = headings[0];
|
||||
var masterLevel = parseInt(headingLevels.charAt(1));
|
||||
|
||||
// Get the lowest heading level
|
||||
var lowestLevel = parseInt(headingLevels.charAt(headingLevels - 1));
|
||||
|
||||
switch (tocType) {
|
||||
case TocTypeEnum.HORIZONTAL:
|
||||
CreateHorizontalTOC(headings, masterLevel, lowestLevel, tbody_element);
|
||||
break;
|
||||
case TocTypeEnum.VERTICAL:
|
||||
CreateVerticalTOC(headings, masterLevel, lowestLevel, tbody_element);
|
||||
break;
|
||||
default:
|
||||
}
|
||||
}
|
||||
|
||||
function CreateHorizontalTOC(
|
||||
headings, masterLevel, lowestLevel, tbody_element) {
|
||||
|
||||
// Initialize the header counter
|
||||
var h = 0;
|
||||
var ignoreChildren = false;
|
||||
|
||||
while (h < headings.length) {
|
||||
// Get current heading
|
||||
var heading = headings[h];
|
||||
|
||||
// Get the current heading level
|
||||
var level = parseInt(heading.tagName.charAt(1));
|
||||
|
||||
if (isNaN(level) || level < 1 || level > lowestLevel) continue;
|
||||
|
||||
// If level is a masterLevel, make it a TOC parent category
|
||||
if ((level == masterLevel) && (!hasClass(heading, 'ignoreLink'))) {
|
||||
toc_current_row = AddTOCMaster(tbody_element, heading);
|
||||
ignoreChildren = false;
|
||||
}
|
||||
|
||||
if ((level == masterLevel) && (hasClass(heading, 'ignoreLink'))) {
|
||||
ignoreChildren = true;
|
||||
}
|
||||
|
||||
if ((level != masterLevel) && (!ignoreChildren)) {
|
||||
AddTOCElements(toc_current_row, heading);
|
||||
}
|
||||
|
||||
// Advance the header counter
|
||||
h++;
|
||||
}
|
||||
}
|
||||
|
||||
// Adds a master Table of Content heading
|
||||
function AddTOCMaster(tocTable, heading) {
|
||||
|
||||
// Add the table row scaffolding
|
||||
var toc_tr = document.createElement('tr');
|
||||
tocTable.appendChild(toc_tr);
|
||||
toc_tr.setAttribute('valign', 'top');
|
||||
var toc_tr_td = document.createElement('td');
|
||||
toc_tr.appendChild(toc_tr_td);
|
||||
var toc_category = document.createElement('div');
|
||||
toc_tr_td.appendChild(toc_category);
|
||||
toc_category.className = 'toc_category';
|
||||
|
||||
// Create the link to this header
|
||||
var link = document.createElement('a');
|
||||
link.href = '#' + heading.id; // Create the anchor link
|
||||
link.textContent = heading.textContent; // Link text is same as heading
|
||||
toc_category.appendChild(link);
|
||||
|
||||
// Add the container table cell for its children
|
||||
var toc_td = document.createElement('td');
|
||||
toc_tr.appendChild(toc_td);
|
||||
var toc_td_div = document.createElement('div');
|
||||
toc_td_div.className = 'toc_stylepoint';
|
||||
toc_td.appendChild(toc_td_div);
|
||||
|
||||
return (toc_td_div);
|
||||
}
|
||||
|
||||
// Adds Table of Contents element to a master heading as children
|
||||
function AddTOCElements(toc_div, heading) {
|
||||
|
||||
if (heading.offsetParent === null) {
|
||||
// The element is currently hidden, so don't create a TOC entry
|
||||
} else {
|
||||
// Create the list item element
|
||||
var toc_list_element = document.createElement('li');
|
||||
toc_list_element.className = 'toc_entry';
|
||||
toc_div.appendChild(toc_list_element);
|
||||
|
||||
// Create the link to this header
|
||||
var link = document.createElement('a');
|
||||
link.href = '#' + heading.id; // Create the anchor link
|
||||
link.textContent = heading.textContent; // Link text is same as heading
|
||||
toc_list_element.appendChild(link);
|
||||
}
|
||||
}
|
||||
|
||||
function CreateVerticalTOC(headings, masterLevel, lowestLevel, tbody_element) {
|
||||
|
||||
// Create the Column scaffolding
|
||||
var toc_tr = document.createElement('tr');
|
||||
tbody_element.appendChild(toc_tr);
|
||||
var toc_tr_td = document.createElement('td');
|
||||
toc_tr_td.className = 'two_columns';
|
||||
toc_tr.appendChild(toc_tr_td);
|
||||
|
||||
|
||||
// Initialize the header counter and the current row
|
||||
var h = 0;
|
||||
var toc_current_col = null;
|
||||
var ignoreChildren = false;
|
||||
|
||||
while (h < headings.length) {
|
||||
// Get current heading
|
||||
var heading = headings[h];
|
||||
|
||||
// Get the current heading level
|
||||
var level = parseInt(heading.tagName.charAt(1));
|
||||
|
||||
if (isNaN(level) || level < 1 || level > lowestLevel) continue;
|
||||
|
||||
// If level is a masterLevel, make it a TOC parent category
|
||||
if ((level == masterLevel) && (!hasClass(heading, 'ignoreLink'))) {
|
||||
if (heading.offsetParent === null) {
|
||||
// The element is currently hidden, so don't create a TOC entry
|
||||
} else {
|
||||
var td_dl = document.createElement('dl');
|
||||
toc_tr_td.appendChild(td_dl);
|
||||
var td_dt = document.createElement('dt');
|
||||
td_dl.appendChild(td_dt);
|
||||
toc_current_col = td_dl;
|
||||
|
||||
// Create the link to this header
|
||||
var link = document.createElement('a');
|
||||
link.href = '#' + heading.id; // Create the anchor link
|
||||
link.textContent = heading.textContent; // Link text is same as heading
|
||||
td_dt.appendChild(link);
|
||||
ignoreChildren = false;
|
||||
}
|
||||
}
|
||||
|
||||
// If level is a masterLevel but it's specified to ignore links, skip it
|
||||
// and its children.
|
||||
if ((level == masterLevel) && (hasClass(heading, 'ignoreLink'))) {
|
||||
ignoreChildren = true;
|
||||
}
|
||||
|
||||
if ((level != masterLevel) && (!ignoreChildren)) {
|
||||
if (heading.offsetParent === null) {
|
||||
// The element is currently hidden, so don't create a TOC entry
|
||||
} else {
|
||||
var td_dd = document.createElement('dd');
|
||||
toc_current_col.appendChild(td_dd);
|
||||
// Create the link to this header
|
||||
var link = document.createElement('a');
|
||||
link.href = '#' + heading.id; // Create the anchor link
|
||||
link.textContent = heading.textContent; // Link text is same as heading
|
||||
td_dd.appendChild(link);
|
||||
}
|
||||
}
|
||||
|
||||
// Advance the header counter
|
||||
h++;
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
* Utility function for finding elements with a given
|
||||
* class.
|
||||
*/
|
||||
function hasClass(element, cls) {
|
||||
return (' ' + element.className + ' ').indexOf(' ' + cls + ' ') > -1;
|
||||
}
|
||||
|
||||
/*
|
||||
* Linkify all h2 through h4 headers, except for those marked
|
||||
* "ignoreLink"
|
||||
*/
|
||||
|
||||
// Add the link image to the element.
|
||||
function LinkifyHeader(header, fileName, sizePixels) {
|
||||
var link = document.createElement('a');
|
||||
link.href = '#' + header.id;
|
||||
link.alt = 'link to ' + header.id;
|
||||
link.innerHTML =
|
||||
'<img src="include/' + fileName + '"' +
|
||||
' width=' + sizePixels +
|
||||
' height=' + sizePixels +
|
||||
' style="float:left;position:relative;bottom:5px;">';
|
||||
header.appendChild(link);
|
||||
}
|
||||
|
||||
// Find all elements of the given tag and linkify if
|
||||
// they don't have 'ignoreLink' in their class.
|
||||
function LinkifyHeadersForTag(tagName) {
|
||||
var headers = document.getElementsByTagName(tagName);
|
||||
var header;
|
||||
for (var j = 0; j != headers.length; j++) {
|
||||
header = headers[j];
|
||||
if (!hasClass(header, 'ignoreLink') && ('id' in header)) {
|
||||
if (header.id != '') {
|
||||
LinkifyHeader(header, 'link.png', 21);
|
||||
header.style.left = '-46px';
|
||||
header.style.position = 'relative';
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Linkify all h2, h3, and h4s. h1s are titles.
|
||||
function LinkifyHeaders() {
|
||||
LinkifyHeadersForTag('h2');
|
||||
LinkifyHeadersForTag('h3');
|
||||
LinkifyHeadersForTag('h4');
|
||||
}
|
||||
|
||||
/*
|
||||
* Initialize the style guide by showing all internal
|
||||
* elements and then linkifying the headers.
|
||||
*/
|
||||
|
||||
function initStyleGuide() {
|
||||
LinkifyHeaders();
|
||||
CreateTOC('tocDiv');
|
||||
}
|
||||
|
|
@ -1,476 +0,0 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<code_scheme name="GoogleStyle">
|
||||
<option name="JAVA_INDENT_OPTIONS">
|
||||
<value>
|
||||
<option name="INDENT_SIZE" value="2" />
|
||||
<option name="CONTINUATION_INDENT_SIZE" value="4" />
|
||||
<option name="TAB_SIZE" value="8" />
|
||||
<option name="USE_TAB_CHARACTER" value="false" />
|
||||
<option name="SMART_TABS" value="false" />
|
||||
<option name="LABEL_INDENT_SIZE" value="0" />
|
||||
<option name="LABEL_INDENT_ABSOLUTE" value="false" />
|
||||
<option name="USE_RELATIVE_INDENTS" value="false" />
|
||||
</value>
|
||||
</option>
|
||||
<option name="CLASS_COUNT_TO_USE_IMPORT_ON_DEMAND" value="99" />
|
||||
<option name="NAMES_COUNT_TO_USE_IMPORT_ON_DEMAND" value="99" />
|
||||
<option name="IMPORT_LAYOUT_TABLE">
|
||||
<value>
|
||||
<package name="com.google" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="android" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="antenna" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="antlr" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="ar" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="asposewobfuscated" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="asquare" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="atg" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="au" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="beaver" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="bibtex" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="bmsi" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="bsh" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="ccl" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="cern" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="ChartDirector" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="checkers" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="com" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="COM" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="common" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="contribs" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="corejava" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="cryptix" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="cybervillains" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="dalvik" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="danbikel" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="de" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="EDU" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="eg" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="eu" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="examples" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="fat" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="fit" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="fitlibrary" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="fmpp" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="freemarker" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="gnu" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="groovy" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="groovyjarjarantlr" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="groovyjarjarasm" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="hak" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="hep" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="ie" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="imageinfo" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="info" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="it" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="jal" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="Jama" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="japa" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="japacheckers" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="jas" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="jasmin" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="javancss" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="javanet" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="javassist" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="javazoom" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="java_cup" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="jcifs" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="jetty" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="JFlex" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="jj2000" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="jline" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="jp" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="JSci" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="jsr166y" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="junit" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="jxl" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="jxxload_help" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="kawa" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="kea" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="libcore" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="libsvm" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="lti" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="memetic" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="mt" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="mx4j" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="net" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="netscape" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="nl" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="nu" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="oauth" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="ognl" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="opennlp" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="oracle" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="org" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="penn2dg" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="pennconverter" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="pl" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="prefuse" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="proguard" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="repackage" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="scm" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="se" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="serp" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="simple" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="soot" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="sqlj" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="src" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="ssa" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="sun" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="sunlabs" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="tcl" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="testdata" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="testshell" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="testsuite" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="twitter4j" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="uk" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="ViolinStrings" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="weka" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="wet" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="winstone" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="woolfel" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="wowza" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="java" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="javax" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="" withSubpackages="true" static="false" />
|
||||
<emptyLine />
|
||||
<package name="" withSubpackages="true" static="true" />
|
||||
</value>
|
||||
</option>
|
||||
<option name="RIGHT_MARGIN" value="100" />
|
||||
<option name="JD_P_AT_EMPTY_LINES" value="false" />
|
||||
<option name="JD_KEEP_EMPTY_PARAMETER" value="false" />
|
||||
<option name="JD_KEEP_EMPTY_EXCEPTION" value="false" />
|
||||
<option name="JD_KEEP_EMPTY_RETURN" value="false" />
|
||||
<option name="KEEP_CONTROL_STATEMENT_IN_ONE_LINE" value="false" />
|
||||
<option name="KEEP_BLANK_LINES_IN_CODE" value="1" />
|
||||
<option name="BLANK_LINES_AFTER_CLASS_HEADER" value="1" />
|
||||
<option name="ALIGN_MULTILINE_PARAMETERS_IN_CALLS" value="true" />
|
||||
<option name="ALIGN_MULTILINE_BINARY_OPERATION" value="true" />
|
||||
<option name="ALIGN_MULTILINE_ASSIGNMENT" value="true" />
|
||||
<option name="ALIGN_MULTILINE_TERNARY_OPERATION" value="true" />
|
||||
<option name="ALIGN_MULTILINE_THROWS_LIST" value="true" />
|
||||
<option name="ALIGN_MULTILINE_EXTENDS_LIST" value="true" />
|
||||
<option name="ALIGN_MULTILINE_PARENTHESIZED_EXPRESSION" value="true" />
|
||||
<option name="ALIGN_MULTILINE_ARRAY_INITIALIZER_EXPRESSION" value="true" />
|
||||
<option name="CALL_PARAMETERS_WRAP" value="1" />
|
||||
<option name="METHOD_PARAMETERS_WRAP" value="1" />
|
||||
<option name="EXTENDS_LIST_WRAP" value="1" />
|
||||
<option name="THROWS_LIST_WRAP" value="1" />
|
||||
<option name="EXTENDS_KEYWORD_WRAP" value="1" />
|
||||
<option name="THROWS_KEYWORD_WRAP" value="1" />
|
||||
<option name="METHOD_CALL_CHAIN_WRAP" value="1" />
|
||||
<option name="BINARY_OPERATION_WRAP" value="1" />
|
||||
<option name="BINARY_OPERATION_SIGN_ON_NEXT_LINE" value="true" />
|
||||
<option name="TERNARY_OPERATION_WRAP" value="1" />
|
||||
<option name="TERNARY_OPERATION_SIGNS_ON_NEXT_LINE" value="true" />
|
||||
<option name="FOR_STATEMENT_WRAP" value="1" />
|
||||
<option name="ARRAY_INITIALIZER_WRAP" value="1" />
|
||||
<option name="ASSIGNMENT_WRAP" value="5" />
|
||||
<option name="WRAP_COMMENTS" value="true" />
|
||||
<option name="IF_BRACE_FORCE" value="3" />
|
||||
<option name="DOWHILE_BRACE_FORCE" value="3" />
|
||||
<option name="WHILE_BRACE_FORCE" value="3" />
|
||||
<option name="FOR_BRACE_FORCE" value="3" />
|
||||
<ADDITIONAL_INDENT_OPTIONS fileType="css">
|
||||
<option name="INDENT_SIZE" value="4" />
|
||||
<option name="CONTINUATION_INDENT_SIZE" value="8" />
|
||||
<option name="TAB_SIZE" value="4" />
|
||||
<option name="USE_TAB_CHARACTER" value="false" />
|
||||
<option name="SMART_TABS" value="false" />
|
||||
<option name="LABEL_INDENT_SIZE" value="0" />
|
||||
<option name="LABEL_INDENT_ABSOLUTE" value="false" />
|
||||
<option name="USE_RELATIVE_INDENTS" value="false" />
|
||||
</ADDITIONAL_INDENT_OPTIONS>
|
||||
<ADDITIONAL_INDENT_OPTIONS fileType="haml">
|
||||
<option name="INDENT_SIZE" value="2" />
|
||||
<option name="CONTINUATION_INDENT_SIZE" value="8" />
|
||||
<option name="TAB_SIZE" value="4" />
|
||||
<option name="USE_TAB_CHARACTER" value="false" />
|
||||
<option name="SMART_TABS" value="false" />
|
||||
<option name="LABEL_INDENT_SIZE" value="0" />
|
||||
<option name="LABEL_INDENT_ABSOLUTE" value="false" />
|
||||
<option name="USE_RELATIVE_INDENTS" value="false" />
|
||||
</ADDITIONAL_INDENT_OPTIONS>
|
||||
<ADDITIONAL_INDENT_OPTIONS fileType="java">
|
||||
<option name="INDENT_SIZE" value="2" />
|
||||
<option name="CONTINUATION_INDENT_SIZE" value="4" />
|
||||
<option name="TAB_SIZE" value="8" />
|
||||
<option name="USE_TAB_CHARACTER" value="false" />
|
||||
<option name="SMART_TABS" value="false" />
|
||||
<option name="LABEL_INDENT_SIZE" value="0" />
|
||||
<option name="LABEL_INDENT_ABSOLUTE" value="false" />
|
||||
<option name="USE_RELATIVE_INDENTS" value="false" />
|
||||
</ADDITIONAL_INDENT_OPTIONS>
|
||||
<ADDITIONAL_INDENT_OPTIONS fileType="js">
|
||||
<option name="INDENT_SIZE" value="4" />
|
||||
<option name="CONTINUATION_INDENT_SIZE" value="4" />
|
||||
<option name="TAB_SIZE" value="4" />
|
||||
<option name="USE_TAB_CHARACTER" value="false" />
|
||||
<option name="SMART_TABS" value="false" />
|
||||
<option name="LABEL_INDENT_SIZE" value="0" />
|
||||
<option name="LABEL_INDENT_ABSOLUTE" value="false" />
|
||||
<option name="USE_RELATIVE_INDENTS" value="false" />
|
||||
</ADDITIONAL_INDENT_OPTIONS>
|
||||
<ADDITIONAL_INDENT_OPTIONS fileType="jsp">
|
||||
<option name="INDENT_SIZE" value="4" />
|
||||
<option name="CONTINUATION_INDENT_SIZE" value="8" />
|
||||
<option name="TAB_SIZE" value="4" />
|
||||
<option name="USE_TAB_CHARACTER" value="false" />
|
||||
<option name="SMART_TABS" value="false" />
|
||||
<option name="LABEL_INDENT_SIZE" value="0" />
|
||||
<option name="LABEL_INDENT_ABSOLUTE" value="false" />
|
||||
<option name="USE_RELATIVE_INDENTS" value="false" />
|
||||
</ADDITIONAL_INDENT_OPTIONS>
|
||||
<ADDITIONAL_INDENT_OPTIONS fileType="php">
|
||||
<option name="INDENT_SIZE" value="4" />
|
||||
<option name="CONTINUATION_INDENT_SIZE" value="8" />
|
||||
<option name="TAB_SIZE" value="4" />
|
||||
<option name="USE_TAB_CHARACTER" value="false" />
|
||||
<option name="SMART_TABS" value="false" />
|
||||
<option name="LABEL_INDENT_SIZE" value="0" />
|
||||
<option name="LABEL_INDENT_ABSOLUTE" value="false" />
|
||||
<option name="USE_RELATIVE_INDENTS" value="false" />
|
||||
</ADDITIONAL_INDENT_OPTIONS>
|
||||
<ADDITIONAL_INDENT_OPTIONS fileType="sass">
|
||||
<option name="INDENT_SIZE" value="2" />
|
||||
<option name="CONTINUATION_INDENT_SIZE" value="8" />
|
||||
<option name="TAB_SIZE" value="4" />
|
||||
<option name="USE_TAB_CHARACTER" value="false" />
|
||||
<option name="SMART_TABS" value="false" />
|
||||
<option name="LABEL_INDENT_SIZE" value="0" />
|
||||
<option name="LABEL_INDENT_ABSOLUTE" value="false" />
|
||||
<option name="USE_RELATIVE_INDENTS" value="false" />
|
||||
</ADDITIONAL_INDENT_OPTIONS>
|
||||
<ADDITIONAL_INDENT_OPTIONS fileType="xml">
|
||||
<option name="INDENT_SIZE" value="4" />
|
||||
<option name="CONTINUATION_INDENT_SIZE" value="8" />
|
||||
<option name="TAB_SIZE" value="4" />
|
||||
<option name="USE_TAB_CHARACTER" value="false" />
|
||||
<option name="SMART_TABS" value="false" />
|
||||
<option name="LABEL_INDENT_SIZE" value="0" />
|
||||
<option name="LABEL_INDENT_ABSOLUTE" value="false" />
|
||||
<option name="USE_RELATIVE_INDENTS" value="false" />
|
||||
</ADDITIONAL_INDENT_OPTIONS>
|
||||
<ADDITIONAL_INDENT_OPTIONS fileType="yml">
|
||||
<option name="INDENT_SIZE" value="2" />
|
||||
<option name="CONTINUATION_INDENT_SIZE" value="8" />
|
||||
<option name="TAB_SIZE" value="4" />
|
||||
<option name="USE_TAB_CHARACTER" value="false" />
|
||||
<option name="SMART_TABS" value="false" />
|
||||
<option name="LABEL_INDENT_SIZE" value="0" />
|
||||
<option name="LABEL_INDENT_ABSOLUTE" value="false" />
|
||||
<option name="USE_RELATIVE_INDENTS" value="false" />
|
||||
</ADDITIONAL_INDENT_OPTIONS>
|
||||
<codeStyleSettings language="ECMA Script Level 4">
|
||||
<option name="KEEP_CONTROL_STATEMENT_IN_ONE_LINE" value="false" />
|
||||
<option name="KEEP_BLANK_LINES_IN_CODE" value="1" />
|
||||
<option name="BLANK_LINES_AFTER_CLASS_HEADER" value="1" />
|
||||
<option name="ALIGN_MULTILINE_PARAMETERS_IN_CALLS" value="true" />
|
||||
<option name="ALIGN_MULTILINE_BINARY_OPERATION" value="true" />
|
||||
<option name="ALIGN_MULTILINE_ASSIGNMENT" value="true" />
|
||||
<option name="ALIGN_MULTILINE_TERNARY_OPERATION" value="true" />
|
||||
<option name="ALIGN_MULTILINE_THROWS_LIST" value="true" />
|
||||
<option name="ALIGN_MULTILINE_EXTENDS_LIST" value="true" />
|
||||
<option name="ALIGN_MULTILINE_PARENTHESIZED_EXPRESSION" value="true" />
|
||||
<option name="ALIGN_MULTILINE_ARRAY_INITIALIZER_EXPRESSION" value="true" />
|
||||
<option name="CALL_PARAMETERS_WRAP" value="1" />
|
||||
<option name="METHOD_PARAMETERS_WRAP" value="1" />
|
||||
<option name="EXTENDS_LIST_WRAP" value="1" />
|
||||
<option name="THROWS_LIST_WRAP" value="1" />
|
||||
<option name="EXTENDS_KEYWORD_WRAP" value="1" />
|
||||
<option name="THROWS_KEYWORD_WRAP" value="1" />
|
||||
<option name="METHOD_CALL_CHAIN_WRAP" value="1" />
|
||||
<option name="BINARY_OPERATION_WRAP" value="1" />
|
||||
<option name="BINARY_OPERATION_SIGN_ON_NEXT_LINE" value="true" />
|
||||
<option name="TERNARY_OPERATION_WRAP" value="1" />
|
||||
<option name="TERNARY_OPERATION_SIGNS_ON_NEXT_LINE" value="true" />
|
||||
<option name="FOR_STATEMENT_WRAP" value="1" />
|
||||
<option name="ARRAY_INITIALIZER_WRAP" value="1" />
|
||||
<option name="ASSIGNMENT_WRAP" value="5" />
|
||||
<option name="WRAP_COMMENTS" value="true" />
|
||||
<option name="IF_BRACE_FORCE" value="3" />
|
||||
<option name="DOWHILE_BRACE_FORCE" value="3" />
|
||||
<option name="WHILE_BRACE_FORCE" value="3" />
|
||||
<option name="FOR_BRACE_FORCE" value="3" />
|
||||
<option name="PARENT_SETTINGS_INSTALLED" value="true" />
|
||||
</codeStyleSettings>
|
||||
<codeStyleSettings language="JavaScript">
|
||||
<option name="KEEP_CONTROL_STATEMENT_IN_ONE_LINE" value="false" />
|
||||
<option name="KEEP_BLANK_LINES_IN_CODE" value="1" />
|
||||
<option name="BLANK_LINES_AFTER_CLASS_HEADER" value="1" />
|
||||
<option name="ALIGN_MULTILINE_PARAMETERS_IN_CALLS" value="true" />
|
||||
<option name="ALIGN_MULTILINE_BINARY_OPERATION" value="true" />
|
||||
<option name="ALIGN_MULTILINE_ASSIGNMENT" value="true" />
|
||||
<option name="ALIGN_MULTILINE_TERNARY_OPERATION" value="true" />
|
||||
<option name="ALIGN_MULTILINE_THROWS_LIST" value="true" />
|
||||
<option name="ALIGN_MULTILINE_EXTENDS_LIST" value="true" />
|
||||
<option name="ALIGN_MULTILINE_PARENTHESIZED_EXPRESSION" value="true" />
|
||||
<option name="ALIGN_MULTILINE_ARRAY_INITIALIZER_EXPRESSION" value="true" />
|
||||
<option name="CALL_PARAMETERS_WRAP" value="1" />
|
||||
<option name="METHOD_PARAMETERS_WRAP" value="1" />
|
||||
<option name="EXTENDS_LIST_WRAP" value="1" />
|
||||
<option name="THROWS_LIST_WRAP" value="1" />
|
||||
<option name="EXTENDS_KEYWORD_WRAP" value="1" />
|
||||
<option name="THROWS_KEYWORD_WRAP" value="1" />
|
||||
<option name="METHOD_CALL_CHAIN_WRAP" value="1" />
|
||||
<option name="BINARY_OPERATION_WRAP" value="1" />
|
||||
<option name="BINARY_OPERATION_SIGN_ON_NEXT_LINE" value="true" />
|
||||
<option name="TERNARY_OPERATION_WRAP" value="1" />
|
||||
<option name="TERNARY_OPERATION_SIGNS_ON_NEXT_LINE" value="true" />
|
||||
<option name="FOR_STATEMENT_WRAP" value="1" />
|
||||
<option name="ARRAY_INITIALIZER_WRAP" value="1" />
|
||||
<option name="ASSIGNMENT_WRAP" value="5" />
|
||||
<option name="WRAP_COMMENTS" value="true" />
|
||||
<option name="IF_BRACE_FORCE" value="3" />
|
||||
<option name="DOWHILE_BRACE_FORCE" value="3" />
|
||||
<option name="WHILE_BRACE_FORCE" value="3" />
|
||||
<option name="FOR_BRACE_FORCE" value="3" />
|
||||
<option name="PARENT_SETTINGS_INSTALLED" value="true" />
|
||||
</codeStyleSettings>
|
||||
<codeStyleSettings language="PHP">
|
||||
<option name="KEEP_CONTROL_STATEMENT_IN_ONE_LINE" value="false" />
|
||||
<option name="KEEP_BLANK_LINES_IN_CODE" value="1" />
|
||||
<option name="BLANK_LINES_AFTER_CLASS_HEADER" value="1" />
|
||||
<option name="ALIGN_MULTILINE_ASSIGNMENT" value="true" />
|
||||
<option name="ALIGN_MULTILINE_TERNARY_OPERATION" value="true" />
|
||||
<option name="ALIGN_MULTILINE_THROWS_LIST" value="true" />
|
||||
<option name="ALIGN_MULTILINE_EXTENDS_LIST" value="true" />
|
||||
<option name="ALIGN_MULTILINE_PARENTHESIZED_EXPRESSION" value="true" />
|
||||
<option name="CALL_PARAMETERS_WRAP" value="1" />
|
||||
<option name="METHOD_PARAMETERS_WRAP" value="1" />
|
||||
<option name="EXTENDS_LIST_WRAP" value="1" />
|
||||
<option name="THROWS_LIST_WRAP" value="1" />
|
||||
<option name="EXTENDS_KEYWORD_WRAP" value="1" />
|
||||
<option name="THROWS_KEYWORD_WRAP" value="1" />
|
||||
<option name="METHOD_CALL_CHAIN_WRAP" value="1" />
|
||||
<option name="BINARY_OPERATION_WRAP" value="1" />
|
||||
<option name="BINARY_OPERATION_SIGN_ON_NEXT_LINE" value="true" />
|
||||
<option name="TERNARY_OPERATION_WRAP" value="1" />
|
||||
<option name="TERNARY_OPERATION_SIGNS_ON_NEXT_LINE" value="true" />
|
||||
<option name="FOR_STATEMENT_WRAP" value="1" />
|
||||
<option name="ARRAY_INITIALIZER_WRAP" value="1" />
|
||||
<option name="ASSIGNMENT_WRAP" value="5" />
|
||||
<option name="WRAP_COMMENTS" value="true" />
|
||||
<option name="IF_BRACE_FORCE" value="3" />
|
||||
<option name="DOWHILE_BRACE_FORCE" value="3" />
|
||||
<option name="WHILE_BRACE_FORCE" value="3" />
|
||||
<option name="FOR_BRACE_FORCE" value="3" />
|
||||
<option name="PARENT_SETTINGS_INSTALLED" value="true" />
|
||||
</codeStyleSettings>
|
||||
</code_scheme>
|
||||
|
||||
515
javaguide.css
515
javaguide.css
|
|
@ -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
793
javaguide.html
|
|
@ -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 & 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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 & R style <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 <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 <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 & R Style</a>.)</p><a name="s4.3-one-statement-per-line"/>
|
||||
<h3>4.3 One statement per line <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 <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 <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 <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"><T extends Foo & Bar></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 <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 <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 <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 <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"><T extends Foo & Bar></code></li><li>the pipe for a catch block that handles multiple exceptions:
|
||||
<code class="prettyprint lang-java">catch (FooException | BarException e)</code></li><li>the colon (<code class="prettyprint lang-java">:</code>) in an enhanced
|
||||
<code class="prettyprint lang-java">for</code> ("foreach") statement</li></ul></li><li>After <code class="prettyprint lang-java">,:;</code> or the closing parenthesis
|
||||
(<code class="prettyprint lang-java">)</code>) of a cast</li><li>On both sides of the double slash (<code class="prettyprint lang-java">//</code>) that
|
||||
begins an end-of-line comment. Here, multiple spaces are allowed, but not required.</li><li>Between the type and variable of a declaration:
|
||||
<code class="prettyprint lang-java">List<String> list</code></li><li><em>Optional</em> just inside both braces of an array initializer
|
||||
<ul><li><code class="prettyprint lang-java">new int[] {5, 6}</code> and
|
||||
<code class="prettyprint lang-java">new int[] { 5, 6 }</code> are both valid</li></ul></li></ol><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 <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 <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 <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 <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 <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 <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 <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 <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" <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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><MethodUnderTest></i>_<i><state></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 <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<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"};
|
||||
</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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <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 <a href="#s7-javadoc"><img height="21" width="21" src="javaguidelink.png"/></a></h2>
|
||||
<a name="s7.1-javadoc-formatting"/>
|
||||
<h3>7.1 Formatting <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 <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 <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><p></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 <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 <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 <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 <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 <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>
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 189 B |
3627
javascriptguide.xml
3627
javascriptguide.xml
File diff suppressed because it is too large
Load Diff
|
|
@ -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
1187
jsoncstyleguide.xml
File diff suppressed because it is too large
Load Diff
Binary file not shown.
|
Before Width: | Height: | Size: 312 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 253 KiB |
3887
lispguide.xml
3887
lispguide.xml
File diff suppressed because it is too large
Load Diff
1884
objcguide.xml
1884
objcguide.xml
File diff suppressed because it is too large
Load Diff
2311
pyguide.html
2311
pyguide.html
File diff suppressed because it is too large
Load Diff
0
cpplint/cpplint.py → src/cpplint.py
vendored
0
cpplint/cpplint.py → src/cpplint.py
vendored
147
styleguide.css
147
styleguide.css
|
|
@ -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
924
styleguide.xsl
|
|
@ -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="'▶'" />
|
||||
<xsl:variable name="hide_button_text" select="'▽'" />
|
||||
<!-- The suffix for names -->
|
||||
<xsl:variable name="button_suffix" select="'__button'"/>
|
||||
<xsl:variable name="body_suffix" select="'__body'"/>
|
||||
<!-- For easy reference, the name of the button -->
|
||||
<xsl:variable name="show_hide_all_button" select="'show_hide_all_button'"/>
|
||||
|
||||
<!-- The top-level element -->
|
||||
<xsl:template match="GUIDE">
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<TITLE><xsl:value-of select="@title"/></TITLE>
|
||||
<META http-equiv="Content-Type" content="text/html; charset=utf-8"/>
|
||||
<LINK HREF="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 && str.indexOf(suffix, l) == l;
|
||||
}
|
||||
|
||||
function RefreshVisibilityFromHashParam() {
|
||||
var hashRegexp = new RegExp('#([^&#]*)$');
|
||||
var hashMatch = hashRegexp.exec(window.location.href);
|
||||
var anchor = hashMatch && GetElementsByName(hashMatch[1])[0];
|
||||
var node = anchor;
|
||||
var suffix = '<xsl:value-of select="$body_suffix"/>';
|
||||
while (node) {
|
||||
var id = node.id;
|
||||
var matched = id && EndsWith(id, suffix);
|
||||
if (matched) {
|
||||
var len = id.length - suffix.length;
|
||||
ShowByName(id.substring(0, len));
|
||||
if (anchor.scrollIntoView) {
|
||||
anchor.scrollIntoView();
|
||||
}
|
||||
|
||||
return;
|
||||
}
|
||||
node = node.parentNode;
|
||||
}
|
||||
}
|
||||
|
||||
window.onhashchange = RefreshVisibilityFromHashParam;
|
||||
|
||||
window.onload = function() {
|
||||
// if the URL contains "?showall=y", expand the details of all children
|
||||
var showHideAllRegex = new RegExp("[\\?&](showall)=([^&#]*)");
|
||||
var showHideAllValue = showHideAllRegex.exec(window.location.href);
|
||||
if (showHideAllValue != null) {
|
||||
if (showHideAllValue[2] == "y") {
|
||||
SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
|
||||
"inline", '<xsl:value-of select="$hide_button_text"/>');
|
||||
} else {
|
||||
SetHiddenState(document.getElementsByTagName("body")[0].childNodes,
|
||||
"none", '<xsl:value-of select="$show_button_text"/>');
|
||||
}
|
||||
}
|
||||
var showOneRegex = new RegExp("[\\?&](showone)=([^&#]*)");
|
||||
var showOneValue = showOneRegex.exec(window.location.href);
|
||||
if (showOneValue) {
|
||||
ShowHideByName(showOneValue[2]);
|
||||
}
|
||||
|
||||
|
||||
RefreshVisibilityFromHashParam();
|
||||
}
|
||||
</SCRIPT>
|
||||
</HEAD>
|
||||
<BODY>
|
||||
<H1><xsl:value-of select="@title"/></H1>
|
||||
<xsl:apply-templates/>
|
||||
</BODY>
|
||||
</HTML>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="OVERVIEW">
|
||||
<xsl:variable name="button_text">
|
||||
<xsl:choose>
|
||||
<xsl:when test="$show_explanation_default">
|
||||
<xsl:value-of select="$hide_button_text"/>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:value-of select="$show_button_text"/>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:variable>
|
||||
<DIV style="margin-left: 50%; font-size: 75%;">
|
||||
<P>
|
||||
Each style point has a summary for which additional information is available
|
||||
by toggling the accompanying arrow button that looks this way:
|
||||
<SPAN class="showhide_button" style="margin-left: 0; float: none">
|
||||
<xsl:value-of select="$show_button_text"/></SPAN>.
|
||||
You may toggle all summaries with the big arrow button:
|
||||
</P>
|
||||
<DIV style=" font-size: larger; margin-left: +2em;">
|
||||
<SPAN class="showhide_button" style="font-size: 180%; float: none">
|
||||
<xsl:attribute name="onclick"><xsl:value-of select="'javascript:ShowHideAll()'"/></xsl:attribute>
|
||||
<xsl:attribute name="name"><xsl:value-of select="$show_hide_all_button"/></xsl:attribute>
|
||||
<xsl:attribute name="id"><xsl:value-of select="$show_hide_all_button"/></xsl:attribute>
|
||||
<xsl:value-of select="$button_text"/>
|
||||
</SPAN>
|
||||
Toggle all summaries
|
||||
</DIV>
|
||||
</DIV>
|
||||
<xsl:call-template name="TOC">
|
||||
<xsl:with-param name="root" select=".."/>
|
||||
</xsl:call-template>
|
||||
<xsl:apply-templates/>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="PARTING_WORDS">
|
||||
<H2>Parting Words</H2>
|
||||
<xsl:apply-templates/>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="CATEGORY">
|
||||
<DIV>
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<H2>
|
||||
<xsl:variable name="category_name">
|
||||
<xsl:call-template name="anchorname">
|
||||
<xsl:with-param name="sectionname" select="@title"/>
|
||||
</xsl:call-template>
|
||||
</xsl:variable>
|
||||
<xsl:attribute name="name"><xsl:value-of select="$category_name"/></xsl:attribute>
|
||||
<xsl:attribute name="id"><xsl:value-of select="$category_name"/></xsl:attribute>
|
||||
<xsl:value-of select="@title"/>
|
||||
</H2>
|
||||
<xsl:apply-templates/>
|
||||
</DIV>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="STYLEPOINT">
|
||||
<DIV>
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<xsl:variable name="stylepoint_name">
|
||||
<xsl:call-template name="anchorname">
|
||||
<xsl:with-param name="sectionname" select="@title"/>
|
||||
</xsl:call-template>
|
||||
</xsl:variable>
|
||||
<xsl:variable name="button_text">
|
||||
<xsl:choose>
|
||||
<xsl:when test="$show_explanation_default">
|
||||
<xsl:value-of select="$hide_button_text"/>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:value-of select="$show_button_text"/>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:variable>
|
||||
<H3>
|
||||
<A>
|
||||
<xsl:attribute name="name"><xsl:value-of select="$stylepoint_name"/></xsl:attribute>
|
||||
<xsl:attribute name="id"><xsl:value-of select="$stylepoint_name"/></xsl:attribute>
|
||||
<xsl:value-of select="@title"/>
|
||||
</A>
|
||||
</H3>
|
||||
<xsl:variable name="buttonName">
|
||||
<xsl:value-of select="$stylepoint_name"/><xsl:value-of select="$button_suffix"/>
|
||||
</xsl:variable>
|
||||
<xsl:variable name="onclick_definition">
|
||||
<xsl:text>javascript:ShowHideByName('</xsl:text>
|
||||
<xsl:value-of select="$stylepoint_name"/>
|
||||
<xsl:text>')</xsl:text>
|
||||
</xsl:variable>
|
||||
<SPAN class="link_button" id="link-{$buttonName}" name="link-{$buttonName}">
|
||||
<A>
|
||||
<xsl:attribute name="href">?showone=<xsl:value-of select="$stylepoint_name"/>#<xsl:value-of select="$stylepoint_name"/></xsl:attribute>
|
||||
link
|
||||
</A>
|
||||
</SPAN>
|
||||
<SPAN class="showhide_button">
|
||||
<xsl:attribute name="onclick"><xsl:value-of select="$onclick_definition"/></xsl:attribute>
|
||||
<xsl:attribute name="name"><xsl:value-of select="$buttonName"/></xsl:attribute>
|
||||
<xsl:attribute name="id"><xsl:value-of select="$buttonName"/></xsl:attribute>
|
||||
<xsl:value-of select="$button_text"/>
|
||||
</SPAN>
|
||||
<xsl:apply-templates>
|
||||
<xsl:with-param name="anchor_prefix" select="$stylepoint_name" />
|
||||
</xsl:apply-templates>
|
||||
</DIV>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="SUMMARY">
|
||||
<xsl:param name="anchor_prefix" />
|
||||
<DIV style="display:inline;">
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<xsl:apply-templates/>
|
||||
</DIV>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="BODY">
|
||||
<xsl:param name="anchor_prefix" />
|
||||
<DIV>
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<DIV class="stylepoint_body">
|
||||
<xsl:attribute name="name"><xsl:value-of select="$anchor_prefix"/><xsl:value-of select="$body_suffix"/></xsl:attribute>
|
||||
<xsl:attribute name="id"><xsl:value-of select="$anchor_prefix"/><xsl:value-of select="$body_suffix"/></xsl:attribute>
|
||||
<xsl:attribute name="style">
|
||||
<xsl:choose>
|
||||
<xsl:when test="$show_explanation_default">display: inline</xsl:when>
|
||||
<xsl:otherwise>display: none</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:attribute>
|
||||
<xsl:apply-templates/>
|
||||
</DIV>
|
||||
</DIV>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="DEFINITION">
|
||||
<P>
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<SPAN class="stylepoint_section">Definition: </SPAN>
|
||||
<xsl:apply-templates/>
|
||||
</P>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="PROS">
|
||||
<P>
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<SPAN class="stylepoint_section">Pros: </SPAN>
|
||||
<xsl:apply-templates/>
|
||||
</P>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="CONS">
|
||||
<P>
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<SPAN class="stylepoint_section">Cons: </SPAN>
|
||||
<xsl:apply-templates/>
|
||||
</P>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="DECISION">
|
||||
<P>
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<SPAN class="stylepoint_section">Decision: </SPAN>
|
||||
<xsl:apply-templates/>
|
||||
</P>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="TODO">
|
||||
<P>
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<DIV style="font-size: 150%;">TODO:
|
||||
<xsl:apply-templates/>
|
||||
</DIV>
|
||||
</P>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="SUBSECTION">
|
||||
<P>
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<SPAN class="stylepoint_subsection"><xsl:value-of select="@title"/> </SPAN>
|
||||
<xsl:apply-templates/>
|
||||
</P>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="SUBSUBSECTION">
|
||||
<P>
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<SPAN class="stylepoint_subsubsection"><xsl:value-of select="@title"/> </SPAN>
|
||||
<xsl:apply-templates/>
|
||||
</P>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="CODE_SNIPPET">
|
||||
<DIV>
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<PRE><xsl:call-template name="print_without_leading_chars">
|
||||
<xsl:with-param name="text" select="."/>
|
||||
<xsl:with-param name="strip" select="1"/>
|
||||
<xsl:with-param name="is_firstline" select="1"/>
|
||||
<xsl:with-param name="trim_count">
|
||||
<xsl:call-template name="num_leading_spaces">
|
||||
<xsl:with-param name="text" select="."/>
|
||||
<xsl:with-param name="max_so_far" select="1000"/>
|
||||
</xsl:call-template>
|
||||
</xsl:with-param>
|
||||
</xsl:call-template></PRE>
|
||||
</DIV>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="BAD_CODE_SNIPPET">
|
||||
<DIV>
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<PRE class="badcode"><xsl:call-template name="print_without_leading_chars">
|
||||
<xsl:with-param name="text" select="."/>
|
||||
<xsl:with-param name="strip" select="1"/>
|
||||
<xsl:with-param name="is_firstline" select="1"/>
|
||||
<xsl:with-param name="trim_count">
|
||||
<xsl:call-template name="num_leading_spaces">
|
||||
<xsl:with-param name="text" select="."/>
|
||||
<xsl:with-param name="max_so_far" select="1000"/>
|
||||
</xsl:call-template>
|
||||
</xsl:with-param>
|
||||
</xsl:call-template></PRE>
|
||||
</DIV>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="PY_CODE_SNIPPET">
|
||||
<DIV>
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<PRE><xsl:call-template name="print_python_code">
|
||||
<xsl:with-param name="text" select="."/>
|
||||
</xsl:call-template></PRE>
|
||||
</DIV>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="BAD_PY_CODE_SNIPPET">
|
||||
<DIV>
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<PRE class="badcode"><xsl:call-template name="print_python_code">
|
||||
<xsl:with-param name="text" select="."/>
|
||||
</xsl:call-template></PRE>
|
||||
</DIV>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="FUNCTION">
|
||||
<xsl:call-template name="print_function_name">
|
||||
<xsl:with-param name="text" select="."/>
|
||||
</xsl:call-template>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="SYNTAX">
|
||||
<I>
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<xsl:apply-templates/>
|
||||
</I>
|
||||
</xsl:template>
|
||||
|
||||
|
||||
<!-- This passes through any HTML elements that the
|
||||
XML doc uses for minor formatting -->
|
||||
<xsl:template match="a|address|blockquote|br|center|cite|code|dd|div|dl|dt|em|hr|i|img|li|ol|p|pre|span|table|td|th|tr|ul|var|A|ADDRESS|BLOCKQUOTE|BR|CENTER|CITE|CODE|DD|DIV|DL|DT|EM|HR|I|LI|OL|P|PRE|SPAN|TABLE|TD|TH|TR|UL|VAR">
|
||||
<xsl:element name="{local-name()}">
|
||||
<xsl:copy-of select="@*"/>
|
||||
<xsl:apply-templates/>
|
||||
</xsl:element>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Builds the table of contents -->
|
||||
<xsl:template name="TOC">
|
||||
<xsl:param name="root"/>
|
||||
<DIV class="toc">
|
||||
<DIV class="toc_title">Table of Contents</DIV>
|
||||
<TABLE>
|
||||
<xsl:for-each select="$root/CATEGORY">
|
||||
<TR valign="top">
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<TD>
|
||||
<DIV class="toc_category">
|
||||
<A>
|
||||
<xsl:attribute name="href">
|
||||
<xsl:text>#</xsl:text>
|
||||
<xsl:call-template name="anchorname">
|
||||
<xsl:with-param name="sectionname" select="@title"/>
|
||||
</xsl:call-template>
|
||||
</xsl:attribute>
|
||||
<xsl:value-of select="@title"/>
|
||||
</A>
|
||||
</DIV>
|
||||
</TD><TD>
|
||||
<DIV class="toc_stylepoint">
|
||||
<xsl:for-each select="./STYLEPOINT">
|
||||
<SPAN style="padding-right: 1em; white-space:nowrap;">
|
||||
<xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute>
|
||||
<A>
|
||||
<xsl:attribute name="href">
|
||||
<xsl:text>#</xsl:text>
|
||||
<xsl:call-template name="anchorname">
|
||||
<xsl:with-param name="sectionname" select="@title"/>
|
||||
</xsl:call-template>
|
||||
</xsl:attribute>
|
||||
<xsl:value-of select="@title"/>
|
||||
</A>
|
||||
</SPAN>
|
||||
<xsl:text> </xsl:text>
|
||||
</xsl:for-each>
|
||||
</DIV>
|
||||
</TD>
|
||||
</TR>
|
||||
</xsl:for-each>
|
||||
</TABLE>
|
||||
</DIV>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template name="TOC_one_stylepoint">
|
||||
<xsl:param name="stylepoint"/>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Creates a standard anchor given any text.
|
||||
Substitutes underscore for characters unsuitable for URLs -->
|
||||
<xsl:template name="anchorname">
|
||||
<xsl:param name="sectionname"/>
|
||||
<!-- strange quoting necessary to strip apostrophes -->
|
||||
<xsl:variable name="bad_characters" select="" ()#'""/>
|
||||
<xsl:value-of select="translate($sectionname,$bad_characters,'_____')"/>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Given text, evaluates to the number of leading spaces. -->
|
||||
<!-- TODO(csilvers): deal well with leading tabs (treat as 8 spaces?) -->
|
||||
<xsl:template name="num_leading_spaces_one_line">
|
||||
<xsl:param name="text"/>
|
||||
<xsl:param name="current_count"/>
|
||||
<xsl:choose>
|
||||
<xsl:when test="starts-with($text, ' ')">
|
||||
<xsl:call-template name="num_leading_spaces_one_line">
|
||||
<xsl:with-param name="text" select="substring($text, 2)"/>
|
||||
<xsl:with-param name="current_count" select="$current_count + 1"/>
|
||||
</xsl:call-template>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:value-of select="$current_count"/>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Given a block of text, each line terminated by \n, evaluates to
|
||||
the indentation-level of that text; that is, the largest number
|
||||
n such that every non-blank line starts with at least n spaces. -->
|
||||
<xsl:template name="num_leading_spaces">
|
||||
<xsl:param name="text"/>
|
||||
<xsl:param name="max_so_far"/>
|
||||
<!-- TODO(csilvers): deal with case text doesn't end in a newline -->
|
||||
<xsl:variable name="line" select="substring-before($text, '
')"/>
|
||||
<xsl:variable name="rest" select="substring-after($text, '
')"/>
|
||||
<xsl:variable name="num_spaces_this_line">
|
||||
<xsl:choose>
|
||||
<xsl:when test="$line=''">
|
||||
<xsl:value-of select="$max_so_far"/>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:call-template name="num_leading_spaces_one_line">
|
||||
<xsl:with-param name="text" select="$line"/>
|
||||
<xsl:with-param name="current_count" select="0"/>
|
||||
</xsl:call-template>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:variable>
|
||||
<xsl:variable name="new_max_so_far">
|
||||
<xsl:choose>
|
||||
<xsl:when test="$num_spaces_this_line < $max_so_far">
|
||||
<xsl:value-of select="$num_spaces_this_line"/>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:value-of select="$max_so_far"/>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:variable>
|
||||
<!-- now check if we're on the last line, and if not, recurse -->
|
||||
<xsl:if test="$rest=''">
|
||||
<xsl:value-of select="$new_max_so_far"/>
|
||||
</xsl:if>
|
||||
<xsl:if test="not($rest='')">
|
||||
<xsl:call-template name="num_leading_spaces">
|
||||
<xsl:with-param name="text" select="$rest"/>
|
||||
<xsl:with-param name="max_so_far" select="$new_max_so_far"/>
|
||||
</xsl:call-template>
|
||||
</xsl:if>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Given text, determine the starting position of code.
|
||||
This similar to num_leading_spaces_one_line but treats "Yes:" and "No:"
|
||||
as spaces. Also, if there is no code on the first line, it searches
|
||||
subsequent lines until a non-empty line is found.
|
||||
Used to find the start of code in snippets like:
|
||||
Yes: if(foo):
|
||||
No : if(foo):
|
||||
As well as:
|
||||
Yes:
|
||||
if (foo):
|
||||
-->
|
||||
<xsl:template name="code_start_index">
|
||||
<xsl:param name="text"/>
|
||||
<xsl:param name="current_count"/>
|
||||
<xsl:choose>
|
||||
<xsl:when test="starts-with($text, ' ')">
|
||||
<xsl:call-template name="code_start_index">
|
||||
<xsl:with-param name="text" select="substring($text, 2)"/>
|
||||
<xsl:with-param name="current_count" select="$current_count + 1"/>
|
||||
</xsl:call-template>
|
||||
</xsl:when>
|
||||
<xsl:when test="starts-with($text, 'Yes:')">
|
||||
<xsl:call-template name="code_start_index">
|
||||
<xsl:with-param name="text" select="substring($text, 5)"/>
|
||||
<xsl:with-param name="current_count" select="$current_count + 4"/>
|
||||
</xsl:call-template>
|
||||
</xsl:when>
|
||||
<xsl:when test="starts-with($text, 'No:')">
|
||||
<xsl:call-template name="code_start_index">
|
||||
<xsl:with-param name="text" select="substring($text, 4)"/>
|
||||
<xsl:with-param name="current_count" select="$current_count + 3"/>
|
||||
</xsl:call-template>
|
||||
</xsl:when>
|
||||
<!-- This is only reached if the first line is entirely whitespace or
|
||||
contains nothing but "Yes:" or "No:"-->
|
||||
<xsl:when test="starts-with($text, '
')">
|
||||
<xsl:call-template name="code_start_index">
|
||||
<xsl:with-param name="text" select="substring($text, 2)"/>
|
||||
<xsl:with-param name="current_count" select="0"/>
|
||||
</xsl:call-template>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:value-of select="$current_count"/>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Helper for ends_with_colon. Determine whether the given line is nothing
|
||||
but spaces and python-style comments. -->
|
||||
<xsl:template name="is_blank_or_comment">
|
||||
<xsl:param name="line"/>
|
||||
<xsl:choose>
|
||||
<xsl:when test="$line = ''">
|
||||
<xsl:value-of select="1"/>
|
||||
</xsl:when>
|
||||
<xsl:when test="starts-with($line, '
')">
|
||||
<xsl:value-of select="1"/>
|
||||
</xsl:when>
|
||||
<xsl:when test="starts-with($line, '#')">
|
||||
<xsl:value-of select="1"/>
|
||||
</xsl:when>
|
||||
<xsl:when test="starts-with($line, ' ')">
|
||||
<xsl:call-template name="is_blank_or_comment">
|
||||
<xsl:with-param name="line" select="substring($line, 2)"/>
|
||||
</xsl:call-template>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:value-of select="0"/>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Determine whether the given line ends with a colon. Note that Python
|
||||
style comments are ignored so the following lines return True:
|
||||
- def foo():
|
||||
- def foo(): # Bar
|
||||
- if(foo):
|
||||
|
||||
But some code may confuse this function. For example the following are
|
||||
also consider to "end_with_colon" even though they don't for Python
|
||||
- foo(": #")
|
||||
- foo() # No need for :
|
||||
-->
|
||||
<xsl:template name="ends_with_colon">
|
||||
<xsl:param name="line"/>
|
||||
<xsl:param name="found_colon"/>
|
||||
<xsl:choose>
|
||||
<xsl:when test="$line = ''">
|
||||
<xsl:value-of select="$found_colon"/>
|
||||
</xsl:when>
|
||||
<xsl:when test="starts-with($line, '
')">
|
||||
<xsl:value-of select="$found_colon"/>
|
||||
</xsl:when>
|
||||
<xsl:when test="starts-with($line, ' ')">
|
||||
<xsl:call-template name="ends_with_colon">
|
||||
<xsl:with-param name="line" select="substring($line, 2)"/>
|
||||
<xsl:with-param name="found_colon" select="$found_colon"/>
|
||||
</xsl:call-template>
|
||||
</xsl:when>
|
||||
<xsl:when test="starts-with($line, ':')">
|
||||
<xsl:variable name="rest_is_comment">
|
||||
<xsl:call-template name="is_blank_or_comment">
|
||||
<xsl:with-param name="line" select="substring($line, 2)"/>
|
||||
</xsl:call-template>
|
||||
</xsl:variable>
|
||||
<xsl:choose>
|
||||
<xsl:when test="$rest_is_comment = '1'">
|
||||
<xsl:value-of select="1"/>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:call-template name="ends_with_colon">
|
||||
<xsl:with-param name="line" select="substring($line, 2)"/>
|
||||
<xsl:with-param name="found_colon" select="0"/>
|
||||
</xsl:call-template>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:call-template name="ends_with_colon">
|
||||
<xsl:with-param name="line" select="substring($line, 2)"/>
|
||||
<xsl:with-param name="found_colon" select="0"/>
|
||||
</xsl:call-template>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Prints one line of python code with proper indent and calls itself
|
||||
recursively for the rest of the text.
|
||||
This template uses "a", "b", "c" and "d" to refer to four key column
|
||||
numbers. They are:
|
||||
- a: the indentation common to all lines in a code snippet. This is
|
||||
stripped out to allow for cleaner code in the xml.
|
||||
- b: the indentation of the most out-dented line of code. This is
|
||||
different from "a" when code is labelled with "Yes:" or "No:"
|
||||
- c: the indentation of the current python block, in other words, the
|
||||
indentation of the first line of this block, which is the
|
||||
indentation of the last line we saw that ended with a colon.
|
||||
- d: the "total" indentation of the line, ignorng possible "Yes:" or
|
||||
"No:" text on the line.
|
||||
|
||||
For example, for the last line of the following code snippet, the
|
||||
positions of a, b, c and d are indicated below:
|
||||
Yes: def Foo():
|
||||
if bar():
|
||||
a += 1
|
||||
baz()
|
||||
a b c d
|
||||
|
||||
The algorithm is:
|
||||
1) Split the text into first line and the rest. Note that the
|
||||
substring-before function is supposed to handle the case where the
|
||||
character is not present in the string but does not so we
|
||||
automatically ignore the last line of the snippet which is always
|
||||
empty (the closing snippet tag). This is consistent with the
|
||||
behavior or print_without_leading_chars.
|
||||
2) If the current is empty (only whitespace), print newline and call
|
||||
itself recursively on the rest of the text with the rest of the
|
||||
parameters unchanged.
|
||||
3) Otherwise, measure "d"
|
||||
4) Measure "c" by taking:
|
||||
- the value of "d" if the previous line ended with a colon or the
|
||||
current line is outdented compare to the previous line
|
||||
- the indent of the previous line otherwise
|
||||
5) Print line[a:c] (Note that we ignore line[0:a])
|
||||
6) Print line[b:c] in an external span (in order to double the block
|
||||
indent in external code).
|
||||
7) Print line[c:<end>] with function names processed to produce both
|
||||
internal and external names.
|
||||
8) If there are more lines, recurse.
|
||||
-->
|
||||
<xsl:template name="print_python_line_recursively">
|
||||
<xsl:param name="text"/>
|
||||
<xsl:param name="a"/>
|
||||
<xsl:param name="b"/>
|
||||
<xsl:param name="previous_indent"/>
|
||||
<xsl:param name="previous_ends_with_colon"/>
|
||||
<xsl:param name="is_first_line"/>
|
||||
<xsl:variable name="line" select="substring-before($text, '
')"/>
|
||||
<xsl:variable name="rest" select="substring-after($text, '
')"/>
|
||||
<xsl:choose>
|
||||
<xsl:when test="substring($line, $b) = '' and not($rest = '')">
|
||||
<xsl:if test="not($is_first_line = '1')">
|
||||
<xsl:text>
</xsl:text>
|
||||
</xsl:if>
|
||||
<xsl:call-template name="print_python_line_recursively">
|
||||
<xsl:with-param name="text" select="$rest"/>
|
||||
<xsl:with-param name="a" select="$a"/>
|
||||
<xsl:with-param name="b" select="$b"/>
|
||||
<xsl:with-param name="previous_indent" select="$previous_indent"/>
|
||||
<xsl:with-param name="previous_ends_with_colon"
|
||||
select="$previous_ends_with_colon"/>
|
||||
<xsl:with-param name="is_first_line" select="0"/>
|
||||
</xsl:call-template>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:variable name="indent_after_b">
|
||||
<xsl:call-template name="num_leading_spaces_one_line">
|
||||
<xsl:with-param name="text" select="substring($line, $b + 1)"/>
|
||||
<xsl:with-param name="current_count" select="0"/>
|
||||
</xsl:call-template>
|
||||
</xsl:variable>
|
||||
<xsl:variable name="d" select="$b + $indent_after_b"/>
|
||||
<xsl:variable name="c">
|
||||
<xsl:choose>
|
||||
<xsl:when test="$previous_ends_with_colon = '1' or
|
||||
$previous_indent > $d">
|
||||
<xsl:value-of select="$d"/>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:value-of select="$previous_indent"/>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:variable>
|
||||
|
||||
<xsl:value-of select="substring($line, $a + 1, $c - $a)"/>
|
||||
<span class="external">
|
||||
<xsl:value-of select="substring($line, $b + 1, $c - $b)"/>
|
||||
</span>
|
||||
<xsl:call-template name="munge_function_names_in_text">
|
||||
<xsl:with-param name="stripped_line"
|
||||
select="substring($line, $c + 1)"/>
|
||||
</xsl:call-template>
|
||||
<xsl:if test="not(substring($rest, $a) = '')">
|
||||
<xsl:text>
</xsl:text>
|
||||
<xsl:call-template name="print_python_line_recursively">
|
||||
<xsl:with-param name="text" select="$rest"/>
|
||||
<xsl:with-param name="a" select="$a"/>
|
||||
<xsl:with-param name="b" select="$b"/>
|
||||
<xsl:with-param name="previous_indent" select="$c"/>
|
||||
<xsl:with-param name="previous_ends_with_colon">
|
||||
<xsl:call-template name="ends_with_colon">
|
||||
<xsl:with-param name="line" select="$line"/>
|
||||
<xsl:with-param name="found_colon" select="0"/>
|
||||
</xsl:call-template>
|
||||
</xsl:with-param>
|
||||
<xsl:with-param name="is_first_line" select="0"/>
|
||||
</xsl:call-template>
|
||||
</xsl:if>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Print python code with internal and external styles.
|
||||
In order to conform with PEP-8 externally, we identify 2-space indents
|
||||
and an external-only 4-space indent.
|
||||
Function names that are marked with $$FunctionName/$$ have an external
|
||||
lower_with_underscore version added. -->
|
||||
<xsl:template name="print_python_code">
|
||||
<xsl:param name="text"/>
|
||||
|
||||
<xsl:variable name="a">
|
||||
<xsl:call-template name="num_leading_spaces">
|
||||
<xsl:with-param name="text" select="."/>
|
||||
<xsl:with-param name="max_so_far" select="1000"/>
|
||||
</xsl:call-template>
|
||||
</xsl:variable>
|
||||
|
||||
<xsl:variable name="b">
|
||||
<xsl:call-template name="code_start_index">
|
||||
<xsl:with-param name="text" select="$text"/>
|
||||
<xsl:with-param name="current_count" select="0"/>
|
||||
</xsl:call-template>
|
||||
</xsl:variable>
|
||||
|
||||
<xsl:call-template name="print_python_line_recursively">
|
||||
<xsl:with-param name="text" select="$text"/>
|
||||
<xsl:with-param name="a" select="$a"/>
|
||||
<xsl:with-param name="b" select="$b"/>
|
||||
<xsl:with-param name="previous_indent" select="$b"/>
|
||||
<xsl:with-param name="previous_ends_with_colon" select="0"/>
|
||||
<xsl:with-param name="is_first_line" select="1"/>
|
||||
</xsl:call-template>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Given a block of text, each line terminated by \n, and a number n,
|
||||
emits the text with the first n characters of each line
|
||||
deleted. If strip==1, then we omit blank lines at the beginning
|
||||
and end of the text (but not the middle!) -->
|
||||
<!-- TODO(csilvers): deal well with leading tabs (treat as 8 spaces?) -->
|
||||
<xsl:template name="print_without_leading_chars">
|
||||
<xsl:param name="text"/>
|
||||
<xsl:param name="trim_count"/>
|
||||
<xsl:param name="strip"/>
|
||||
<xsl:param name="is_firstline"/>
|
||||
<!-- TODO(csilvers): deal with case text doesn't end in a newline -->
|
||||
<xsl:variable name="line" select="substring-before($text, '
')"/>
|
||||
<xsl:variable name="rest" select="substring-after($text, '
')"/>
|
||||
<xsl:variable name="stripped_line" select="substring($line, $trim_count+1)"/>
|
||||
<xsl:choose>
|
||||
<!-- $line (or $rest) is considered empty if we'd trim the entire line -->
|
||||
<xsl:when test="($strip = '1') and ($is_firstline = '1') and
|
||||
(string-length($line) <= $trim_count)">
|
||||
</xsl:when>
|
||||
<xsl:when test="($strip = '1') and
|
||||
(string-length($rest) <= $trim_count)">
|
||||
<xsl:value-of select="$stripped_line"/>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:value-of select="$stripped_line"/>
|
||||
<xsl:text>
</xsl:text>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
<xsl:if test="not($rest='')">
|
||||
<xsl:call-template name="print_without_leading_chars">
|
||||
<xsl:with-param name="text" select="$rest"/>
|
||||
<xsl:with-param name="trim_count" select="$trim_count"/>
|
||||
<xsl:with-param name="strip" select="$strip"/>
|
||||
<xsl:with-param name="is_firstline" select="0"/>
|
||||
</xsl:call-template>
|
||||
</xsl:if>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Given a line of code, find function names that are marked with $$ /$$ and
|
||||
print out the line with the internal and external versions of the
|
||||
function names.-->
|
||||
<xsl:template name="munge_function_names_in_text">
|
||||
<xsl:param name="stripped_line"/>
|
||||
<xsl:choose>
|
||||
<xsl:when test="contains($stripped_line, '$$')">
|
||||
<xsl:value-of select="substring-before($stripped_line, '$$')"/>
|
||||
<xsl:call-template name="print_function_name">
|
||||
<xsl:with-param name="text" select="substring-after(substring-before($stripped_line, '/$$'), '$$')"/>
|
||||
</xsl:call-template>
|
||||
<xsl:call-template name="munge_function_names_in_text">
|
||||
<xsl:with-param name="stripped_line" select="substring-after($stripped_line, '/$$')"/>
|
||||
</xsl:call-template>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:value-of select="$stripped_line"/>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Given a function name, print out both the internal and external version
|
||||
of the function name in their respective spans.-->
|
||||
<xsl:template name="print_function_name">
|
||||
<xsl:param name="text"/>
|
||||
<xsl:call-template name="convert_camel_case_to_lowercase_with_under">
|
||||
<xsl:with-param name="text" select="$text"/>
|
||||
</xsl:call-template>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Given a single word of text convert it from CamelCase to
|
||||
lower_with_under.
|
||||
This means replacing each uppercase character with _ followed by the
|
||||
lowercase version except for the first character which is replaced
|
||||
without adding the _.-->
|
||||
<xsl:template name="convert_camel_case_to_lowercase_with_under">
|
||||
<xsl:param name="text"/>
|
||||
<xsl:param name="is_recursive_call"/>
|
||||
<xsl:variable name="first_char" select="substring($text, 1, 1)"/>
|
||||
<xsl:variable name="rest" select="substring($text, 2)"/>
|
||||
<xsl:choose>
|
||||
<xsl:when test="contains('ABCDEFGHIJKLMNOPQRSTUVWXYZ', $first_char)">
|
||||
<xsl:if test="$is_recursive_call='1'">
|
||||
<xsl:text>_</xsl:text>
|
||||
</xsl:if>
|
||||
<xsl:value-of select="translate($first_char, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')"/>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:value-of select="$first_char" />
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
<xsl:if test="not($rest='')">
|
||||
<xsl:call-template name="convert_camel_case_to_lowercase_with_under">
|
||||
<xsl:with-param name="text" select="$rest"/>
|
||||
<xsl:with-param name="is_recursive_call" select="1"/>
|
||||
</xsl:call-template>
|
||||
</xsl:if>
|
||||
</xsl:template>
|
||||
</xsl:stylesheet>
|
||||
|
||||
1534
vimscriptfull.xml
1534
vimscriptfull.xml
File diff suppressed because it is too large
Load Diff
|
|
@ -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-<Plug>.) should be defined in
|
||||
<code>plugin/plugs.vim</code>.
|
||||
</p>
|
||||
</BODY>
|
||||
</STYLEPOINT>
|
||||
<STYLEPOINT title="Settings">
|
||||
<SUMMARY>Change settings locally</SUMMARY>
|
||||
<BODY>
|
||||
<p>
|
||||
Use <code>:setlocal</code> and <code>&l:</code> instead of
|
||||
<code>:set</code> and <code>&</code> unless you have explicit
|
||||
reason to do otherwise.
|
||||
</p>
|
||||
</BODY>
|
||||
</STYLEPOINT>
|
||||
</CATEGORY>
|
||||
|
||||
<CATEGORY title="Style">
|
||||
<p>
|
||||
Follow google style conventions. When in doubt, treat vimscript style
|
||||
like python style.
|
||||
</p>
|
||||
|
||||
<STYLEPOINT title="Whitespace">
|
||||
<SUMMARY>
|
||||
Similar to python.
|
||||
|
||||
<br/>
|
||||
<br/>
|
||||
</SUMMARY>
|
||||
<BODY>
|
||||
<ul>
|
||||
<li>Use two spaces for indents</li>
|
||||
<li>Do not use tabs</li>
|
||||
<li>Use spaces around operators
|
||||
<p>This does not apply to arguments to commands.</p>
|
||||
<CODE_SNIPPET>
|
||||
let s:variable = "concatenated " . "strings"
|
||||
command -range=% MyCommand
|
||||
</CODE_SNIPPET>
|
||||
</li>
|
||||
<li>Do not introduce trailing whitespace
|
||||
<p>You need not go out of your way to remove it.</p>
|
||||
<p>
|
||||
Trailing whitespace is allowed in mappings which prep commands
|
||||
for user input, such as
|
||||
"<code>noremap <leader>gf :grep -f </code>".
|
||||
</p>
|
||||
</li>
|
||||
<li>Restrict lines to 80 columns wide</li>
|
||||
<li>Indent continued lines by four spaces</li>
|
||||
<li>Do not align arguments of commands
|
||||
<BAD_CODE_SNIPPET>
|
||||
command -bang MyCommand call myplugin#foo()
|
||||
command MyCommand2 call myplugin#bar()
|
||||
</BAD_CODE_SNIPPET>
|
||||
<CODE_SNIPPET>
|
||||
command -bang MyCommand call myplugin#foo()
|
||||
command MyCommand2 call myplugin#bar()
|
||||
</CODE_SNIPPET>
|
||||
</li>
|
||||
</ul>
|
||||
</BODY>
|
||||
</STYLEPOINT>
|
||||
|
||||
<STYLEPOINT title="Naming">
|
||||
<SUMMARY>
|
||||
<p>
|
||||
In general, use
|
||||
<code>plugin-names-like-this</code>,
|
||||
<code>FunctionNamesLikeThis</code>,
|
||||
<code>CommandNamesLikeThis</code>,
|
||||
<code>augroup_names_like_this</code>,
|
||||
<code>variable_names_like_this</code>.
|
||||
</p>
|
||||
<p>Always prefix variables with their scope.</p>
|
||||
</SUMMARY>
|
||||
<BODY>
|
||||
<SUBSECTION title="plugin-names-like-this">
|
||||
<p>Keep them short and sweet.</p>
|
||||
|
||||
</SUBSECTION>
|
||||
<SUBSECTION title="FunctionNamesLikeThis">
|
||||
<p>Prefix script-local functions with <code>s:</code></p>
|
||||
<p>Autoloaded functions may not have a scope prefix.</p>
|
||||
<p>
|
||||
Do not create global functions. Use autoloaded functions
|
||||
instead.
|
||||
</p>
|
||||
</SUBSECTION>
|
||||
<SUBSECTION title="CommandNamesLikeThis">
|
||||
<p>Prefer succinct command names over common command prefixes.</p>
|
||||
</SUBSECTION>
|
||||
<SUBSECTION title="variable_names_like_this">
|
||||
<p>Augroup names count as variables for naming purposes.</p>
|
||||
</SUBSECTION>
|
||||
<SUBSECTION title="Prefix all variables with their scope.">
|
||||
<ul>
|
||||
<li>Global variables with <code>g:</code></li>
|
||||
<li>Script-local variables with <code>s:</code></li>
|
||||
<li>Function arguments with <code>a:</code></li>
|
||||
<li>Function-local variables with <code>l:</code></li>
|
||||
<li>Vim-predefined variables with <code>v:</code></li>
|
||||
<li>Buffer-local variables with <code>b:</code></li>
|
||||
</ul>
|
||||
<p>
|
||||
<code>g:</code>, <code>s:</code>, and <code>a:</code> must always
|
||||
be used.
|
||||
</p>
|
||||
<p>
|
||||
<code>b:</code> changes the variable semantics; use it when you
|
||||
want buffer-local semantics.
|
||||
</p>
|
||||
<p>
|
||||
<code>l:</code> and <code>v:</code> should be used for consistency,
|
||||
future proofing, and to avoid subtle bugs. They are not strictly
|
||||
required. Add them in new code but don’t go out of your way to add
|
||||
them elsewhere.
|
||||
</p>
|
||||
</SUBSECTION>
|
||||
</BODY>
|
||||
</STYLEPOINT>
|
||||
</CATEGORY>
|
||||
|
||||
<p align="right">
|
||||
Revision 1.1
|
||||
</p>
|
||||
|
||||
|
||||
<address>
|
||||
Nate Soares<br/>
|
||||
Joshua Hoak<br/>
|
||||
David Barnett<br/>
|
||||
</address>
|
||||
</GUIDE>
|
||||
681
xmlstyle.html
681
xmlstyle.html
|
|
@ -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). Document formats usually include both formal parts (DTDs, schemas) and parts expressed in normative English prose.<br><br>These guidelines apply to new designs, and are not intended to force retroactive changes in existing designs. When participating in the creation of public or private document format designs, the guidelines may be helpful but should not control the group consensus.<br><br>This guide is meant for the design of XML that is to be generated and consumed by machines rather than human beings. Its rules are <i>not applicable</i> to formats such as XHTML (which should be formatted as much like HTML as possible) or ODF which are meant to express rich text. A document that includes embedded content in XHTML or some other rich-text format, but also contains purely machine-interpretable portions, SHOULD follow this style guide for the machine-interpretable portions. It also does not affect XML document formats that are created by translations from proto buffers or through some other type of format.<br><br>Brief rationales have been added to most of the guidelines. They are maintained in the same document in hopes that they won't get out of date, but they are not considered normative.<br><br>The terms MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are used in this document in the sense of <a title="RFC 2119" href="http://www.ietf.org/rfc/rfc2119.txt" id="iecm">RFC 2119.</a><br> <br><h2>1. To design or not to design, that is the question<br></h2><ol><li>Attempt to reuse existing XML formats whenever possible, especially those which allow extensions. Creating an entirely new format should be done only with care and consideration; read <a title="Tim Bray's warnings" href="http://www.tbray.org/ongoing/When/200x/2006/01/08/No-New-XML-Languages" id="d3cy">Tim Bray's warnings</a> first. Try to get wide review of your format, from outside your organization as well, if possible. [<i>Rationale:</i> New document formats have a cost: they must be reviewed, documented, and learned by users.]<br><br></li><li>If you are reusing or extending an existing format, make <i>sensible</i>
|
||||
|
||||
use of the prescribed elements and attributes, especially any that are
|
||||
required. Don't completely repurpose them, but do try to see how they
|
||||
might be used in creative ways if the vanilla semantics aren't
|
||||
suitable. As a last resort when an element or attribute is required by the format but is not appropriate for your use case, use some
|
||||
fixed string as its value. [<i>Rationale:</i> Markup reuse is good, markup abuse is bad.]<br><br></li><li>When extending formats, use the implicit style of the existing format, even if it contradicts this guide. [<i>Rationale: </i>Consistency.]<br></li></ol><br><h2>2. Schemas</h2><ol><li>Document formats SHOULD be expressed using a schema language. [<i>Rationale: </i>Clarity and machine-checkability.]<br><br></li><li>The schema language SHOULD be <a title="RELAX NG" href="http://www.relaxng.org/" id="p1s7">RELAX NG</a> <a title="compact syntax" href="http://www.relaxng.org/compact-tutorial-20030326.html" id="ulci">compact syntax</a>. Embedded <a title="Schematron" href="http://www.schematron.com/" id="ymh-">Schematron</a> rules MAY be added to the schema for additional fine control. [<i>Rationale:</i>
|
||||
|
||||
RELAX NG is the most flexible schema language, with very few arbitrary
|
||||
restrictions on designs. The compact syntax is quite easy to read and
|
||||
learn, and can be converted one-to-one to and from the XML syntax when
|
||||
necessary. Schematron handles arbitrary cross-element and
|
||||
cross-attribute constraints nicely.]<br><br></li><li>Schemas SHOULD use the <a title=""Salami Slice" style" href="http://www.xfront.com/GlobalVersusLocal.html#SecondDesign" id="r:fj">"Salami Slice" style</a> (one rule per element). Schemas MAY use the <a title=""Russian Doll" style" href="http://www.xfront.com/GlobalVersusLocal.html#FirstDesign" id="h14y">"Russian Doll" style</a> (schema resembles document) if they are short and simple. The <a title=""Venetian Blind" style" href="http://www.xfront.com/GlobalVersusLocal.html#ThirdDesign" id="dr_g">"Venetian Blind" style</a> (one rule per element type) is unsuited to RELAX NG and SHOULD NOT be used.<br><br></li><li>Regular expressions SHOULD be provided to assist in validating complex values.<br><br></li><li>DTDs and/or W3C XML Schemas MAY be provided for compatibility with existing products, tools, or users. [<i>Rationale:</i> We can't change the world all at once.]<br></li></ol></div><div><br><h2>3. Namespaces</h2><ol><li>Element names MUST be in a namespace, except
|
||||
when extending pre-existing document types that do not use namespaces.
|
||||
|
||||
A default namespace SHOULD be used. [<i>Rationale:</i> Namespace-free
|
||||
documents are obsolete; every set of names should be in some
|
||||
namespace. Using a default namespace improves readability.]<br><br></li><li>Attribute
|
||||
names SHOULD NOT be in a namespace unless they are drawn from a foreign
|
||||
document type or are meant to be used in foreign document types. [<i>Rationale:</i> Attribute names in a namespace must always have a prefix, which is annoying to type and hard to read.]<br><br>
|
||||
</li><li>Namespace names are HTTP URIs. Namespace names SHOULD take the form <span style="font-family: Courier New;">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. There may be additional URI-path parts
|
||||
before the <i>year.</i> [<i>Rationale:</i> Existing convention. Providing the year allows for the possible recycling of code names.]<br><br></li><li>Namespaces MUST NOT be changed unless the semantics of particular elements or attributes has changed in drastically incompatible ways. [<i>Rationale:</i> Changing the namespace requires changing all client code.]<br><br></li><li>Namespace prefixes SHOULD be short (but not so short that they are likely to be conflict with another project). Single-letter prefixes MUST NOT be used. Prefixes SHOULD contain only lower-case ASCII letters. [<i>Rationale:</i> Ease of typing and absence of encoding compatibility problems.]</li></ol><br>
|
||||
|
||||
<h2>4. Names and enumerated values</h2><b>Note: </b>"Names" refers to the names of elements, attributes, and enumerated values.<br><br><ol><li>All names MUST use lowerCamelCase. That is, they start with an initial lower-case letter, then each new word within the name starts with an initial capital letter. [<i>Rationale:</i> Adopting a single style provides consistency, which helps when referring to names since the capitalization is known and so does not have to be remembered. It matches Java style, and other languages can be dealt with using automated name conversion.]<br><br></li><li>Names MUST contain only ASCII letters and digits.
|
||||
[<i>Rationale:</i> Ease of typing and absence of encoding compatibility problems.]<br> <br></li><li>Names SHOULD NOT exceed 25 characters. Longer names SHOULD be
|
||||
avoided by devising concise and informative names. If a name can only remain within this limit by becoming obscure, the limit SHOULD be ignored. [<i>Rationale: </i>Longer names are awkward to use and require additional bandwidth.]<br><br></li><li>Published standard abbreviations, if sufficiently well-known, MAY be employed in constructing names. Ad hoc abbreviations MUST NOT be used. Acronyms MUST be treated as words for camel-casing purposes: informationUri, not informationURI. [<i>Rationale:</i> An abbreviation that is well known
|
||||
to one community is often incomprehensible to others who need to use
|
||||
the same document format (and who do understand the full name); treating an acronym as a word makes it easier to see where the word boundaries are.] <br></li></ol><p><br></p><p>
|
||||
|
||||
</p><h2>
|
||||
5. Elements</h2><ol><li>All elements MUST contain either nothing, character content, or child elements. Mixed content MUST NOT be used. [<i>Rationale:</i> Many XML data models don't handle mixed content properly, and its use makes the element order-dependent. As always, textual formats are not covered by this rule.]<br><br></li><li>XML elements that merely wrap repeating child elements SHOULD NOT be used. [<i>Rationale:</i> They are not used in Atom and add nothing.]</li></ol>
|
||||
|
||||
<p><br></p><h2>6. Attributes</h2><ol><li>Document formats MUST NOT depend on the order of attributes in a start-tag. [<i>Rationale:</i> Few XML parsers report the order, and it is not part of the XML Infoset.]<br><br></li><li>Elements SHOULD NOT be overloaded with too many attributes (no more
|
||||
than 10 as a rule of thumb). Instead, use child elements to
|
||||
encapsulate closely related attributes. [<i>Rationale:</i> This
|
||||
approach maintains the built-in extensibility that XML provides with
|
||||
elements, and is useful for providing forward compatibility as a
|
||||
specification evolves.]<br><br></li><li>Attributes MUST NOT be used to hold values in which line breaks are significant. [<i>Rationale:</i> Such line breaks are converted to spaces by conformant XML parsers.]<br><br></li><li>Document formats MUST allow either single or double quotation marks around attribute values. [<i>Rationale:</i> XML parsers don't report the difference.]<br></li></ol>
|
||||
|
||||
<p><br></p>
|
||||
<p>
|
||||
</p><h2>
|
||||
7. Values</h2><ol><li>Numeric values SHOULD be 32-bit signed integers, 64-bit signed integers, or 64-bit IEEE doubles, all expressed in base 10. These correspond to the XML Schema types <span style="font-family: Courier New;">xsd:int</span>, <span style="font-family: Courier New;">xsd:long</span>, and <span style="font-family: Courier New;">xsd:double</span> respectively. If required in particular cases, <span style="font-family: Courier New;">xsd:integer</span> (unlimited-precision integer) values MAY also be used. [<i>Rationale:</i> There are far too many numeric types in XML Schema: these provide a reasonable subset.] <br><br></li><li>
|
||||
|
||||
Boolean values SHOULD NOT be used (use enumerations instead). If they must be used, they MUST be expressed as <span style="font-family: Courier New;">true</span> or <span style="font-family: Courier New;">false</span>, corresponding to a subset of the XML Schema type <span style="font-family: Courier New;">xsd:boolean</span>. The alternative <span style="font-family: Courier New;">xsd:boolean</span> values <span style="font-family: Courier New;">1</span> and <span style="font-family: Courier New;">0</span> MUST NOT be used. [<i>Rationale:</i> Boolean arguments are not extensible. The additional flexibility of allowing numeric values is not abstracted away by any parser.]<br><br></li><li>Dates should be represented using <a title="RFC 3339" href="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. UTC times SHOULD be used rather than local times.
|
||||
|
||||
[<i>Rationale:</i> There are far too many date formats and time zones, although it is recognized that sometimes local time preserves important information.]<br><br></li><li>Embedded syntax in character content and attribute values SHOULD NOT be
|
||||
used. Syntax in values means XML tools are largely useless. Syntaxes such as dates, URIs, and
|
||||
XPath expressions are exceptions. [<i>Rationale:</i>
|
||||
Users should be able to process XML documents using only an XML parser
|
||||
without requiring additional special-purpose parsers, which are easy to
|
||||
get wrong.]<br><br></li><li>Be careful with whitespace in values. XML parsers don't strip whitespace in elements, but do convert newlines to spaces in attributes. However, application frameworks may do more aggressive whitespace stripping. Your document format SHOULD give rules for whitespace stripping.<br></li></ol>
|
||||
|
||||
<p><br>
|
||||
</p>
|
||||
<p>
|
||||
</p><h2>8. Key-value pairs<br></h2><ol><li>
|
||||
Simple key-value pairs SHOULD be represented with an empty element whose name represents the key, with the <span style="font-family: Courier New;">value</span> attribute containing the value. Elements that have a <span style="font-family: Courier New;">value</span> attribute MAY also have a <span style="font-family: Courier New;">unit</span> attribute to specify the unit of a measured value. For physical measurements, the <a title="SI system" href="http://en.wikipedia.org/wiki/International_System_of_Units" id="rhxg">SI system</a> SHOULD be used. [<i>Rationale:</i>
|
||||
|
||||
Simplicity and design consistency. Keeping the value in an attribute
|
||||
hides it from the user, since displaying just the value without the key is not useful.]<br><br></li><li>If the number of possible keys is very large or unbounded, key-value pairs MAY be represented by a single generic element with <span style="font-family: Courier New;">key</span>, <span style="font-family: Courier New;">value</span>, and optional <span style="font-family: Courier New;">unit</span> and <span style="font-family: Courier New;">scheme</span>
|
||||
attributes (which serve to discriminate keys from different domains).
|
||||
In that case, also provide (not necessarily in the same document) a
|
||||
list of keys with human-readable explanations.</li></ol><br><h2>9. Binary data</h2><p><b>Note: </b>There are no hard and fast rules about whether binary data should be included as part of an XML document or not. If it's too large, it's probably better to link to it.</p><p><br></p><ol><li>Binary data MUST NOT be included directly as-is in XML documents, but MUST be encoded using Base64 encoding. [<i>Rationale:</i> XML does not allow arbitrary binary bytes.]<br><br></li><li>
|
||||
|
||||
The line breaks required by Base64 MAY be omitted. [<i>Rationale:</i> The line breaks are meant to keep plain text lines short, but XML is not really plain text.]<br><br></li><li>An attribute named <span style="font-family: Courier New;">xsi:type</span> with value <span style="font-family: Courier New;">xs:base64Binary</span> MAY be attached to this element to signal that the Base64 format is in use. [Rationale: Opaque blobs should have decoding instructions attached.]<br><br></li></ol>
|
||||
<h2>10. Processing instructions</h2><ol><li>New processing instructions MUST NOT be created except in order to specify purely local processing conventions, and SHOULD be avoided altogether. Existing standardized processing instructions MAY be used. [<i>Rationale:</i> Processing instructions fit awkwardly into XML data models and can always be replaced by elements; they exist primarily to avoid breaking backward compatibility.]</li></ol><p> </p>
|
||||
|
||||
<p>
|
||||
</p><p> </p><h2>11. Representation of XML document instances<br></h2><p><b>Note:</b> These points are only guidelines, as the format of program-created instances will often be outside the programmer's control (for example, when an XML serialization library is being used). <i>In no case</i> should XML parsers rely on these guidelines being followed. Use standard XML parsers, not hand-rolled hacks.<br></p><p><br></p><ol><li>The character encoding used SHOULD be UTF-8. Exceptions should require extremely compelling circumstances. [<i>Rationale:</i> UTF-8 is universal and in common use.]<br><br></li><li>Namespaces SHOULD be declared in the root element of a document wherever possible. [<i>Rationale: </i>Clarity and consistency.]<br><br></li><li>The mapping of namespace URIs to prefixes SHOULD remain constant throughout the document, and SHOULD also be used in documentation of the design. [<i>Rationale: </i>Clarity and consistency.]<br><br></li><li>Well-known prefixes such as html: (for XHTML), dc: (for Dublin Core metadata), and xs: (for XML Schema) should be used for standard namespaces. [<i>Rationale:</i> Human readability.]<br><br></li><li>Redundant whitespace in a tag SHOULD NOT be
|
||||
used. Use one space before each attribute in a start-tag; if the start
|
||||
tag is too long, the space MAY be replaced by a newline. [<i>Rationale:</i> Consistency and conciseness.]<br><br></li><li>Empty elements MAY be expressed as empty tags or a start-tag
|
||||
immediately followed by an end-tag. No distinction should be made
|
||||
between these two formats by any application. [<i>Rationale:</i> They are not distinguished by XML parsers.]<br><br></li><li>Documents MAY be pretty-printed using 2-space indentation for child
|
||||
elements. Elements that contain character content SHOULD NOT be
|
||||
wrapped. Long start-tags MAY be broken using newlines (possibly with extra indentation) after any attribute value except the last. [<i>Rationale:</i> General compatibility with our style. Wrapping character content affects its value.]<br><br></li><li>Attribute values MAY be surrounded with either quotation marks or apostrophes.
|
||||
Specifications MUST NOT require or forbid the use of either form. <span style="font-family: Courier New;">&apos;</span> and <span style="font-family: Courier New;">&quot;</span> may be freely used to escape each type of quote. [<i>Rationale:</i> No XML parsers report the distinction.]<br><br>
|
||||
|
||||
</li><li>Comments MUST NOT be used to carry real data. Comments MAY be used to contain TODOs in hand-written XML. Comments SHOULD NOT be used at all in publicly transmitted documents. [<i>Rationale: </i>Comments are often discarded by parsers.]<br><br></li><li>If comments are nevertheless used, they SHOULD appear only in the document prolog or in elements that
|
||||
contain child elements. If pretty-printing is required, pretty-print
|
||||
comments like elements, but with line wrapping. Comments SHOULD NOT
|
||||
appear in elements that contain character content. [<i>Rationale: </i>Whitespace in and around comments improves readability, but embedding a
|
||||
comment in character content can lead to confusion about what
|
||||
whitespace is or is not in the content.]<br><br></li><li>Comments SHOULD have whitespace following <span style="font-family: Courier New;"><!--</span> and preceding <span style="font-family: Courier New;">--></span>. [<i>Rationale:</i> Readability.]<br><br></li><li>CDATA sections MAY be used; they are equivalent to the use of <span style="font-family: Courier New;">&amp;</span> and <span style="font-family: Courier New;">&lt;</span>. Specifications MUST NOT require or forbid the use of CDATA sections. [<i>Rationale:</i> Few XML parsers report the distinction, and combinations of CDATA and text are often reported as single objects anyway.]<br><br></li><li>Entity references other than the XML standard entity references <span style="font-family: Courier New;">&amp;</span>, <span style="font-family: Courier New;">&lt;</span>, <span style="font-family: Courier New;">&gt;</span>, <span style="font-family: Courier New;">&quot;</span>, and <span style="font-family: Courier New;">&apos;</span> MUST NOT be used. Character references MAY be used, but actual characters are preferred, unless the character encoding is not UTF-8. As usual, textual formats are exempt from this rule.<br></li></ol>
|
||||
|
||||
<br><p> </p><p>
|
||||
</p>
|
||||
<p>
|
||||
</p><br><br><h2>
|
||||
12. Elements vs. Attributes
|
||||
</h2>
|
||||
<p>
|
||||
<b>Note:</b> There are no hard and fast rules for deciding when to use attributes and when to use elements. Here are some of the considerations that designers should take into account; no rationales are given.
|
||||
</p>
|
||||
<h3>
|
||||
12.1. General points:<br>
|
||||
</h3>
|
||||
|
||||
<ol>
|
||||
<li>
|
||||
<p>
|
||||
Attributes are more restrictive than elements, and all designs have some elements, so an all-element design is simplest -- which is not the same as best.
|
||||
</p>
|
||||
<p>
|
||||
<br>
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
In a tree-style data model, elements are typically represented internally as nodes, which use more memory than the strings used to represent attributes. Sometimes the nodes are of different application-specific classes, which in many languages also takes up memory to represent the classes.
|
||||
</p>
|
||||
<p>
|
||||
<br>
|
||||
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
When streaming, elements are processed one at a time (possibly even piece by piece, depending on the XML parser you are using), whereas all the attributes of an element and their values are reported at once, which costs memory, particularly if some attribute values are very long.
|
||||
</p>
|
||||
<p>
|
||||
<br>
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
Both element content and attribute values need to be escaped appropriately, so escaping should not be a consideration in the design.
|
||||
</p>
|
||||
<p>
|
||||
<br>
|
||||
</p>
|
||||
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
In some programming languages and libraries, processing elements is easier; in others, processing attributes is easier. Beware of using ease of processing as a criterion. In particular, XSLT can handle either with equal facility.
|
||||
</p>
|
||||
<p>
|
||||
<br>
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
If a piece of data should usually be shown to the user, consider using an element; if not, consider using an attribute. (This rule is often violated for one reason or another.)
|
||||
|
||||
</p>
|
||||
<p>
|
||||
<br>
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
If you are extending an existing schema, do things by analogy to how things are done in that schema.
|
||||
</p>
|
||||
<p>
|
||||
<br>
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
Sensible schema languages, meaning RELAX NG and Schematron, treat elements and attributes symmetrically. Older and cruder<a href="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. Similarly, if the data is a constituent part of some larger piece of data, put it in an element.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<br>
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
An exception to the previous rule: multiple whitespace-separated tokens can safely be put in an attribute. In principle, the separator can be anything, but schema-language validators are currently only able to handle whitespace, so it's best to stick with that.
|
||||
</p>
|
||||
<p>
|
||||
<br>
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
If a piece of data extends across multiple lines, use an element: XML parsers will change newlines in attribute values into spaces.
|
||||
|
||||
<br><br></p></li><li>If a piece of data is very large, use an element so that its content can be streamed.<br><br></li>
|
||||
<li>
|
||||
<p>
|
||||
If a piece of data is in a natural language, put it in an element so you can use the <span style="font-family: Courier New;">xml:lang</span> attribute to label the language being used. Some kinds of natural-language text, like Japanese, often make use <a href="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. For example, language tags, currency codes, medical diagnostic codes, etc. are best handled as attributes.
|
||||
</p>
|
||||
<p>
|
||||
<br>
|
||||
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
If a piece of data is really metadata on some other piece of data (for example, representing a class or role that the main data serves, or specifying a method of processing it), put it in an attribute if possible.
|
||||
</p>
|
||||
<p>
|
||||
<br>
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
In particular, if a piece of data is an ID for some other piece of data, or a reference to such an ID, put the identifying piece in an attribute. When it's an ID, use the name <span style="font-family: Courier New;">xml:id</span> for the attribute.
|
||||
|
||||
</p>
|
||||
<p>
|
||||
<br>
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
Hypertext references are conventionally put in <span style="font-family: Courier New;">href</span> attributes.
|
||||
</p>
|
||||
<p>
|
||||
<br>
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
|
||||
<p>
|
||||
If a piece of data is applicable to an element and any descendant elements unless it is overridden in some of them, it is conventional to put it in an attribute. Well-known examples are <span style="font-family: Courier New;">xml:lang</span>, <span style="font-family: Courier New;">xml:space</span>, <span style="font-family: Courier New;">xml:base</span>, and namespace declarations.
|
||||
</p>
|
||||
<p>
|
||||
<br>
|
||||
</p>
|
||||
</li>
|
||||
<li>
|
||||
<p>
|
||||
|
||||
If terseness is really the <i>most</i> important thing, use attributes, but consider <span style="font-family: Courier New;">gzip</span> compression instead -- it works very well on documents with highly repetitive structures.</p></li>
|
||||
</ol></div><br><div><div><div><div><div>
|
||||
<br><h2>13. Parting words
|
||||
</h2>
|
||||
<p>
|
||||
</p><p>
|
||||
Use common sense and <i>BE CONSISTENT</i>. Design for extensibility. You <i>are</i> gonna need it. [<i>Rationale:</i> Long and painful experience.]<br></p><p><br> </p>
|
||||
|
||||
<p>
|
||||
When designing XML formats, take a few minutes to look at other formats and determine their style. The point of having style guidelines is so that people can concentrate on what you are
|
||||
saying, rather than on how you are saying it. <br></p><p>
|
||||
<br>
|
||||
Break <i>ANY OR ALL</i> of these rules (yes, even the ones that say MUST) rather than create a crude, arbitrary, disgusting mess of a design if that's what following them slavishly would give you. In particular, random mixtures of attributes and child elements are hard to follow and hard to use, though it often makes good sense to use both when the data clearly fall into two different groups such as simple/complex or metadata/data.
|
||||
</p>
|
||||
<div><p>
|
||||
<br>
|
||||
Newbies always ask:
|
||||
</p>
|
||||
|
||||
<p>
|
||||
"Elements or attributes?
|
||||
</p>
|
||||
<p>
|
||||
Which will serve me best?"
|
||||
</p>
|
||||
<p>
|
||||
Those who know roar like lions;
|
||||
</p>
|
||||
<p>
|
||||
Wise hackers smile like tigers.
|
||||
</p>
|
||||
<p>
|
||||
--a <a href="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>
|
||||
Loading…
Reference in New Issue
Block a user