mirror of
https://github.com/google/styleguide.git
synced 2026-10-28 08:25:21 +08:00
Automated export from internal guides
PiperOrigin-RevId: 1001469701
This commit is contained in:
Google Open Source Bot authored and Copybara-Service committed
1 parent
b2a398d17f
commit
24cfcced57
14 files changed
+318
-321
No files matched your search
@@ -15,8 +15,10 @@ Google uses the [styler](https://github.com/r-lib/styler) package on every
|
||||
checked in file to ensure code consistency and help reviewers focus on more
|
||||
important issues.
|
||||
|
||||
<!-- mdformat off -->
|
||||
* TOC
|
||||
{:toc}
|
||||
<!-- mdformat on -->
|
||||
|
||||
## Syntax
|
||||
|
||||
|
||||
@@ -4,8 +4,10 @@ This style guide is for C# code developed internally at Google, and is the
|
||||
default style for C# code at Google. It makes stylistic choices that conform to
|
||||
other languages at Google, such as Google C++ style and Google Java style.
|
||||
|
||||
<!-- mdformat off -->
|
||||
* TOC
|
||||
{:toc}
|
||||
<!-- mdformat on -->
|
||||
|
||||
## Formatting guidelines
|
||||
|
||||
|
||||
+9
-8
@@ -2,8 +2,10 @@
|
||||
|
||||
Revision 1.01
|
||||
|
||||
<!-- mdformat off -->
|
||||
* TOC
|
||||
{:toc}
|
||||
<!-- mdformat on -->
|
||||
|
||||
<a id="Background"></a>
|
||||
|
||||
@@ -19,7 +21,8 @@ style are generally closely tied to the semantics of the code you wish to
|
||||
convey. As such, this guide tends to be somewhat less prescriptive than most, as
|
||||
there are just fewer arbitrary choices to make when coding Haskell.
|
||||
|
||||
Open-source projects developed by Google should conform to the requirements in this guide.
|
||||
Open-source projects developed by Google should conform to the requirements in
|
||||
this guide.
|
||||
|
||||
<a id="Structure"></a>
|
||||
|
||||
@@ -83,8 +86,7 @@ explicitly naming them in the export list would be counter-productive.
|
||||
### Imports
|
||||
|
||||
* Imports may be split up into groups separated by a single newline.
|
||||
* Recommended: Split imports into two groups: external and
|
||||
internal modules.
|
||||
* Recommended: Split imports into two groups: external and internal modules.
|
||||
* Within each group, imports must be alphabetized by full module name.
|
||||
* Imports can either be qualified or for specific elements. It is okay to have
|
||||
both.
|
||||
@@ -141,13 +143,12 @@ GHC options and `LANGUAGE` pragmas go at the very top of the file.
|
||||
|
||||
The `OPTIONS_GHC` directive should only be used for specific options that relate
|
||||
to the source file, such as `-fno-warn-orphans` for test code. General
|
||||
compilation options, like `-O2`, belong in
|
||||
the `.cabal` file.
|
||||
compilation options, like `-O2`, belong in the `.cabal` file.
|
||||
|
||||
Features enabled by the `LANGUAGE` pragma should always be listed in each source
|
||||
file that needs them, and never turned on globally via flags in the
|
||||
the `.cabal` file. This is so future
|
||||
developers know what language extensions are in effect when reading the code.
|
||||
file that needs them, and never turned on globally via flags in the the `.cabal`
|
||||
file. This is so future developers know what language extensions are in effect
|
||||
when reading the code.
|
||||
|
||||
`INLINE`, `INLINEABLE`, and similar pragmas should only be used when you've
|
||||
tested that they actually improve speed in cases that you care about. When used,
|
||||
|
||||
+4
-2
@@ -2,8 +2,10 @@
|
||||
|
||||
# Google HTML/CSS Style Guide
|
||||
|
||||
<!-- mdformat off -->
|
||||
* TOC
|
||||
{:toc}
|
||||
<!-- mdformat on -->
|
||||
|
||||
<div class="numbered"></div>
|
||||
|
||||
@@ -1039,8 +1041,8 @@ color: #ebc;
|
||||
Avoid using `!important` declarations.
|
||||
|
||||
These declarations break the natural cascade of CSS and make it difficult to
|
||||
reason about and compose styles. Use
|
||||
[selector specificity] to override properties instead.
|
||||
reason about and compose styles. Use [selector specificity] to override
|
||||
properties instead.
|
||||
|
||||
[selector specificity]: https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity
|
||||
|
||||
|
||||
+55
-52
@@ -2,8 +2,10 @@
|
||||
|
||||
Revision 0.9
|
||||
|
||||
<!-- mdformat off -->
|
||||
* TOC
|
||||
{:toc}
|
||||
<!-- mdformat on -->
|
||||
|
||||
<a id="Introduction"></a>
|
||||
|
||||
@@ -131,8 +133,9 @@ Choose meaningful property names.
|
||||
Property names must conform to the following guidelines:
|
||||
|
||||
* Property names should be meaningful names with defined semantics.
|
||||
* Property names must be [lower
|
||||
camel-cased](https://en.wikipedia.org/wiki/Camel_case), ASCII strings.
|
||||
* Property names must be
|
||||
[lower camel-cased](https://en.wikipedia.org/wiki/Camel_case), ASCII
|
||||
strings.
|
||||
* The first character must be a letter, an underscore (`_`) or a dollar sign
|
||||
(`$`).
|
||||
* Subsequent characters can be a letter, a digit, an underscore, or a dollar
|
||||
@@ -393,8 +396,8 @@ easily parsed.
|
||||
|
||||
Dates should be formatted as recommended by RFC 3339.
|
||||
|
||||
Dates should be strings formatted as recommended by [RFC
|
||||
3339](https://www.ietf.org/rfc/rfc3339.txt).
|
||||
Dates should be strings formatted as recommended by
|
||||
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt).
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -408,8 +411,8 @@ Dates should be strings formatted as recommended by [RFC
|
||||
|
||||
Time durations should be formatted as recommended by ISO 8601.
|
||||
|
||||
Time duration values should be strings formatted as recommended by [ISO
|
||||
8601](https://en.wikipedia.org/wiki/ISO_8601#Durations).
|
||||
Time duration values should be strings formatted as recommended by
|
||||
[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Durations).
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -425,9 +428,9 @@ Time duration values should be strings formatted as recommended by [ISO
|
||||
|
||||
Latitudes/Longitudes should be formatted as recommended by ISO 6709.
|
||||
|
||||
Latitude/Longitude should be strings formatted as recommended by [ISO
|
||||
6709](https://en.wikipedia.org/wiki/ISO_6709). Furthermore, they should favor
|
||||
the ±DD.DDDD±DDD.DDDD degrees format.
|
||||
Latitude/Longitude should be strings formatted as recommended by
|
||||
[ISO 6709](https://en.wikipedia.org/wiki/ISO_6709). Furthermore, they should
|
||||
favor the ±DD.DDDD±DDD.DDDD degrees format.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -519,7 +522,7 @@ The top-level of the JSON object may contain the following properties.
|
||||
|
||||
### apiVersion
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: -
|
||||
|
||||
Represents the desired version of the service API in a request, and the version
|
||||
@@ -537,7 +540,7 @@ Example:
|
||||
|
||||
### context
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: -
|
||||
|
||||
Client sets this value and server echoes data in the response. This is useful in
|
||||
@@ -599,7 +602,7 @@ function handleResponse(response) {
|
||||
|
||||
### id
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: -
|
||||
|
||||
A server supplied identifier for the response (regardless of whether the
|
||||
@@ -616,7 +619,7 @@ Example:
|
||||
|
||||
### method
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: -
|
||||
|
||||
Represents the operation to perform, or that was performed, on the data. In the
|
||||
@@ -641,7 +644,7 @@ operation to perform on the `params` property:
|
||||
|
||||
### params
|
||||
|
||||
Property Value Type: `object`\
|
||||
Property Value Type: `object` \
|
||||
Parent: -
|
||||
|
||||
This object serves as a map of input parameters to send to an RPC request. It
|
||||
@@ -665,7 +668,7 @@ Example:
|
||||
|
||||
### data
|
||||
|
||||
Property Value Type: `object`\
|
||||
Property Value Type: `object` \
|
||||
Parent: -
|
||||
|
||||
Container for all the data from a response. This property itself has many
|
||||
@@ -678,7 +681,7 @@ present, the `error` object takes precedence.
|
||||
|
||||
### error
|
||||
|
||||
Property Value Type: `object`\
|
||||
Property Value Type: `object` \
|
||||
Parent: -
|
||||
|
||||
Indicates that an error has occurred, with details about the error. The error
|
||||
@@ -714,7 +717,7 @@ The `data` property of the JSON object may contain the following properties.
|
||||
|
||||
### data.kind
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: `data`
|
||||
|
||||
The `kind` property serves as a guide to what type of information this
|
||||
@@ -735,7 +738,7 @@ Example:
|
||||
|
||||
### data.fields
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: `data`
|
||||
|
||||
Represents the fields present in the response when doing a partial GET, or the
|
||||
@@ -759,7 +762,7 @@ Example:
|
||||
|
||||
### data.etag
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: `data`
|
||||
|
||||
Represents the etag for the response. Details about ETags in the GData APIs can
|
||||
@@ -776,7 +779,7 @@ Example:
|
||||
|
||||
### data.id
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: `data`
|
||||
|
||||
A globally unique string used to reference the object. The specific details of
|
||||
@@ -792,13 +795,13 @@ Example:
|
||||
|
||||
### data.lang
|
||||
|
||||
Property Value Type: `string` (formatted as specified in BCP 47)\
|
||||
Property Value Type: `string` (formatted as specified in BCP 47) \
|
||||
Parent: `data` (or any child element)
|
||||
|
||||
Indicates the language of the rest of the properties in this object. This
|
||||
property mimics HTML's `lang` property and XML's `xml:lang` properties. The
|
||||
value should be a language value as defined in [BCP
|
||||
47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt). If a single JSON object
|
||||
value should be a language value as defined in
|
||||
[BCP 47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt). If a single JSON object
|
||||
contains data in multiple languages, the service is responsible for developing
|
||||
and documenting an appropriate location for the `lang` property.
|
||||
|
||||
@@ -819,7 +822,7 @@ Example:
|
||||
|
||||
### data.updated
|
||||
|
||||
Property Value Type: `string` (formatted as specified in RFC 3339)\
|
||||
Property Value Type: `string` (formatted as specified in RFC 3339) \
|
||||
Parent: `data`
|
||||
|
||||
Indicates the last date/time ([RFC 3339](https://www.ietf.org/rfc/rfc3339.txt))
|
||||
@@ -835,7 +838,7 @@ Example:
|
||||
|
||||
### data.deleted
|
||||
|
||||
Property Value Type: `boolean`\
|
||||
Property Value Type: `boolean` \
|
||||
Parent: `data` (or any child element)
|
||||
|
||||
A marker element, that, when present, indicates the containing entry is deleted.
|
||||
@@ -858,7 +861,7 @@ Example:
|
||||
|
||||
### data.items
|
||||
|
||||
Property Value Type: `array`\
|
||||
Property Value Type: `array` \
|
||||
Parent: `data`
|
||||
|
||||
The property name `items` is reserved to represent an array of items (for
|
||||
@@ -895,9 +898,9 @@ The paging properties below allow for various styles of paging, including:
|
||||
|
||||
* Previous/Next paging - Allows users to move forward and backward through a
|
||||
list, one page at a time. The `nextLink` and `previousLink` properties
|
||||
(described in the [Reserved Property Names for
|
||||
Links](#Reserved_Property_Names_for_Links) section below) are used for this
|
||||
style of paging.
|
||||
(described in the
|
||||
[Reserved Property Names for Links](#Reserved_Property_Names_for_Links)
|
||||
section below) are used for this style of paging.
|
||||
* Index-based paging - Allows users to jump directly to a specific item
|
||||
position within a list of items. For example, to load 10 items starting at
|
||||
item 200, the developer may point the user to a URL with the query string
|
||||
@@ -917,7 +920,7 @@ the end of this guide.
|
||||
|
||||
### data.currentItemCount
|
||||
|
||||
Property Value Type: `integer`\
|
||||
Property Value Type: `integer` \
|
||||
Parent: `data`
|
||||
|
||||
The number of items in this result set. Should be equivalent to `items.length`,
|
||||
@@ -944,7 +947,7 @@ Example:
|
||||
|
||||
### data.itemsPerPage
|
||||
|
||||
Property Value Type: `integer`\
|
||||
Property Value Type: `integer` \
|
||||
Parent: `data`
|
||||
|
||||
The number of items in the result. This is not necessarily the size of the
|
||||
@@ -966,7 +969,7 @@ Example:
|
||||
|
||||
### data.startIndex
|
||||
|
||||
Property Value Type: `integer`\
|
||||
Property Value Type: `integer` \
|
||||
Parent: `data`
|
||||
|
||||
The index of the first item in `data.items`. For consistency, `startIndex`
|
||||
@@ -988,7 +991,7 @@ Example:
|
||||
|
||||
### data.totalItems
|
||||
|
||||
Property Value Type: `integer`\
|
||||
Property Value Type: `integer` \
|
||||
Parent: `data`
|
||||
|
||||
The total number of items available in this set. For example, if a user has 100
|
||||
@@ -1009,7 +1012,7 @@ Example:
|
||||
|
||||
### data.pagingLinkTemplate
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: `data`
|
||||
|
||||
A URI template indicating how users can calculate subsequent paging links. The
|
||||
@@ -1030,7 +1033,7 @@ Example:
|
||||
|
||||
### data.pageIndex
|
||||
|
||||
Property Value Type: `integer`\
|
||||
Property Value Type: `integer` \
|
||||
Parent: `data`
|
||||
|
||||
The index of the current page of items. For consistency, `pageIndex` should be
|
||||
@@ -1052,7 +1055,7 @@ Example:
|
||||
|
||||
### data.totalPages
|
||||
|
||||
Property Value Type: `integer`\
|
||||
Property Value Type: `integer` \
|
||||
Parent: `data`
|
||||
|
||||
The total number of pages in the result set. `totalPages` can also be calculated
|
||||
@@ -1085,7 +1088,7 @@ references to other resources. There are two forms of link properties:
|
||||
|
||||
### data.self / data.selfLink
|
||||
|
||||
Property Value Type: `object` / `string`\
|
||||
Property Value Type: `object` / `string` \
|
||||
Parent: `data`
|
||||
|
||||
The self link can be used to retrieve the item's data. For example, in a list of
|
||||
@@ -1107,7 +1110,7 @@ Example:
|
||||
|
||||
### data.edit / data.editLink
|
||||
|
||||
Property Value Type: `object` / `string`\
|
||||
Property Value Type: `object` / `string` \
|
||||
Parent: `data`
|
||||
|
||||
The edit link indicates where a user can send update or delete requests. This is
|
||||
@@ -1129,7 +1132,7 @@ Example:
|
||||
|
||||
### data.next / data.nextLink
|
||||
|
||||
Property Value Type: `object` / `string`\
|
||||
Property Value Type: `object` / `string` \
|
||||
Parent: `data`
|
||||
|
||||
The next link indicates how more data can be retrieved. It points to the
|
||||
@@ -1152,7 +1155,7 @@ Example:
|
||||
|
||||
### data.previous / data.previousLink
|
||||
|
||||
Property Value Type: `object` / `string`\
|
||||
Property Value Type: `object` / `string` \
|
||||
Parent: `data`
|
||||
|
||||
The previous link indicates how more data can be retrieved. It points to the
|
||||
@@ -1181,7 +1184,7 @@ The `error` property of the JSON object may contain the following properties.
|
||||
|
||||
### error.code
|
||||
|
||||
Property Value Type: `integer`\
|
||||
Property Value Type: `integer` \
|
||||
Parent: `error`
|
||||
|
||||
Represents the code for this error. This property value will usually represent
|
||||
@@ -1202,7 +1205,7 @@ Example:
|
||||
|
||||
### error.message
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: `error`
|
||||
|
||||
A human readable message providing more details about the error. If there are
|
||||
@@ -1222,7 +1225,7 @@ Example:
|
||||
|
||||
### error.errors
|
||||
|
||||
Property Value Type: `array`\
|
||||
Property Value Type: `array` \
|
||||
Parent: `error`
|
||||
|
||||
Container for any additional information regarding the error. If the service
|
||||
@@ -1239,7 +1242,7 @@ Example:
|
||||
|
||||
### error.errors\[\].domain
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: `error.errors`
|
||||
|
||||
Unique identifier for the service raising this error. This helps distinguish
|
||||
@@ -1260,7 +1263,7 @@ Example:
|
||||
|
||||
### error.errors\[\].reason
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: `error.errors`
|
||||
|
||||
Unique identifier for this error. Different from the `error.code` property in
|
||||
@@ -1280,7 +1283,7 @@ Example:
|
||||
|
||||
### error.errors\[\].message
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: `error.errors`
|
||||
|
||||
A human readable message providing more details about the error. If there is
|
||||
@@ -1302,7 +1305,7 @@ Example:
|
||||
|
||||
### error.errors\[\].location
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: `error.errors`
|
||||
|
||||
The location of the error (the interpretation of its value depends on
|
||||
@@ -1322,7 +1325,7 @@ Example:
|
||||
|
||||
### error.errors\[\].locationType
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: `error.errors`
|
||||
|
||||
Indicates how the `location` property should be interpreted.
|
||||
@@ -1341,7 +1344,7 @@ Example:
|
||||
|
||||
### error.errors\[\].extendedHelp
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: `error.errors`
|
||||
|
||||
A URI for a help text that might shed some more light on the error.
|
||||
@@ -1360,7 +1363,7 @@ Example:
|
||||
|
||||
### error.errors\[\].sendReport
|
||||
|
||||
Property Value Type: `string`\
|
||||
Property Value Type: `string` \
|
||||
Parent: `error.errors`
|
||||
|
||||
A URI for a report form used by the service to collect data about the error
|
||||
@@ -1573,8 +1576,8 @@ The words below are reserved by the JavaScript language and cannot be referred
|
||||
to using dot notation. The list represents best knowledge of keywords at this
|
||||
time; the list may change or vary based on your specific execution environment.
|
||||
|
||||
From the [ECMAScript Language Specification 5th
|
||||
Edition](https://www.ecma-international.org/publications-and-standards/standards/ecma-262/):
|
||||
From the
|
||||
[ECMAScript Language Specification 5th Edition](https://www.ecma-international.org/publications-and-standards/standards/ecma-262/):
|
||||
|
||||
<div class='badcode'></div>
|
||||
|
||||
|
||||
+17
-12
@@ -13,8 +13,10 @@ mistakes in this document, you may file bugs in the
|
||||
"[Lisp]" in the issue title since the repository contains Style Guides for
|
||||
several languages.
|
||||
|
||||
<!-- mdformat off -->
|
||||
* TOC
|
||||
{:toc}
|
||||
<!-- mdformat on -->
|
||||
|
||||
### References
|
||||
|
||||
@@ -1038,7 +1040,9 @@ assignments.
|
||||
|
||||
### Assertions and Conditions
|
||||
|
||||
Use `assert`, `check-type`, and `etypecase` to detect internal bugs only, and use them liberally.
|
||||
Use `assert`, `check-type`, and `etypecase` to detect internal bugs only, and
|
||||
use them liberally.
|
||||
|
||||
- Prefer `etypecase` over `typecase`
|
||||
- Use `error` to check input from a file.
|
||||
- If a function signals an error, document it in its contract.
|
||||
@@ -1053,14 +1057,13 @@ Use `assert`, `check-type`, and `etypecase` to detect internal bugs only, and us
|
||||
- Never clean up by resignaling.
|
||||
- Never return a condition or error value, signal it with ERROR instead.
|
||||
|
||||
Use `assert` to detect internal bugs ONLY.
|
||||
Code should `assert` invariants whose failure indicates that the software is
|
||||
itself broken. Incorrect input should be handled properly at runtime, and must
|
||||
not cause an assertion violation. The audience for an `assert` failure is a
|
||||
developer. Do not use the data-form and argument-form in `assert` to specify a
|
||||
condition to signal. It's fine to use them to print out a message for debugging
|
||||
purposes (and since it's only for debugging, there's no issue of
|
||||
internationalization).
|
||||
Use `assert` to detect internal bugs ONLY. Code should `assert` invariants whose
|
||||
failure indicates that the software is itself broken. Incorrect input should be
|
||||
handled properly at runtime, and must not cause an assertion violation. The
|
||||
audience for an `assert` failure is a developer. Do not use the data-form and
|
||||
argument-form in `assert` to specify a condition to signal. It's fine to use
|
||||
them to print out a message for debugging purposes (and since it's only for
|
||||
debugging, there's no issue of internationalization).
|
||||
|
||||
`check-type`, `etypecase` are also forms of assertion. When one of these fails,
|
||||
that's a detected bug. Prefer `check-type` over `(declare (type ...))` for the
|
||||
@@ -1170,7 +1173,8 @@ Scott McKay puts it:
|
||||
|
||||
Use appropriate declarations in internal low-level functions where these
|
||||
declarations are used for optimization. When you do, however, see our
|
||||
recommendations for [Unsafe Operations](lispprogrammingguide.md#unsafe-operations).
|
||||
recommendations for
|
||||
[Unsafe Operations](lispprogrammingguide.md#unsafe-operations).
|
||||
|
||||
## Meta-language guidelines
|
||||
|
||||
@@ -1734,8 +1738,9 @@ or control to leak to attackers.
|
||||
- Use `:START` and `:END` arguments to `string=` or `string-equal` instead of
|
||||
using `subseq`.
|
||||
- Use `zerop`, `plusp`, or `minusp` instead of comparing to `0` or `0.0`.
|
||||
- See also [Comparison Operators](lispprogrammingguide.md#comparison-operators) in
|
||||
the programming guide for proper usage.
|
||||
- See also
|
||||
[Comparison Operators](lispprogrammingguide.md#comparison-operators) in the
|
||||
programming guide for proper usage.
|
||||
|
||||
When choosing between `eq` and `eql`, you should use `eql` unless you are
|
||||
writing performance-critical low-level code. `eql` reduces the opportunity for a
|
||||
|
||||
@@ -8,8 +8,10 @@ style, but that are important to new Lisp Programmers. The three main topics
|
||||
covered include common optimization techniques, as well as common pitfalls for
|
||||
new Lisp programmers.
|
||||
|
||||
<!-- mdformat off -->
|
||||
* TOC
|
||||
{:toc}
|
||||
<!-- mdformat on -->
|
||||
|
||||
## Optimization
|
||||
|
||||
@@ -296,8 +298,8 @@ none~; ~S~; ~S and ~S~:;~@{~#[~; and~] ~S~^ ,~}~]."`
|
||||
|
||||
- You should the appropriate predicates when comparing objects.
|
||||
- Also see the notes for
|
||||
[Comparison Operators](lispguide.md#comparison-operators) in the style
|
||||
guide for style rules.
|
||||
[Comparison Operators](lispguide.md#comparison-operators) in the style guide
|
||||
for style rules.
|
||||
|
||||
Lisp provides four general equality predicates: `EQ`, `EQL`, `EQUAL`, and
|
||||
`EQUALP`, which subtly vary in semantics. Additionally, Lisp provides the
|
||||
|
||||
+78
-77
@@ -5,22 +5,24 @@
|
||||
> is one of the primary development languages for applications on Apple
|
||||
> platforms.
|
||||
>
|
||||
> Apple has already written a very good, and widely accepted, [Cocoa Coding
|
||||
> Guidelines](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html)
|
||||
> Apple has already written a very good, and widely accepted,
|
||||
> [Cocoa Coding Guidelines](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html)
|
||||
> for Objective-C. Please read it in addition to this guide.
|
||||
>
|
||||
> The purpose of this document is to describe the Objective-C (and
|
||||
> Objective-C++) coding guidelines and practices. These guidelines have evolved
|
||||
> and been proven over time on other projects and teams.
|
||||
> Open-source projects developed by Google conform to the requirements in this guide.
|
||||
> and been proven over time on other projects and teams. Open-source projects
|
||||
> developed by Google conform to the requirements in this guide.
|
||||
>
|
||||
> Note that this guide is not an Objective-C tutorial. We assume that the reader
|
||||
> is familiar with the language. If you are new to Objective-C or need a
|
||||
> refresher, please read [Programming with
|
||||
> Objective-C](https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html).
|
||||
> refresher, please read
|
||||
> [Programming with Objective-C](https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html).
|
||||
|
||||
<!-- mdformat off -->
|
||||
* TOC
|
||||
{:toc}
|
||||
<!-- mdformat on -->
|
||||
|
||||
## Principles
|
||||
|
||||
@@ -170,8 +172,7 @@ An example source file, demonstrating the correct commenting and spacing for the
|
||||
## Naming
|
||||
|
||||
Names should be as descriptive as possible, within reason. Follow standard
|
||||
[Objective-C naming
|
||||
rules](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html).
|
||||
[Objective-C naming rules](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html).
|
||||
|
||||
Avoid non-standard abbreviations (including non-standard acronyms and
|
||||
initialisms). Don't worry about saving horizontal space as it is far more
|
||||
@@ -439,8 +440,8 @@ NSEnumerator *enumerator = [frogs reverseObjectEnumerator]; // GOOD.
|
||||
NSEnumerator *enumerator = frogs.reverseObjectEnumerator; // AVOID.
|
||||
```
|
||||
|
||||
See [Apple's Guide to Naming
|
||||
Methods](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingMethods.html#//apple_ref/doc/uid/20001282-BCIGIJJF)
|
||||
See
|
||||
[Apple's Guide to Naming Methods](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingMethods.html#//apple_ref/doc/uid/20001282-BCIGIJJF)
|
||||
for more details on Objective-C naming.
|
||||
|
||||
These guidelines are for Objective-C methods only. C++ method names continue to
|
||||
@@ -620,10 +621,10 @@ void CallWithAFoo(Foo *foo);
|
||||
|
||||
### Method Declarations
|
||||
|
||||
As shown in the [example](#Example), the recommended order
|
||||
for declarations in an `@interface` declaration are: properties, class methods,
|
||||
initializers, and then finally instance methods. The class methods section
|
||||
should begin with any convenience constructors.
|
||||
As shown in the [example](#Example), the recommended order for declarations in
|
||||
an `@interface` declaration are: properties, class methods, initializers, and
|
||||
then finally instance methods. The class methods section should begin with any
|
||||
convenience constructors.
|
||||
|
||||
<a id="Local_Variables"></a>
|
||||
|
||||
@@ -661,8 +662,8 @@ objects are automatically initialized to `nil`, so explicit initialization to
|
||||
`nil` is not required for those common cases. However, automatic initialization
|
||||
does *not* occur for many Objective-C pointer types, including object pointers
|
||||
declared with the `__unsafe_unretained` ownership qualifier and CoreFoundation
|
||||
object pointer types. When in doubt, prefer to initialize all Objective-C
|
||||
local variables.
|
||||
object pointer types. When in doubt, prefer to initialize all Objective-C local
|
||||
variables.
|
||||
|
||||
### Static Variables
|
||||
|
||||
@@ -718,8 +719,8 @@ NS_ENUM will be more appropriate.
|
||||
|
||||
Be aware that types long, NSInteger, NSUInteger and CGFloat have sizes that
|
||||
differ in 32- and 64-bit builds. Their use is appropriate when matching system
|
||||
interfaces but should be avoided when dealing with APIs that
|
||||
require exact sizing, e.g., proto APIs.
|
||||
interfaces but should be avoided when dealing with APIs that require exact
|
||||
sizing, e.g., proto APIs.
|
||||
|
||||
<div class='goodcode'></div>
|
||||
|
||||
@@ -755,8 +756,8 @@ warnings.
|
||||
Since all Google iOS projects are now targeting only 64-bit runtime, `CGFloat`
|
||||
constants may omit the suffix (use `double` values). However, teams may choose
|
||||
to continue using `float` numbers for legacy code consistency, until they
|
||||
eventually migrate to `double` values everywhere. Avoid a mixture of `float`
|
||||
and `double` values in the same code.
|
||||
eventually migrate to `double` values everywhere. Avoid a mixture of `float` and
|
||||
`double` values in the same code.
|
||||
|
||||
<div class='goodcode'></div>
|
||||
|
||||
@@ -806,15 +807,15 @@ will need to understand your code. Be generous—the next one may be you!
|
||||
A file may optionally start with a description of its contents.
|
||||
|
||||
Every file may contain the following items, in order
|
||||
* License boilerplate if necessary. Choose the appropriate boilerplate for the
|
||||
|
||||
* License boilerplate if necessary. Choose the appropriate boilerplate for the
|
||||
license used by the project.
|
||||
* A basic description of the contents of the file if necessary.
|
||||
* A basic description of the contents of the file if necessary.
|
||||
|
||||
If you make significant changes to a file with an author line, consider deleting
|
||||
the author line since revision history already provides a more detailed and
|
||||
accurate record of authorship.
|
||||
|
||||
|
||||
<a id="Declaration_Comments"></a>
|
||||
|
||||
### Declaration Comments
|
||||
@@ -825,7 +826,6 @@ comment describing its purpose and how it fits into the larger picture.
|
||||
Comments should be used to document classes, properties, ivars, functions,
|
||||
categories, protocol declarations, and enums.
|
||||
|
||||
|
||||
<div class='goodcode'></div>
|
||||
|
||||
```objectivec
|
||||
@@ -848,10 +848,9 @@ categories, protocol declarations, and enums.
|
||||
```
|
||||
|
||||
[Doxygen](https://doxygen.nl)-style comments are encouraged for interfaces as
|
||||
they are parsed by Xcode
|
||||
to display formatted documentation. There is a wide variety of
|
||||
[Doxygen commands](https://www.doxygen.nl/manual/commands.html);
|
||||
use them consistently within a project.
|
||||
they are parsed by Xcode to display formatted documentation. There is a wide
|
||||
variety of [Doxygen commands](https://www.doxygen.nl/manual/commands.html); use
|
||||
them consistently within a project.
|
||||
|
||||
If you have already described an interface in detail in the comments at the top
|
||||
of your file, feel free to simply state, "See comment at top of file for a
|
||||
@@ -877,10 +876,10 @@ Declaration comments explain how a method or function is used. Comments
|
||||
explaining how a method or function is implemented should be with the
|
||||
implementation rather than with the declaration.
|
||||
|
||||
Declaration comments may be omitted on test case classes and test methods
|
||||
if comments would communicate no additional information beyond the method's
|
||||
name. Utility methods in tests or test-specific classes (such as helpers) should
|
||||
be commented.
|
||||
Declaration comments may be omitted on test case classes and test methods if
|
||||
comments would communicate no additional information beyond the method's name.
|
||||
Utility methods in tests or test-specific classes (such as helpers) should be
|
||||
commented.
|
||||
|
||||
<a id="Implementation_Comments"></a>
|
||||
|
||||
@@ -918,8 +917,8 @@ line them up.
|
||||
### Disambiguating Symbols
|
||||
|
||||
Where needed to avoid ambiguity, use backticks or vertical bars to quote
|
||||
variable names and symbols in comments in preference to using quotation marks
|
||||
or naming the symbols inline.
|
||||
variable names and symbols in comments in preference to using quotation marks or
|
||||
naming the symbols inline.
|
||||
|
||||
In Doxygen-style comments, prefer demarcating symbols with a monospace text
|
||||
command, such as [`@c`](https://www.doxygen.nl/manual/commands.html#cmdc).
|
||||
@@ -1062,9 +1061,9 @@ practices. Do not define macros that appear to be C or Objective-C keywords.
|
||||
Avoid macros that expand to unbalanced C or Objective-C constructs. Avoid macros
|
||||
that introduce scope, or may obscure the capturing of values in blocks.
|
||||
|
||||
Avoid macros that generate class, property, or method definitions in
|
||||
headers to be used as public API. These only make the code hard to
|
||||
understand, and the language already has better ways of doing this.
|
||||
Avoid macros that generate class, property, or method definitions in headers to
|
||||
be used as public API. These only make the code hard to understand, and the
|
||||
language already has better ways of doing this.
|
||||
|
||||
Avoid macros that generate method implementations, or that generate declarations
|
||||
of variables that are later used outside of the macro. Macros shouldn't make
|
||||
@@ -1083,9 +1082,9 @@ ARRAY_ADDER(NSString) {
|
||||
}
|
||||
```
|
||||
|
||||
Examples of acceptable macro use include assertion and debug logging macros
|
||||
that are conditionally compiled based on build settings—often, these are
|
||||
not compiled into release builds.
|
||||
Examples of acceptable macro use include assertion and debug logging macros that
|
||||
are conditionally compiled based on build settings—often, these are not compiled
|
||||
into release builds.
|
||||
|
||||
### `nullptr` vs. `NULL`
|
||||
|
||||
@@ -1225,8 +1224,8 @@ Convenience class factory methods for creating instances may precede the
|
||||
Don't initialize instance variables to `0` or `nil` in the `init` method; doing
|
||||
so is redundant.
|
||||
|
||||
All instance variables for a newly allocated object are [initialized
|
||||
to](https://developer.apple.com/library/mac/documentation/General/Conceptual/CocoaEncyclopedia/ObjectAllocation/ObjectAllocation.html)
|
||||
All instance variables for a newly allocated object are
|
||||
[initialized to](https://developer.apple.com/library/mac/documentation/General/Conceptual/CocoaEncyclopedia/ObjectAllocation/ObjectAllocation.html)
|
||||
`0` (except for isa), so don't clutter up the init method by re-initializing
|
||||
variables to `0` or `nil`.
|
||||
|
||||
@@ -1281,8 +1280,8 @@ prevent subclasses from unintentionally overriding them.
|
||||
|
||||
`#import` Objective-C and Objective-C++ headers, and `#include` C/C++ headers.
|
||||
|
||||
C/C++ headers include other C/C++ headers using `#include`. Using `#import`
|
||||
on C/C++ headers prevents future inclusions using `#include` and could result in
|
||||
C/C++ headers include other C/C++ headers using `#include`. Using `#import` on
|
||||
C/C++ headers prevents future inclusions using `#include` and could result in
|
||||
unintended compilation behavior.
|
||||
|
||||
C/C++ headers should provide their own `#define` guard.
|
||||
@@ -1295,9 +1294,9 @@ The standard order for header inclusion is the related header, operating system
|
||||
headers, language library headers, and finally groups of headers for other
|
||||
dependencies.
|
||||
|
||||
The related header precedes others to ensure it has no hidden dependencies.
|
||||
For implementation files the related header is the header file.
|
||||
For test files the related header is the header containing the tested interface.
|
||||
The related header precedes others to ensure it has no hidden dependencies. For
|
||||
implementation files the related header is the header file. For test files the
|
||||
related header is the header containing the tested interface.
|
||||
|
||||
Separate each non-empty group of includes with one blank line. Within each group
|
||||
the includes should be ordered alphabetically.
|
||||
@@ -1477,8 +1476,8 @@ leading to slower execution and substantial increases in binary size.
|
||||
|
||||
### Mutables, Copies and Ownership
|
||||
|
||||
For [Foundation and other hierarchies containing both immutable and mutable
|
||||
subclasses](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/ObjectMutability/ObjectMutability.html)
|
||||
For
|
||||
[Foundation and other hierarchies containing both immutable and mutable subclasses](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/ObjectMutability/ObjectMutability.html)
|
||||
a mutable subclass may be substituted for an immutable so long as the
|
||||
immutable's contract is honored.
|
||||
|
||||
@@ -1545,9 +1544,8 @@ initializers and setters
|
||||
Synthesized accessors should use the `copy` keyword to ensure the generated code
|
||||
matches these expectations.
|
||||
|
||||
NOTE: [The `copy` property keyword only affects the synthesized setter and has
|
||||
no effect on
|
||||
getters](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ObjectiveC/Chapters/ocProperties.html#//apple_ref/doc/uid/TP30001163-CH17-SW27).
|
||||
NOTE:
|
||||
[The `copy` property keyword only affects the synthesized setter and has no effect on getters](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ObjectiveC/Chapters/ocProperties.html#//apple_ref/doc/uid/TP30001163-CH17-SW27).
|
||||
Since property keywords have no effect on direct ivar access, custom accessors
|
||||
must implement the same copy semantics.
|
||||
|
||||
@@ -1674,8 +1672,7 @@ Don't `@throw` Objective-C exceptions, but you should be prepared to catch them
|
||||
from third-party or OS calls.
|
||||
|
||||
This follows the recommendation to use error objects for error delivery in
|
||||
[Apple's Introduction to Exception Programming Topics for
|
||||
Cocoa](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/Exceptions/Exceptions.html).
|
||||
[Apple's Introduction to Exception Programming Topics for Cocoa](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/Exceptions/Exceptions.html).
|
||||
|
||||
We do compile with `-fobjc-exceptions` (mainly so we get `@synchronized`), but
|
||||
we don't `@throw`. Uses of `@try`, `@catch`, and `@finally` are allowed when
|
||||
@@ -1687,8 +1684,8 @@ document exactly which methods you expect to throw.
|
||||
### `nil` Checks
|
||||
|
||||
Avoid `nil` pointer checks that exist only to prevent sending messages to `nil`.
|
||||
Sending a message to `nil` [reliably
|
||||
returns](http://www.sealiesoftware.com/blog/archive/2012/2/29/objc_explain_return_value_of_message_to_nil.html)
|
||||
Sending a message to `nil`
|
||||
[reliably returns](http://www.sealiesoftware.com/blog/archive/2012/2/29/objc_explain_return_value_of_message_to_nil.html)
|
||||
`nil` as a pointer, zero as an integer or floating-point value, structs
|
||||
initialized to `0`, and `_Complex` values equal to `{0, 0}`.
|
||||
|
||||
@@ -1761,22 +1758,23 @@ NSArray<GTMBook *> *__nullable GTMLoadBooksFromTitle(NSString *__nonnull path);
|
||||
|
||||
Do not assume that a pointer is not null based on a nonnull qualifier, because
|
||||
the compiler only checks a subset of such cases, and does not guarantee that the
|
||||
pointer is not null. Avoid intentionally violating nullability semantics
|
||||
of function, method, and property declarations.
|
||||
pointer is not null. Avoid intentionally violating nullability semantics of
|
||||
function, method, and property declarations.
|
||||
|
||||
<a id="BOOL_Pitfalls"></a>
|
||||
|
||||
### BOOL Pitfalls
|
||||
|
||||
<a id="BOOL_Expressions_Conversions"></a>
|
||||
|
||||
#### BOOL Expressions and Conversions
|
||||
|
||||
Be careful when converting general integral values to `BOOL`. Avoid comparing
|
||||
directly with `YES` or comparing multiple `BOOL` values with comparison
|
||||
operators.
|
||||
|
||||
`BOOL` on some Apple platforms (notably Intel macOS, watchOS, and 32-bit iOS)
|
||||
is defined as a signed `char`, so it may have values other than `YES` (`1`) and
|
||||
`BOOL` on some Apple platforms (notably Intel macOS, watchOS, and 32-bit iOS) is
|
||||
defined as a signed `char`, so it may have values other than `YES` (`1`) and
|
||||
`NO` (`0`). Do not cast or convert general integral values directly to `BOOL`.
|
||||
|
||||
Common mistakes include casting or converting an array's size, a pointer value,
|
||||
@@ -1826,9 +1824,9 @@ conditional operator.
|
||||
}
|
||||
```
|
||||
|
||||
Don't directly compare `BOOL` variables with `YES`. Not only is
|
||||
it harder to read for those well-versed in C, but the first point above
|
||||
demonstrates that return values may not always be what you expect.
|
||||
Don't directly compare `BOOL` variables with `YES`. Not only is it harder to
|
||||
read for those well-versed in C, but the first point above demonstrates that
|
||||
return values may not always be what you expect.
|
||||
|
||||
<div class='badcode'></div>
|
||||
|
||||
@@ -1848,9 +1846,9 @@ if (great) { // GOOD.
|
||||
}
|
||||
```
|
||||
|
||||
Don't directly compare `BOOL` values using comparison operators. `BOOL`
|
||||
values that are true may not be equal. Use logical operators in place
|
||||
of bitwise comparisons of `BOOL` values.
|
||||
Don't directly compare `BOOL` values using comparison operators. `BOOL` values
|
||||
that are true may not be equal. Use logical operators in place of bitwise
|
||||
comparisons of `BOOL` values.
|
||||
|
||||
<div class='badcode'></div>
|
||||
|
||||
@@ -1875,14 +1873,17 @@ if (!oldBoolValue != !newBoolValue) {
|
||||
|
||||
#### BOOL Literals
|
||||
|
||||
The [BOOL NSNumber literals](https://clang.llvm.org/docs/ObjectiveCLiterals.html#nsnumber-literals)
|
||||
The
|
||||
[BOOL NSNumber literals](https://clang.llvm.org/docs/ObjectiveCLiterals.html#nsnumber-literals)
|
||||
are `@YES` and `@NO` which are equivalent to `[NSNumber numberWithBool:...]`.
|
||||
|
||||
Avoid using [boxed expressions](https://clang.llvm.org/docs/ObjectiveCLiterals.html#boxed-expressions)
|
||||
to create BOOL values, including simple expressions like `@(YES)`.
|
||||
Boxed expressions suffer from [the same pitfalls as other BOOL expressions]
|
||||
(#BOOL_Expressions_Conversions) as boxing general integral values can
|
||||
produce true or false `NSNumbers` that are not equal to `@YES` and `@NO`.
|
||||
Avoid using
|
||||
[boxed expressions](https://clang.llvm.org/docs/ObjectiveCLiterals.html#boxed-expressions)
|
||||
to create BOOL values, including simple expressions like `@(YES)`. Boxed
|
||||
expressions suffer from
|
||||
[the same pitfalls as other BOOL expressions](#BOOL_Expressions_Conversions) as
|
||||
boxing general integral values can produce true or false `NSNumbers` that are
|
||||
not equal to `@YES` and `@NO`.
|
||||
|
||||
When converting a general integral value to a BOOL literal, use conditional
|
||||
operators to convert to `@YES` or `@NO`. Do not embed a conditional operator
|
||||
@@ -2127,8 +2128,8 @@ next line indented by at least four spaces.
|
||||
|
||||
Prefer putting the return type on the same line as the function name and append
|
||||
all parameters on the same line if they will fit. Wrap parameter lists which do
|
||||
not fit on a single line as you would wrap arguments in a [function
|
||||
call](#Function_Calls).
|
||||
not fit on a single line as you would wrap arguments in a
|
||||
[function call](#Function_Calls).
|
||||
|
||||
<div class='goodcode'></div>
|
||||
|
||||
@@ -2375,9 +2376,9 @@ UpdateTally(scoreHeuristic, x, y, z);
|
||||
Format exceptions with `@catch` and `@finally` labels on the same line as the
|
||||
preceding `}`. Add a space between the `@` label and the opening brace (`{`), as
|
||||
well as between the `@catch` and the caught object declaration. If you must use
|
||||
Objective-C exceptions, format them as follows. However, see [Avoid Throwing
|
||||
Exceptions](#Avoid_Throwing_Exceptions) for reasons why you should not be using
|
||||
exceptions.
|
||||
Objective-C exceptions, format them as follows. However, see
|
||||
[Avoid Throwing Exceptions](#Avoid_Throwing_Exceptions) for reasons why you
|
||||
should not be using exceptions.
|
||||
|
||||
<div class='goodcode'></div>
|
||||
|
||||
|
||||
+76
-87
@@ -6,8 +6,10 @@ See README.md for details.
|
||||
|
||||
# Google Python Style Guide
|
||||
|
||||
<!-- mdformat off -->
|
||||
* TOC
|
||||
{:toc}
|
||||
<!-- mdformat on -->
|
||||
|
||||
<a id="s1-background"></a>
|
||||
<a id="1-background"></a>
|
||||
@@ -19,10 +21,13 @@ See README.md for details.
|
||||
Python is the main dynamic language used at Google. This style guide is a list
|
||||
of *dos and don'ts* for Python programs.
|
||||
|
||||
To help you format code correctly, we've created a [settings file for Vim](google_python_style.vim). For Emacs, the default settings should be fine.
|
||||
To help you format code correctly, we've created a
|
||||
[settings file for Vim](google_python_style.vim). For Emacs, the default
|
||||
settings should be fine.
|
||||
|
||||
Many teams use the [Black](https://github.com/psf/black) or [Pyink](https://github.com/google/pyink)
|
||||
auto-formatter to avoid arguing over formatting.
|
||||
Many teams use the [Black](https://github.com/psf/black) or
|
||||
[Pyink](https://github.com/google/pyink) auto-formatter to avoid arguing over
|
||||
formatting.
|
||||
|
||||
<a id="s2-python-language-rules"></a>
|
||||
<a id="2-python-language-rules"></a>
|
||||
@@ -38,7 +43,8 @@ auto-formatter to avoid arguing over formatting.
|
||||
|
||||
### 2.1 Lint
|
||||
|
||||
Run `pylint` over your code using this [pylintrc](https://google.github.io/styleguide/pylintrc).
|
||||
Run `pylint` over your code using this
|
||||
[pylintrc](https://google.github.io/styleguide/pylintrc).
|
||||
|
||||
<a id="s2.1.1-definition"></a>
|
||||
<a id="211-definition"></a>
|
||||
@@ -47,12 +53,10 @@ Run `pylint` over your code using this [pylintrc](https://google.github.io/style
|
||||
|
||||
#### 2.1.1 Definition
|
||||
|
||||
`pylint`
|
||||
is a tool for finding bugs and style problems in Python source code. It finds
|
||||
problems that are typically caught by a compiler for less dynamic languages like
|
||||
C and C++. Because of the dynamic nature of Python,
|
||||
some warnings may be incorrect; however, spurious warnings should be fairly
|
||||
infrequent.
|
||||
`pylint` is a tool for finding bugs and style problems in Python source code. It
|
||||
finds problems that are typically caught by a compiler for less dynamic
|
||||
languages like C and C++. Because of the dynamic nature of Python, some warnings
|
||||
may be incorrect; however, spurious warnings should be fairly infrequent.
|
||||
|
||||
<a id="s2.1.2-pros"></a>
|
||||
<a id="212-pros"></a>
|
||||
@@ -70,9 +74,8 @@ Catches easy-to-miss errors like typos, using-vars-before-assignment, etc.
|
||||
|
||||
#### 2.1.3 Cons
|
||||
|
||||
`pylint`
|
||||
isn't perfect. To take advantage of it, sometimes we'll need to write around it,
|
||||
suppress its warnings or fix it.
|
||||
`pylint` isn't perfect. To take advantage of it, sometimes we'll need to write
|
||||
around it, suppress its warnings or fix it.
|
||||
|
||||
<a id="s2.1.4-decision"></a>
|
||||
<a id="214-decision"></a>
|
||||
@@ -81,9 +84,7 @@ suppress its warnings or fix it.
|
||||
|
||||
#### 2.1.4 Decision
|
||||
|
||||
Make sure you run
|
||||
`pylint`
|
||||
on your code.
|
||||
Make sure you run `pylint` on your code.
|
||||
|
||||
Suppress warnings if they are inappropriate so that other issues are not hidden.
|
||||
To suppress warnings, you can set a line-level comment:
|
||||
@@ -95,8 +96,7 @@ def do_PUT(self): # WSGI name, so pylint: disable=invalid-name
|
||||
...
|
||||
```
|
||||
|
||||
`pylint`
|
||||
warnings are each identified by symbolic name (`empty-docstring`)
|
||||
`pylint` warnings are each identified by symbolic name (`empty-docstring`)
|
||||
Google-specific warnings start with `g-`.
|
||||
|
||||
If the reason for the suppression is not clear from the symbolic name, add an
|
||||
@@ -105,9 +105,7 @@ explanation.
|
||||
Suppressing in this way has the advantage that we can easily search for
|
||||
suppressions and revisit them.
|
||||
|
||||
You can get a list of
|
||||
`pylint`
|
||||
warnings by doing:
|
||||
You can get a list of `pylint` warnings by doing:
|
||||
|
||||
```shell
|
||||
pylint --list-msgs
|
||||
@@ -363,8 +361,7 @@ Exceptions must follow certain conditions:
|
||||
`assert` conditionals are
|
||||
[not guaranteed](https://docs.python.org/3/reference/simple_stmts.html#the-assert-statement)
|
||||
to be evaluated. For [pytest](https://pytest.org) based tests, `assert` is
|
||||
okay and expected to verify expectations.
|
||||
For example:
|
||||
okay and expected to verify expectations. For example:
|
||||
|
||||
<div class='goodcode'></div>
|
||||
|
||||
@@ -1252,8 +1249,7 @@ def foo(x: Iterable[int]):
|
||||
bar()
|
||||
```
|
||||
|
||||
So `foo([1, 2, 3])` will print `1 2 3
|
||||
3`, not `1 2 3 4`.
|
||||
So `foo([1, 2, 3])` will print `1 2 3 3`, not `1 2 3 4`.
|
||||
|
||||
<a id="s2.16.4-decision"></a>
|
||||
<a id="2164-decision"></a>
|
||||
@@ -1477,8 +1473,7 @@ upgrades.
|
||||
|
||||
Such code may not work on very old interpreter versions prior to the
|
||||
introduction of the needed future statement. The need for this is more common in
|
||||
projects supporting an extremely wide variety of
|
||||
environments.
|
||||
projects supporting an extremely wide variety of environments.
|
||||
|
||||
<a id="s2.20.4-decision"></a>
|
||||
<a id="2204-decision"></a>
|
||||
@@ -1525,9 +1520,10 @@ Use other `from __future__` import statements as you see fit.
|
||||
|
||||
You can annotate Python code with
|
||||
[type hints](https://docs.python.org/3/library/typing.html). Type-check the code
|
||||
at build time with a type checking tool like [pytype](https://github.com/google/pytype).
|
||||
In most cases, when feasible, type annotations are in source files. For
|
||||
third-party or extension modules, annotations can be in
|
||||
at build time with a type checking tool like
|
||||
[pytype](https://github.com/google/pytype). In most cases, when feasible, type
|
||||
annotations are in source files. For third-party or extension modules,
|
||||
annotations can be in
|
||||
[stub `.pyi` files](https://peps.python.org/pep-0484/#stub-files).
|
||||
|
||||
<a id="s2.21.1-definition"></a>
|
||||
@@ -1572,11 +1568,10 @@ your ability to use [Power Features](#power-features).
|
||||
|
||||
#### 2.21.3 Cons
|
||||
|
||||
You will have to keep the type declarations up to
|
||||
date. You might see type errors that you
|
||||
think are valid code. Use of a
|
||||
[type checker](https://github.com/google/pytype)
|
||||
may reduce your ability to use [Power Features](#power-features).
|
||||
You will have to keep the type declarations up to date. You might see type
|
||||
errors that you think are valid code. Use of a
|
||||
[type checker](https://github.com/google/pytype) may reduce your ability to use
|
||||
[Power Features](#power-features).
|
||||
|
||||
<a id="s2.21.4-decision"></a>
|
||||
<a id="2214-decision"></a>
|
||||
@@ -1588,11 +1583,11 @@ may reduce your ability to use [Power Features](#power-features).
|
||||
You are strongly encouraged to enable Python type analysis when updating code.
|
||||
When adding or modifying public APIs, include type annotations and enable
|
||||
checking via pytype in the build system. As static analysis is relatively new to
|
||||
Python, we acknowledge that undesired side-effects (such
|
||||
as wrongly inferred types) may prevent adoption by
|
||||
some projects. In those situations, authors are encouraged to add a comment with
|
||||
a TODO or link to a bug describing the issue(s) currently preventing type
|
||||
annotation adoption in the BUILD file or in the code itself as appropriate.
|
||||
Python, we acknowledge that undesired side-effects (such as wrongly inferred
|
||||
types) may prevent adoption by some projects. In those situations, authors are
|
||||
encouraged to add a comment with a TODO or link to a bug describing the issue(s)
|
||||
currently preventing type annotation adoption in the BUILD file or in the code
|
||||
itself as appropriate.
|
||||
|
||||
<a id="s3-python-style-rules"></a>
|
||||
<a id="3-python-style-rules"></a>
|
||||
@@ -1625,8 +1620,7 @@ Explicit exceptions to the 80 character limit:
|
||||
- Long import statements.
|
||||
- URLs, pathnames, or long flags in comments.
|
||||
- Long string module-level constants not containing whitespace that would be
|
||||
inconvenient to split across lines such as URLs or
|
||||
pathnames.
|
||||
inconvenient to split across lines such as URLs or pathnames.
|
||||
- Pylint disable comments. (e.g.: `# pylint: disable=invalid-name`)
|
||||
|
||||
Do not use a backslash for
|
||||
@@ -1749,10 +1743,11 @@ above; see the [indentation](#s3.4-indentation) section for explanation.
|
||||
limit.
|
||||
|
||||
In all other cases where a line exceeds 80 characters, and the
|
||||
[Black](https://github.com/psf/black) or [Pyink](https://github.com/google/pyink)
|
||||
auto-formatter does not help bring the line below the limit, the line is allowed
|
||||
to exceed this maximum. Authors are encouraged to manually break the line up per
|
||||
the notes above when it is sensible.
|
||||
[Black](https://github.com/psf/black) or
|
||||
[Pyink](https://github.com/google/pyink) auto-formatter does not help bring the
|
||||
line below the limit, the line is allowed to exceed this maximum. Authors are
|
||||
encouraged to manually break the line up per the notes above when it is
|
||||
sensible.
|
||||
|
||||
<a id="s3.3-parentheses"></a>
|
||||
<a id="33-parentheses"></a>
|
||||
@@ -1892,10 +1887,11 @@ No: # Stuff on first line forbidden.
|
||||
Trailing commas in sequences of items are recommended only when the closing
|
||||
container token `]`, `)`, or `}` does not appear on the same line as the final
|
||||
element, as well as for tuples with a single element. The presence of a trailing
|
||||
comma is also used as a hint to our Python code
|
||||
auto-formatter [Black](https://github.com/psf/black) or [Pyink](https://github.com/google/pyink)
|
||||
to direct it to auto-format the container of items to one item per line when the
|
||||
`,` after the final element is present.
|
||||
comma is also used as a hint to our Python code auto-formatter
|
||||
[Black](https://github.com/psf/black) or
|
||||
[Pyink](https://github.com/google/pyink) to direct it to auto-format the
|
||||
container of items to one item per line when the `,` after the final element is
|
||||
present.
|
||||
|
||||
<div class='goodcode'></div>
|
||||
|
||||
@@ -2079,12 +2075,13 @@ No:
|
||||
|
||||
### 3.7 Shebang Line
|
||||
|
||||
Most `.py` files do not need to start with a `#!` line. Start the main file of
|
||||
a
|
||||
Most `.py` files do not need to start with a `#!` line. Start the main file of a
|
||||
program with `#!/usr/bin/env python3` (to support virtualenvs) or
|
||||
`#!/usr/bin/python3` per [PEP-394](https://peps.python.org/pep-0394/).
|
||||
|
||||
This line is used by the kernel to find the Python interpreter, but is ignored by Python when importing modules. It is only necessary on a file intended to be executed directly.
|
||||
This line is used by the kernel to find the Python interpreter, but is ignored
|
||||
by Python when importing modules. It is only necessary on a file intended to be
|
||||
executed directly.
|
||||
|
||||
<a id="s3.8-comments-and-docstrings"></a>
|
||||
<a id="s3.8-comments"></a>
|
||||
@@ -2108,9 +2105,8 @@ inline comments.
|
||||
Python uses *docstrings* to document code. A docstring is a string that is the
|
||||
first statement in a package, module, class or function. These strings can be
|
||||
extracted automatically through the `__doc__` member of the object and are used
|
||||
by `pydoc`.
|
||||
(Try running `pydoc` on your module to see how it looks.) Always use the
|
||||
three-double-quote `"""` format for docstrings (per
|
||||
by `pydoc`. (Try running `pydoc` on your module to see how it looks.) Always use
|
||||
the three-double-quote `"""` format for docstrings (per
|
||||
[PEP 257](https://peps.python.org/pep-0257/)). A docstring should be organized
|
||||
as a summary line (one physical line not exceeding 80 characters) terminated by
|
||||
a period, question mark, or exclamation point. When writing more (encouraged),
|
||||
@@ -2126,7 +2122,9 @@ are more formatting guidelines for docstrings below.
|
||||
|
||||
#### 3.8.2 Modules
|
||||
|
||||
Every file should contain license boilerplate. Choose the appropriate boilerplate for the license used by the project (for example, Apache 2.0, BSD, LGPL, GPL).
|
||||
Every file should contain license boilerplate. Choose the appropriate
|
||||
boilerplate for the license used by the project (for example, Apache 2.0, BSD,
|
||||
LGPL, GPL).
|
||||
|
||||
Files should start with a docstring describing the contents and usage of the
|
||||
module.
|
||||
@@ -2508,10 +2506,10 @@ after the decorator has been applied.
|
||||
#### 3.8.5 Block and Inline Comments
|
||||
|
||||
The final place to have comments is in tricky parts of the code. If you're going
|
||||
to have to explain it at the next [code review](http://en.wikipedia.org/wiki/Code_review),
|
||||
you should comment it now. Complicated operations get a few lines of comments
|
||||
before the operations commence. Non-obvious ones get comments at the end of the
|
||||
line.
|
||||
to have to explain it at the next
|
||||
[code review](http://en.wikipedia.org/wiki/Code_review), you should comment it
|
||||
now. Complicated operations get a few lines of comments before the operations
|
||||
commence. Non-obvious ones get comments at the end of the line.
|
||||
|
||||
<div class='goodcode'></div>
|
||||
|
||||
@@ -2625,8 +2623,7 @@ No: employee_table = '<table>'
|
||||
|
||||
Be consistent with your choice of string quote character within a file. Pick `'`
|
||||
or `"` and stick with it. It is okay to use the other quote character on a
|
||||
string to avoid the need to backslash-escape quote characters within the
|
||||
string.
|
||||
string to avoid the need to backslash-escape quote characters within the string.
|
||||
|
||||
<div class='goodcode'></div>
|
||||
|
||||
@@ -2902,8 +2899,7 @@ good-enough but not perfect.
|
||||
A `TODO` comment begins with the word `TODO` in all caps, and a parenthesized
|
||||
link to a resource that contains the context, ideally a bug reference. A bug
|
||||
reference is preferable because bugs are tracked and have follow-up comments.
|
||||
Follow this piece of context with a colon and an explanatory
|
||||
string.
|
||||
Follow this piece of context with a colon and an explanatory string.
|
||||
|
||||
The purpose is to have a consistent `TODO` format that can be searched to find
|
||||
out how to get more details.
|
||||
@@ -2982,8 +2978,7 @@ grouped from most generic to least generic:
|
||||
import sys
|
||||
```
|
||||
|
||||
3. [third-party](https://pypi.org/)
|
||||
module or package imports. For example:
|
||||
3. [third-party](https://pypi.org/) module or package imports. For example:
|
||||
|
||||
<div class='goodcode'></div>
|
||||
|
||||
@@ -2991,8 +2986,7 @@ grouped from most generic to least generic:
|
||||
import tensorflow as tf
|
||||
```
|
||||
|
||||
4. Code repository
|
||||
sub-package imports. For example:
|
||||
4. Code repository sub-package imports. For example:
|
||||
|
||||
<div class='goodcode'></div>
|
||||
|
||||
@@ -3001,8 +2995,7 @@ grouped from most generic to least generic:
|
||||
```
|
||||
|
||||
5. **Deprecated:** application-specific imports that are part of the same
|
||||
top-level
|
||||
sub-package as this file. For example:
|
||||
top-level sub-package as this file. For example:
|
||||
|
||||
<div class='goodcode'></div>
|
||||
|
||||
@@ -3190,9 +3183,8 @@ Always use a `.py` filename extension. Never use dashes.
|
||||
(using name mangling); we discourage its use as it impacts readability and
|
||||
testability, and isn't *really* private. Prefer a single underscore.
|
||||
|
||||
- Place related classes and top-level functions together in
|
||||
a module.
|
||||
Unlike Java, there is no need to limit yourself to one class per module.
|
||||
- Place related classes and top-level functions together in a module. Unlike
|
||||
Java, there is no need to limit yourself to one class per module.
|
||||
|
||||
- Use CapWords for class names, but lower\_with\_under.py for module names.
|
||||
Although there are some old modules named CapWords.py, this is now
|
||||
@@ -3402,12 +3394,11 @@ months may add new behavior. This could result in bugs that are hard to find.
|
||||
Keeping your functions short and simple makes it easier for other people to read
|
||||
and modify your code.
|
||||
|
||||
You could find long and complicated functions when working with
|
||||
some
|
||||
code. Do not be intimidated by modifying existing code: if working with such a
|
||||
function proves to be difficult, you find that errors are hard to debug, or you
|
||||
want to use a piece of it in several different contexts, consider breaking up
|
||||
the function into smaller and more manageable pieces.
|
||||
You could find long and complicated functions when working with some code. Do
|
||||
not be intimidated by modifying existing code: if working with such a function
|
||||
proves to be difficult, you find that errors are hard to debug, or you want to
|
||||
use a piece of it in several different contexts, consider breaking up the
|
||||
function into smaller and more manageable pieces.
|
||||
|
||||
<a id="s3.19-type-annotations"></a>
|
||||
<a id="319-type-annotations"></a>
|
||||
@@ -3527,9 +3518,8 @@ def my_method(
|
||||
...
|
||||
```
|
||||
|
||||
`pylint`
|
||||
allows you to move the closing parenthesis to a new line and align with the
|
||||
opening one, but this is less readable.
|
||||
`pylint` allows you to move the closing parenthesis to a new line and align with
|
||||
the opening one, but this is less readable.
|
||||
|
||||
<div class='badcode'></div>
|
||||
|
||||
@@ -3988,8 +3978,7 @@ TYPE_CHECKING:` block.
|
||||
not be imported at runtime.
|
||||
- The block should be right after all the normal imports.
|
||||
- There should be no empty lines in the typing imports list.
|
||||
- Sort this list as if it were a regular imports
|
||||
list.
|
||||
- Sort this list as if it were a regular imports list.
|
||||
|
||||
<div class='goodcode'></div>
|
||||
|
||||
@@ -4010,8 +3999,8 @@ def f(x: "sketch.Sketch"): ...
|
||||
|
||||
Circular dependencies that are caused by typing are code smells. Such code is a
|
||||
good candidate for refactoring. Although technically it is possible to keep
|
||||
circular dependencies, various build systems will not let you
|
||||
do so because each module has to depend on the other.
|
||||
circular dependencies, various build systems will not let you do so because each
|
||||
module has to depend on the other.
|
||||
|
||||
Replace modules that create circular dependency imports with `Any`. Set an
|
||||
[alias](#typing-aliases) with a meaningful name, and use the real type name from
|
||||
|
||||
+8
-9
@@ -83,10 +83,10 @@ Some guidelines:
|
||||
|
||||
Executables should have a `.sh` extension or no extension.
|
||||
|
||||
- If the executable will have a build rule that renames the source
|
||||
file then prefer to use a `.sh` extension. This
|
||||
enables you to use the recommended naming convention, with a source file
|
||||
like `foo.sh` and a build rule named `foo`.
|
||||
- If the executable will have a build rule that renames the source file then
|
||||
prefer to use a `.sh` extension. This enables you to use the recommended
|
||||
naming convention, with a source file like `foo.sh` and a build rule named
|
||||
`foo`.
|
||||
- If the executable will be added directly to the user's `PATH`, then prefer
|
||||
to use no extension. It is not necessary to know what language a program is
|
||||
written in when executing it and shell doesn't require an extension so we
|
||||
@@ -108,8 +108,7 @@ secure sufficiently to allow SUID/SGID. While bash does make it difficult to run
|
||||
SUID, it's still possible on some platforms which is why we're being explicit
|
||||
about banning it.
|
||||
|
||||
Use `sudo` to provide elevated access if you need
|
||||
it.
|
||||
Use `sudo` to provide elevated access if you need it.
|
||||
|
||||
<a id="s3-environment"></a>
|
||||
|
||||
@@ -150,8 +149,7 @@ fi
|
||||
Start each file with a description of its contents.
|
||||
|
||||
Every file must have a top-level comment including a brief overview of its
|
||||
contents. A copyright notice and author information
|
||||
are optional.
|
||||
contents. A copyright notice and author information are optional.
|
||||
|
||||
Example:
|
||||
|
||||
@@ -243,7 +241,8 @@ put a short comment in.
|
||||
Use TODO comments for code that is temporary, a short-term solution, or
|
||||
good-enough but not perfect.
|
||||
|
||||
This matches the convention in the [C++ Guide](https://google.github.io/styleguide/cppguide.html#TODO_Comments).
|
||||
This matches the convention in the
|
||||
[C++ Guide](https://google.github.io/styleguide/cppguide.html#TODO_Comments).
|
||||
|
||||
`TODO`s should include the string `TODO` in all caps, followed by the name,
|
||||
e-mail address, or other identifier of the person with the best context about
|
||||
|
||||
@@ -6,8 +6,10 @@
|
||||
|
||||
# Google Verilog Style Guide
|
||||
|
||||
<!-- mdformat off -->
|
||||
* TOC
|
||||
{:toc}
|
||||
<!-- mdformat on -->
|
||||
|
||||
<a id="basics"></a>
|
||||
|
||||
|
||||
+7
-18
@@ -1,17 +1,15 @@
|
||||
# Google Vimscript Guide
|
||||
|
||||
* Nate Soares
|
||||
* Artemis Sparks
|
||||
* David Barnett
|
||||
* Nate Soares
|
||||
* Artemis Sparks
|
||||
* David Barnett
|
||||
|
||||
<!-- mdformat on -->
|
||||
|
||||
## Background
|
||||
|
||||
This is the in-depth vimscript guide. If you're just a casual user looking to
|
||||
write a plugin, the
|
||||
[abbreviated style guide](./vimscriptguide.md)
|
||||
is for you.
|
||||
write a plugin, the [abbreviated style guide](./vimscriptguide.md) is for you.
|
||||
|
||||
This rather rotund guide dives into justifications and clarifications. It
|
||||
provides an idealized set of rules that are rather too draconian to push on
|
||||
@@ -24,8 +22,10 @@ safely.
|
||||
Fair warning: Vimscript is a maddening abyss. When you gaze into it, it gazes
|
||||
also into you. Proceed with caution.
|
||||
|
||||
<!-- mdformat off -->
|
||||
* TOC
|
||||
{:toc}
|
||||
<!-- mdformat on -->
|
||||
|
||||
## Portability
|
||||
|
||||
@@ -209,8 +209,7 @@ All other language features are fair game.
|
||||
|
||||
* `plugin-names-like-this`
|
||||
|
||||
* Plugin names should be descriptive and
|
||||
concise.
|
||||
* Plugin names should be descriptive and concise.
|
||||
|
||||
* Each plugin must consist of one directory (or code repository), sharing a
|
||||
name with the plugin (with a "vim-" prefix or ".vim" suffix if desired).
|
||||
@@ -292,7 +291,6 @@ what Vim's all about.
|
||||
endif
|
||||
```
|
||||
|
||||
|
||||
## Style Guide
|
||||
|
||||
Follow google-wide style conventions. Mimic google python style when in doubt.
|
||||
@@ -432,7 +430,6 @@ Follow google-wide conventions.
|
||||
" comment block
|
||||
```
|
||||
|
||||
|
||||
### Variables
|
||||
|
||||
`plugin-names-like-this`, `FunctionNamesLikeThis`, `CommandNamesLikeThis`,
|
||||
@@ -482,7 +479,6 @@ their scope.
|
||||
|
||||
* This is useful for plugins that keep per-buffer or per-window state.
|
||||
|
||||
|
||||
### Strings
|
||||
|
||||
Prefer single quotes.
|
||||
@@ -521,7 +517,6 @@ Prefer single quoted strings. Specifically, in order of precedence:
|
||||
|
||||
* Break ties in favor of single quotes.
|
||||
|
||||
|
||||
### Settings
|
||||
|
||||
Prefer long names. Set settings locally.
|
||||
@@ -531,7 +526,6 @@ Prefer long names. Set settings locally.
|
||||
|
||||
* Use `setlocal` and `&l:` instead of `set` and `&`.
|
||||
|
||||
|
||||
## Usage Guide
|
||||
|
||||
Vim plugins should provide any or all of the following: **Commands**,
|
||||
@@ -599,7 +593,6 @@ Vim plugins should provide any or all of the following: **Commands**,
|
||||
|
||||
* The function should receive a boolean parameter, not a string.
|
||||
|
||||
|
||||
### Autocommands
|
||||
|
||||
<div>
|
||||
@@ -635,7 +628,6 @@ Vim plugins should provide any or all of the following: **Commands**,
|
||||
|
||||
* This allows your plugins to be re-enterable.
|
||||
|
||||
|
||||
### Functions
|
||||
|
||||
<div>
|
||||
@@ -687,7 +679,6 @@ Vim plugins should provide any or all of the following: **Commands**,
|
||||
* Top-level functions expecting errors may catch them and print error
|
||||
messages, but even those should throw their own errors when they choke.
|
||||
|
||||
|
||||
### Mappings
|
||||
|
||||
<div>
|
||||
@@ -740,7 +731,6 @@ Vim plugins should provide any or all of the following: **Commands**,
|
||||
* Using `s:` will often fail as the mapping attempts to type a literal s
|
||||
and colon.
|
||||
|
||||
|
||||
## Conventions
|
||||
|
||||
### Dependency Checking
|
||||
@@ -788,7 +778,6 @@ purpose of the plugin (powerline, etc.).
|
||||
* This is useful for users who want only the most relevant flag and do not
|
||||
have a colored statusline.
|
||||
|
||||
|
||||
## Forbidden Commands
|
||||
|
||||
These are commands which can only be used by a limited number of plugins, and
|
||||
|
||||
+10
-10
@@ -1,8 +1,8 @@
|
||||
# Google Vimscript Style Guide
|
||||
|
||||
* Nate Soares
|
||||
* Artemis Sparks
|
||||
* David Barnett
|
||||
* Nate Soares
|
||||
* Artemis Sparks
|
||||
* David Barnett
|
||||
|
||||
<!-- mdformat on -->
|
||||
|
||||
@@ -11,11 +11,12 @@
|
||||
This is a casual version of the vimscript style guide, because vimscript is a
|
||||
casual language. When submitting vim plugin code, you must adhere to these
|
||||
rules. For clarifications, justifications, and explanations about the finer
|
||||
points of vimscript, please refer to
|
||||
the [heavy guide](./vimscriptfull.md).
|
||||
points of vimscript, please refer to the [heavy guide](./vimscriptfull.md).
|
||||
|
||||
<!-- mdformat off -->
|
||||
* TOC
|
||||
{:toc}
|
||||
<!-- mdformat on -->
|
||||
|
||||
## Portability
|
||||
|
||||
@@ -91,7 +92,6 @@ Loud scripts are annoying. Message the user only when:
|
||||
* A long-running process has kicked off.
|
||||
* An error has occurred.
|
||||
|
||||
|
||||
### Type checking
|
||||
|
||||
Use strict and explicit checks where possible.
|
||||
@@ -135,7 +135,6 @@ maktaba removes boilerplate, including:
|
||||
* Error handling
|
||||
* Dependency checking
|
||||
|
||||
|
||||
### Plugin layout
|
||||
|
||||
Organize functionality into modular plugins
|
||||
@@ -166,7 +165,8 @@ should be extracted into functions and autoloaded.
|
||||
|
||||
### Commands
|
||||
|
||||
In the plugin/commands.vim or under the ftplugin/ directory, defined without `[!]`.
|
||||
In the plugin/commands.vim or under the ftplugin/ directory, defined without
|
||||
`[!]`.
|
||||
|
||||
General commands go in `plugin/commands.vim`. Filetype-specific commands go in
|
||||
`ftplugin/`.
|
||||
@@ -188,7 +188,8 @@ augroup. This makes your plugin re-entrable.
|
||||
|
||||
### Mappings
|
||||
|
||||
Place them in `plugin/mappings.vim`, using `maktaba#plugin#MapPrefix` to get a prefix.
|
||||
Place them in `plugin/mappings.vim`, using `maktaba#plugin#MapPrefix` to get a
|
||||
prefix.
|
||||
|
||||
All key mappings should be defined in `plugin/mappings.vim`.
|
||||
|
||||
@@ -258,7 +259,6 @@ Similar to python.
|
||||
command MyCommand2 call myplugin#bar()
|
||||
```
|
||||
|
||||
|
||||
### Naming
|
||||
|
||||
In general, use `plugin-names-like-this`, `FunctionNamesLikeThis`,
|
||||
|
||||
+44
-44
@@ -3,15 +3,17 @@
|
||||
Version 1.0 \
|
||||
Copyright Google 2008
|
||||
|
||||
<!-- mdformat off -->
|
||||
* TOC
|
||||
{:toc}
|
||||
<!-- mdformat on -->
|
||||
|
||||
## Introduction
|
||||
|
||||
This document provides a set of guidelines for general use when designing new
|
||||
XML document formats (and to some extent XML documents as well; see [document
|
||||
instances](#s11)). Document formats usually include both formal parts (DTDs,
|
||||
schemas) and parts expressed in normative English prose.
|
||||
XML document formats (and to some extent XML documents as well; see
|
||||
[document instances](#s11)). Document formats usually include both formal parts
|
||||
(DTDs, schemas) and parts expressed in normative English prose.
|
||||
|
||||
These guidelines apply to new designs, and are not intended to force retroactive
|
||||
changes in existing designs. These guidelines should be taken into account when
|
||||
@@ -43,12 +45,11 @@ in the sense of [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
|
||||
|
||||
1. Attempt to reuse existing XML formats whenever possible, especially those
|
||||
which allow extensions. Creating an entirely new format should be done only
|
||||
with care and consideration; read [Tim Bray's
|
||||
warnings](https://www.tbray.org/ongoing/When/200x/2006/01/08/No-New-XML-Languages)
|
||||
first. Try to get wide review of your format, from
|
||||
outside your organization as well, if
|
||||
possible. \[*Rationale:* New document formats have a cost: they must be
|
||||
reviewed, documented, and learned by users.\]
|
||||
with care and consideration; read
|
||||
[Tim Bray's warnings](https://www.tbray.org/ongoing/When/200x/2006/01/08/No-New-XML-Languages)
|
||||
first. Try to get wide review of your format, from outside your organization
|
||||
as well, if possible. \[*Rationale:* New document formats have a cost: they
|
||||
must be reviewed, documented, and learned by users.\]
|
||||
|
||||
2. If you are reusing or extending an existing format, make *sensible* use of
|
||||
the prescribed elements and attributes, especially any that are required.
|
||||
@@ -68,22 +69,22 @@ in the sense of [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
|
||||
1. Document formats SHOULD be expressed using a schema language. \[*Rationale:*
|
||||
Clarity and machine-checkability.\]
|
||||
|
||||
2. The schema language SHOULD be [RELAX NG](http://www.relaxng.org/) [compact
|
||||
syntax](http://www.relaxng.org/compact-tutorial-20030326.html). Embedded
|
||||
[Schematron](https://www.schematron.com/) rules MAY be added to the schema
|
||||
for additional fine control. \[*Rationale:* RELAX NG is the most flexible
|
||||
schema language, with very few arbitrary restrictions on designs. The
|
||||
compact syntax is quite easy to read and learn, and can be converted
|
||||
2. The schema language SHOULD be [RELAX NG](http://www.relaxng.org/)
|
||||
[compact syntax](http://www.relaxng.org/compact-tutorial-20030326.html).
|
||||
Embedded [Schematron](https://www.schematron.com/) rules MAY be added to the
|
||||
schema for additional fine control. \[*Rationale:* RELAX NG is the most
|
||||
flexible schema language, with very few arbitrary restrictions on designs.
|
||||
The compact syntax is quite easy to read and learn, and can be converted
|
||||
one-to-one to and from the XML syntax when necessary. Schematron handles
|
||||
arbitrary cross-element and cross-attribute constraints nicely.\]
|
||||
|
||||
3. Schemas SHOULD use the ["Salami Slice"
|
||||
style](https://www.xfront.com/GlobalVersusLocal.html#SecondDesign) (one rule
|
||||
per element). Schemas MAY use the ["Russian Doll"
|
||||
style](https://www.xfront.com/GlobalVersusLocal.html#FirstDesign) (schema
|
||||
resembles document) if they are short and simple. The ["Venetian Blind"
|
||||
style](https://www.xfront.com/GlobalVersusLocal.html#ThirdDesign) (one rule
|
||||
per element type) is unsuited to RELAX NG and SHOULD NOT be used.
|
||||
3. Schemas SHOULD use the
|
||||
["Salami Slice" style](https://www.xfront.com/GlobalVersusLocal.html#SecondDesign)
|
||||
(one rule per element). Schemas MAY use the
|
||||
["Russian Doll" style](https://www.xfront.com/GlobalVersusLocal.html#FirstDesign)
|
||||
(schema resembles document) if they are short and simple. The
|
||||
["Venetian Blind" style](https://www.xfront.com/GlobalVersusLocal.html#ThirdDesign)
|
||||
(one rule per element type) is unsuited to RELAX NG and SHOULD NOT be used.
|
||||
|
||||
4. Regular expressions SHOULD be provided to assist in validating complex
|
||||
values.
|
||||
@@ -107,13 +108,12 @@ in the sense of [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
|
||||
\[*Rationale:* Attribute names in a namespace must always have a prefix,
|
||||
which is annoying to type and hard to read.\]
|
||||
|
||||
3. Namespace names are HTTP URIs. Namespace
|
||||
names SHOULD take the
|
||||
form `https://example.com/whatever/year`, where *whatever* is a unique value
|
||||
3. Namespace names are HTTP URIs. Namespace names SHOULD take the form
|
||||
`https://example.com/whatever/year`, where *whatever* is a unique value
|
||||
based on the name of the service or document type, and *year* is the year
|
||||
the namespace was created. There may be additional URI-path parts before the
|
||||
*year*. \[*Rationale:* Existing convention.
|
||||
Providing the year allows for the possible recycling of code names.\]
|
||||
*year*. \[*Rationale:* Existing convention. Providing the year allows for
|
||||
the possible recycling of code names.\]
|
||||
|
||||
4. Namespaces MUST NOT be changed unless the semantics of particular elements
|
||||
or attributes has changed in drastically incompatible ways. \[*Rationale:*
|
||||
@@ -205,11 +205,11 @@ values.
|
||||
not extensible. The additional flexibility of allowing numeric values is not
|
||||
abstracted away by any parser.\]
|
||||
|
||||
3. Dates should be represented using [RFC
|
||||
3339](https://www.ietf.org/rfc/rfc3339.txt) format, a subset of both ISO
|
||||
8601 format and XML Schema `xsd:dateTime` format. UTC times SHOULD be used
|
||||
rather than local times. \[*Rationale:* There are far too many date formats
|
||||
and time zones, although it is recognized that sometimes local time
|
||||
3. Dates should be represented using
|
||||
[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format, a subset of both
|
||||
ISO 8601 format and XML Schema `xsd:dateTime` format. UTC times SHOULD be
|
||||
used rather than local times. \[*Rationale:* There are far too many date
|
||||
formats and time zones, although it is recognized that sometimes local time
|
||||
preserves important information.\]
|
||||
|
||||
4. Embedded syntax in character content and attribute values SHOULD NOT be
|
||||
@@ -230,11 +230,11 @@ values.
|
||||
1. Simple key-value pairs SHOULD be represented with an empty element whose
|
||||
name represents the key, with the `value` attribute containing the value.
|
||||
Elements that have a `value` attribute MAY also have a `unit` attribute to
|
||||
specify the unit of a measured value. For physical measurements, the [SI
|
||||
system](https://en.wikipedia.org/wiki/International_System_of_Units) SHOULD
|
||||
be used. \[*Rationale:* Simplicity and design consistency. Keeping the value
|
||||
in an attribute hides it from the user, since displaying just the value
|
||||
without the key is not useful.\]
|
||||
specify the unit of a measured value. For physical measurements, the
|
||||
[SI system](https://en.wikipedia.org/wiki/International_System_of_Units)
|
||||
SHOULD be used. \[*Rationale:* Simplicity and design consistency. Keeping
|
||||
the value in an attribute hides it from the user, since displaying just the
|
||||
value without the key is not useful.\]
|
||||
|
||||
2. If the number of possible keys is very large or unbounded, key-value pairs
|
||||
MAY be represented by a single generic element with `key`, `value`, and
|
||||
@@ -295,8 +295,8 @@ hacks.
|
||||
\[*Rationale:* Clarity and consistency.\]
|
||||
|
||||
4. Well-known prefixes such as html: (for XHTML), dc: (for Dublin Core
|
||||
metadata), and xs: (for XML Schema) should be used
|
||||
for standard namespaces. \[*Rationale:* Human readability.\]
|
||||
metadata), and xs: (for XML Schema) should be used for standard namespaces.
|
||||
\[*Rationale:* Human readability.\]
|
||||
|
||||
5. Redundant whitespace in a tag SHOULD NOT be used. Use one space before each
|
||||
attribute in a start-tag; if the start tag is too long, the space MAY be
|
||||
@@ -479,11 +479,11 @@ child elements are hard to follow and hard to use, though it often makes good
|
||||
sense to use both when the data clearly fall into two different groups such as
|
||||
simple/complex or metadata/data.
|
||||
|
||||
> Newbies always ask:\
|
||||
> "Elements or attributes?\
|
||||
> Which will serve me best?"\
|
||||
> Those who know roar like lions;\
|
||||
> Wise hackers smile like tigers.\
|
||||
> Newbies always ask: \
|
||||
> "Elements or attributes? \
|
||||
> Which will serve me best?" \
|
||||
> Those who know roar like lions; \
|
||||
> Wise hackers smile like tigers. \
|
||||
> --a
|
||||
> [tanka](https://en.wikipedia.org/wiki/Waka_%28poetry%29#Forms_of_waka), or
|
||||
> extended haiku
|
||||
|
||||
Reference in new issue
Block a user