mirror of
https://github.com/google/styleguide.git
synced 2024-03-22 13:11:43 +08:00
Replaced HTTP where HTTPS been awailable.
This commit is contained in:
Ackermann Yuriy
parent
acb4f9016f
commit
7969290bac
28
README.md
28
README.md
|
|
@ -26,22 +26,22 @@ rules, it also contains advice on designing your own vs. adapting an existing
|
|||
format, on XML instance document formatting, and on elements vs. attributes.
|
||||
|
||||
These style guides are licensed under the CC-By 3.0 License, which encourages
|
||||
you to share these documents. See http://creativecommons.org/licenses/by/3.0/
|
||||
you to share these documents. See [https://creativecommons.org/licenses/by/3.0/](https://creativecommons.org/licenses/by/3.0/)
|
||||
for more details.
|
||||
|
||||
<a rel="license" href="http://creativecommons.org/licenses/by/3.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/3.0/88x31.png" /></a>
|
||||
<a rel="license" href="https://creativecommons.org/licenses/by/3.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/3.0/88x31.png" /></a>
|
||||
|
||||
[cpp]: http://google.github.io/styleguide/cppguide.html
|
||||
[objc]: http://google.github.io/styleguide/objcguide.xml
|
||||
[java]: http://google.github.io/styleguide/javaguide.html
|
||||
[py]: http://google.github.io/styleguide/pyguide.html
|
||||
[r]: http://google.github.io/styleguide/Rguide.xml
|
||||
[sh]: http://google.github.io/styleguide/shell.xml
|
||||
[htmlcss]: http://google.github.io/styleguide/htmlcssguide.xml
|
||||
[js]: http://google.github.io/styleguide/javascriptguide.xml
|
||||
[angular]: http://google.github.io/styleguide/angularjs-google-style.html
|
||||
[cl]: http://google.github.io/styleguide/lispguide.xml
|
||||
[vim]: http://google.github.io/styleguide/vimscriptguide.xml
|
||||
[cpp]: https://google.github.io/styleguide/cppguide.html
|
||||
[objc]: https://google.github.io/styleguide/objcguide.xml
|
||||
[java]: https://google.github.io/styleguide/javaguide.html
|
||||
[py]: https://google.github.io/styleguide/pyguide.html
|
||||
[r]: https://google.github.io/styleguide/Rguide.xml
|
||||
[sh]: https://google.github.io/styleguide/shell.xml
|
||||
[htmlcss]: https://google.github.io/styleguide/htmlcssguide.xml
|
||||
[js]: https://google.github.io/styleguide/javascriptguide.xml
|
||||
[angular]: https://google.github.io/styleguide/angularjs-google-style.html
|
||||
[cl]: https://google.github.io/styleguide/lispguide.xml
|
||||
[vim]: https://google.github.io/styleguide/vimscriptguide.xml
|
||||
[cpplint]: https://github.com/google/styleguide/tree/gh-pages/cpplint
|
||||
[emacs]: https://raw.githubusercontent.com/google/styleguide/gh-pages/google-c-style.el
|
||||
[xml]: http://google.github.io/styleguide/xmlstyle.html
|
||||
[xml]: https://google.github.io/styleguide/xmlstyle.html
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0"?>
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<html xmlns="https://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"/>
|
||||
|
|
@ -378,8 +378,8 @@ CalculateSampleCovariance <- function(x, y, verbose = TRUE) {
|
|||
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>.)
|
||||
<a href="https://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf">
|
||||
https://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
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd">
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "https://www.w3.org/TR/REC-html40/strict.dtd">
|
||||
<html>
|
||||
<head>
|
||||
<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
|
|
@ -21,24 +21,24 @@
|
|||
(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">
|
||||
supplements and extends the <a href="https://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">
|
||||
href="https://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">
|
||||
<a href="https://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">
|
||||
<a href="https://books.google.com/books/about/JavaScript.html?id=PXa2bby0oQ0C">
|
||||
Javascript, the Good Parts</a> as a counter.)</p>
|
||||
|
||||
<h5>1 Angular Language Rules</h5>
|
||||
|
|
@ -152,7 +152,7 @@ goog.provide('hello.versions.Versions');
|
|||
|
||||
<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">
|
||||
See <a href="https://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
|
||||
|
|
@ -343,8 +343,8 @@ module.service('request', hello.request.Request);
|
|||
|
||||
<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>
|
||||
<li><a href = "https://docs.angularjs.org/api/angular.mock.module">module</a>
|
||||
<li><a href="https://docs.angularjs.org/api/angular.mock.inject">inject</a>
|
||||
</ul>
|
||||
</p>
|
||||
|
||||
|
|
@ -385,7 +385,7 @@ my.app.MyCtrl = function($http, myService) {
|
|||
<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">
|
||||
<li><a href="https://www.youtube.com/watch?v=ZhfUv0spHCY">
|
||||
Meetup video</a> (not Google specific)</li>
|
||||
</ul>
|
||||
<address>
|
||||
|
|
|
|||
|
|
@ -617,7 +617,7 @@ bool UpdateInternals(Frobber* f, int newval) {
|
|||
|
||||
<p>Namespaces wrap the entire source file after
|
||||
includes,
|
||||
<a href="http://gflags.github.io/gflags/">
|
||||
<a href="https://gflags.github.io/gflags/">
|
||||
gflags</a> definitions/declarations
|
||||
and forward declarations of classes from other namespaces.</p>
|
||||
|
||||
|
|
@ -1155,7 +1155,7 @@ in some cases.</p>
|
|||
operations for them can be confusing, nonsensical, or outright
|
||||
incorrect. Copy/assigment operations for base class types are
|
||||
hazardous, because use of them can lead to
|
||||
<a href="http://en.wikipedia.org/wiki/Object_slicing">object
|
||||
<a href="https://en.wikipedia.org/wiki/Object_slicing">object
|
||||
slicing</a>. Defaulted or carelessly-implemented copy operations
|
||||
can be incorrect, and the resulting bugs can be confusing and
|
||||
difficult to diagnose.</p>
|
||||
|
|
@ -1689,7 +1689,7 @@ reasons, we allow data members of a test fixture class to
|
|||
be <code>protected</code> when using
|
||||
|
||||
|
||||
<a href="http://code.google.com/p/googletest/">Google
|
||||
<a href="https://code.google.com/p/googletest/">Google
|
||||
Test</a>).</p>
|
||||
</div>
|
||||
|
||||
|
|
@ -2715,7 +2715,7 @@ may select a different overload than you expect).</li>
|
|||
<li>The practice of building up output through chains
|
||||
of <code><<</code> operators interferes with
|
||||
internationalization, because it bakes word order into the
|
||||
code, and streams' support for localization is <a href="http://www.boost.org/doc/libs/1_48_0/libs/locale/doc/html/rationale.html#rationale_why">
|
||||
code, and streams' support for localization is <a href="https://www.boost.org/doc/libs/1_48_0/libs/locale/doc/html/rationale.html#rationale_why">
|
||||
flawed</a>.</li>
|
||||
|
||||
|
||||
|
|
@ -3763,7 +3763,7 @@ collection.</p>
|
|||
|
||||
<div class="definition">
|
||||
<p> The
|
||||
<a href="http://www.boost.org/">
|
||||
<a href="https://www.boost.org/">
|
||||
Boost library collection</a> is a popular collection of
|
||||
peer-reviewed, free, open-source C++ libraries.</p>
|
||||
</div>
|
||||
|
|
@ -3793,27 +3793,27 @@ Currently, the following libraries are permitted:</p>
|
|||
|
||||
<ul>
|
||||
<li>
|
||||
<a href="http://www.boost.org/libs/utility/call_traits.htm">
|
||||
<a href="https://www.boost.org/libs/utility/call_traits.htm">
|
||||
Call Traits</a> from <code>boost/call_traits.hpp</code></li>
|
||||
|
||||
<li><a href="http://www.boost.org/libs/utility/compressed_pair.htm">
|
||||
<li><a href="https://www.boost.org/libs/utility/compressed_pair.htm">
|
||||
Compressed Pair</a> from <code>boost/compressed_pair.hpp</code></li>
|
||||
|
||||
<li><a href="http://www.boost.org/libs/graph/">
|
||||
<li><a href="https://www.boost.org/libs/graph/">
|
||||
The Boost Graph Library (BGL)</a> from <code>boost/graph</code>,
|
||||
except serialization (<code>adj_list_serialize.hpp</code>) and
|
||||
parallel/distributed algorithms and data structures
|
||||
(<code>boost/graph/parallel/*</code> and
|
||||
<code>boost/graph/distributed/*</code>).</li>
|
||||
|
||||
<li><a href="http://www.boost.org/libs/property_map/">
|
||||
<li><a href="https://www.boost.org/libs/property_map/">
|
||||
Property Map</a> from <code>boost/property_map</code>, except
|
||||
parallel/distributed property maps (<code>boost/property_map/parallel/*</code>).</li>
|
||||
|
||||
<li><a href="http://www.boost.org/libs/iterator/">
|
||||
<li><a href="https://www.boost.org/libs/iterator/">
|
||||
Iterator</a> from <code>boost/iterator</code></li>
|
||||
|
||||
<li>The part of <a href="http://www.boost.org/libs/polygon/">
|
||||
<li>The part of <a href="https://www.boost.org/libs/polygon/">
|
||||
Polygon</a> that deals with Voronoi diagram
|
||||
construction and doesn't depend on the rest of
|
||||
Polygon:
|
||||
|
|
@ -3821,25 +3821,25 @@ Currently, the following libraries are permitted:</p>
|
|||
<code>boost/polygon/voronoi_diagram.hpp</code>, and
|
||||
<code>boost/polygon/voronoi_geometry_type.hpp</code></li>
|
||||
|
||||
<li><a href="http://www.boost.org/libs/bimap/">
|
||||
<li><a href="https://www.boost.org/libs/bimap/">
|
||||
Bimap</a> from <code>boost/bimap</code></li>
|
||||
|
||||
<li><a href="http://www.boost.org/libs/math/doc/html/dist.html">
|
||||
<li><a href="https://www.boost.org/libs/math/doc/html/dist.html">
|
||||
Statistical Distributions and Functions</a> from
|
||||
<code>boost/math/distributions</code></li>
|
||||
|
||||
<li><a href="http://www.boost.org/libs/multi_index/">
|
||||
<li><a href="https://www.boost.org/libs/multi_index/">
|
||||
Multi-index</a> from <code>boost/multi_index</code></li>
|
||||
|
||||
<li><a href="http://www.boost.org/libs/heap/">
|
||||
<li><a href="https://www.boost.org/libs/heap/">
|
||||
Heap</a> from <code>boost/heap</code></li>
|
||||
|
||||
<li>The flat containers from <a href="http://www.boost.org/libs/container/">
|
||||
<li>The flat containers from <a href="https://www.boost.org/libs/container/">
|
||||
Container</a>:
|
||||
<code>boost/container/flat_map</code>, and
|
||||
<code>boost/container/flat_set</code></li>
|
||||
|
||||
<li><a href="http://www.boost.org/libs/intrusive/">
|
||||
<li><a href="https://www.boost.org/libs/intrusive/">
|
||||
Intrusive</a> from <code>boost/intrusive</code>.</li>
|
||||
</ul>
|
||||
|
||||
|
|
@ -3853,12 +3853,12 @@ is discouraged because they've been superseded by
|
|||
standard libraries in C++11:</p>
|
||||
|
||||
<ul>
|
||||
<li><a href="http://www.boost.org/libs/array/">
|
||||
<li><a href="https://www.boost.org/libs/array/">
|
||||
Array</a> from <code>boost/array.hpp</code>: use
|
||||
<a href="http://en.cppreference.com/w/cpp/container/array">
|
||||
<code>std::array</code></a> instead.</li>
|
||||
|
||||
<li><a href="http://www.boost.org/libs/ptr_container/">
|
||||
<li><a href="https://www.boost.org/libs/ptr_container/">
|
||||
Pointer Container</a> from <code>boost/ptr_container</code>: use containers of
|
||||
<a href="http://en.cppreference.com/w/cpp/memory/unique_ptr">
|
||||
<code>std::unique_ptr</code></a> instead.</li>
|
||||
|
|
@ -3910,7 +3910,7 @@ the former, but the latter requires expertise that a type author
|
|||
usually doesn't have, and shouldn't need. The stakes here are high
|
||||
because low-quality hash functions can be security vulnerabilities,
|
||||
due to the emergence of
|
||||
<a href="http://emboss.github.io/blog/2012/12/14/breaking-murmur-hash-flooding-dos-reloaded/">
|
||||
<a href="https://emboss.github.io/blog/2012/12/14/breaking-murmur-hash-flooding-dos-reloaded/">
|
||||
hash flooding attacks</a>.</p>
|
||||
|
||||
<p>Even for experts, <code>std::hash</code> specializations are
|
||||
|
|
@ -3963,7 +3963,7 @@ project. </p>
|
|||
<div class="stylebody">
|
||||
|
||||
<div class="definition">
|
||||
<p> C++11 contains <a href="http://en.wikipedia.org/wiki/C%2B%2B11">
|
||||
<p> C++11 contains <a href="https://en.wikipedia.org/wiki/C%2B%2B11">
|
||||
significant changes</a> both to the language and
|
||||
libraries. </p>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
This is automated checker to make sure a C++ file follows Google's C++ style
|
||||
guide (http://google.github.io/styleguide/cppguide.html). As it
|
||||
guide [https://google.github.io/styleguide/cppguide.html](https://google.github.io/styleguide/cppguide.html). As it
|
||||
heavily relies on regular expressions, cpplint.py won't catch all violations of
|
||||
the style guide and will very occasionally report a false positive. There is a
|
||||
list of things we currently don't handle very well at the top of cpplint.py,
|
||||
|
|
|
|||
6
cpplint/cpplint.py
vendored
6
cpplint/cpplint.py
vendored
|
|
@ -60,7 +60,7 @@ Syntax: cpplint.py [--verbose=#] [--output=vs7] [--filter=-x,+y,...]
|
|||
<file> [file] ...
|
||||
|
||||
The style guidelines this tries to follow are those in
|
||||
http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
|
||||
https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
|
||||
|
||||
Every problem is given a confidence score from 1-5, with 5 meaning we are
|
||||
certain of the problem, and 1 meaning it could be a legitimate construct.
|
||||
|
|
@ -2844,7 +2844,7 @@ def CheckForFunctionLengths(filename, clean_lines, linenum,
|
|||
"""Reports for long function bodies.
|
||||
|
||||
For an overview why this is done, see:
|
||||
http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Write_Short_Functions
|
||||
https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Write_Short_Functions
|
||||
|
||||
Uses a simplistic algorithm assuming other style guidelines
|
||||
(especially spacing) are followed.
|
||||
|
|
@ -4912,7 +4912,7 @@ def CheckLanguage(filename, clean_lines, linenum, file_extension,
|
|||
and line[-1] != '\\'):
|
||||
error(filename, linenum, 'build/namespaces', 4,
|
||||
'Do not use unnamed namespaces in header files. See '
|
||||
'http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Namespaces'
|
||||
'https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Namespaces'
|
||||
' for more information.')
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -3794,7 +3794,7 @@ class CpplintTest(CpplintTestBase):
|
|||
self.TestLanguageRulesCheck(
|
||||
'foo.h', 'namespace {',
|
||||
'Do not use unnamed namespaces in header files. See'
|
||||
' http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Namespaces'
|
||||
' https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Namespaces'
|
||||
' for more information. [build/namespaces] [4]')
|
||||
# namespace registration macros are OK.
|
||||
self.TestLanguageRulesCheck('foo.h', 'namespace { \\', '')
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# Documentation Best Practices
|
||||
|
||||
"Say what you mean, simply and directly." - [Brian Kernighan]
|
||||
(http://en.wikipedia.org/wiki/The_Elements_of_Programming_Style)
|
||||
(https://en.wikipedia.org/wiki/The_Elements_of_Programming_Style)
|
||||
|
||||
Contents:
|
||||
|
||||
|
|
|
|||
|
|
@ -366,8 +366,8 @@ 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.
|
||||
Apple | [Juicy](https://example.com/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Firm, Sweet | Apples keep doctors away.
|
||||
Banana | [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery), Soft, Sweet | Contrary to popular belief, most apes prefer mangoes.
|
||||
|
||||
DO NOT DO THIS
|
||||
```
|
||||
|
|
@ -380,7 +380,7 @@ in a slightly less compact, though much more edit-friendly way:
|
|||
|
||||
### Apple
|
||||
|
||||
* [Juicy](http://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)
|
||||
* [Juicy](https://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL)
|
||||
* Firm
|
||||
* Sweet
|
||||
|
||||
|
|
@ -388,7 +388,7 @@ Apples keep doctors away.
|
|||
|
||||
### Banana
|
||||
|
||||
* [Convenient](http://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery)
|
||||
* [Convenient](https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery)
|
||||
* Soft
|
||||
* Sweet
|
||||
|
||||
|
|
|
|||
|
|
@ -58,7 +58,7 @@
|
|||
</p>
|
||||
<BAD_CODE_SNIPPET>
|
||||
<!-- Not recommended -->
|
||||
<script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script>
|
||||
<script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>
|
||||
</BAD_CODE_SNIPPET>
|
||||
<CODE_SNIPPET>
|
||||
<!-- Recommended -->
|
||||
|
|
@ -67,7 +67,7 @@
|
|||
<BAD_CODE_SNIPPET>
|
||||
/* Not recommended */
|
||||
.example {
|
||||
background: url(http://www.google.com/images/example);
|
||||
background: url(https://www.google.com/images/example);
|
||||
}
|
||||
</BAD_CODE_SNIPPET>
|
||||
<CODE_SNIPPET>
|
||||
|
|
@ -170,7 +170,7 @@
|
|||
</p>
|
||||
<p>
|
||||
(More on encodings and when and how to specify them can be
|
||||
found in <a href="http://www.w3.org/International/tutorials/tutorial-char-enc/">Handling
|
||||
found in <a href="https://www.w3.org/International/tutorials/tutorial-char-enc/">Handling
|
||||
character encodings in HTML and CSS</a>.)
|
||||
</p>
|
||||
</BODY>
|
||||
|
|
@ -239,7 +239,7 @@
|
|||
</p>
|
||||
<p>
|
||||
(It’s recommended to use HTML, as <code>text/html</code>. Do not use
|
||||
XHTML. XHTML, as <a href="http://hixie.ch/advocacy/xhtml"><code>application/xhtml+xml</code></a>,
|
||||
XHTML. XHTML, as <a href="https://hixie.ch/advocacy/xhtml"><code>application/xhtml+xml</code></a>,
|
||||
lacks both browser and infrastructure support and offers
|
||||
less room for optimization than HTML.)
|
||||
</p>
|
||||
|
|
@ -260,7 +260,7 @@
|
|||
</p>
|
||||
|
||||
<p>
|
||||
Use tools such as the <a href="http://validator.w3.org/nu/">W3C
|
||||
Use tools such as the <a href="https://validator.w3.org/nu/">W3C
|
||||
HTML validator</a> to test.
|
||||
</p>
|
||||
<p>
|
||||
|
|
@ -435,7 +435,7 @@
|
|||
<p>
|
||||
For file size optimization and scannability purposes,
|
||||
consider omitting optional tags.
|
||||
The <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/syntax.html#syntax-tag-omission">HTML5
|
||||
The <a href="https://whatwg.org/specs/web-apps/current-work/multipage/syntax.html#syntax-tag-omission">HTML5
|
||||
specification</a> defines what tags can be omitted.
|
||||
</p>
|
||||
<p>
|
||||
|
|
@ -478,9 +478,9 @@
|
|||
<p>
|
||||
Specifying <code>type</code> attributes in these contexts is
|
||||
not necessary as HTML5 implies
|
||||
<a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#attr-style-type"><code>text/css</code></a>
|
||||
<a href="https://whatwg.org/specs/web-apps/current-work/multipage/semantics.html#attr-style-type"><code>text/css</code></a>
|
||||
and
|
||||
<a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#attr-script-type"><code>text/javascript</code></a>
|
||||
<a href="https://whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#attr-script-type"><code>text/javascript</code></a>
|
||||
as defaults. This can be safely done even for older browsers.
|
||||
</p>
|
||||
<BAD_CODE_SNIPPET>
|
||||
|
|
@ -587,7 +587,7 @@
|
|||
</p>
|
||||
|
||||
<p>
|
||||
Use tools such as the <a href="http://jigsaw.w3.org/css-validator/">W3C
|
||||
Use tools such as the <a href="https://jigsaw.w3.org/css-validator/">W3C
|
||||
CSS validator</a> to test.
|
||||
</p>
|
||||
<p>
|
||||
|
|
@ -698,7 +698,7 @@
|
|||
</SUMMARY>
|
||||
<BODY>
|
||||
<p>
|
||||
CSS offers a variety of <a href="http://www.w3.org/TR/CSS21/about.html#shorthand">shorthand</a>
|
||||
CSS offers a variety of <a href="https://www.w3.org/TR/CSS21/about.html#shorthand">shorthand</a>
|
||||
properties (like <code>font</code>)
|
||||
that should be used whenever possible, even in cases where
|
||||
only one value is explicitly set.
|
||||
|
|
@ -880,7 +880,7 @@
|
|||
</SUMMARY>
|
||||
<BODY>
|
||||
<p>
|
||||
Indent all <a href="http://www.w3.org/TR/CSS21/syndata.html#block">block
|
||||
Indent all <a href="https://www.w3.org/TR/CSS21/syndata.html#block">block
|
||||
content</a>, that is rules within rules as well as declarations, so to
|
||||
reflect hierarchy and improve understanding.
|
||||
</p>
|
||||
|
|
@ -951,7 +951,7 @@
|
|||
<BODY>
|
||||
<p>
|
||||
Always use a single space between the last selector and the opening
|
||||
brace that begins the <a href="http://www.w3.org/TR/CSS21/syndata.html#rule-sets">declaration
|
||||
brace that begins the <a href="https://www.w3.org/TR/CSS21/syndata.html#rule-sets">declaration
|
||||
block</a>.
|
||||
</p>
|
||||
<p>
|
||||
|
|
@ -1035,7 +1035,7 @@
|
|||
</p>
|
||||
<p>
|
||||
Exception: If you do need to use the <code>@charset</code> rule,
|
||||
use double quotation marks—<a href="http://www.w3.org/TR/CSS21/syndata.html#charset">single
|
||||
use double quotation marks—<a href="https://www.w3.org/TR/CSS21/syndata.html#charset">single
|
||||
quotation marks are not permitted</a>.
|
||||
</p>
|
||||
<BAD_CODE_SNIPPET>
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
<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"
|
||||
<link href="https://www.google.com/favicon.ico"
|
||||
type="image/x-icon" rel="shortcut icon" />
|
||||
<title>Google Java Style</title>
|
||||
</head>
|
||||
|
|
@ -353,7 +353,7 @@ the body of a class, method or constructor. Note that, by Section 4.8.3.1 on
|
|||
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>")
|
||||
("<a href="https://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
|
||||
|
|
@ -729,7 +729,7 @@ Foo.aStaticMethod(); // good
|
|||
</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>
|
||||
<a href="https://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"/>
|
||||
|
|
|
|||
|
|
@ -355,7 +355,7 @@
|
|||
first appear! </p>
|
||||
|
||||
<p>For that reason, it is best to use <code>goog.inherits()</code> from
|
||||
<a href="http://code.google.com/closure/library/">
|
||||
<a href="https://code.google.com/closure/library/">
|
||||
the Closure Library
|
||||
</a>
|
||||
or a similar library function.
|
||||
|
|
@ -804,7 +804,7 @@
|
|||
|
||||
|
||||
<p>Many JavaScript libraries, including
|
||||
<a href="http://code.google.com/closure/library/">
|
||||
<a href="https://code.google.com/closure/library/">
|
||||
the Closure Library
|
||||
</a>
|
||||
and
|
||||
|
|
@ -1135,7 +1135,7 @@
|
|||
<a href="https://docs.google.com/document/pub?id=1ETFAuh2kaXMVL-vafUYhaWlhl6b5D9TOvboVg7Zl68Y"><code>goog.scope</code></a>
|
||||
may be used to shorten references to
|
||||
namespaced symbols in programs using
|
||||
<a href="http://code.google.com/closure/library/">the Closure
|
||||
<a href="https://code.google.com/closure/library/">the Closure
|
||||
Library</a>.</p>
|
||||
<p>Only one <code>goog.scope</code> invocation may be added per
|
||||
file. Always place it in the global scope.</p>
|
||||
|
|
@ -1301,7 +1301,7 @@
|
|||
functions, and properties.</p>
|
||||
<p>The --jscomp_warning=visibility compiler flag turns on compiler
|
||||
warnings for visibility violations. See
|
||||
<a href="http://code.google.com/p/closure-compiler/wiki/Warnings">
|
||||
<a href="https://code.google.com/p/closure-compiler/wiki/Warnings">
|
||||
Closure Compiler
|
||||
Warnings</a>.
|
||||
</p>
|
||||
|
|
@ -2220,7 +2220,7 @@
|
|||
</p>
|
||||
|
||||
<p>All files, classes, methods and properties should be documented with
|
||||
<a href="http://code.google.com/p/jsdoc-toolkit/">JSDoc</a>
|
||||
<a href="https://code.google.com/p/jsdoc-toolkit/">JSDoc</a>
|
||||
comments with the appropriate <a href="#JSDoc_Tag_Reference">tags</a>
|
||||
and <a href="#JsTypes">types</a>. Textual descriptions for properties,
|
||||
methods, method parameters and method return values should be included
|
||||
|
|
@ -2235,7 +2235,7 @@
|
|||
|
||||
<SUBSECTION title="Comment Syntax">
|
||||
<p>The JSDoc syntax is based on
|
||||
<a href="http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html">
|
||||
<a href="https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html">
|
||||
JavaDoc</a>. Many tools extract metadata from JSDoc comments to
|
||||
perform code validation and optimizations. These comments must be
|
||||
well-formed.</p>
|
||||
|
|
@ -2322,7 +2322,7 @@
|
|||
*/
|
||||
</CODE_SNIPPET>
|
||||
|
||||
The <a href="http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html">
|
||||
The <a href="https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html">
|
||||
JavaDoc</a> style guide is a useful resource on how to write
|
||||
well-formed doc comments.
|
||||
</SUBSECTION>
|
||||
|
|
@ -2860,7 +2860,7 @@
|
|||
For example, <code>@type {Foo}</code> means "an instance of Foo",
|
||||
but <code>@lends {Foo}</code> means "the constructor Foo".<p/>
|
||||
|
||||
The <a href="http://code.google.com/p/jsdoc-toolkit/wiki/TagLends">
|
||||
The <a href="https://code.google.com/p/jsdoc-toolkit/wiki/TagLends">
|
||||
JSDoc Toolkit docs</a> have more information on this
|
||||
annotation.
|
||||
</td>
|
||||
|
|
@ -3313,7 +3313,7 @@
|
|||
<p>
|
||||
You may also see other types of JSDoc annotations in third-party
|
||||
code. These annotations appear in the
|
||||
<a href="http://code.google.com/p/jsdoc-toolkit/wiki/TagReference">
|
||||
<a href="https://code.google.com/p/jsdoc-toolkit/wiki/TagReference">
|
||||
JSDoc Toolkit Tag Reference
|
||||
</a>
|
||||
but are currently discouraged in Google code. You should consider
|
||||
|
|
@ -3389,7 +3389,7 @@
|
|||
|
||||
|
||||
<p>Use of JS compilers such as the
|
||||
<a href="http://code.google.com/closure/compiler/">Closure Compiler</a>
|
||||
<a href="https://code.google.com/closure/compiler/">Closure Compiler</a>
|
||||
is required for all customer-facing code.</p>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -70,7 +70,7 @@ Data should not be arbitrarily grouped for convenience.
|
|||
<CODE_SNIPPET>
|
||||
{
|
||||
"company": "Google",
|
||||
"website": "http://www.google.com/",
|
||||
"website": "https://www.google.com/",
|
||||
"addressLine1": "111 8th Ave",
|
||||
"addressLine2": "4th Floor",
|
||||
"state": "NY",
|
||||
|
|
@ -82,7 +82,7 @@ Data should not be arbitrarily grouped for convenience.
|
|||
<CODE_SNIPPET>
|
||||
{
|
||||
"company": "Google",
|
||||
"website": "http://www.google.com/",
|
||||
"website": "https://www.google.com/",
|
||||
"address": {
|
||||
"line1": "111 8th Ave",
|
||||
"line2": "4th Floor",
|
||||
|
|
@ -292,7 +292,7 @@ public enum Color {
|
|||
Dates should be formatted as recommended by RFC 3339.
|
||||
</SUMMARY>
|
||||
<BODY>
|
||||
<p>Dates should be strings formatted as recommended by <a href="http://www.ietf.org/rfc/rfc3339.txt">RFC 3339</a></p>
|
||||
<p>Dates should be strings formatted as recommended by <a href="https://www.ietf.org/rfc/rfc3339.txt">RFC 3339</a></p>
|
||||
<CODE_SNIPPET>
|
||||
{
|
||||
"lastUpdate": "2007-11-06T16:34:41.000Z"
|
||||
|
|
@ -306,7 +306,7 @@ Dates should be formatted as recommended by RFC 3339.
|
|||
Time durations should be formatted as recommended by ISO 8601.
|
||||
</SUMMARY>
|
||||
<BODY>
|
||||
<p>Time duration values should be strings formatted as recommended by <a href="http://en.wikipedia.org/wiki/ISO_8601#Durations">ISO 8601</a>.</p>
|
||||
<p>Time duration values should be strings formatted as recommended by <a href="https://en.wikipedia.org/wiki/ISO_8601#Durations">ISO 8601</a>.</p>
|
||||
<CODE_SNIPPET>
|
||||
{
|
||||
// three years, six months, four days, twelve hours,
|
||||
|
|
@ -322,7 +322,7 @@ Time durations should be formatted as recommended by ISO 8601.
|
|||
Latitudes/Longitudes should be formatted as recommended by ISO 6709.
|
||||
</SUMMARY>
|
||||
<BODY>
|
||||
<p>Latitude/Longitude should be strings formatted as recommended by <a href="http://en.wikipedia.org/wiki/ISO_6709">ISO 6709</a>. Furthermore, they should favor the ±DD.DDDD±DDD.DDDD degrees format.</p>
|
||||
<p>Latitude/Longitude should be strings formatted as recommended by <a href="https://en.wikipedia.org/wiki/ISO_6709">ISO 6709</a>. Furthermore, they should favor the ±DD.DDDD±DDD.DDDD degrees format.</p>
|
||||
<CODE_SNIPPET>
|
||||
{
|
||||
// The latitude/longitude location of the statue of liberty.
|
||||
|
|
@ -334,7 +334,7 @@ Latitudes/Longitudes should be formatted as recommended by ISO 6709.
|
|||
</STYLEPOINT>
|
||||
</CATEGORY>
|
||||
<CATEGORY title="JSON Structure & Reserved Property Names">
|
||||
<p>In order to maintain a consistent interface across APIs, JSON objects should follow the structure outlined below. This structure applies to both requests and responses made with JSON. Within this structure, there are certain property names that are reserved for specific uses. These properties are NOT required; in other words, each reserved property may appear zero or one times. But if a service needs these properties, this naming convention is recommend. Here is a schema of the JSON structure, represented in <a href="http://www.google.com/url?sa=D&q=http%3A%2F%2Forderly-json.org%2F">Orderly</a> format (which in turn can be compiled into a <a href="http://www.google.com/url?sa=D&q=http%3A%2F%2Fjson-schema.org%2F">JSONSchema</a>). You can few examples of the JSON structure at the end of this guide.</p>
|
||||
<p>In order to maintain a consistent interface across APIs, JSON objects should follow the structure outlined below. This structure applies to both requests and responses made with JSON. Within this structure, there are certain property names that are reserved for specific uses. These properties are NOT required; in other words, each reserved property may appear zero or one times. But if a service needs these properties, this naming convention is recommend. Here is a schema of the JSON structure, represented in <a href="https://www.google.com/url?sa=D&q=http%3A%2F%2Forderly-json.org%2F">Orderly</a> format (which in turn can be compiled into a <a href="https://www.google.com/url?sa=D&q=http%3A%2F%2Fjson-schema.org%2F">JSONSchema</a>). You can few examples of the JSON structure at the end of this guide.</p>
|
||||
<CODE_SNIPPET>
|
||||
object {
|
||||
string apiVersion?;
|
||||
|
|
@ -412,12 +412,12 @@ Property Value Type: string<br />Parent: -
|
|||
<BODY>
|
||||
<p>Client sets this value and server echos data in the response. This is useful in JSON-P and batch situations , where the user can use the <code>context</code> to correlate responses with requests. This property is a top-level property because the <code>context</code> should present regardless of whether the response was successful or an error. <code>context</code> differs from <code>id</code> in that <code>context</code> is specified by the user while <code>id</code> is assigned by the service.</p><p>Example:</p><p>Request #1:</p>
|
||||
<CODE_SNIPPET>
|
||||
http://www.google.com/myapi?context=bart
|
||||
https://www.google.com/myapi?context=bart
|
||||
|
||||
</CODE_SNIPPET>
|
||||
<p>Request #2:</p>
|
||||
<CODE_SNIPPET>
|
||||
http://www.google.com/myapi?context=lisa
|
||||
https://www.google.com/myapi?context=lisa
|
||||
|
||||
</CODE_SNIPPET>
|
||||
<p>Response #1:</p>
|
||||
|
|
@ -572,7 +572,7 @@ Property Value Type: string<br />Parent: <code>data</code>
|
|||
Property Value Type: string<br />Parent: <code>data</code>
|
||||
</SUMMARY>
|
||||
<BODY>
|
||||
<p>Represents the etag for the response. Details about ETags in the GData APIs can be found here: <a href="http://code.google.com/apis/gdata/docs/2.0/reference.html#ResourceVersioning">http://code.google.com/apis/gdata/docs/2.0/reference.html#ResourceVersioning</a></p><p>Example:</p>
|
||||
<p>Represents the etag for the response. Details about ETags in the GData APIs can be found here: <a href="https://code.google.com/apis/gdata/docs/2.0/reference.html#ResourceVersioning">https://code.google.com/apis/gdata/docs/2.0/reference.html#ResourceVersioning</a></p><p>Example:</p>
|
||||
<CODE_SNIPPET>
|
||||
{"data": {"etag": "W/"C0QBRXcycSp7ImA9WxRVFUk.""}}
|
||||
|
||||
|
|
@ -596,7 +596,7 @@ Property Value Type: string<br />Parent: <code>data</code>
|
|||
Property Value Type: string (formatted as specified in BCP 47)<br />Parent: <code>data (or any child element)</code>
|
||||
</SUMMARY>
|
||||
<BODY>
|
||||
<p>Indicates the language of the rest of the properties in this object. This property mimics HTML's <code>lang</code> property and XML's <code>xml:lang</code> properties. The value should be a language value as defined in <a href="http://www.rfc-editor.org/rfc/bcp/bcp47.txt">BCP 47</a>. If a single JSON object contains data in multiple languages, the service is responsible for developing and documenting an appropriate location for the <code>lang</code> property.</p><p>Example:</p>
|
||||
<p>Indicates the language of the rest of the properties in this object. This property mimics HTML's <code>lang</code> property and XML's <code>xml:lang</code> properties. The value should be a language value as defined in <a href="https://www.rfc-editor.org/rfc/bcp/bcp47.txt">BCP 47</a>. If a single JSON object contains data in multiple languages, the service is responsible for developing and documenting an appropriate location for the <code>lang</code> property.</p><p>Example:</p>
|
||||
<CODE_SNIPPET>
|
||||
{"data": {
|
||||
"items": [
|
||||
|
|
@ -614,7 +614,7 @@ Property Value Type: string (formatted as specified in BCP 47)<br />Parent: <cod
|
|||
Property Value Type: string (formatted as specified in RFC 3339)<br />Parent: <code>data</code>
|
||||
</SUMMARY>
|
||||
<BODY>
|
||||
<p>Indicates the last date/time (<a href="http://www.ietf.org/rfc/rfc3339.txt">RFC 3339</a>) the item was updated, as defined by the service.</p><p>Example:</p>
|
||||
<p>Indicates the last date/time (<a href="https://www.ietf.org/rfc/rfc3339.txt">RFC 3339</a>) the item was updated, as defined by the service.</p><p>Example:</p>
|
||||
<CODE_SNIPPET>
|
||||
{"data": {"updated": "2007-11-06T16:34:41.000Z"}}
|
||||
|
||||
|
|
@ -737,7 +737,7 @@ Property Value Type: string<br />Parent: <code>data</code>
|
|||
<CODE_SNIPPET>
|
||||
{
|
||||
"data": {
|
||||
"pagingLinkTemplate": "http://www.google.com/search/hl=en&q=chicago+style+pizza&start={index}&sa=N"
|
||||
"pagingLinkTemplate": "https://www.google.com/search/hl=en&q=chicago+style+pizza&start={index}&sa=N"
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -789,7 +789,7 @@ Property Value Type: object / string<br />Parent: <code>data</code>
|
|||
{
|
||||
"data": {
|
||||
"self": { },
|
||||
"selfLink": "http://www.google.com/feeds/album/1234"
|
||||
"selfLink": "https://www.google.com/feeds/album/1234"
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -806,7 +806,7 @@ Property Value Type: object / string<br />Parent: <code>data</code>
|
|||
{
|
||||
"data": {
|
||||
"edit": { },
|
||||
"editLink": "http://www.google.com/feeds/album/1234/edit"
|
||||
"editLink": "https://www.google.com/feeds/album/1234/edit"
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -823,7 +823,7 @@ Property Value Type: object / string<br />Parent: <code>data</code>
|
|||
{
|
||||
"data": {
|
||||
"next": { },
|
||||
"nextLink": "http://www.google.com/feeds/album/1234/next"
|
||||
"nextLink": "https://www.google.com/feeds/album/1234/next"
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -840,7 +840,7 @@ Property Value Type: object / string<br />Parent: <code>data</code>
|
|||
{
|
||||
"data": {
|
||||
"previous": { },
|
||||
"previousLink": "http://www.google.com/feeds/album/1234/next"
|
||||
"previousLink": "https://www.google.com/feeds/album/1234/next"
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -1001,7 +1001,7 @@ Property Value Type: string<br />Parent: <code>error.errors</code>
|
|||
<CODE_SNIPPET>
|
||||
{
|
||||
"error":{
|
||||
"errors": [{"sendReport": "http://report.example.com/"}]
|
||||
"errors": [{"sendReport": "https://report.example.com/"}]
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -1054,7 +1054,7 @@ Property Value Type: string<br />Parent: <code>error.errors</code>
|
|||
<CATEGORY title="Examples">
|
||||
<STYLEPOINT title="YouTube JSON API">
|
||||
<SUMMARY>
|
||||
Here's an example of the YouTube JSON API's response object. You can learn more about YouTube's JSON API here: <a href="http://code.google.com/apis/youtube/2.0/developers_guide_jsonc.html">http://code.google.com/apis/youtube/2.0/developers_guide_jsonc.html</a>.
|
||||
Here's an example of the YouTube JSON API's response object. You can learn more about YouTube's JSON API here: <a href="https://code.google.com/apis/youtube/2.0/developers_guide_jsonc.html">https://code.google.com/apis/youtube/2.0/developers_guide_jsonc.html</a>.
|
||||
</SUMMARY>
|
||||
<BODY>
|
||||
<CODE_SNIPPET>
|
||||
|
|
@ -1081,16 +1081,16 @@ Here's an example of the YouTube JSON API's response object. You can learn more
|
|||
"golden retriever",
|
||||
],
|
||||
"thumbnail": {
|
||||
"default": "http://i.ytimg.com/vi/BGODurRfVv4/default.jpg",
|
||||
"hqDefault": "http://i.ytimg.com/vi/BGODurRfVv4/hqdefault.jpg"
|
||||
"default": "https://i.ytimg.com/vi/BGODurRfVv4/default.jpg",
|
||||
"hqDefault": "https://i.ytimg.com/vi/BGODurRfVv4/hqdefault.jpg"
|
||||
},
|
||||
"player": {
|
||||
"default": "http://www.youtube.com/watch?v=BGODurRfVv4&feature=youtube_gdata",
|
||||
"mobile": "http://m.youtube.com/details?v=BGODurRfVv4"
|
||||
"default": "https://www.youtube.com/watch?v=BGODurRfVv4&feature=youtube_gdata",
|
||||
"mobile": "https://m.youtube.com/details?v=BGODurRfVv4"
|
||||
},
|
||||
"content": {
|
||||
"1": "rtsp://v5.cache6.c.youtube.com/CiILENy73wIaGQn-Vl-0uoNjBBMYDSANFEgGUgZ2aWRlb3MM/0/0/0/video.3gp",
|
||||
"5": "http://www.youtube.com/v/BGODurRfVv4?f=videos&app=youtube_gdata",
|
||||
"5": "https://www.youtube.com/v/BGODurRfVv4?f=videos&app=youtube_gdata",
|
||||
"6": "rtsp://v7.cache7.c.youtube.com/CiILENy73wIaGQn-Vl-0uoNjBBMYESARFEgGUgZ2aWRlb3MM/0/0/0/video.3gp"
|
||||
},
|
||||
"duration": 315,
|
||||
|
|
@ -1125,9 +1125,9 @@ This example demonstrates how the Google search items could be represented as a
|
|||
"itemsPerPage": 10,
|
||||
"startIndex": 11,
|
||||
"totalItems": 2700000,
|
||||
"nextLink": "http://www.google.com/search?hl=en&q=chicago+style+pizza&start=20&sa=N"
|
||||
"previousLink": "http://www.google.com/search?hl=en&q=chicago+style+pizza&start=0&sa=N",
|
||||
"pagingLinkTemplate": "http://www.google.com/search/hl=en&q=chicago+style+pizza&start={index}&sa=N",
|
||||
"nextLink": "https://www.google.com/search?hl=en&q=chicago+style+pizza&start=20&sa=N"
|
||||
"previousLink": "https://www.google.com/search?hl=en&q=chicago+style+pizza&start=0&sa=N",
|
||||
"pagingLinkTemplate": "https://www.google.com/search/hl=en&q=chicago+style+pizza&start={index}&sa=N",
|
||||
"items": [
|
||||
{
|
||||
"title": "Pizz'a Chicago Home Page"
|
||||
|
|
@ -1149,7 +1149,7 @@ This example demonstrates how the Google search items could be represented as a
|
|||
A list of reserved JavaScript words that should be avoided in property names.
|
||||
</SUMMARY>
|
||||
<BODY>
|
||||
<p>The words below are reserved by the JavaScript language and cannot be referred to using dot notation. The list represents best knowledge of keywords at this time; the list may change or vary based on your specific execution environment.</p><p>From the <a href="http://www.google.com/url?sa=D&q=http%3A%2F%2Fwww.ecma-international.org%2Fpublications%2Fstandards%2FEcma-262.htm">ECMAScript Language Specification 5th Edition</a></p>
|
||||
<p>The words below are reserved by the JavaScript language and cannot be referred to using dot notation. The list represents best knowledge of keywords at this time; the list may change or vary based on your specific execution environment.</p><p>From the <a href="https://www.google.com/url?sa=D&q=http%3A%2F%2Fwww.ecma-international.org%2Fpublications%2Fstandards%2FEcma-262.htm">ECMAScript Language Specification 5th Edition</a></p>
|
||||
<BAD_CODE_SNIPPET>
|
||||
abstract
|
||||
boolean break byte
|
||||
|
|
@ -1175,7 +1175,7 @@ yield
|
|||
<HR/>
|
||||
|
||||
<p align="center">
|
||||
Except as otherwise <a href="http://code.google.com/policies.html">noted</a>, the content of this page is licensed under the <a href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 License</a>, and code samples are licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache 2.0 License</a>.
|
||||
Except as otherwise <a href="https://code.google.com/policies.html">noted</a>, the content of this page is licensed under the <a href="https://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 License</a>, and code samples are licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache 2.0 License</a>.
|
||||
</p>
|
||||
<p align="right">
|
||||
Revision 0.9
|
||||
|
|
|
|||
|
|
@ -85,7 +85,7 @@ Robert Brown
|
|||
<SUMMARY>
|
||||
Each guideline's level of importance is indicated
|
||||
by use of the following keywords and phrases, adapted from
|
||||
<a href="http://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>.
|
||||
<a href="https://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>.
|
||||
</SUMMARY>
|
||||
<BODY>
|
||||
<table>
|
||||
|
|
@ -676,10 +676,10 @@ Robert Brown
|
|||
<p>
|
||||
Common Lisp indentation in Emacs is provided by the cl-indent library.
|
||||
The latest version of cl-indent is packaged with
|
||||
<a HREF="http://www.common-lisp.net/project/slime/">SLIME</a>
|
||||
<a HREF="https://www.common-lisp.net/project/slime/">SLIME</a>
|
||||
(under contrib/slime-cl-indent.el). After installing SLIME, set up Emacs
|
||||
to load SLIME automatically using
|
||||
<a HREF="http://www.common-lisp.net/project/slime/doc/html/Loading-Contribs.html">these instructions</a>, adding slime-indentation to the list of
|
||||
<a HREF="https://www.common-lisp.net/project/slime/doc/html/Loading-Contribs.html">these instructions</a>, adding slime-indentation to the list of
|
||||
contrib libraries to be loaded in the call to slime-setup.
|
||||
</p>
|
||||
<p>
|
||||
|
|
@ -692,7 +692,7 @@ Robert Brown
|
|||
This is particularly useful when creating forms that behave like macros
|
||||
or special operators that are indented differently than standard
|
||||
function calls (e.g. defun, labels, or let). Add a
|
||||
<a HREF="http://www.gnu.org/software/emacs/manual/html_node/emacs/Hooks.html">hook</a> to 'lisp-mode-hook that calls common-lisp-set-style to set
|
||||
<a HREF="https://www.gnu.org/software/emacs/manual/html_node/emacs/Hooks.html">hook</a> to 'lisp-mode-hook that calls common-lisp-set-style to set
|
||||
the appropriate style automatically.
|
||||
</p>
|
||||
|
||||
|
|
@ -1065,7 +1065,7 @@ Robert Brown
|
|||
;;;; project-euler.lisp
|
||||
;;;; File-level comments or comments for large sections of code.
|
||||
|
||||
;;; Problems are described in more detail here: http://projecteuler.net/
|
||||
;;; Problems are described in more detail here: https://projecteuler.net/
|
||||
|
||||
;;; Divisibility
|
||||
;;; Comments that describe a group of definitions.
|
||||
|
|
@ -1153,7 +1153,7 @@ Robert Brown
|
|||
<p>
|
||||
Be specific when indicating times or software releases
|
||||
in a TODO comment and use
|
||||
<a HREF="http://www.w3.org/TR/NOTE-datetime">YYYY-MM-DD</a>
|
||||
<a HREF="https://www.w3.org/TR/NOTE-datetime">YYYY-MM-DD</a>
|
||||
format for dates to make automated processing of such dates easier,
|
||||
e.g., 2038-01-20 for the end of the 32-bit signed <code>time_t</code>.
|
||||
</p>
|
||||
|
|
@ -1972,7 +1972,7 @@ Robert Brown
|
|||
much less first-class "protocol" objects.
|
||||
However, there may indeed be an abstract CLOS class
|
||||
or an
|
||||
<a href="http://common-lisp.net/~frideau/lil-ilc2012/lil-ilc2012.html">Interface-Passing Style</a> interface
|
||||
<a href="https://common-lisp.net/~frideau/lil-ilc2012/lil-ilc2012.html">Interface-Passing Style</a> interface
|
||||
that embodies the protocol.
|
||||
Further (sub)classes or (sub)interfaces may then implement
|
||||
all or part of a protocol by defining
|
||||
|
|
@ -2311,7 +2311,7 @@ Robert Brown
|
|||
Lisp evaluation happens at several times,
|
||||
some of them interleaved.
|
||||
Be aware of them when writing macros.
|
||||
<a href="http://fare.livejournal.com/146698.html">EVAL-WHEN considered harmful to your mental health</a>.
|
||||
<a href="https://fare.livejournal.com/146698.html">EVAL-WHEN considered harmful to your mental health</a>.
|
||||
</p>
|
||||
<p>
|
||||
In summary of the article linked above,
|
||||
|
|
@ -2808,7 +2808,7 @@ Robert Brown
|
|||
</p>
|
||||
<BAD_CODE_SNIPPET>
|
||||
;; Bad
|
||||
(defconstant +google-url+ "http://www.google.com/")
|
||||
(defconstant +google-url+ "https://www.google.com/")
|
||||
(defconstant +valid-colors+ '(red green blue))
|
||||
</BAD_CODE_SNIPPET>
|
||||
|
||||
|
|
@ -2825,7 +2825,7 @@ Robert Brown
|
|||
</p>
|
||||
<CODE_SNIPPET>
|
||||
;; Better, for Open-Source code:
|
||||
(define-constant +google-url+ "http://www.google.com/" :test #'string=)
|
||||
(define-constant +google-url+ "https://www.google.com/" :test #'string=)
|
||||
(define-constant +valid-colors+ '(red green blue))
|
||||
</CODE_SNIPPET>
|
||||
<p>
|
||||
|
|
@ -3815,7 +3815,7 @@ Robert Brown
|
|||
</CODE_SNIPPET>
|
||||
<p>
|
||||
In particular, the above means that the
|
||||
<a href="http://www.lispworks.com/documentation/HyperSpec/Body/t_satisf.htm">example</a>
|
||||
<a href="https://www.lispworks.com/documentation/HyperSpec/Body/t_satisf.htm">example</a>
|
||||
used in the Common Lisp Standard is erroneous:
|
||||
<code>(and integer (satisfies evenp))</code>
|
||||
is <em>not</em> a safe, conformant type specifier to use,
|
||||
|
|
|
|||
|
|
@ -60,14 +60,14 @@ Revision 2.59
|
|||
sure you've read:
|
||||
<ul>
|
||||
<li>
|
||||
<a href="http://developer.apple.com/documentation/Cocoa/Conceptual/CodingGuidelines/index.html">
|
||||
<a href="https://developer.apple.com/documentation/Cocoa/Conceptual/CodingGuidelines/index.html">
|
||||
Apple's Cocoa Coding Guidelines
|
||||
</a>
|
||||
</li>
|
||||
<li>
|
||||
|
||||
<div>
|
||||
<a href="http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml">
|
||||
<a href="https://google-styleguide.googlecode.com/svn/trunk/cppguide.xml">
|
||||
Google's Open Source C++ Style Guide
|
||||
</a>
|
||||
</div>
|
||||
|
|
@ -95,7 +95,7 @@ Revision 2.59
|
|||
<p>
|
||||
Google has already released open-source code that conforms to these
|
||||
guidelines as part of the
|
||||
<a href="http://code.google.com/p/google-toolbox-for-mac/">
|
||||
<a href="https://code.google.com/p/google-toolbox-for-mac/">
|
||||
Google Toolbox for Mac project
|
||||
</a>
|
||||
(abbreviated GTM throughout this document).
|
||||
|
|
@ -109,7 +109,7 @@ Revision 2.59
|
|||
Note that this guide is not an Objective-C tutorial. We assume that the
|
||||
reader is familiar with the language. If you are new to Objective-C or
|
||||
need a refresher, please read
|
||||
<a href="http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html">
|
||||
<a href="https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html">
|
||||
Programming with Objective-C
|
||||
</a>.
|
||||
</p>
|
||||
|
|
@ -616,7 +616,7 @@ Revision 2.59
|
|||
Naming rules are very important in maintainable code. Objective-C method
|
||||
names tend to be very long, but this has the benefit that a block of code
|
||||
can almost read like prose, thus rendering many comments unnecessary. </p>
|
||||
<p> When writing pure Objective-C code, we mostly follow standard <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html">Objective-C
|
||||
<p> When writing pure Objective-C code, we mostly follow standard <a href="https://developer.apple.com/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html">Objective-C
|
||||
naming rules</a>. These naming guidelines may differ
|
||||
significantly from those outlined in the C++ style guide. For example,
|
||||
Google's C++ style guide recommends the use of underscores between words
|
||||
|
|
@ -625,7 +625,7 @@ Revision 2.59
|
|||
</p>
|
||||
<p>
|
||||
Any class, category, method, or variable name may use all capitals for
|
||||
<a href="http://en.wikipedia.org/wiki/Initialism">initialisms</a>
|
||||
<a href="https://en.wikipedia.org/wiki/Initialism">initialisms</a>
|
||||
within the name. This follows Apple's standard of using all capitals
|
||||
within a name for initialisms such as URL, TIFF, and EXIF.
|
||||
</p>
|
||||
|
|
@ -807,7 +807,7 @@ Revision 2.59
|
|||
The method name should read like a sentence if possible, meaning you
|
||||
should choose parameter names that flow with the method name. (e.g.
|
||||
<code>convertPoint:fromRect:</code> or
|
||||
<code>replaceCharactersInRange:withString:</code>). See <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingMethods.html#//apple_ref/doc/uid/20001282-BCIGIJJF">Apple's
|
||||
<code>replaceCharactersInRange:withString:</code>). See <a href="https://developer.apple.com/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingMethods.html#//apple_ref/doc/uid/20001282-BCIGIJJF">Apple's
|
||||
Guide to Naming Methods</a> for more details.
|
||||
</p>
|
||||
<p>
|
||||
|
|
@ -1189,7 +1189,7 @@ Revision 2.59
|
|||
</CODE_SNIPPET>
|
||||
<p>
|
||||
If you are using Objective-C 2.0, you should instead declare your
|
||||
private category using a <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/Articles/chapter_4_section_5.html#">class
|
||||
private category using a <a href="https://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/Articles/chapter_4_section_5.html#">class
|
||||
extension</a>, for example:
|
||||
</p>
|
||||
<CODE_SNIPPET>
|
||||
|
|
|
|||
26
pyguide.html
26
pyguide.html
|
|
@ -1,8 +1,8 @@
|
|||
<HTML 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">
|
||||
<HTML xmlns:rdf="https://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="https://www.w3.org/1999/XSL/Format" xmlns:fn="https://www.w3.org/2005/xpath-functions">
|
||||
<HEAD>
|
||||
<TITLE>Google Python Style Guide</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="https://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">
|
||||
|
||||
|
|
@ -521,7 +521,7 @@ from sound.effects import echo
|
|||
<P class="">
|
||||
<SPAN class="stylepoint_section">Pros: </SPAN>
|
||||
Allows definition of utility classes and functions that are only
|
||||
used inside of a very limited scope. Very <a HREF="http://en.wikipedia.org/wiki/Abstract_data_type">ADT</a>-y.
|
||||
used inside of a very limited scope. Very <a HREF="https://en.wikipedia.org/wiki/Abstract_data_type">ADT</a>-y.
|
||||
</P>
|
||||
<P class="">
|
||||
<SPAN class="stylepoint_section">Cons: </SPAN>
|
||||
|
|
@ -1069,7 +1069,7 @@ No: <span class="external"></span>def foo(a, b=FLAGS.my_thing): # sys.argv has
|
|||
<P class="">
|
||||
<SPAN class="stylepoint_section">Cons: </SPAN>
|
||||
Can lead to confusing bugs. Such as this example based on
|
||||
<a HREF="http://www.python.org/dev/peps/pep-0227/">PEP-0227</a>:
|
||||
<a HREF="https://www.python.org/dev/peps/pep-0227/">PEP-0227</a>:
|
||||
<DIV class=""><PRE class="badcode">
|
||||
<span class="external"></span>i = 4
|
||||
<span class="external"></span>def foo(x):
|
||||
|
|
@ -1104,7 +1104,7 @@ No: <span class="external"></span>def foo(a, b=FLAGS.my_thing): # sys.argv has
|
|||
<P class="">
|
||||
<SPAN class="stylepoint_section">Definition: </SPAN>
|
||||
|
||||
<a HREF="http://www.python.org/doc/2.4.3/whatsnew/node6.html">Decorators
|
||||
<a HREF="https://www.python.org/doc/2.4.3/whatsnew/node6.html">Decorators
|
||||
for Functions and Methods</a>
|
||||
(a.k.a "the <code>@</code> notation").
|
||||
The most common decorators are <code>@classmethod</code> and
|
||||
|
|
@ -1267,7 +1267,7 @@ No: <span class="external"></span>def foo(a, b=FLAGS.my_thing): # sys.argv has
|
|||
<p>
|
||||
Make use of Python's
|
||||
|
||||
<a HREF="http://docs.python.org/reference/lexical_analysis.html#implicit-line-joining">implicit
|
||||
<a HREF="https://docs.python.org/reference/lexical_analysis.html#implicit-line-joining">implicit
|
||||
line joining inside parentheses, brackets and braces</a>.
|
||||
If necessary, you can add an extra pair of parentheses around an
|
||||
expression.
|
||||
|
|
@ -1295,10 +1295,10 @@ No: <span class="external"></span>def foo(a, b=FLAGS.my_thing): # sys.argv has
|
|||
</p>
|
||||
|
||||
<DIV class=""><PRE>Yes: <span class="external"></span># See details at
|
||||
<span class="external"></span># http://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html</PRE></DIV>
|
||||
<span class="external"></span># https://www.example.com/us/developer/documentation/api/content/v2.0/csv_file_name_extension_full_specification.html</PRE></DIV>
|
||||
|
||||
<DIV class=""><PRE class="badcode">No: <span class="external"></span># See details at
|
||||
<span class="external"></span># http://www.example.com/us/developer/documentation/api/content/\
|
||||
<span class="external"></span># https://www.example.com/us/developer/documentation/api/content/\
|
||||
<span class="external"></span># v2.0/csv_file_name_extension_full_specification.html</PRE></DIV>
|
||||
|
||||
<p>
|
||||
|
|
@ -1508,7 +1508,7 @@ No: <span class="external"></span>def foo(a, b=FLAGS.my_thing): # sys.argv has
|
|||
program with
|
||||
<code>#!/usr/bin/python</code> with an optional single digit
|
||||
<code>2</code> or <code>3</code> suffix per
|
||||
<a href="http://www.python.org/dev/peps/pep-0394/">PEP-394</a>.
|
||||
<a href="https://www.python.org/dev/peps/pep-0394/">PEP-394</a>.
|
||||
</DIV>
|
||||
<DIV class=""><DIV class="stylepoint_body" name="Shebang_Line__body" id="Shebang_Line__body" style="display: none">
|
||||
|
||||
|
|
@ -1542,7 +1542,7 @@ No: <span class="external"></span>def foo(a, b=FLAGS.my_thing): # sys.argv has
|
|||
object and are used by <code>pydoc</code>. (Try running
|
||||
<code>pydoc</code> on your module to see how it looks.) We
|
||||
always use the three double-quote <code>"""</code> format for doc strings
|
||||
(per <a href="http://www.python.org/dev/peps/pep-0257/">PEP 257</a>).
|
||||
(per <a href="https://www.python.org/dev/peps/pep-0257/">PEP 257</a>).
|
||||
A doc string should be organized as a
|
||||
summary line (one physical line) terminated by a period,
|
||||
question mark, or exclamation point, followed by a blank line,
|
||||
|
|
@ -1700,7 +1700,7 @@ No: <span class="external"></span>def foo(a, b=FLAGS.my_thing): # sys.argv has
|
|||
<p>
|
||||
The final place to have comments is in tricky parts of the
|
||||
code. If you're going to have to explain it at the next
|
||||
<a HREF="http://en.wikipedia.org/wiki/Code_review">code review</a>,
|
||||
<a HREF="https://en.wikipedia.org/wiki/Code_review">code review</a>,
|
||||
you should comment it now. Complicated operations get a few lines of
|
||||
comments before the operations
|
||||
commence. Non-obvious ones get comments at the end of the line.
|
||||
|
|
@ -1907,7 +1907,7 @@ Don'<span class="external"></span>t do this.
|
|||
</p>
|
||||
|
||||
<p>
|
||||
The preferred way to manage files is using the <a HREF="http://docs.python.org/reference/compound_stmts.html#the-with-statement">
|
||||
The preferred way to manage files is using the <a HREF="https://docs.python.org/reference/compound_stmts.html#the-with-statement">
|
||||
"with" statement</a>:
|
||||
</p>
|
||||
|
||||
|
|
@ -1924,7 +1924,7 @@ Don'<span class="external"></span>t do this.
|
|||
<DIV class=""><PRE>
|
||||
<span class="external"></span>import contextlib
|
||||
|
||||
<span class="external"></span>with contextlib.closing(urllib.urlopen("http://www.python.org/")) as front_page:
|
||||
<span class="external"></span>with contextlib.closing(urllib.urlopen("https://www.python.org/")) as front_page:
|
||||
<span class="external"> </span>for line in front_page:
|
||||
<span class="external"> </span>print line</PRE></DIV>
|
||||
|
||||
|
|
|
|||
|
|
@ -652,7 +652,7 @@ Revision 1.26
|
|||
# alnum character class followed by the string name.
|
||||
# Note that the RHS should not be quoted here.
|
||||
# For the gory details, see
|
||||
# E14 at http://tiswww.case.edu/php/chet/bash/FAQ
|
||||
# E14 at https://tiswww.case.edu/php/chet/bash/FAQ
|
||||
if [[ "filename" =~ ^[[:alnum:]]+name ]]; then
|
||||
echo "Match"
|
||||
fi
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
<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:xsl="https://www.w3.org/1999/XSL/Transform"
|
||||
xmlns:rdf="https://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">
|
||||
xmlns:fo="https://www.w3.org/1999/XSL/Format"
|
||||
xmlns:fn="https://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" />
|
||||
|
|
@ -23,7 +23,7 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">
|
|||
<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"
|
||||
<LINK HREF="https://www.google.com/favicon.ico" type="image/x-icon"
|
||||
rel="shortcut icon"/>
|
||||
<LINK HREF="styleguide.css"
|
||||
type="text/css" rel="stylesheet"/>
|
||||
|
|
|
|||
|
|
@ -348,7 +348,7 @@ footer.style.display = 'none';
|
|||
<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>
|
||||
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="https://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="https://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
|
||||
|
|
@ -368,7 +368,7 @@ 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>
|
||||
</li><li>Namespace names are HTTP URIs. Namespace names SHOULD take the form <span style="font-family: Courier New;">https://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>
|
||||
|
|
@ -394,7 +394,7 @@ specification evolves.]<br><br></li><li>Attributes MUST NOT be used to hold valu
|
|||
</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
|
||||
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="https://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
|
||||
|
|
@ -408,7 +408,7 @@ get wrong.]<br><br></li><li>Be careful with whitespace in values. XML pars
|
|||
</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>
|
||||
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="https://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>
|
||||
|
|
@ -511,7 +511,7 @@ If you are extending an existing schema, do things by analogy to how things are
|
|||
</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.
|
||||
Sensible schema languages, meaning RELAX NG and Schematron, treat elements and attributes symmetrically. Older and cruder<a href="https://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>
|
||||
|
|
@ -580,7 +580,7 @@ If a piece of data extends across multiple lines, use an element: XML parsers wi
|
|||
<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.
|
||||
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="https://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="https://www.w3.org/TR/2001/REC-ruby-20010531" id="ehyv" title="bidirectionality">bidirectionality</a> properly.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user