This document describes the code comment style applied to TiKV repositories. Since TiKV uses Rust as its development language, most of the styles or rules described in this guide are specific to Rust.
When you are to commit, be sure to follow the style to write good code comments.
Write a comment where/when there is context that is missing from the code or is hard to deduce from the code. Specifically, use a comment:
A comment is generally used for:
Non-doc comment
//
for a line commentNote: Block comments (
/* ... */
) are not recommended unless for personal reasons or temporary purposes prior to being converted to line comments.
Doc comment
///
for item documentation (functions, attributes, structures, etc.).//!
for module level documentation.For more detailed guidelines on Rust doc comments, see Making Useful Documentation Comments.
Place the single-line and block comment above the code it’s annotating.
Fold long lines of comments.
The maximum width for a line is 100 characters.
Use relative URLs when appropriate for Rustdoc links.
Word
Use American English rather than British English.
Use correct spelling.
Use standard or official capitalization.
Use words and expressions consistently.
Do not use lengthy compound words.
Do not abbreviate unless it is necessary (for readability purposes).
"we" should be used only when it means the code writer and the reader.
Sentence
For each comment, capitalize the first letter and end the sentence with a period.
When used for description, comments should be descriptive rather than imperative.
Use "this" instead of "the" to refer to the current thing.
The Markdown format is allowed.
log
fileThe Code Comment Style defined in this document follows the CNCF Code of Conduct. The following language uses are deemed as taboos and are not acceptable in code comments:
Thanks for your contribution!
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。