PingCAP Style Guide

Guide to writing idiomatic code at PingCAP and in the TiKV project.

Project maintained by pingcap Hosted on GitHub Pages — Theme by mattgraham



Where/When to comment?

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:

The last three should be highlighted with FIXME (prefer that to TODO so that developers can use TODO for temporary reminders). In most cases, you should file an issue and add it to the comment: FIXME(#1234): a summary of the issue.

Prefer to write about why something is done, rather than what and how (which can be gleaned from the code), unless the code is complicated. It is very useful to write about trade-offs or performance issues which are not clear from the code.

Language for a good comment


Why does a good comment matter?

<< Naming | Modules and crates >>