Comments¶
Note
If peppering your code with lots of comments is good, then having zillions of comments in your code must be great, right? Not quite. It doesn’t make sense to comment every step your code makes, or to comment on things that don’t need to be explained.
Comments in code should describe:
- what is being done
- why it’s being done
They do not need to describe:
- how it is being done (the code already shows this)
- what you are thinking about
Section Comments¶
In addition to the regular comments, we introduced the section comment. Use this style to separate large chungs of logic (which you should generally avoid). The line is exactly 80 characters long:
// #############################################################################
// NAME
Inline Comments¶
When using comments inline, make use of the appropriate formats:
{# ... #}
or{% comment %} ... {% endcomment %}
for Django templates and never<!-- ... -->
// ...
and/* ... */
for Sass and JavaScript
Notes¶
We also use several comment helpers which, if configured in your editor, add additional highlighting to your code:
FIXME:
to annotate problems with the code
function Calculator() {
// FIXME: shouldn't use a global here
total = 0;
...
}
TODO:
to annotate solutions to problems with the code
function Calculator() {
// TODO: total should be configurable by an options param
this.total = 0;
...
}
DOCS:
provides a simple docs link
// DOCS: https://django-cms.readthedocs.org/en/latest/
Formatting¶
Comments
- Add proper whitespace.
- In general use lowercases except for the Notes.
bad
//TODO: THIS NEEDS ADDITIONAL REVIEW
//
// square root of n with Newton-Raphson approximation
/**
* Contains various helpers, feel free to extend and adapt
*/
good
// TODO: this needs additional review
// square root of n with Newton-Raphson approximation
/**
* Contains various helpers, feel free to extend and adapt
*
* @class Utils
* @namespace Cl
*/