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

1118 lines
35 KiB
XML
Raw Normal View History

Initial release
2012-04-25 06:21:00 +08:00
<?xml version="1.0"?>
Adding back style sheet link (dropped after file re-generation).
2012-07-18 04:17:21 +08:00
<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
Initial release
2012-04-25 06:21:00 +08:00
<GUIDE title="Google HTML/CSS Style Guide">
<p class="revision">
Update C++ style guide to 3.260: - Add boost::bimap to the list of allowed Boost libraries. - C++11: remove mention of constexpr. - Remove noun/verb naming rules, and consolidate "General Naming Rules". - C++11: allow variadic templates. - Revise guidance on function definition comments. - Clarify that one space is sufficient before trailing /* */ comments. - C++11: allow alias templates. - C++11: allow <array>, deprecate Boost array. - C++11: allow unique_ptr, deprecate Boost pointer container. - C++11: allow braced initializer lists. Update Objective-C style guide to 2.56: - Add details on constant declarations to clarify naming and scope issues. - Update link to Apple's Objective-C guide. - Allow left-aligning multi-block method invocation segments. - Add section on container literals. Update Python style guide to 2.54: - Allow str.format in addition to the % operator. - Allow #!/usr/bin/python2 and #!/usr/bin/python3. - Move the closing brace example from column 4 to 0. - Remove the requirement to use named parameters for arguments with defaults. Update HTML/CSS style guide to 2.23: - No changes. Update JavaScript style guide to 2.82: - Fix typos, whitespace, and character entities. - Include property descriptions in the clause about omitting obvious comments. - Make file overviews optional. - Fix example in "HTML in JSDoc" section. - Remove the semicolon-insertion language from the operators section. - State that complete sentences are recommended but not required. - Document usage of goog.scope to declare new classes. Update Common Lisp style guide to 1.20: - Indicate both variable and function predicates require a "p". - Make the abbreviations rules consistent and in one location. - Don't allow for the use of &AUX. - Allow for "body" and "end" as exceptions to the suffix rule. - Use the TODO convention to mark code that needs to be addressed. - Remove file maintainership requirements, require a description. - Change top-level form requirements to the length of a page. - Remove "don't be clever".
2013-07-13 02:53:13 +08:00
Revision 2.23
Initial release
2012-04-25 06:21:00 +08:00
</p>
<OVERVIEW>
<CATEGORY title="Important Note">
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Displaying Hidden Details in This Guide">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
This style guide contains many details that are initially
hidden from view. They are marked by the triangle icon, which you
see here on your left. Click it now.
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
You should see “Hooray” appear below.
Initial release
2012-04-25 06:21:00 +08:00
</SUMMARY>
<BODY>
<p>
Hooray! Now you know you can expand points to get more
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
details. Alternatively, there’s a “toggle all” at the
Initial release
2012-04-25 06:21:00 +08:00
top of this document.
</p>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="Background">
<p>
This document defines formatting and style rules for HTML and
CSS. It aims at improving collaboration, code quality, and
enabling supporting infrastructure. It applies to raw,
working files that use HTML and CSS, including GSS
files. Tools are free to obfuscate, minify, and compile as
long as the general code quality is maintained.
</p>
</CATEGORY>
</OVERVIEW>
<CATEGORY title="General Style Rules">
<STYLEPOINT title="Protocol">
<SUMMARY>
Omit the protocol from embedded resources.
</SUMMARY>
<BODY>
<p>
Omit the protocol portion (<code>http:</code>,
<code>https:</code>) from URLs pointing to images and other
media files, style sheets, and scripts unless the respective
files are not available over both protocols.
</p>
<p>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
Omitting the protocol—which makes the URL
relative—prevents mixed content issues and results in
Initial release
2012-04-25 06:21:00 +08:00
minor file size savings.
</p>
<BAD_CODE_SNIPPET>
&lt;!-- Not recommended --&gt;
Replaced HTTP where HTTPS been awailable.
2016-04-01 16:41:34 +08:00
&lt;script src="https://www.google.com/js/gweb/analytics/autotrack.js"&gt;&lt;/script&gt;
Initial release
2012-04-25 06:21:00 +08:00
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
&lt;!-- Recommended --&gt;
&lt;script src="//www.google.com/js/gweb/analytics/autotrack.js"&gt;&lt;/script&gt;
</CODE_SNIPPET>
<BAD_CODE_SNIPPET>
/* Not recommended */
.example {
Replaced HTTP where HTTPS been awailable.
2016-04-01 16:41:34 +08:00
background: url(https://www.google.com/images/example);
Initial release
2012-04-25 06:21:00 +08:00
}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
.example {
background: url(//www.google.com/images/example);
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="General Formatting Rules">
<STYLEPOINT title="Indentation">
<SUMMARY>
Indent by 2 spaces at a time.
</SUMMARY>
<BODY>
<p>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
Don’t use tabs or mix tabs and spaces for indentation.
Initial release
2012-04-25 06:21:00 +08:00
</p>
<CODE_SNIPPET>
&lt;ul&gt;
&lt;li&gt;Fantastic
&lt;li&gt;Great
&lt;/ul&gt;
</CODE_SNIPPET>
<CODE_SNIPPET>
.example {
color: blue;
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Capitalization">
<SUMMARY>
Use only lowercase.
</SUMMARY>
<BODY>
<p>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
All code has to be lowercase: This applies to HTML element names,
Initial release
2012-04-25 06:21:00 +08:00
attributes, attribute values (unless
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<code>text/CDATA</code>), CSS selectors, properties, and
Initial release
2012-04-25 06:21:00 +08:00
property values (with the exception of strings).
</p>
<BAD_CODE_SNIPPET>
&lt;!-- Not recommended --&gt;
&lt;A HREF="/"&gt;Home&lt;/A&gt;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
&lt;!-- Recommended --&gt;
&lt;img src="google.png" alt="Google"&gt;
</CODE_SNIPPET>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<BAD_CODE_SNIPPET>
/* Not recommended */
color: #E5E5E5;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
color: #e5e5e5;
</CODE_SNIPPET>
Initial release
2012-04-25 06:21:00 +08:00
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Trailing Whitespace">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Remove trailing white spaces.
</SUMMARY>
<BODY>
<p>
Trailing white spaces are unnecessary and can complicate
diffs.
</p>
<BAD_CODE_SNIPPET>
&lt;!-- Not recommended --&gt;
&lt;p&gt;What?_
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
&lt;!-- Recommended --&gt;
&lt;p&gt;Yes please.
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="General Meta Rules">
<STYLEPOINT title="Encoding">
<SUMMARY>
Use UTF-8 (no BOM).
</SUMMARY>
<BODY>
<p>
Make sure your editor uses UTF-8 as character encoding,
without a byte order mark.
</p>
<p>
Specify the encoding in HTML templates and documents via
<code>&lt;meta charset="utf-8"&gt;</code>. Do not specify
the encoding of style sheets as these assume UTF-8.
</p>
<p>
(More on encodings and when and how to specify them can be
Replaced HTTP where HTTPS been awailable.
2016-04-01 16:41:34 +08:00
found in <a href="https://www.w3.org/International/tutorials/tutorial-char-enc/">Handling
Update C++ style guide to 3.231: - Clarify that sentence-like non-sentence comments are permitted. - Note that older code with incorrect #include ordering should be fixed. - Revamp the section on default function arguments. - Avoid explicitly recommending Init() methods. - C++11: permit "auto". - C++11: permit ">>" in place of "> >". - C++11: permit range-based "for". - C++11: permit variadic macros (already permitted as a C++03 extension). - C++11: permit "LL" and "ULL" literal suffixes (already permitted as a C++03 extension). - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. - C++11: permit new features in <algorithm> and the portion of <numeric> that does not require initializer lists. - Revise rules on forward declarations: explicitly forbid forward-declared functions, do not mandate forward declarations, discourage forward-declared templates. - Remove the rule requiring "const" qualifiers for member functions to be on the same line as the closing parenthesis of the parameter list. - Fix typo: "unnamed namespaces." - C++11: permit local types as template parameters. - Fix typo: "unfamiliar." - Relax RTTI rules to permit its use, but warn about its abuse. - C++11: permit nullptr and nullptr_t. Revise text referring to NULL to refer more generically to null pointers. - Remove the "don't go crazy with const" rule. - Fix typo: "dir/foo2" should bee "dir2/foo2." - Remove reference to a specific GCC version. Update Objective-C style guide to 2.48: - Revise method declaration and invocation formatting rules for long names. - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. Top-of-file comments are not required. - Fix dead link in the "nil Checks" section. - Cover ARC. - Specify that @private is only required for instance variables in header files. - Permit NSNumber literals. - Change the naming convention for instance variables from trailing underscore to leading underscore, allowing a wide exception for existing code and projects. - Fix description of BOOL with respect to its signedness. Update Python style guide to 2.45: - Recommend "pylint: disable" over "pylint: disable-msg." - Fix case-sensitive anchor. - Provide a better explanation of the problems with catch-all "except:." - Permit "map" and "filter" in absence of inlined lambdas. Update JavaScript style guide to 2.64: - Clarify rules for requiring and providing inner dependencies on classes. - Clarify semicolons for functions. - Note proper namespace and filename casing. - Fix typos: "@extends." - Permit parentheses to be omitted on unions. - Don't require method descriptions when obvious. - "in" is a keyword, put it in <code>. - New "Aliasing with goog.scope" section. - Rewrite the "Constants" section. - Remove the recommendation to use join() to build strings. - Add the "@expose" annotation. - Fix the "@suppress" example. - Remove reference alternate cast syntax. - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. - Say that "use strict" is not required. - Fix links to "optional" section. - Rewrite "JavaScript Types" section. - Fix typos: "parameterizes," "converted." - Prefer in-constructor field initialization. - Add a section on "delete" and null-assignment. - Add a note about optional JSDoc comments on enum values. - State explicitly that dot operators belong at the ends of lines. - Add "@dict" and "@struct" annotations. - Add links to the JavaScript Types section. - Require (rather than encourage) compiling. Update HTML/CSS style guide to 2.19: - Rephrased quotation guidelines. - Updated W3C I18N article reference. - Fixed revision number. Update styleguide.xsl to 1.34: - Fix error in RefreshVisibilityFromHashParam when a URL fragment points to a named anchor within a section, as used by the JavaScript style guide.
2012-11-29 04:26:27 +08:00
character encodings in HTML and CSS</a>.)
Initial release
2012-04-25 06:21:00 +08:00
</p>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Comments">
<SUMMARY>
Explain code as needed, where possible.
</SUMMARY>
<BODY>
<p>
Sync.
2012-07-18 04:12:10 +08:00
Use comments to explain code: What does it cover, what
Initial release
2012-04-25 06:21:00 +08:00
purpose does it serve, why is respective solution used or
preferred?
</p>
<p>
(This item is optional as it is not deemed a realistic
expectation to always demand fully documented code. Mileage
may vary heavily for HTML and CSS code and depends on the
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
project’s complexity.)
Initial release
2012-04-25 06:21:00 +08:00
</p>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Action Items">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Mark todos and action items with <code>TODO</code>.
</SUMMARY>
<BODY>
<p>
Highlight todos by using the keyword <code>TODO</code> only,
not other common formats like <code>@@</code>.
</p>
<p>
Append a contact (username or mailing list) in parentheses
as with the format <code>TODO(contact)</code>.
</p>
<p>
Append action items after a colon as in <code>TODO: action
item</code>.
</p>
<CODE_SNIPPET>
{# TODO(john.doe): revisit centering #}
&lt;center&gt;Test&lt;/center&gt;
</CODE_SNIPPET>
<CODE_SNIPPET>
&lt;!-- TODO: remove optional tags --&gt;
&lt;ul&gt;
&lt;li&gt;Apples&lt;/li&gt;
&lt;li&gt;Oranges&lt;/li&gt;
&lt;/ul&gt;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="HTML Style Rules">
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Document Type">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Use HTML5.
</SUMMARY>
<BODY>
<p>
HTML5 (HTML syntax) is preferred for all HTML documents:
<code>&lt;!DOCTYPE html&gt;</code>.
</p>
<p>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
(It’s recommended to use HTML, as <code>text/html</code>. Do not use
Replaced HTTP where HTTPS been awailable.
2016-04-01 16:41:34 +08:00
XHTML. XHTML, as <a href="https://hixie.ch/advocacy/xhtml"><code>application/xhtml+xml</code></a>,
Initial release
2012-04-25 06:21:00 +08:00
lacks both browser and infrastructure support and offers
less room for optimization than HTML.)
</p>
Sync.
2012-07-18 04:12:10 +08:00
<p>
Although fine with HTML, do not close void elements, i.e. write
<code>&lt;br&gt;</code>, not <code>&lt;br /&gt;</code>.
</p>
Initial release
2012-04-25 06:21:00 +08:00
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="HTML Validity">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Use valid HTML where possible.
</SUMMARY>
<BODY>
<p>
Use valid HTML code unless that is not possible due to
otherwise unattainable performance goals regarding file size.
</p>
<p>
Replaced HTTP where HTTPS been awailable.
2016-04-01 16:41:34 +08:00
Use tools such as the <a href="https://validator.w3.org/nu/">W3C
Initial release
2012-04-25 06:21:00 +08:00
HTML validator</a> to test.
</p>
<p>
Using valid HTML is a measurable baseline quality attribute
that contributes to learning about technical requirements
and constraints, and that ensures proper HTML usage.
</p>
<BAD_CODE_SNIPPET>
&lt;!-- Not recommended --&gt;
&lt;title&gt;Test&lt;/title&gt;
&lt;article&gt;This is only a test.
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
&lt;!-- Recommended --&gt;
&lt;!DOCTYPE html&gt;
&lt;meta charset="utf-8"&gt;
&lt;title&gt;Test&lt;/title&gt;
&lt;article&gt;This is only a test.&lt;/article&gt;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Semantics">
<SUMMARY>
Use HTML according to its purpose.
</SUMMARY>
<BODY>
<p>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
Use elements (sometimes incorrectly called “tags”) for what
Initial release
2012-04-25 06:21:00 +08:00
they have been created for. For example, use heading
elements for headings, <code>p</code> elements for
paragraphs, <code>a</code> elements for anchors, etc.
</p>
<p>
Using HTML according to its purpose is important for
accessibility, reuse, and code efficiency reasons.
</p>
<BAD_CODE_SNIPPET>
&lt;!-- Not recommended --&gt;
&lt;div onclick="goToRecommendations();"&gt;All recommendations&lt;/div&gt;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
&lt;!-- Recommended --&gt;
&lt;a href="recommendations/"&gt;All recommendations&lt;/a&gt;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Multimedia Fallback">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Provide alternative contents for multimedia.
</SUMMARY>
<BODY>
<p>
For multimedia, such as images, videos, animated objects via
<code>canvas</code>, make sure to offer alternative
access. For images that means use of meaningful alternative
text (<code>alt</code>) and for video and audio transcripts
and captions, if available.
</p>
<p>
Providing alternative contents is important for
Sync.
2012-07-18 04:12:10 +08:00
accessibility reasons: A blind user has few cues to tell
Initial release
2012-04-25 06:21:00 +08:00
what an image is about without <code>@alt</code>, and other
users may have no way of understanding what video or audio
contents are about either.
</p>
<p>
(For images whose <code>alt</code> attributes would
introduce redundancy, and for images whose purpose is purely
decorative which you cannot immediately use CSS for, use no
alternative text, as in <code>alt=""</code>.)
</p>
<BAD_CODE_SNIPPET>
&lt;!-- Not recommended --&gt;
&lt;img src="spreadsheet.png"&gt;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
&lt;!-- Recommended --&gt;
&lt;img src="spreadsheet.png" alt="Spreadsheet screenshot."&gt;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Separation of Concerns">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Separate structure from presentation from behavior.
</SUMMARY>
<BODY>
<p>
Strictly keep structure (markup), presentation (styling),
and behavior (scripting) apart, and try to keep the
interaction between the three to an absolute minimum.
</p>
<p>
That is, make sure documents and templates contain only HTML
and HTML that is solely serving structural purposes. Move
everything presentational into style sheets, and everything
behavioral into scripts.
</p>
<p>
In addition, keep the contact area as small as possible by
linking as few style sheets and scripts as possible from
documents and templates.
</p>
<p>
Separating structure from presentation from behavior is
important for maintenance reasons. It is always more
expensive to change HTML documents and templates than it is
to update style sheets and scripts.
</p>
<BAD_CODE_SNIPPET>
&lt;!-- Not recommended --&gt;
&lt;!DOCTYPE html&gt;
&lt;title&gt;HTML sucks&lt;/title&gt;
&lt;link rel="stylesheet" href="base.css" media="screen"&gt;
&lt;link rel="stylesheet" href="grid.css" media="screen"&gt;
&lt;link rel="stylesheet" href="print.css" media="print"&gt;
&lt;h1 style="font-size: 1em;"&gt;HTML sucks&lt;/h1&gt;
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
&lt;p&gt;I’ve read about this on a few sites but now I’m sure:
Initial release
2012-04-25 06:21:00 +08:00
&lt;u&gt;HTML is stupid!!1&lt;/u&gt;
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
&lt;center&gt;I can’t believe there’s no way to control the styling of
Initial release
2012-04-25 06:21:00 +08:00
my website without doing everything all over again!&lt;/center&gt;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
&lt;!-- Recommended --&gt;
&lt;!DOCTYPE html&gt;
&lt;title&gt;My first CSS-only redesign&lt;/title&gt;
&lt;link rel="stylesheet" href="default.css"&gt;
&lt;h1&gt;My first CSS-only redesign&lt;/h1&gt;
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
&lt;p&gt;I’ve read about this on a few sites but today I’m actually
Initial release
2012-04-25 06:21:00 +08:00
doing it: separating concerns and avoiding anything in the HTML of
my website that is presentational.
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
&lt;p&gt;It’s awesome!
Initial release
2012-04-25 06:21:00 +08:00
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Entity References">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Do not use entity references.
</SUMMARY>
<BODY>
<p>
There is no need to use entity references like
<code>&amp;mdash;</code>, <code>&amp;rdquo;</code>, or
<code>&amp;#x263a;</code>, assuming the same encoding
(UTF-8) is used for files and editors as well as among
teams.
</p>
<p>
The only exceptions apply to characters with special meaning
in HTML (like <code>&lt;</code> and <code>&amp;</code>) as
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
well as control or “invisible” characters (like no-break
Initial release
2012-04-25 06:21:00 +08:00
spaces).
</p>
<BAD_CODE_SNIPPET>
&lt;!-- Not recommended --&gt;
The currency symbol for the Euro is &amp;ldquo;&amp;eur;&amp;rdquo;.
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
&lt;!-- Recommended --&gt;
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
The currency symbol for the Euro is “€”.
Initial release
2012-04-25 06:21:00 +08:00
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Optional Tags">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Omit optional tags (optional).
</SUMMARY>
<BODY>
<p>
For file size optimization and scannability purposes,
consider omitting optional tags.
Replaced HTTP where HTTPS been awailable.
2016-04-01 16:41:34 +08:00
The <a href="https://whatwg.org/specs/web-apps/current-work/multipage/syntax.html#syntax-tag-omission">HTML5
Initial release
2012-04-25 06:21:00 +08:00
specification</a> defines what tags can be omitted.
</p>
<p>
(This approach may require a grace period to be established
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
as a wider guideline as it’s significantly different
Initial release
2012-04-25 06:21:00 +08:00
from what web developers are typically taught. For
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
consistency and simplicity reasons it’s best served
Initial release
2012-04-25 06:21:00 +08:00
omitting all optional tags, not just a selection.)
</p>
<BAD_CODE_SNIPPET>
&lt;!-- Not recommended --&gt;
&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;head&gt;
&lt;title&gt;Spending money, spending bytes&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;p&gt;Sic.&lt;/p&gt;
&lt;/body&gt;
&lt;/html&gt;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
&lt;!-- Recommended --&gt;
&lt;!DOCTYPE html&gt;
&lt;title&gt;Saving money, saving bytes&lt;/title&gt;
&lt;p&gt;Qed.
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="type Attributes">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Omit <code>type</code> attributes for style sheets and scripts.
</SUMMARY>
<BODY>
<p>
Do not use <code>type</code> attributes for style sheets
(unless not using CSS) and scripts (unless not using
JavaScript).
</p>
<p>
Specifying <code>type</code> attributes in these contexts is
not necessary as HTML5 implies
Replaced HTTP where HTTPS been awailable.
2016-04-01 16:41:34 +08:00
<a href="https://whatwg.org/specs/web-apps/current-work/multipage/semantics.html#attr-style-type"><code>text/css</code></a>
Initial release
2012-04-25 06:21:00 +08:00
and
Replaced HTTP where HTTPS been awailable.
2016-04-01 16:41:34 +08:00
<a href="https://whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#attr-script-type"><code>text/javascript</code></a>
Initial release
2012-04-25 06:21:00 +08:00
as defaults. This can be safely done even for older browsers.
</p>
<BAD_CODE_SNIPPET>
&lt;!-- Not recommended --&gt;
&lt;link rel="stylesheet" href="//www.google.com/css/maia.css"
type="text/css"&gt;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
&lt;!-- Recommended --&gt;
&lt;link rel="stylesheet" href="//www.google.com/css/maia.css"&gt;
</CODE_SNIPPET>
<BAD_CODE_SNIPPET>
&lt;!-- Not recommended --&gt;
&lt;script src="//www.google.com/js/gweb/analytics/autotrack.js"
type="text/javascript"&gt;&lt;/script&gt;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
&lt;!-- Recommended --&gt;
&lt;script src="//www.google.com/js/gweb/analytics/autotrack.js"&gt;&lt;/script&gt;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="HTML Formatting Rules">
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="General Formatting">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Use a new line for every block, list, or table element, and
indent every such child element.
</SUMMARY>
<BODY>
<p>
Independent of the styling of an element (as CSS allows
elements to assume a different role per <code>display</code>
property), put every block, list, or table element on a new
line.
</p>
<p>
Also, indent them if they are child elements of a block,
list, or table element.
</p>
<p>
(If you run into issues around whitespace between list items
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
it’s acceptable to put all <code>li</code> elements in one
Initial release
2012-04-25 06:21:00 +08:00
line. A linter is encouraged to throw a warning instead of
an error.)
</p>
<CODE_SNIPPET>
&lt;blockquote&gt;
&lt;p&gt;&lt;em&gt;Space&lt;/em&gt;, the final frontier.&lt;/p&gt;
&lt;/blockquote&gt;
</CODE_SNIPPET>
<CODE_SNIPPET>
&lt;ul&gt;
&lt;li&gt;Moe
&lt;li&gt;Larry
&lt;li&gt;Curly
&lt;/ul&gt;
</CODE_SNIPPET>
<CODE_SNIPPET>
&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th scope="col"&gt;Income
&lt;th scope="col"&gt;Taxes
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;$ 5.00
&lt;td&gt;$ 4.50
&lt;/table&gt;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="HTML Quotation Marks">
Sync.
2012-07-18 04:12:10 +08:00
<SUMMARY>
Update C++ style guide to 3.231: - Clarify that sentence-like non-sentence comments are permitted. - Note that older code with incorrect #include ordering should be fixed. - Revamp the section on default function arguments. - Avoid explicitly recommending Init() methods. - C++11: permit "auto". - C++11: permit ">>" in place of "> >". - C++11: permit range-based "for". - C++11: permit variadic macros (already permitted as a C++03 extension). - C++11: permit "LL" and "ULL" literal suffixes (already permitted as a C++03 extension). - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. - C++11: permit new features in <algorithm> and the portion of <numeric> that does not require initializer lists. - Revise rules on forward declarations: explicitly forbid forward-declared functions, do not mandate forward declarations, discourage forward-declared templates. - Remove the rule requiring "const" qualifiers for member functions to be on the same line as the closing parenthesis of the parameter list. - Fix typo: "unnamed namespaces." - C++11: permit local types as template parameters. - Fix typo: "unfamiliar." - Relax RTTI rules to permit its use, but warn about its abuse. - C++11: permit nullptr and nullptr_t. Revise text referring to NULL to refer more generically to null pointers. - Remove the "don't go crazy with const" rule. - Fix typo: "dir/foo2" should bee "dir2/foo2." - Remove reference to a specific GCC version. Update Objective-C style guide to 2.48: - Revise method declaration and invocation formatting rules for long names. - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. Top-of-file comments are not required. - Fix dead link in the "nil Checks" section. - Cover ARC. - Specify that @private is only required for instance variables in header files. - Permit NSNumber literals. - Change the naming convention for instance variables from trailing underscore to leading underscore, allowing a wide exception for existing code and projects. - Fix description of BOOL with respect to its signedness. Update Python style guide to 2.45: - Recommend "pylint: disable" over "pylint: disable-msg." - Fix case-sensitive anchor. - Provide a better explanation of the problems with catch-all "except:." - Permit "map" and "filter" in absence of inlined lambdas. Update JavaScript style guide to 2.64: - Clarify rules for requiring and providing inner dependencies on classes. - Clarify semicolons for functions. - Note proper namespace and filename casing. - Fix typos: "@extends." - Permit parentheses to be omitted on unions. - Don't require method descriptions when obvious. - "in" is a keyword, put it in <code>. - New "Aliasing with goog.scope" section. - Rewrite the "Constants" section. - Remove the recommendation to use join() to build strings. - Add the "@expose" annotation. - Fix the "@suppress" example. - Remove reference alternate cast syntax. - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. - Say that "use strict" is not required. - Fix links to "optional" section. - Rewrite "JavaScript Types" section. - Fix typos: "parameterizes," "converted." - Prefer in-constructor field initialization. - Add a section on "delete" and null-assignment. - Add a note about optional JSDoc comments on enum values. - State explicitly that dot operators belong at the ends of lines. - Add "@dict" and "@struct" annotations. - Add links to the JavaScript Types section. - Require (rather than encourage) compiling. Update HTML/CSS style guide to 2.19: - Rephrased quotation guidelines. - Updated W3C I18N article reference. - Fixed revision number. Update styleguide.xsl to 1.34: - Fix error in RefreshVisibilityFromHashParam when a URL fragment points to a named anchor within a section, as used by the JavaScript style guide.
2012-11-29 04:26:27 +08:00
When quoting attributes values, use double quotation marks.
Sync.
2012-07-18 04:12:10 +08:00
</SUMMARY>
<BODY>
<p>
Update C++ style guide to 3.231: - Clarify that sentence-like non-sentence comments are permitted. - Note that older code with incorrect #include ordering should be fixed. - Revamp the section on default function arguments. - Avoid explicitly recommending Init() methods. - C++11: permit "auto". - C++11: permit ">>" in place of "> >". - C++11: permit range-based "for". - C++11: permit variadic macros (already permitted as a C++03 extension). - C++11: permit "LL" and "ULL" literal suffixes (already permitted as a C++03 extension). - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. - C++11: permit new features in <algorithm> and the portion of <numeric> that does not require initializer lists. - Revise rules on forward declarations: explicitly forbid forward-declared functions, do not mandate forward declarations, discourage forward-declared templates. - Remove the rule requiring "const" qualifiers for member functions to be on the same line as the closing parenthesis of the parameter list. - Fix typo: "unnamed namespaces." - C++11: permit local types as template parameters. - Fix typo: "unfamiliar." - Relax RTTI rules to permit its use, but warn about its abuse. - C++11: permit nullptr and nullptr_t. Revise text referring to NULL to refer more generically to null pointers. - Remove the "don't go crazy with const" rule. - Fix typo: "dir/foo2" should bee "dir2/foo2." - Remove reference to a specific GCC version. Update Objective-C style guide to 2.48: - Revise method declaration and invocation formatting rules for long names. - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. Top-of-file comments are not required. - Fix dead link in the "nil Checks" section. - Cover ARC. - Specify that @private is only required for instance variables in header files. - Permit NSNumber literals. - Change the naming convention for instance variables from trailing underscore to leading underscore, allowing a wide exception for existing code and projects. - Fix description of BOOL with respect to its signedness. Update Python style guide to 2.45: - Recommend "pylint: disable" over "pylint: disable-msg." - Fix case-sensitive anchor. - Provide a better explanation of the problems with catch-all "except:." - Permit "map" and "filter" in absence of inlined lambdas. Update JavaScript style guide to 2.64: - Clarify rules for requiring and providing inner dependencies on classes. - Clarify semicolons for functions. - Note proper namespace and filename casing. - Fix typos: "@extends." - Permit parentheses to be omitted on unions. - Don't require method descriptions when obvious. - "in" is a keyword, put it in <code>. - New "Aliasing with goog.scope" section. - Rewrite the "Constants" section. - Remove the recommendation to use join() to build strings. - Add the "@expose" annotation. - Fix the "@suppress" example. - Remove reference alternate cast syntax. - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. - Say that "use strict" is not required. - Fix links to "optional" section. - Rewrite "JavaScript Types" section. - Fix typos: "parameterizes," "converted." - Prefer in-constructor field initialization. - Add a section on "delete" and null-assignment. - Add a note about optional JSDoc comments on enum values. - State explicitly that dot operators belong at the ends of lines. - Add "@dict" and "@struct" annotations. - Add links to the JavaScript Types section. - Require (rather than encourage) compiling. Update HTML/CSS style guide to 2.19: - Rephrased quotation guidelines. - Updated W3C I18N article reference. - Fixed revision number. Update styleguide.xsl to 1.34: - Fix error in RefreshVisibilityFromHashParam when a URL fragment points to a named anchor within a section, as used by the JavaScript style guide.
2012-11-29 04:26:27 +08:00
Use double (<code>""</code>) rather than single quotation marks
(<code>''</code>) around attribute values.
Sync.
2012-07-18 04:12:10 +08:00
</p>
<BAD_CODE_SNIPPET>
&lt;!-- Not recommended --&gt;
&lt;a class='maia-button maia-button-secondary'&gt;Sign in&lt;/a&gt;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
&lt;!-- Recommended --&gt;
&lt;a class="maia-button maia-button-secondary"&gt;Sign in&lt;/a&gt;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Initial release
2012-04-25 06:21:00 +08:00
</CATEGORY>
<CATEGORY title="CSS Style Rules">
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="CSS Validity">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Use valid CSS where possible.
</SUMMARY>
<BODY>
<p>
Unless dealing with CSS validator bugs or requiring
proprietary syntax, use valid CSS code.
</p>
<p>
Replaced HTTP where HTTPS been awailable.
2016-04-01 16:41:34 +08:00
Use tools such as the <a href="https://jigsaw.w3.org/css-validator/">W3C
Update C++ style guide to 3.231: - Clarify that sentence-like non-sentence comments are permitted. - Note that older code with incorrect #include ordering should be fixed. - Revamp the section on default function arguments. - Avoid explicitly recommending Init() methods. - C++11: permit "auto". - C++11: permit ">>" in place of "> >". - C++11: permit range-based "for". - C++11: permit variadic macros (already permitted as a C++03 extension). - C++11: permit "LL" and "ULL" literal suffixes (already permitted as a C++03 extension). - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. - C++11: permit new features in <algorithm> and the portion of <numeric> that does not require initializer lists. - Revise rules on forward declarations: explicitly forbid forward-declared functions, do not mandate forward declarations, discourage forward-declared templates. - Remove the rule requiring "const" qualifiers for member functions to be on the same line as the closing parenthesis of the parameter list. - Fix typo: "unnamed namespaces." - C++11: permit local types as template parameters. - Fix typo: "unfamiliar." - Relax RTTI rules to permit its use, but warn about its abuse. - C++11: permit nullptr and nullptr_t. Revise text referring to NULL to refer more generically to null pointers. - Remove the "don't go crazy with const" rule. - Fix typo: "dir/foo2" should bee "dir2/foo2." - Remove reference to a specific GCC version. Update Objective-C style guide to 2.48: - Revise method declaration and invocation formatting rules for long names. - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. Top-of-file comments are not required. - Fix dead link in the "nil Checks" section. - Cover ARC. - Specify that @private is only required for instance variables in header files. - Permit NSNumber literals. - Change the naming convention for instance variables from trailing underscore to leading underscore, allowing a wide exception for existing code and projects. - Fix description of BOOL with respect to its signedness. Update Python style guide to 2.45: - Recommend "pylint: disable" over "pylint: disable-msg." - Fix case-sensitive anchor. - Provide a better explanation of the problems with catch-all "except:." - Permit "map" and "filter" in absence of inlined lambdas. Update JavaScript style guide to 2.64: - Clarify rules for requiring and providing inner dependencies on classes. - Clarify semicolons for functions. - Note proper namespace and filename casing. - Fix typos: "@extends." - Permit parentheses to be omitted on unions. - Don't require method descriptions when obvious. - "in" is a keyword, put it in <code>. - New "Aliasing with goog.scope" section. - Rewrite the "Constants" section. - Remove the recommendation to use join() to build strings. - Add the "@expose" annotation. - Fix the "@suppress" example. - Remove reference alternate cast syntax. - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. - Say that "use strict" is not required. - Fix links to "optional" section. - Rewrite "JavaScript Types" section. - Fix typos: "parameterizes," "converted." - Prefer in-constructor field initialization. - Add a section on "delete" and null-assignment. - Add a note about optional JSDoc comments on enum values. - State explicitly that dot operators belong at the ends of lines. - Add "@dict" and "@struct" annotations. - Add links to the JavaScript Types section. - Require (rather than encourage) compiling. Update HTML/CSS style guide to 2.19: - Rephrased quotation guidelines. - Updated W3C I18N article reference. - Fixed revision number. Update styleguide.xsl to 1.34: - Fix error in RefreshVisibilityFromHashParam when a URL fragment points to a named anchor within a section, as used by the JavaScript style guide.
2012-11-29 04:26:27 +08:00
CSS validator</a> to test.
Initial release
2012-04-25 06:21:00 +08:00
</p>
<p>
Using valid CSS is a measurable baseline quality attribute
that allows to spot CSS code that may not have any effect
and can be removed, and that ensures proper CSS usage.
</p>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="ID and Class Naming">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Use meaningful or generic ID and class names.
</SUMMARY>
<BODY>
<p>
Instead of presentational or cryptic names, always use ID
and class names that reflect the purpose of the element in
question, or that are otherwise generic.
</p>
<p>
Names that are specific and reflect the purpose of the
element should be preferred as these are most understandable
and the least likely to change.
</p>
<p>
Generic names are simply a fallback for elements that have no
particular or no meaning different from their siblings. They are
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
typically needed as “helpers.”
Initial release
2012-04-25 06:21:00 +08:00
</p>
<p>
Using functional or generic names reduces the probability of
unnecessary document or template changes.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended: meaningless */
#yee-1901 {}
/* Not recommended: presentational */
.button-green {}
.clear {}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended: specific */
#gallery {}
#login {}
.video {}
/* Recommended: generic */
.aux {}
.alt {}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="ID and Class Name Style">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Use ID and class names that are as short as possible but as long as
necessary.
</SUMMARY>
<BODY>
<p>
Try to convey what an ID or class is about while being as
brief as possible.
</p>
<p>
Using ID and class names this way contributes to acceptable
levels of understandability and code efficiency.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended */
#navigation {}
.atr {}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
#nav {}
.author {}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Type Selectors">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Avoid qualifying ID and class names with type selectors.
</SUMMARY>
<BODY>
<p>Unless necessary (for example with helper classes), do not
use element names in conjunction with IDs or classes.
</p>
<p>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
Avoiding unnecessary ancestor selectors is useful for <a href="http://www.stevesouders.com/blog/2009/06/18/simplifying-css-selectors/">performance
Initial release
2012-04-25 06:21:00 +08:00
reasons</a>.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended */
ul#example {}
div.error {}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
#example {}
.error {}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Shorthand Properties">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Use shorthand properties where possible.
</SUMMARY>
<BODY>
<p>
Replaced HTTP where HTTPS been awailable.
2016-04-01 16:41:34 +08:00
CSS offers a variety of <a href="https://www.w3.org/TR/CSS21/about.html#shorthand">shorthand</a>
Initial release
2012-04-25 06:21:00 +08:00
properties (like <code>font</code>)
that should be used whenever possible, even in cases where
only one value is explicitly set.
</p>
<p>
Using shorthand properties is useful for code efficiency and
understandability.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended */
border-top-style: none;
font-family: palatino, georgia, serif;
font-size: 100%;
line-height: 1.6;
padding-bottom: 2em;
padding-left: 1em;
padding-right: 1em;
padding-top: 0;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
border-top: 0;
font: 100%/1.6 palatino, georgia, serif;
padding: 0 1em 2em;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="0 and Units">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
Omit unit specification after “0” values.
Initial release
2012-04-25 06:21:00 +08:00
</SUMMARY>
<BODY>
<p>
Do not use units after <code>0</code> values unless they are
required.
</p>
<CODE_SNIPPET>
margin: 0;
padding: 0;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Leading 0s">
<SUMMARY>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
Omit leading “0”s in values.
Initial release
2012-04-25 06:21:00 +08:00
</SUMMARY>
<BODY>
<p>
Do not use put <code>0</code>s in front of values or lengths
between -1 and 1.
</p>
<CODE_SNIPPET>
font-size: .8em;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Hexadecimal Notation">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Use 3 character hexadecimal notation where possible.
</SUMMARY>
<BODY>
<p>
For color values that permit it, 3 character hexadecimal
notation is shorter and more succinct.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended */
color: #eebbcc;
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
color: #ebc;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Prefixes">
<SUMMARY>
Prefix selectors with an application-specific prefix (optional).
</SUMMARY>
<BODY>
<p>
In large projects as well as for code that gets embedded in
other projects or on external sites use prefixes (as
namespaces) for ID and class names. Use short, unique
identifiers followed by a dash.
</p>
<p>
Using namespaces helps preventing naming conflicts and can
make maintenance easier, for example in search and replace
operations.
</p>
<CODE_SNIPPET>
.adw-help {} /* AdWords */
#maia-note {} /* Maia */
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="ID and Class Name Delimiters">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Separate words in ID and class names by a hyphen.
</SUMMARY>
<BODY>
<p>
Do not concatenate words and abbreviations in selectors by
any characters (including none at all) other than hyphens,
in order to improve understanding and scannability.
</p>
<BAD_CODE_SNIPPET>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
/* Not recommended: does not separate the words “demo” and “image” */
Initial release
2012-04-25 06:21:00 +08:00
.demoimage {}
/* Not recommended: uses underscore instead of hyphen */
.error_status {}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
#video-id {}
.ads-sample {}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Hacks">
<SUMMARY>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
Avoid user agent detection as well as CSS “hacks”—try a different
Initial release
2012-04-25 06:21:00 +08:00
approach first.
</SUMMARY>
<BODY>
<p>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
It’s tempting to address styling differences over user
Initial release
2012-04-25 06:21:00 +08:00
agent detection or special CSS filters, workarounds, and
hacks. Both approaches should be considered last resort in
order to achieve and maintain an efficient and manageable
code base. Put another way, giving detection and hacks a
free pass will hurt projects in the long run as projects
tend to take the way of least resistance. That is, allowing
and making it easy to use detection and hacks means using
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
detection and hacks more frequently—and more frequently
Initial release
2012-04-25 06:21:00 +08:00
is too frequently.
</p>
</BODY>
</STYLEPOINT>
</CATEGORY>
<CATEGORY title="CSS Formatting Rules">
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Declaration Order">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Alphabetize declarations.
</SUMMARY>
<BODY>
<p>
Put declarations in alphabetical order in order to achieve
consistent code in a way that is easy to remember and
maintain.
</p>
<p>
Ignore vendor-specific prefixes for sorting purposes. However,
multiple vendor-specific prefixes for a certain CSS property should
be kept sorted (e.g. -moz prefix comes before -webkit).
</p>
<CODE_SNIPPET>
background: fuchsia;
border: 1px solid;
-moz-border-radius: 4px;
-webkit-border-radius: 4px;
border-radius: 4px;
color: black;
text-align: center;
text-indent: 2em;
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Block Content Indentation">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Indent all block content.
</SUMMARY>
<BODY>
<p>
Replaced HTTP where HTTPS been awailable.
2016-04-01 16:41:34 +08:00
Indent all <a href="https://www.w3.org/TR/CSS21/syndata.html#block">block
Initial release
2012-04-25 06:21:00 +08:00
content</a>, that is rules within rules as well as declarations, so to
reflect hierarchy and improve understanding.
</p>
<CODE_SNIPPET>
@media screen, projection {
html {
background: #fff;
color: #444;
}
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Declaration Stops">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Use a semicolon after every declaration.
</SUMMARY>
<BODY>
<p>
End every declaration with a semicolon for consistency and
extensibility reasons.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended */
.test {
display: block;
height: 100px
}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
.test {
display: block;
height: 100px;
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Property Name Stops">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
Use a space after a property name’s colon.
Initial release
2012-04-25 06:21:00 +08:00
</SUMMARY>
<BODY>
<p>
Always use a single space between property and value (but no
space between property and colon) for consistency reasons.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended */
h3 {
font-weight:bold;
}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
h3 {
font-weight: bold;
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Declaration Block Separation">
<SUMMARY>
Use a space between the last selector and the declaration block.
</SUMMARY>
<BODY>
<p>
Always use a single space between the last selector and the opening
Replaced HTTP where HTTPS been awailable.
2016-04-01 16:41:34 +08:00
brace that begins the <a href="https://www.w3.org/TR/CSS21/syndata.html#rule-sets">declaration
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
block</a>.
</p>
<p>
The opening brace should be on the same line as the last selector in a
given rule.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended: missing space */
#video{
margin-top: 1em;
}
/* Not recommended: unnecessary line break */
#video
{
margin-top: 1em;
}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
#video {
margin-top: 1em;
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="Selector and Declaration Separation">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Separate selectors and declarations by new lines.
</SUMMARY>
<BODY>
<p>
Always start a new line for each selector and declaration.
</p>
<BAD_CODE_SNIPPET>
/* Not recommended */
a:focus, a:active {
position: relative; top: 1px;
}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
h1,
h2,
h3 {
font-weight: normal;
line-height: 1.2;
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Rule Separation">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Separate rules by new lines.
</SUMMARY>
<BODY>
<p>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
Always put a blank line (two line breaks) between rules.
Initial release
2012-04-25 06:21:00 +08:00
</p>
<CODE_SNIPPET>
html {
background: #fff;
}
body {
margin: auto;
width: 50%;
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="CSS Quotation Marks">
Sync.
2012-07-18 04:12:10 +08:00
<SUMMARY>
Update C++ style guide to 3.231: - Clarify that sentence-like non-sentence comments are permitted. - Note that older code with incorrect #include ordering should be fixed. - Revamp the section on default function arguments. - Avoid explicitly recommending Init() methods. - C++11: permit "auto". - C++11: permit ">>" in place of "> >". - C++11: permit range-based "for". - C++11: permit variadic macros (already permitted as a C++03 extension). - C++11: permit "LL" and "ULL" literal suffixes (already permitted as a C++03 extension). - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. - C++11: permit new features in <algorithm> and the portion of <numeric> that does not require initializer lists. - Revise rules on forward declarations: explicitly forbid forward-declared functions, do not mandate forward declarations, discourage forward-declared templates. - Remove the rule requiring "const" qualifiers for member functions to be on the same line as the closing parenthesis of the parameter list. - Fix typo: "unnamed namespaces." - C++11: permit local types as template parameters. - Fix typo: "unfamiliar." - Relax RTTI rules to permit its use, but warn about its abuse. - C++11: permit nullptr and nullptr_t. Revise text referring to NULL to refer more generically to null pointers. - Remove the "don't go crazy with const" rule. - Fix typo: "dir/foo2" should bee "dir2/foo2." - Remove reference to a specific GCC version. Update Objective-C style guide to 2.48: - Revise method declaration and invocation formatting rules for long names. - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. Top-of-file comments are not required. - Fix dead link in the "nil Checks" section. - Cover ARC. - Specify that @private is only required for instance variables in header files. - Permit NSNumber literals. - Change the naming convention for instance variables from trailing underscore to leading underscore, allowing a wide exception for existing code and projects. - Fix description of BOOL with respect to its signedness. Update Python style guide to 2.45: - Recommend "pylint: disable" over "pylint: disable-msg." - Fix case-sensitive anchor. - Provide a better explanation of the problems with catch-all "except:." - Permit "map" and "filter" in absence of inlined lambdas. Update JavaScript style guide to 2.64: - Clarify rules for requiring and providing inner dependencies on classes. - Clarify semicolons for functions. - Note proper namespace and filename casing. - Fix typos: "@extends." - Permit parentheses to be omitted on unions. - Don't require method descriptions when obvious. - "in" is a keyword, put it in <code>. - New "Aliasing with goog.scope" section. - Rewrite the "Constants" section. - Remove the recommendation to use join() to build strings. - Add the "@expose" annotation. - Fix the "@suppress" example. - Remove reference alternate cast syntax. - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. - Say that "use strict" is not required. - Fix links to "optional" section. - Rewrite "JavaScript Types" section. - Fix typos: "parameterizes," "converted." - Prefer in-constructor field initialization. - Add a section on "delete" and null-assignment. - Add a note about optional JSDoc comments on enum values. - State explicitly that dot operators belong at the ends of lines. - Add "@dict" and "@struct" annotations. - Add links to the JavaScript Types section. - Require (rather than encourage) compiling. Update HTML/CSS style guide to 2.19: - Rephrased quotation guidelines. - Updated W3C I18N article reference. - Fixed revision number. Update styleguide.xsl to 1.34: - Fix error in RefreshVisibilityFromHashParam when a URL fragment points to a named anchor within a section, as used by the JavaScript style guide.
2012-11-29 04:26:27 +08:00
Use single quotation marks for attribute selectors and property values.
Sync.
2012-07-18 04:12:10 +08:00
</SUMMARY>
<BODY>
<p>
Update C++ style guide to 3.231: - Clarify that sentence-like non-sentence comments are permitted. - Note that older code with incorrect #include ordering should be fixed. - Revamp the section on default function arguments. - Avoid explicitly recommending Init() methods. - C++11: permit "auto". - C++11: permit ">>" in place of "> >". - C++11: permit range-based "for". - C++11: permit variadic macros (already permitted as a C++03 extension). - C++11: permit "LL" and "ULL" literal suffixes (already permitted as a C++03 extension). - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. - C++11: permit new features in <algorithm> and the portion of <numeric> that does not require initializer lists. - Revise rules on forward declarations: explicitly forbid forward-declared functions, do not mandate forward declarations, discourage forward-declared templates. - Remove the rule requiring "const" qualifiers for member functions to be on the same line as the closing parenthesis of the parameter list. - Fix typo: "unnamed namespaces." - C++11: permit local types as template parameters. - Fix typo: "unfamiliar." - Relax RTTI rules to permit its use, but warn about its abuse. - C++11: permit nullptr and nullptr_t. Revise text referring to NULL to refer more generically to null pointers. - Remove the "don't go crazy with const" rule. - Fix typo: "dir/foo2" should bee "dir2/foo2." - Remove reference to a specific GCC version. Update Objective-C style guide to 2.48: - Revise method declaration and invocation formatting rules for long names. - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. Top-of-file comments are not required. - Fix dead link in the "nil Checks" section. - Cover ARC. - Specify that @private is only required for instance variables in header files. - Permit NSNumber literals. - Change the naming convention for instance variables from trailing underscore to leading underscore, allowing a wide exception for existing code and projects. - Fix description of BOOL with respect to its signedness. Update Python style guide to 2.45: - Recommend "pylint: disable" over "pylint: disable-msg." - Fix case-sensitive anchor. - Provide a better explanation of the problems with catch-all "except:." - Permit "map" and "filter" in absence of inlined lambdas. Update JavaScript style guide to 2.64: - Clarify rules for requiring and providing inner dependencies on classes. - Clarify semicolons for functions. - Note proper namespace and filename casing. - Fix typos: "@extends." - Permit parentheses to be omitted on unions. - Don't require method descriptions when obvious. - "in" is a keyword, put it in <code>. - New "Aliasing with goog.scope" section. - Rewrite the "Constants" section. - Remove the recommendation to use join() to build strings. - Add the "@expose" annotation. - Fix the "@suppress" example. - Remove reference alternate cast syntax. - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. - Say that "use strict" is not required. - Fix links to "optional" section. - Rewrite "JavaScript Types" section. - Fix typos: "parameterizes," "converted." - Prefer in-constructor field initialization. - Add a section on "delete" and null-assignment. - Add a note about optional JSDoc comments on enum values. - State explicitly that dot operators belong at the ends of lines. - Add "@dict" and "@struct" annotations. - Add links to the JavaScript Types section. - Require (rather than encourage) compiling. Update HTML/CSS style guide to 2.19: - Rephrased quotation guidelines. - Updated W3C I18N article reference. - Fixed revision number. Update styleguide.xsl to 1.34: - Fix error in RefreshVisibilityFromHashParam when a URL fragment points to a named anchor within a section, as used by the JavaScript style guide.
2012-11-29 04:26:27 +08:00
Use single (<code>''</code>) rather than double (<code>""</code>)
quotation marks for attribute selectors or property values. Do not
use quotation marks in URI values (<code>url()</code>).
</p>
<p>
Exception: If you do need to use the <code>@charset</code> rule,
Replaced HTTP where HTTPS been awailable.
2016-04-01 16:41:34 +08:00
use double quotation marks—<a href="https://www.w3.org/TR/CSS21/syndata.html#charset">single
Update C++ style guide to 3.231: - Clarify that sentence-like non-sentence comments are permitted. - Note that older code with incorrect #include ordering should be fixed. - Revamp the section on default function arguments. - Avoid explicitly recommending Init() methods. - C++11: permit "auto". - C++11: permit ">>" in place of "> >". - C++11: permit range-based "for". - C++11: permit variadic macros (already permitted as a C++03 extension). - C++11: permit "LL" and "ULL" literal suffixes (already permitted as a C++03 extension). - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. - C++11: permit new features in <algorithm> and the portion of <numeric> that does not require initializer lists. - Revise rules on forward declarations: explicitly forbid forward-declared functions, do not mandate forward declarations, discourage forward-declared templates. - Remove the rule requiring "const" qualifiers for member functions to be on the same line as the closing parenthesis of the parameter list. - Fix typo: "unnamed namespaces." - C++11: permit local types as template parameters. - Fix typo: "unfamiliar." - Relax RTTI rules to permit its use, but warn about its abuse. - C++11: permit nullptr and nullptr_t. Revise text referring to NULL to refer more generically to null pointers. - Remove the "don't go crazy with const" rule. - Fix typo: "dir/foo2" should bee "dir2/foo2." - Remove reference to a specific GCC version. Update Objective-C style guide to 2.48: - Revise method declaration and invocation formatting rules for long names. - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. Top-of-file comments are not required. - Fix dead link in the "nil Checks" section. - Cover ARC. - Specify that @private is only required for instance variables in header files. - Permit NSNumber literals. - Change the naming convention for instance variables from trailing underscore to leading underscore, allowing a wide exception for existing code and projects. - Fix description of BOOL with respect to its signedness. Update Python style guide to 2.45: - Recommend "pylint: disable" over "pylint: disable-msg." - Fix case-sensitive anchor. - Provide a better explanation of the problems with catch-all "except:." - Permit "map" and "filter" in absence of inlined lambdas. Update JavaScript style guide to 2.64: - Clarify rules for requiring and providing inner dependencies on classes. - Clarify semicolons for functions. - Note proper namespace and filename casing. - Fix typos: "@extends." - Permit parentheses to be omitted on unions. - Don't require method descriptions when obvious. - "in" is a keyword, put it in <code>. - New "Aliasing with goog.scope" section. - Rewrite the "Constants" section. - Remove the recommendation to use join() to build strings. - Add the "@expose" annotation. - Fix the "@suppress" example. - Remove reference alternate cast syntax. - Reflect the revised copyright and author line policy: copyright notices are not required, but license boilerplate may still be used (and generally contains a copyright notice). Author lines are not required. - Say that "use strict" is not required. - Fix links to "optional" section. - Rewrite "JavaScript Types" section. - Fix typos: "parameterizes," "converted." - Prefer in-constructor field initialization. - Add a section on "delete" and null-assignment. - Add a note about optional JSDoc comments on enum values. - State explicitly that dot operators belong at the ends of lines. - Add "@dict" and "@struct" annotations. - Add links to the JavaScript Types section. - Require (rather than encourage) compiling. Update HTML/CSS style guide to 2.19: - Rephrased quotation guidelines. - Updated W3C I18N article reference. - Fixed revision number. Update styleguide.xsl to 1.34: - Fix error in RefreshVisibilityFromHashParam when a URL fragment points to a named anchor within a section, as used by the JavaScript style guide.
2012-11-29 04:26:27 +08:00
quotation marks are not permitted</a>.
Sync.
2012-07-18 04:12:10 +08:00
</p>
<BAD_CODE_SNIPPET>
/* Not recommended */
@import url("//www.google.com/css/maia.css");
html {
font-family: "open sans", arial, sans-serif;
}
</BAD_CODE_SNIPPET>
<CODE_SNIPPET>
/* Recommended */
@import url(//www.google.com/css/maia.css);
html {
font-family: 'open sans', arial, sans-serif;
}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
Initial release
2012-04-25 06:21:00 +08:00
</CATEGORY>
<CATEGORY title="CSS Meta Rules">
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
<STYLEPOINT title="Section Comments">
Initial release
2012-04-25 06:21:00 +08:00
<SUMMARY>
Group sections by a section comment (optional).
</SUMMARY>
<BODY>
<p>
Sync.
2012-07-18 04:12:10 +08:00
If possible, group style sheet sections together by using
Initial release
2012-04-25 06:21:00 +08:00
comments. Separate sections with new lines.
</p>
<CODE_SNIPPET>
/* Header */
#adw-header {}
/* Footer */
#adw-footer {}
/* Gallery */
.adw-gallery {}
</CODE_SNIPPET>
</BODY>
</STYLEPOINT>
</CATEGORY>
Update C++ style guide to 3.260: - Add boost::bimap to the list of allowed Boost libraries. - C++11: remove mention of constexpr. - Remove noun/verb naming rules, and consolidate "General Naming Rules". - C++11: allow variadic templates. - Revise guidance on function definition comments. - Clarify that one space is sufficient before trailing /* */ comments. - C++11: allow alias templates. - C++11: allow <array>, deprecate Boost array. - C++11: allow unique_ptr, deprecate Boost pointer container. - C++11: allow braced initializer lists. Update Objective-C style guide to 2.56: - Add details on constant declarations to clarify naming and scope issues. - Update link to Apple's Objective-C guide. - Allow left-aligning multi-block method invocation segments. - Add section on container literals. Update Python style guide to 2.54: - Allow str.format in addition to the % operator. - Allow #!/usr/bin/python2 and #!/usr/bin/python3. - Move the closing brace example from column 4 to 0. - Remove the requirement to use named parameters for arguments with defaults. Update HTML/CSS style guide to 2.23: - No changes. Update JavaScript style guide to 2.82: - Fix typos, whitespace, and character entities. - Include property descriptions in the clause about omitting obvious comments. - Make file overviews optional. - Fix example in "HTML in JSDoc" section. - Remove the semicolon-insertion language from the operators section. - State that complete sentences are recommended but not required. - Document usage of goog.scope to declare new classes. Update Common Lisp style guide to 1.20: - Indicate both variable and function predicates require a "p". - Make the abbreviations rules consistent and in one location. - Don't allow for the use of &AUX. - Allow for "body" and "end" as exceptions to the suffix rule. - Use the TODO convention to mark code that needs to be addressed. - Remove file maintainership requirements, require a description. - Change top-level form requirements to the length of a page. - Remove "don't be clever".
2013-07-13 02:53:13 +08:00
Initial release
2012-04-25 06:21:00 +08:00
<PARTING_WORDS>
<p>
<em>Be consistent.</em>
</p>
<p>
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
If you’re editing code, take a few minutes to look at the code
Initial release
2012-04-25 06:21:00 +08:00
around you and determine its style. If they use spaces around
all their arithmetic operators, you should too. If their
comments have little boxes of hash marks around them, make your
comments have little boxes of hash marks around them too.
</p>
<p>
The point of having style guidelines is to have a common vocabulary
Update C++ style guide to 3.245: - Relax the rule for sizeof(varname) vs. sizeof(type). - Allow an exception for nonconst reference parameters where convention dictates their use, such as for swap. - C++11: allow static_assert. - Require non-trivial fall-through between cases in switch statements to be annotated. Trivial fall-through includes consecutive case labels with no intervening code, and no comment is required in these cases. - C++11: allow constexpr. - Revise the "Integer Types" section to note type-width problems. - Clarify that the "arguments on subsequent lines" function call style is acceptable even when the 80-column limit doesn't require it. - Boost: allow part of Polygon. - C++11: allow <tuple>. Update Objective-C style guide to 2.52: - Fix ARC example to not imply the use of @private in .m files. - Add an example to the "Category Names" section. - Require that ARC-using files insert preprocessor directives that generate an error when compiling without ARC. - Fix spacing around the *s in the ARC example per the C++ style guide. Update Python style guide to 2.48: - Allow comments with URLs to exceed 80 characters per line. - Update outdated implicit-line-joining URLs. Update HTML/CSS style guide to 2.21: - Consistent use of title case. - Add new "Declaration Block Separation" section. - Add a CSS example to the "Capitalization" section. - Minor fixes to whitespace. Update JavaScript style to guide to 2.72: - Make it clear that the injunction against aliasing namespaces only applies to local aliases, not goog.scope. - Clarify the style guide's recommendation on array/object literals. - Add documentation on @private {type}, @protected {type}, and @const {type}. - Make JSDoc descriptions required only if not obvious. - Clarify that only private properties and methods need a trailing underscore. - Fix spelling of arv's name. Update Common Lisp style guide to 1.18: - Macro-defining macros are harder to understand for everyone, not just for the "uninitiated." There's no need to condescend. In all of the above style guides: - The guide source is now encoded as UTF-8. The numeric character references have been replaced with raw UTF-8-encoded characters.
2013-03-22 00:03:26 +08:00
of coding so people can concentrate on what you’re saying rather
than on how you’re saying it. We present global style rules here so
Initial release
2012-04-25 06:21:00 +08:00
people know the vocabulary, but local style is also important. If
code you add to a file looks drastically different from the existing
code around it, it throws readers out of their rhythm when they go to
read it. Avoid this.
</p>
</PARTING_WORDS>
<p align="right">
Update C++ style guide to 3.260: - Add boost::bimap to the list of allowed Boost libraries. - C++11: remove mention of constexpr. - Remove noun/verb naming rules, and consolidate "General Naming Rules". - C++11: allow variadic templates. - Revise guidance on function definition comments. - Clarify that one space is sufficient before trailing /* */ comments. - C++11: allow alias templates. - C++11: allow <array>, deprecate Boost array. - C++11: allow unique_ptr, deprecate Boost pointer container. - C++11: allow braced initializer lists. Update Objective-C style guide to 2.56: - Add details on constant declarations to clarify naming and scope issues. - Update link to Apple's Objective-C guide. - Allow left-aligning multi-block method invocation segments. - Add section on container literals. Update Python style guide to 2.54: - Allow str.format in addition to the % operator. - Allow #!/usr/bin/python2 and #!/usr/bin/python3. - Move the closing brace example from column 4 to 0. - Remove the requirement to use named parameters for arguments with defaults. Update HTML/CSS style guide to 2.23: - No changes. Update JavaScript style guide to 2.82: - Fix typos, whitespace, and character entities. - Include property descriptions in the clause about omitting obvious comments. - Make file overviews optional. - Fix example in "HTML in JSDoc" section. - Remove the semicolon-insertion language from the operators section. - State that complete sentences are recommended but not required. - Document usage of goog.scope to declare new classes. Update Common Lisp style guide to 1.20: - Indicate both variable and function predicates require a "p". - Make the abbreviations rules consistent and in one location. - Don't allow for the use of &AUX. - Allow for "body" and "end" as exceptions to the suffix rule. - Use the TODO convention to mark code that needs to be addressed. - Remove file maintainership requirements, require a description. - Change top-level form requirements to the length of a page. - Remove "don't be clever".
2013-07-13 02:53:13 +08:00
Revision 2.23
Initial release
2012-04-25 06:21:00 +08:00
</p>
</GUIDE>
Reference in New Issue Copy Permalink