You SHOULD write your comments in the format specified via the StyleDocco website

[BenjaminRCooper]

Writing comments in this format will allow the Grunt task to produce a component library, which would be a great reference to new maintainers of your codebase.

Even if you feel the style guide is not necessary for the project you are working on, implementing your comments in this way will allow other maintainers of the projects codebase a context in which the module would be used.

Resources:

Style Docco Website (http://jacobrask.github.io/styledocco/)

[BenjaminRCooper]

Implemented.

[BenjaminRCooper]

Ok, we need to change this as it is now incorrect.

I propose we change it so we follow the format implemented via sassdown, with the option of using this in our build process once it becomes more stable.

Thoughts?

Also will add a standard for adding section headers, like so;

// =============================
// Global Variables
// =============================

Ben

[BenjaminRCooper]

On hold

[BenjaminRCooper]

Updated documentation to reference KSS documentation

[BenjaminRCooper]

Reopened to discuss the change in commenting.

[BenjaminRCooper]

This needs rethinking as Styledocco is not the best approach, new tools have came out and I potentially think we don't need to generate documentation from our comments.

I write more comments than code, so I am all for having a defined commenting style, as theres nothing worse than comments in different styles.

There are tools such as; SassDoc, KSS etc, but I'm not sure we need that amount of functionality and the additional overhead in the build and automation process.

What sort of things should we comment?

Here's a list which I use comments for;

• Seperation of code. To define new modules, modifiers or a new section of a file. Example

   // =============================
   // Core Flag Pattern Styling
   // =============================

• Describing what a module or piece of code does and its purpose. If these are single line comments based on a single rule in a declaration block, I do it at the end of the rule. If it's regarding the full block/module, I comment above the block.
• Notes about a module or important information about a piece of code are prefixed with Note -
• I sometimes create diagrams if it's a pattern which needs to be shown in a visual manner. Example;

//    Flag Sidebar               Flag Body
//
//                          ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
//                          ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
//    ~ ~ ~ ~ ~ ~     ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
//    ~             ~     ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
//    ~             ~     ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
//    ~             ~     ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
//    ~ ~ ~ ~ ~ ~     ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
//                          ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
//                          ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
//

• I provide example use cases if it is a construct which needs to be called or included like a function. These contain a heading like so; Example Use:. Example of this;

// Example Use:
//
// @include rem-sizing("font-size", 32px);
//

• If a construct takes parameters, I document what the parameter is and the type it requires. Example;

// Parameter Description:
//
// $property  - A string value which contains the property which you want to set a REM unit value for. // "font-size"
// $value        - The value (in pixels) of the elements property you are setting the REM value for.           // 12px
// $context    - This value is mapped back to the $font-size-base variable set within the _settings.scss partial.

Thoughts?

Ben

[BenjaminRCooper]

Comments haven't rendered correctly.

Provided a screenshot

[lewismorris]

I've got no problem with the comment styles suggested above. I'd say mine are similar apart from the use of diagrams which is not something i do.

+1

[matchboxhero]

Yeah, I think using the two different styles of comments is a good idea, one for labeling sections and then just simple comments for everything else will make it easy when scanning a document to see whats going on.

+1

[BenjaminRCooper]

Will implement and close off once done.

[BenjaminRCooper]

Implemented and closed.