Better Front-End Comments

Commenting involves HUMAN READABLE DESCRIPTIONS that provide details about what the code should be doing. Proper use of comments can make code maintenance significantly easier and finding bugs quicker. Additionally, comments are important when writing code that will be worked on by other developers.

Have you ever written code, only to look at it six months later with no idea how it works?

When writing code complex logic often finds it way in; this is an opportunity to include comments in the code to explain the logic. Whatever developer works on the code down the road will have the comments to assist understanding the logic.

Developers who have spent any time on a large project understand the importance of comments. It should come as no surprise that documenting code via comments is essential, when developing by yourself or on team projects. Ultimately, developers should strive toward clean, readable comments to further explain confusing areas of the codebase.

Ways Of Commenting Code

Block Comments

BLOCK COMMENTS should be placed at the top of a function and describe the purpose the code.

When large explanations are needed generally block comments will do the trick. Descriptive blocks are most notably seen around functions and library files.

Inline Comments

INLINE COMMENTS should be used sparingly, only where the code is not "self-documenting". Place them before (or next to) any code that is not self explanatory. This comment should detail the "idea" behind the code and what is to be accomplished. It may also say how this is to be accomplished if the "algorithm" is complex.

Developers should avoid going overboard with inline comments since we generally do not need to see comments all through the code

What Should Be Commented

One of the things developers usually learn about basic HTML or CSS is how to write comments in the code. However, many developers still do not use comments effectively. There may be comments throughout the HTML and CSS ... but when written properly, and with intent, these comments can really improve the workflow.

A new developer can find looking at manuals or many pages of documentation daunting. Every company is different ... meaning that the codebases, amount of legacy code, development of frameworks, and amount of modular code will be different.

Developers lead with, "Good code does not need comments." While having said that, developers often find themselves going around in circles, completely lost, and searching for documentation because of a lack of comments.

Two Facts About Code Comments

1. Comments are ignored by the browser.
2. Comments are stripped out during minification and mangling.

Based on these two facts tell us that comments are not really meant for machines ... they are meant for humans to read.

HTML

An HTML comment begins with <!-- and the comment closes with -->. HTML comments are visible to anyone that views the page source code, but are not rendered when the HTML document is rendered by a browser.

Logical Grouping (of HTML)

Keep HTML groups organized logically and provide a comment noting what the following grouped HTML pertains to.

CSS

CSS only utilizes the block comments delineated with /* and */. Remember that comments will be openly displayed to visitors, since CSS is not parsed server-side, but this method works great for leaving informative tidbits in the codebase to go back over.

However, CSS is missing the inline comment syntax.

Explain Why !important Might Be Needed

When !important included in code, a developer often assumes they are looking at legacy code or a dirty hack.

Logical Grouping (of CSS)

Keep styles organized in logical groups and provide a comment noting what the following styles pertain to.

JavaScript

To create a single line comment in JavaScript, two slashes // are placed in front of the code or text the JavaScript interpreter should ignore. When these two slashes are used, all text to the right of them will be ignored, until the next line.

These types of comments are great for commenting out single lines of code and writing small notes.

For large comments JavaScript's multi-line comments begin with /* and end with */.

JSON

This is what Douglas Crockford said about removing comments from JSON.

I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't.

Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.

Commit Messages

When using a version control system (such as Git), a developer should take what they know about writing useful comments in code and apply this to the commit messages.

Bad commit messages do not give much context. They look sloppy, and are often hard to understand. They are not helpful as release notes and can be much harder to search. It is also hard for a developer to know what has changed within a commit.

Self Documenting Code

SELF DOCUMENTING CODE has a goal of using well chosen variable (and function) names to make the code as close to human readable as possible. By using proper variable and function names, a developer can minimize the amount of "external" documentation needed.

"Good code is self documenting."

There is a kernel of truth to this statement. But this truth has been abused so frequently that most people who utter the phrase have no idea what it really means.

Is it true? YES

Does it mean a developer should never add comment to the code? NO

First, there is code that DOCUMENTS the system; this could be left out. Then, there is code that CLARIFIES that should never be left out of the codebase.

CLARIFICATION COMMENTS are intended for anyone (including your future self) who may need to maintain, refactor, or extend your code.

Often, these clarification comment are a code smell. It should tell a developer that the code is too complex. Developers should strive to remove clarification comments and simplify the code instead because, “good code is self-documenting.”

Still, there are times when no matter what a developer does to the code itself, a clarification comment is still warranted.

Commented Code Is Important

Comments help maintain consistency. Consistent, well-written comments for what is being built will reinforce build things the same way every time.

Comments facilitate understanding. This is really important in a team where sometimes one person does not do all the work. A developer might write comments to help themselves figure out some logic, and even though all their comments are not kept within the project, it can help better understand how they came to a solution. It can help improve on that solution later on.

Commenting can also assist with hot-fixes or quick fixes. Comments can actually help in three ways here.

1. They help developers understand the code if they need to make a quick fix (especially developers outside of the front-end team who may be helping out),
2. It can help by marking out where these fixes are needed, and
3. It can show where quick fixes have been applied and need to be removed at some point.

Comments help speed up the development process. Developers will have a clearer understanding of what is being created, changed, or removed if there are relevant comments.

Comments facilitate more efficient collaboration. When a developer knows the ins and outs of a project or codebase, they are more likely to get work done quicker, thus improving workflows.

Comments help a lot of people. They not only help the original developer, but they can help other people on the team.

Better Commenting Style

1. KEEP EVERYTHING READABLE: Developers sometimes forget they are writing comments for humans to read.
2. ALLOCATE SPACE: Whitespace is tremendously important. This is doubly true for developers working on massive websites with hundreds of files. They stare at this code all day long.
3. COMMENT WHILE CODING: Along with proper spacing this may be one of the best habits to get into. Nobody wants to go back over their program after it is working and document the details.
4. DEALING WITH BUGS AND ERRORS: Developers, at times, will leave the codebase with some features still broken, planning to come back to the code. In this scenario it is crucial they leave long, detailed comments about where things were left.

Conclusions

There are no hard and fast rules about how to format comments in front-end code. The information to include is up to the developer, or can be decided between the developer and their peers. As long as they keep the format consistent, it will keep things tidy and encourage others working on the code to do the same.

There are many benefits associated with making comments a part of the development process. It is good to get into the habit of including them appropriately, especially when there are many people working in the same codebase.

Comments are an important part of how developers communicate code intent. Strict rules (code for every service and function) can undermine this communication as easily as relying solely on self documenting code. Good comments are as important to the development process as good code.