This is a proposal for comment guidelines, this is intentionally minimal so everyone can stick to it easily.
This text would be used to update https://wiki.blender.org/wiki/Style_Guide/C_Cpp#Comments
Note that this is mostly formalizing what's already done, no big changes are expected as result of this proposal.
Motivation
- Consistent comments across the code-base are generally good for readability.
- This makes running a spell checker on comments more useful/practical.
Checking spelling in comments can easily ignore most non-text if these conventions are followed.- This causes significantly fewer false positives when reporting badly spelled word (when running make check_spelling_c).
- Editors may be configured to ignore non-English text too, e.g:
- Having a standard way to reference symbols means we can validate them, seeing as comments becoming invalid or getting outdated often happens by accident.
- Proper punctuation is more important now with clang-format wrapping comments.
Proposed Guidelines
Writing Style & What to Comment
- Write in the third person perspective, to the point, using the same terminology as the code (think good quality technical documentation).
- Be sure to explain non-obvious algorithms, hidden assumptions, implicit dependencies, and design decisions and the reasons behind them.
Punctuation
Use proper sentences with capitalized words and a full-stop.
Acronyms
Acronyms should always be written in upper-case (write API not api).
Syntax for including code
Literal Strings (following doxygen/markdown)
Code or any text that isn't plain English should be surrounded by back-ticks, eg:
/* This comment includes the expression `x->y / 2` using back-ticks. */
Symbols (following doxygen)
References to symbols such as a function, structs, enum values... etc should start with a #.
e.g: /** Remove by #wmGroupType.type_update_flag. */
Tag usage
Tags should be formatted as follows:
- TODO: body text.
Or optionally, some information can be included:
- TODO(@username): body text. unique user name from developer.blender.org.
- TODO(T123): body text. linking to the task associated with the TODO.
- TODO(D123): body text. linking to the differential associated with the TODO.
Common tags.
- NOTE
- TODO
- FIXME
- WORKAROUND use instead of HACK.
- XXX general alert, prefer one of the more descriptive tags (above) where possible.
Comments should describe the problem and how it may be fixed, not only flagging the issue.
Email Addresses
Email formatting should use angle brackets, matching git First Last <name@addr.com>.
C/C++ Comments
The current code-style says that:
It is preferred to use C-style comments in C++ code too.
I'd like to make this statement more definite, e.g:
C-style comments should be used in C++ code.
Adding dead code is discouraged. In some cases, however, having unused code is useful (gives more semantic meaning, provides reference implementation, ...). It is fine having unused coed in this cases. Use // for a single-line code, and #if 0 for multi-line code. And always explain what the unused code is about.