One of the things you usually learn when you start learning about basic HTML or CSS is how to write comments in your code. However, many web developers still don’t use comments to their advantage. We may use comments widely in HTML and CSS, but when written properly, and with intent, they can really improve our workflow.
When you start working at a new company, looking at manuals or many pages of documentation can be daunting. Every company is different – meaning that the codebases, amount of legacy code, development of frameworks, and amount of modular code can be different.
We’re often told that "good code doesn’t need comments", but do you ever find yourself going around in circles, completely lost, and searching for documentation because of a lack of comments?
Two Facts About Code Comments
- Comments are ignored by the browser.
- Comments are stripped out during minification.
Based on these two facts, we know that comments are not really meant for machines – they are meant for humans to read.
Why Commenting Code Is Important
When you are freelancing and working on a solo project, or when you are the only developer who is going to be looking at your code, it’s easy to go about it your own way and make comments as you see fit, or maybe leave no comments at all. But a lot of the time, developers say that they look back at their own code and wonder, "What was I thinking?" or struggle to understand that code they have written.
Comments can help maintain consistency. If you have consistent, well-written comments for what you are building then you are more likely to build things the same way each time.
Comments facilitate understanding. This is really important in a team where sometimes one person does not do all the work. You might write comments to help yourself figure out some logic, and even though you do not keep all of your comments by the end of the project, it can help you better understand how you came to a solution. It can help you improve on that solution much more easily later on.
Commenting can also assist with hotfixes or quick fixes. Comments can actually help in three ways here. They can 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), it can help by marking out where these fixes are needed, and can show where quick fixes have been applied and need to be removed at some point.
Comments help speed up the development process. You can have a clearer understanding of what you are creating, changing or removing if you include relevant comments.
Comments facilitate more efficient collaboration. If you know the ins and outs of a project or codebase, you are more likely to get bits and pieces done quicker, thus improving workflows.
Comments help a lot of people. They not only help yourself, but they can help other people in your team. Gone are the days that we saw comments like DO NOT STEAL MY CODE in people’s source code. While we used to be very protective of our code, not wanting to share our ‘secrets’, we now live in a world where people share code, work on projects together and collaborate. We are not ashamed of crediting the likes of Harry Roberts, Chris Coyier or Jonathan Snook when it comes to web projects. With this shift in collaboration, we should also take note of our commenting practices – and help our peers.
Some Things to Avoid When It Comes to Comments
Avoid Commenting Absolutely Everything
It may be tempting to get into the habit of commenting every block of code, but this can be more redundant than useful or helpful. Commenting should only be done where something may not be completely clear. If you considered semantics when naming your classes, your code may already be easy to understand.
This may also be where the concept of "good code does not need comments" came from. Comments should not be completely avoided, but only used where necessary.
Do Not Be Too Verbose
I am personally guilty of writing some rather long comments in my CSS, because I love explaining and documenting things. However, you shouldn’t be writing novels – long comments are as much a pain to read as they can be to write. If you can be succinct, do so. Sometimes, when naming CSS classes, the following advice is given:
Make class names as short as possible but as long as necessary.
The same applies to comments. It’s good to read over any comments you write to ensure that you understand them yourself. Imagine you are someone new to the code and you are reading the comments as a guide.
Do Not Spend Too Much Time Writing Comments
I once saw a file in a project I was working on that had a line at the top reading:
[code language="sass"]
// Update this with how many hours you have spent on this file:
// TIME_WASTED = 438;
[/code]
You shouldn’t need to spend a lot of time writing comments. A few words is usually enough. If you are spending too much time trying to comment your code to make sure someone else will understand it, consider that parts of your code might actually need refactoring.
Some Examples of When to Use Comments
To Explain a Pseudo Element's Purpose
This example shows a pseudo element with the content value filled in.
[code language="css"]
.post__comment-container::after {
background-color: #f9f9f9;
border: 1px solid #dedede;
border-radius: 0.25em;
color: #888;
content: 'Post author';
display: inline-block;
font-size: 0.7rem;
margin-left: 0.5rem;
padding: 0.2rem 0.45rem;
vertical-align: middle;
}
[/code]
It may not be immediately clear what a pseudo element is for, especially if the content property is displayed as content: ''. With a short comment above the code block, we can improve this.
[code language="css"]
/* Post author label for comment */
.post__comment-container::after {
background-color: #f9f9f9;
border: 1px solid #dedede;
border-radius: 0.25em;
color: #888;
content: 'Post author';
display: inline-block;
font-size: 0.7rem;
margin-left: 0.5rem;
padding: 0.2rem 0.45rem;
vertical-align: middle;
}
[/code]
Continue reading %How Good Are Your HTML and CSS Comments?%
by Georgie Luhur via SitePoint
No comments:
Post a Comment