Skip to content

Latest commit

 

History

History
92 lines (58 loc) · 4.38 KB

Text.md

File metadata and controls

92 lines (58 loc) · 4.38 KB
Raw

AdGuard Go Team text and commenting guidelines

Following this document is obligatory for comments and text in new code. Some of the rules aren't enforced as thoroughly or remain broken in old texts, but this is still the place to find out about what we want our texts to look like and how to improve them.

The rules are mostly sorted in the alphabetical order.

  • § Avoid overly technical and markup-ey comments. Write comments for people, with full sentences and proper punctuation.

  • § Avoid duplication of words, even if it's grammatically correct. For example, avoid:

    # Bad!  The duplication in “that that” impedes reading.
It isn't obvious that that will not cause issues.

    instead, write something like:

    It isn't obvious that the code will not cause issues.

  • § Capitalize only the first letter in headers and titles, unless a proper name or an acronym is used. So, a header should be something like this:

    Using the new API

    and not like this:

    Using The New API

  • § Changelogs should follow the Keep a Changelog format. The “Security” section may be put first.

  • § End sentences with appropriate punctuation. Do not add full stops to headers.

  • § Mark temporary todos—that is, todos that must be resolved or removed before publishing a change—with two exclamation signs:

    // TODO(usr1): !! Remove this debug before pushing!

    This makes it easier to find them both during development and during code review.

  • § RFC links should lead to the HTMLized version on datatracker.ietf.org. For example:

    https://datatracker.ietf.org/doc/html/rfc9000

  • § Set your editor to always end all your files with a newline to make sure that Unix tools work correctly.

  • § Set your editor to consider one tab to be four (4) columns wide. This is the default in most editors, and it is also a common preference among developers.

  • § Start sentences with a capital letter, unless the first word is a reference to a variable name that starts with a lowercase letter.

  • § Strive to not leave any space on the right side and properly justify the text. For example, do not do this:

    This text is way too
narrow and should be
expanded.

  • § Text should wrap at eighty (80) columns to be more readable, to use a common standard, and to allow editing or diffing side-by-side without wrapping.

    The only exception are long hyperlinks.

    Don't forget to also set the tab width in your editor's settings.

  • § Use U.S. English, as it is the most widely used variety of English in the code right now as well as generally.

  • § Double spacing between sentences may be used in code comments to make sentence borders more clear. In human-facing documentation (Markdown, etc.), prefer single spacing.

  • § Use the serial comma (a.k.a. Oxford comma) to improve comprehension, decrease ambiguity, and use a common standard.

  • § Write todos like this:

    // TODO(usr1):  Fix the frobulation issue.

    Or, if several people need to look at the code:

    // TODO(usr1, usr2):  Fix the frobulation issue.