How to Add Comments to Custom Code in Squarespace
Adding comprehensive comments to Squarespace custom code is the number one way to maintain clean and tidy CSS, HTML, and JS code. You can add comments to header and footer code injections, code blocks, and the Custom CSS editor.
In fact, during my 5 years of coding on the Squarespace platform and working with people who are not familiar with code, I can confidently say that neglecting to add comments is a surefire way of confusing yourself and others in the future. I’m not talking about excessively long lines of comments that can add more clutter than value; I’m talking about short, meaningful comments that explain what a block of code does.
In this article, I will talk about the benefits of using comments in your code and I will show you how to add comprehensive comments to each section of the Squarespace backend.
The benefits of using comments in Squarespace custom code
Does this sound familiar? You found one or 10 blocks of code on the Squarespace forum or you downloaded a third-party plugin and added it to your Squarespace site. You revisit the code editor a few days or weeks later to make edits, and you have no idea what you’re looking at. It’s almost like you weren’t the one who added the code in the first place. Or maybe you need to delete a certain block of code that you no longer need, but you can’t determine which block to delete. Comments can help you avoid issues like these from happening by clearly labeling where a block of code starts and finishes.
Comments are lines of code that will be ignored by the computer when the page is rendered. They are purely for humans to better understand the code.
To give you a better idea of the power of well-written comments, let’s look at the following examples. The image on the top is an example of the Custom CSS editor with comments written as start and end tags, and the image on the bottom shows the CSS editor with no comments. You can see how much easier it is to know which blocks of code do what in the top image, compared to the bottom image which doesn’t look as clear. All code comments in Squarespace are grayed out from the code with color, which makes it easy to know which lines are comments and which lines are active code.
Custom CSS editor with well-written comments.
Custom CSS Editor with no comments.
Adding comments in the Custom CSS editor
There are two ways to add comments to CSS code: multi-line comments and single-line comments. I would recommend using single-line comments as starting and ending tags of a block of code - this way, you know exactly where a block of code starts and where it ends. Here is what that looks like in action:
//Start: Make paragraphs blue
p {
color: blue;
}
//End: Make paragraphs blueMulti-line comments are typically used for commenting out unused CSS code, which means the CSS inside the opening and closing /* … */ tags will be inactive. It is slightly more complicated than single-line comments because you must remember to add both starting and closing tags, otherwise you could mess up how CSS is rendered on your site. Be careful when using multi-line comments to comment out unused code, because this can clutter up your CSS code if it gets excessive. Here’s what that looks like:
//The following code is inactive
/*
p {
color: blue;
}
*/Adding comments in header and footer code injections
The header and footer page code injections use special kinds of HTML elements to include code snippets or code files, including script tags <script> … </script> for JavaScript or style tags for CSS <style> … </style>.
Comments in these areas are notated as follows:
<!-- A comment -->
A comment surrounding the various code examples previously mentioned can help you know where a block of code starts and where it ends. Here’s what that looks like:
<!-- Start: Code Block --> <script src="/link_to_script_file.js"></script> <link href="/link_to_css_file.css"> <!-- End: Code Block -->
<!-- Start: CSS snippet -->
<style>
p {
text-decoration: underline;
}
</style>
<!-- End: CSS Snippet --><!-- Start: JS snippet -->
<script>
console.log("Hello World!");
</script>
<!-- End: JS Snippet -->If you want to comment out a block of code in the header or footer code injection so that it will be inactive, you would need to add the start tag <!-- right before the block of code and add the ending tag --> right after the block is finished. Here’s an example:
<!-- The following code is inactive -->
<!--
<script>
console.log("Hello World!");
</script>
-->Adding comments in code blocks
Code blocks use basic HTML elements, including <p>, <a>, <h1>, <h2>, <h3>, etc. in addition to script tags <script> … </script> for JavaScript code snippets or style tags for CSS code snippets <style> … </style>.
Comments in these areas are notated as follows:
<!-- A comment -->
A comment surrounding the various code examples previously mentioned can help you know where a block of code starts and where it ends. Here’s what that looks like:
<!-- Start: HTML --> <h1>This is a heading 1.</h1> <p>This is a paragraph.</p> <!-- End: HTML -->
<!-- Start: CSS snippet -->
<style>
p {
text-decoration: underline;
}
</style>
<!-- End: CSS Snippet --><!-- Start: JS snippet -->
<script>
console.log("Hello World!");
</script>
<!-- End: JS Snippet -->If you want to comment out a block of code in a code block so that it is inactive, you would need to add the start tag <!-- right before the code block, and add the ending tag --> right after the code block. Here’s an example:
<!--
<style>
p {
text-decoration: underline;
}
</style>
-->For more ways to clean up custom code on your Squarespace site, you might enjoy my article 7 Proven Ways to Clean Up and Speed Up Custom Code - Squarespace where I go into detail about the various ways I’ve found will keep your Squarespace backend looking great and functioning optimally.
Don’t forget to subscribe to my email list for more helpful Squarespace tips and tricks!
