Code documentation may seem like an unnecessary chore, but return to an undocumented web development project after some time away and it quickly becomes apparent how documentation could have helped. Fortunately, a variety of techniques exist to document HTML and CSS web development code, from developer comments, to class names, to whole ways of thinking.
Code Documentation
What Is Documentation in the Web Development Sense?
Documentation is the process of labeling objects, defining their purpose(s), identifying their relationships, and explaining any other useful information.
Comments
Web developers often choose to document code via comments. Comments are simply developer side notes within the code of websites, web apps, and other web development projects. Computers, web browsers, and processors don’t require or even read developer documentation, but humans find them useful.
Web developers can add comments differently depending on the development language. In HTML, create a comment by encasing text like so: <!-- comment --> .HTML comments may span multiple lines as long as all text is encased. In CSS, create a single-line comment by prefacing two forward slashes: //comment. Multi-line CSS comments require the slashes after each line break. JavaScript (JS) can do either the // single-line comments comments or the<!-- multi-line.
comments-->
Besides the opening/closing bracket format, the processor gives no restrictions on what format to use or what content to include in comments. Humans, though, form their own habits. What goes inside the comments can vary from developer to developer, but many developers enter similar kinds of information as each other, such as labeling an upcoming section of code in “human-speak.”
Naming Schema
However, comments aren’t the only way to document. Naming schema can be very useful as well. HTML and CSS element often require names, whether as IDs or classes, to target elements for styling. JS too often requires names to target elements for adding functionality.
Like comments, web development languages don’t restrict names very much. Simply avoid spaces by substituting hyphens and/or underscores. On the other hand, JS has a few additional rules: don’t begin a name with a numeral; don’t use a forbidden word already reserved by the system (like “function” or “class”—so, for example, name a school class variable “course” instead).
Web developers may supply whatever names are desired, but descriptive names are more useful to remind developers or other human readers what the element is and does.
Why Bother Documenting Code?
Overall, code documentation allows web developers to:
- Pair divs together to locate missing or mis-nested tags more easily
- Learn how the code works faster to collaborate on projects with other developers
- Explain how modules operate to diagnose logic errors more quickly
- Show relationship between components
- Assign CSS styles and selectors easily and clearly
- Organize code into neatly-named modules that can be recycled universally
- Eliminate duplicate tasks by reusing templated code (names, grid systems, color and type treatments, etc.)
The BEM Naming Schema
One popular code documentation naming scheme is BEM, or Block Element Modifier. Prominent Russian Internet web giant, Yandex, created the BEM methodology and naming schema to launch websites quickly and scale them easily with future growth and changes.
The elements of BEM are simple:
Block
Represents a standalone entity that is meaningful on its own
E.g. header button menu container
Each block gets a CSS class of the same name too. For example, <button class=”btn” >
Element
Represents a dependent entity nested within a block, without any meaning on its own.
E.g. menu__list-item, portfolio__img-caption, grid__row
Elements augment blocks. Not every block needs a element CSS class, but most have them and some more than one.
Modifier
Defines a block’s appearance, behavior, state, or structure.
E.g. button--orange, link--is-active, image--framed, popup--has-tail
Modifiers augment blocks. Like elements, not every block needs a modifier CSS class, but most have them and some more than one. For example, <button class="btn btn--orange btn--is-focus">
BEM styles objects by CSS class selectors. Tags without at least one CSS class are very rare. Very often, tags have many CSS classes that each build on the previous in some way, adding elements or modifiers.
To apply BEM methodology to your tag names, use the following format:
block__element--modifier
Two underscores precede elements; two hyphens precede modifiers. As a result, the format is visually distinguishable and allows multi-word names to be formed with a single underscore or dash. For example: link--is-active.
Tags using the BEM methodology can get long and wordy depending on how many child (and grand-child) entities as well as how much modification a block has.
Fortunately, BEM only requires a single element in a name. While parent blocks with grand-children entities don’t need a lengthy name, BEM encourages concise names instead. Additionally, BEM limits nested CSS selectors. A CSS rule starting .article .link violates BEM, but the same rule named .article__link upholds BEM.
E.g. DON’T: <a href="#" class="article__main__copy__link">
DO: <a href="#" class="article__link">
Generally, what BEM loses in pretty and/or short names, it gains in flexibility and reusability. Besides names, the BEM methodology also specifies how to modularize code, when to turn a group of modifiers into their own component, overlapping styles, and more. Check out the helpful links below for further reading on BEM.
Harry Roberts’ CSS Guidelines Naming Schema
Another well-known code documentation naming schema are the CSS Guidelines by Harry Roberts. Harry Roberts, a prominent front-end web architect, invented CSS Guidelines for many of the same reasons as Yandex invented the BEM methodology. In fact, he’s been a contributor to BEM’s advocate Get BEM too.
Like BEM, CSS Guidelines also employs the Block Element Modifier format, complete with the same double underscores and hyphens:
block__element--modifier
Also like BEM, CSS Guidelines also permits single underscores and dashes to denote multiple words and restricts double-nesting names.
Yet unlike BEM, CSS Guidelines provides instructions not just for CSS class names, but also CSS comments as well, including aesthetics and a visually distinguishable alignment and indentation style.
Each CSS stylesheet opens with a handy Table of Contents. Headings receive all-caps titles. Similarly, sub-heading receive a title and string of ellipses (just like a real TOC) to an explanation of what that section tackles.
/**
* CONTENTS
*
* SETTINGS
* Global...............Globally-available variables and config.
*
* COMPONENTS
* Page-head............The main page header.
* Page-foot............The main page footer.
* Buttons..............Button elements.
*
* TRUMPS
* Text.................Text helpers.
*/
Basically, this code documentation approach collects related content and CSS styles into easy to find sections. As a result, rules are not only skimmable, but this might also reduce unintended styling conflicts and overrides by allowing the developer to see similar rules together.
Beneath the Table of Contents display the actual CSS rules. The headings above in the TOC stay capitalized and precede each collection of rules with their own distinguishing commenting and indenting format:
/*------------------------------------*\
#SECTION-TITLE
\*------------------------------------*/
.selector { }
Note the pound prefixed to the heading. This allows the developer to jump ahead in the long lines of code immediately to the desired section by searching a particular keyword: the pound sign plus the heading. (Because a pound sign unlikely makes any other appearance in CSS, this format is GREP-friendly.)
CSS Guidelines discuss other alignment and indentation best practices as well, such as:
- Add related selectors to the same line
- Break unrelated selectors onto new lines;
- Place the opening curly brace on the same line as its last CSS selector;
- Add each declaration on its own new line;
- Set the closing curly brace on its own new line;
- “Tab” each declaration by two (2) spaces (no tabs!);
- And more.
While of course the web processor couldn’t care less about whether the CSS is formatted in this manner, this approach nonetheless produces very human-friendly, skimmable, and clear web code.
Conclusion:
Code documentation like comments and naming schemas may have a learning curve and may front-load some extra effort, but the payoff for documentation is human-readable, sharable, reusable code that results in faster launches of your next web project. Documentation like this becomes natural and second-nature once the practices grow familiar.
For Further Reading:
Berner, D. (2016, June 1). “Battling BEM CSS: 10 Common Problems and How to Avoid Them” [Blog article]. Smashing Magazine. Retrieved at https://www.smashingmagazine.com/2016/06/battling-bem-extended-edition-common-problems-and-how-to-avoid-them/
Rambek, N. (2017, June 12). “BEM by Example” [Blog article]. Sparkbox. Retrieved at https://seesparkbox.com/foundry/bem_by_example
Rendle, R. (2015, April 2). “BEM 101” [Blog article]. CSS-Tricks. Retrieved at https://css-tricks.com/bem-101/
Roberts, H. (n.d.) CSS Guidelines. Retrieved from https://cssguidelin.es/
Strukchinsky, V. [@floatdrop] Starkov, V. [@iamstarkov]. (n.d.) Get BEM. Retrieved at http://getbem.com/
Sullivan, N. [webdirections]. (2013, June 2). CSS Preprocessor Performance – Nicole Sullivan Presentation [Video file]. Retrieved from https://www.youtube.com/watch?v=0NDyopLKE1w
