Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-01-27 14:57:26 -05:00
Code Issues Packages Projects Releases Wiki Activity

Clarify intention and context of coding conventions

Browse Source
This commit is contained in:
Andrew David Wong 2021-06-22 06:05:53 -07:00
parent 0e3edb15bf
commit 1a4365fadb
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
1 changed files with 14 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
developer/general/doc-guidelines.md
View File

@ -493,10 +493,12 @@ making contributions, please try to observe the following style conventions:
``` ```
~~~ ~~~
The `#` symbol preceding each comment is ambiguous with a root command prompt. The `#` symbol preceding each comment is ambiguous with a root command
Instead, put your comments *outside* of the code block in normal prose. prompt. Instead, put your comments *outside* of the code block in normal
* Use non-reference-style links like `[website](https://example.com/)`. prose.
Do *not* use reference links like `[website][example]`, `[website][]` or `[website]`. * Use non-reference-style links like `[website](https://example.com/)`. Do
*not* use reference links like `[website][example]`, `[website][]` or
`[website]`.
([This](https://daringfireball.net/projects/markdown/) is a great source for ([This](https://daringfireball.net/projects/markdown/) is a great source for
learning about Markdown.) learning about Markdown.)
@ -504,19 +506,22 @@ learning about Markdown.)
## Coding conventions ## Coding conventions
These conventions apply to the website as a whole, including everything written These conventions apply to the website as a whole, including everything written
in HTML, CSS, YAML, and Liquid. in HTML, CSS, YAML, and Liquid. These conventions are intended to keep the
codebase consistent when multiple collaborators are working on it. They should
be understood as a practical set of rules for maintaining order in this
specific codebase rather than as a statement of what is objectively right or
good.
* Always use spaces. Never use tabs. * Always use spaces. Never use tabs.
* Indent by exactly two (2) spaces. * Indent by exactly two (2) spaces.
* Whenever you add an opening tag, indent the following line. (Exception: If * Whenever you add an opening tag, indent the following line. (Exception: If
you open and close the tag on the same line, do not indent the following you open and close the tag on the same line, do not indent the following
line.) line.)
* Indent Liquid the same way as HTML. (This is the easiest rule for multiple * Indent Liquid the same way as HTML.
collaborators to all follow consistently when editing the same codebase.)
* In general, the starting columns of every adjacent pair of lines should be no * In general, the starting columns of every adjacent pair of lines should be no
more than two spaces apart (example below). more than two spaces apart (example below).
* No blank or empty lines. (Hint: When you feel you need one, add a comment * No blank or empty lines. (Hint: When you feel you need one, add a comment on
on that line instead.) that line instead.)
* Use comments to indicate the purposes of different blocks of code. This makes * Use comments to indicate the purposes of different blocks of code. This makes
the file easier to understand and navigate. the file easier to understand and navigate.
* Use descriptive variable names. Never use one or two letter variable names. * Use descriptive variable names. Never use one or two letter variable names.