-
Notifications
You must be signed in to change notification settings - Fork 0
Code Comment Guide
This project uses the Comment Anchors VS Code plugin, which highlights comments with special comment tags. Here's a list of tags used in this project and what they're used for.
// ANCHOR
A generic tag used to mark a place in the code
// DEPRECIATED
This tag warns about depreciated code that should eventually be removed
// DEBUG
This tag indicates a code chunk that needs to be tested in a few use cases to make sure it is working as intended
// BUG
Indicates a chunk of code that is causing problems and needs to be rethought
// FIX / FIXME
Used to bring attention to bug fixing CSS, and used to describe the purpose of odd workarounds
// HACK
Much like FIX, but this is added as a future action item and will eventually be improved.
// IDEA
Useful as a short-term note to self or used as an alternative to TEMP if the code needs to stay around longer.
// NOTE
An important message to your future self and other developers that is good to know information when working in that code block. NOTEs are never removed from the code, but should be audited from time to time to ensure they are still relevant.
// OPTIMIZE
Used to bring attention to parts of the code that should be improved. Ideally, these should accompany an issue submitted on GitHub and reference that issue in the same comment.
// QUESTION
Used primarily as a note to self to add more documentation, but can also be used in PR reviews to help facilitate discussion
// REVIEW
Similar to QUESTION, useful for pointing out specific lines of code during a PR review or as a future state item that doesn't quite qualify as a TODO, OPTIMIZATION, or GitHub Issue.
// TEMP
Used for code that has been temporarily added for testing, as an idea, or as an experiment. These should be removed before a new version is released.
// TODO
Use as a short-term temporary reminder or as a note to self about code that you can address in the short term. These should be resolved or removed and added as issues before a PR is made.
// WARNING
Similar to NOTE, this tag brings attention to information that developers must know before working on a specific code block. Warnings should only ever be removed if they are no longer relevant, but may be degraded to a NOTE.
Keep comments at a maximum length of 80 characters.
Regions of code can be defined with the SECTION comment anchor. These anchors must also have a closing anchor at the end of the section: !SECTION. Here's what top and sub section comments should look like:
/* ==========================================================================
SECTION: NAME
========================================================================== */
/* END !SECTION: Optional ending tag */
/* SECTION: Name
-------------------------------------------------------------------------- */
A block comment should be used anywhere there is more than one thing to say about a segment of code, or if your comment is longer than 80 characters
/**
* Block comment description
* [1] comment
* [2] comment
**/
.foo {
property: value; /*[1]*/
property: value; /*[2]*/
}
Use inline comments to reference a single declaration or rule set.
/* Inline comment addressing rule set */
.foo {
...
}
/* [1] Inline comment addressing declaration */
.foo {
property: value; /*[1]*/
}
For Sass functions, mixins, and variables, you should document them using sassdoc style comments.
/// Description
/// @name Name of function
/// @group Group it belongs to (optional)
/// @author (optional)
///
/// @param {type} $name [default] - Description
/// @returns - Description
/// @example (optional)
{number(unit)} // where unit can be any css unit or "unitless"
{string}
{map}
{key(map)}
{color} // any valid css color unit
{keyword[array]} // where array is a comma separated list of accepted keywords
{boolean} // when accepted keywords are either "true" or "false"
Separate types with a pipe
{boolean | null}
In addition to the keys shown above, it can also be useful to use @see, @requires, and @deprecated
While it can be difficult to maintain a table of contents, it is extremely helpful when trying to find specific styles
/* --------------------------------------------------------------------------
[Table of contents]
GROUP
* SECTION NAME | _file.scss
* Sub Section.......................Description
* Sub Section.......................Description
*
* SECTION NAME | _file.scss
* Sub Section.......................Description
GROUP
* SECTION NAME | _file.scss
* Sub Section.......................Description
-------------------------------------------------------------------------- */