mirror of https://github.com/apache/druid.git
Suggest adoption of Google Style guide (#14905)
Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com>
This commit is contained in:
parent
3860052de0
commit
de557a62ad
|
@ -36,7 +36,7 @@ While this page might discuss conventions that are also enforced via said mechan
|
||||||
discuss style-related convention that cannot be (or are extremely difficult to be) enforced through such automated
|
discuss style-related convention that cannot be (or are extremely difficult to be) enforced through such automated
|
||||||
mechanisms.
|
mechanisms.
|
||||||
|
|
||||||
## Message Formatting (Logs and Exceptions)
|
## Message formatting for logs and exceptions
|
||||||
|
|
||||||
The way that log and exception messages get formatted is an important part of a project. Specifically, it is
|
The way that log and exception messages get formatted is an important part of a project. Specifically, it is
|
||||||
important that there is consistency in formatting such that someone can easily identify and interpret messages.
|
important that there is consistency in formatting such that someone can easily identify and interpret messages.
|
||||||
|
@ -60,3 +60,8 @@ This consistency applies to both log *and* exception messages.
|
||||||
* Good: `log.info("Filter [%s] on column [%s] cannot be applied to type [%s]", "is not null", "null", "INTEGER")`
|
* Good: `log.info("Filter [%s] on column [%s] cannot be applied to type [%s]", "is not null", "null", "INTEGER")`
|
||||||
* After interpolation, clear separation: `"Filter [is not null] on column [null] cannot be applied to type [INTEGER]"`
|
* After interpolation, clear separation: `"Filter [is not null] on column [null] cannot be applied to type [INTEGER]"`
|
||||||
* With interpolations removed, it is clear what happened, though still hard to figure out which specific thing to adjust: `"Filter on column cannot be applied to type"`
|
* With interpolations removed, it is clear what happened, though still hard to figure out which specific thing to adjust: `"Filter on column cannot be applied to type"`
|
||||||
|
|
||||||
|
|
||||||
|
## Documentation style
|
||||||
|
|
||||||
|
For the majority of style considerations, the Apache Druid documentation follows the [Google Developer Documentation Style Guide](https://developers.google.com/style). For more details, see [Contribute to Druid docs](../docs/development/docs-contribute.md#style-guide).
|
||||||
|
|
|
@ -131,9 +131,47 @@ The docs go through a review process similar to the code where community members
|
||||||
|
|
||||||
## Style guide
|
## Style guide
|
||||||
|
|
||||||
Before publishing new content or updating an existing topic, audit your documentation using this checklist to make sure your contributions align with existing documentation.
|
Consistent style, formatting, and tone make documentation easier to consume.
|
||||||
|
For the majority of style considerations, the Apache Druid documentation follows the [Google Developer Documentation Style Guide](https://developers.google.com/style).
|
||||||
|
The style guide should serve as a point of reference to enable contributors and reviewers to maintain documentation quality.
|
||||||
|
|
||||||
Here are some general guidelines:
|
### Notable style exceptions
|
||||||
|
|
||||||
|
In some cases, Google Style might make the Druid docs more difficult to read and understand. This section highlights those exceptions.
|
||||||
|
|
||||||
|
#### SQL keyword syntax
|
||||||
|
For SQL keywords and functions, use all caps, but do not use code font.
|
||||||
|
|
||||||
|
:::tip
|
||||||
|
|
||||||
|
**Correct**
|
||||||
|
|
||||||
|
The UNNEST clause unnests array values.
|
||||||
|
|
||||||
|
**Incorrect**
|
||||||
|
|
||||||
|
The \`UNNEST\` clause unnests array values.
|
||||||
|
:::
|
||||||
|
|
||||||
|
|
||||||
|
#### Optional parameters and arguments
|
||||||
|
|
||||||
|
For optional parameters and arguments, enclose the optional parameter and leading command in brackets.
|
||||||
|
|
||||||
|
:::tip
|
||||||
|
|
||||||
|
**Correct**
|
||||||
|
|
||||||
|
HUMAN_READABLE_BINARY_BYTE_FORMAT(value[, precision])
|
||||||
|
|
||||||
|
**Incorrect**
|
||||||
|
|
||||||
|
HUMAN_READABLE_BINARY_BYTE_FORMAT(value, \[precision])
|
||||||
|
:::
|
||||||
|
|
||||||
|
### Style checklist
|
||||||
|
|
||||||
|
Before publishing new content or updating an existing topic, you can audit your documentation using the following checklist to make sure your contributions align with existing documentation:
|
||||||
|
|
||||||
* Use descriptive link text. If a link downloads a file, make sure to indicate this action.
|
* Use descriptive link text. If a link downloads a file, make sure to indicate this action.
|
||||||
* Use present tense where possible.
|
* Use present tense where possible.
|
||||||
|
|
Loading…
Reference in New Issue