Follow the criteria below regardless of whether you are writing in source code comments, pull request description fields, documentation, or wikis.
Guideline 1. Write sentences that do not cause variations in interpretation
- Write bad things with predicates that make it clear they are bad. "pattern does not crash even if it becomes slow" can also be read as if it were a good thing. Make the lost function the predicate and write "cannot detect that pattern has become slow"
- State the purpose as a complete clause. Write "so that ~ can be done" or "in order to use it for ~". Do not make it a noun-ending fragment such as "for ~,"
- Do not make the predicate of the purpose an ambiguous word. Write "retain X so that highlight can be determined", not "retain X so that highlight applies". With "applies", you cannot fully state what it is that holds
- When copying a sentence from elsewhere, check whether it fits the surrounding context of the paste destination, and after writing it, read it again to check whether the meaning makes sense. Omissions that presuppose the original context will not make sense at the paste destination
Guideline 2. Do not indicate importance with emphasis symbols; polish the sentence
**bold** Do not express importance with emphasis symbols such as these. If it is important, polish the sentence itself so that it is conveyed through vocabulary, strength of assertion, and sentence position.
Guideline 3. Do not provide supplementary explanation in parentheses
Inserting supplementary explanation in parentheses makes the structure of the sentence ambiguous and hard to read.
- If the supplement is a detail or judgment criterion of the parent item, expand it as a child list
- If the supplement is background or a reason, split the sentence and continue
- Change the order of the sentence, such as by stating the contents of the parentheses first and then entering the main topic
- Delete parenthetical notes that merely reverse the meaning of the sentence. In "retain the notation actually written (not after normalization)", the contents of the parentheses are self-evident once the first half has been stated
Guideline 4. Do not insert spaces between Japanese text and Latin characters
Do not insert spaces between Japanese text and Latin characters or code identifiers.Modal を <dialog> に Write Modalを<dialog>に rather thanreact-bootstrap Modal Keep spaces between English words such as these. Spaces before and after Markdown inline code are outside the scope of this rule.