How to comment in css

CSS GuideLines, часть 2. Комментирование кода

В каждом проекте есть определенные нюансы и тонкости, которые помнят далеко не все, и худшее, что может случиться с разработчиком — это работа с кодом, который писал не он. Даже запоминание тонкостей своего собственного кода является возможным только до определенной степени, не говоря уже о чужом коде. Именно поэтому CSS надо комментировать.

Так как CSS сам по себе не может быть достаточно понятным, то разработчики действительно получают выгоду от комментирования кода.

Как правило, следует комментировать те места кода, которые будут непонятны разработчику, если вырвать их из контекста. Нет необходимости делать пометку о том, что color: red; сделает текст красным. Но, например, если вы используете свойство overflow: hidden; для очистки float’ов, а не для скрытия контента за пределами блока, то вам следовало бы добавить пояснительный комментарий.

Высокоуровневые комментарии

Для больших комментариев, описывающих целую секцию или компонент, мы используем DocBlock-подобные мультистрочные комментарии, соответствующие нашему правилу о 80 символах в строке.

Ниже можно увидеть реальный пример комментирования кода шапки сайта CSSWizardy.

Этот уровень комментирования должен использоваться для описания элемента в общем: его состояния, от чего это состояние зависит и тому подобное.

Указание на наследование стилей

Например, в файле с главным классами (объектами):

В файле с дочерними классами:

Такое комментирование кода не потребует от разработчика больших усилий, и благодаря этим комментариям те, кому придется работать с вашим кодом, легко смогут разобраться в связях между классами.

Низкоуровневые комментарии

Часто нам требуется прокомментировать определенную строку кода с объявлением какого-либо свойства. Для этого мы используем сноски. По ссылке можно увидеть пример более сложного комментирования кода шапки сайта, о которой говорилось выше. Такой способ комментирования позволяет нам держать всю документацию в одном месте, и затем всего лишь ссылаться на нужное место в документации, вместо того, чтобы писать длинный комментарий прямо в коде.

Препроцессоры и комментирование

Во многих, если не во всех препроцессорах есть возможность добавлять комментарии, которые при компиляции не будут выводиться в итоговый файл стилей. Примите за правило использовать такие комментарии для кода, который также не будет скомпилирован. Для кода, который будет выведен в итоговый файл, используйте обычные комментарии.

В этом примере мы задокументировали переменные (которые не будут скомпилированы) с помощью комментариев препроцессора, а для обычного кода мы применили стандартный способ комментирования. Такой способ гарантирует нам то, что в скомпилированных CSS-файлах будет только релевантная и нужная для нас информация.

Удаление комментариев

Следует сказать о том, что при использовании кода в продакшене все комментарии должны быть удалены, а сам CSS должен быть минифицирован перед деплоем.

Как закомментировать CSS (и как писать комментарии)

Хочешь знать больше про веб?

Подпишись на наш телеграм-канал TechRocks WEB-разработка?

Комментарии — составляющая часть кода на любом языке программирования. Есть возможность комментирования и в CSS.

Если вы работаете в команде и занимаетесь большим проектом, вам нужна возможность как-то пояснять свой код товарищам. Тут вам на помощь придут комментарии.

Таблицы стилей со временем могут стать очень сложными и объемными. Поэтому систематическое добавление комментариев должно стать общепринятой практикой в команде.

В этой статье мы рассмотрим, как добавлять встроенные и многострочные комментарии в CSS.

Как закомментировать CSS

Чтобы закомментировать часть CSS-кода, вам понадобится обычный слэш ( / ) и астериск ( * ).

Для добавления как встроенного, так и многострочного комментария в CSS вы начинаете со слэша и астериска ( /* ). Их же, но в обратном порядке ( */ ) вы ставите в конце комментария.

Вот как выглядит встроенный (строчный) комментарий в CSS:

А так выглядит многострочный комментарий:

Вы также можете закомментировать те строки CSS, которые не должны выполняться:

С помощью комментариев обозначают начало и конец стилей отдельных разделов на веб-странице:

Комментарии помогут вам и тогда, когда вы хотите оставить примечание в вашем CSS для разработчиков, которые будут работать с вашим кодом после вас:

Организация CSS при помощи комментариев

Примечание редакции Techrocks: этот раздел взят из другой статьи — «CSS Comment Example – How To Comment Out CSS».

В более крупных проектах CSS-файлы могут быстро разрастись. В результате их может стать трудно поддерживать. Упорядочивание СSS и разделение кода на отдельные части поможет лучше ориентироваться в стилях в будущем. При этом стоит также создать «Содержание» документа:

Заключение

В долгосрочной перспективе комментарии в СSS могут помочь вспомнить, что вы делали, когда писали тот или иной код.

Кроме того, если добавлять комментарии правильно, это облегчает работу над проектом, к которому вы возвращаетесь после долгого перерыва.

CSS Comments: Best Practices to Comment Like a Pro

CSS comment lets you add comments that organize or explain various segments of the stylesheet.

Although adding comments on CSS may seem extraneous when coding, it is extremely useful when redesigning or debugging a website.

Comments in CSS tell the reader the purpose of specific lines of CSS, and such insights are useful especially when multiple developers work on a website. Read on to learn how you can comment like a pro.

How to Comment in CSS

Commenting in CSS helps explain a block of code or even make temporary changes while developing websites. Browsers do not execute commented CSS code.

By simply adding a text inside the /**/ you tell the browser these are notes in CSS and should not be executed. Just like programming languages that rely on the /* */ syntax for comments, you cannot nest CSS comments. It means that the first occurrence of */ after a /* terminates the comment.

The single-line comment is the most common CSS comment format.

– Example – Single-Line CSS Comments

How to Comment Out CSS

Besides explaining what the CSS code does, comments in CSS provide a way to comment out CSS or invalidate CSS ruleset. Commenting out CSS tells the browsers not to execute that styling.

– Example – Commenting out CSS Using Single-line Comment

Using the previous example, we can comment out the font color as shown below.

– Example 2 – Commenting out CSS Using Multi-line Comment

Also, it is possible to comment out the entire ruleset as follows.

Adding notes in CSS

Comments make it easy to add explanatory notes. Using as little as one CSS comment line, can make it possible for you to add notes next to the CSS.

– Example

color: blue; /* setting the font color for paragraph to blue*/

Note: CSS Comments do not interfere with the interpretation of other parts of the stylesheet. As well, they do not affect the front-end layout of a website. What’s more, they are easy to add even for beginners. You can place comments anywhere in the stylesheet where white space is allowed.

Organizing CSS Using Comments – For Large Projects

In huge projects, CSS files tend to be large in size which makes maintaining them difficult. So, organizing CSS code into sections is helpful because it makes it easy to find specific rules even after finishing the project.

Whenever possible, you should group various stylesheet sections using comments and separate one section from another using new lines. Putting comments for each group of CSS code provides an easy way of locating the CSS group when editing.

– Organizing CSS Comments: Example

Techniques To Improve CSS Code and Comment Structure

Using sensible code structure is advisable since it makes it easy to understand the CSS code years later. Comments drastically decrease the complexity of understanding CSS code. Below are the techniques developers use to comment and simplify maintenance of CSS code, and now you can use them in your code too!

– Divide and Conquer

Establish the most important aspects and the layout of the CSS code and group common elements inside sections and give each group a title. For instance, in large projects, developers may have to import external CSS files. So, clearly separate code fragments using comments. Use more * symbols to make the heading of each section in a stylesheet more visible.

CSS Comments: Divide and Conquer Example

Section for Header style

Such sections make it easy to immediately recognize individual blocks while scanning through the code. The divide and conquer approach may not work for large projects since one file may become too big.

For large projects, you might need to divide the code into multiple files to make it easy to see groups of code fragments. In such cases, the master stylesheet has the role of importing groups.

Using a master stylesheet results in a clean code that is easy to understand and maintain. However, it causes unnecessary server requests, so keep that in mind if you want to use it.

CSS Comments: Master Stylesheet Example

@import “flash.css”;

– Defining a Table of Contents

Having a table of contents in a stylesheet helps with the overview of the structure of the code. Through CSS comments, you can include a table of contents that shows a tree overview of the layout. You can rely on some keywords like content group or header section to make it easy to navigate.

What’s more, specific elements that likely require often updates after finishing the project can be part of the table of contents. This way, it becomes easier to find them without scanning the entire code. One way of adding a table of content is through simple enumeration as shown below.

Using the example below, jumping to the Sidebar section is easy using the search tool to find 4. Sidebar. It is fast and effective.

CSS Comments: Defining a Table of Contents Example

[Table of contents]

2. Header / #header

3. Navigation / #navbar

4. Sidebar / #sidebar

5. Right column / #rightcolumn

6. Left column / #leftcolumn

7. Content / #content

9. Search / #search

11. Sideblog / #sideblog

12. Footer / #footer

Also, it is possible to use CSS comments to create an indented table of content. Defining a table of contents makes it easy for others to read and comprehend your CSS code. It is especially useful when working in a team since it saves a lot of time.

– Defining Custom Typography and Colors

CSS comments provide a way of quickly referencing variables like custom colors and typography. Often, web development considers typography and colors as constants. Since CSS does not have constants, developers use CSS comments to define some at the top of the CSS file.

Usually, developers use comments to come up with a color glossary. As such, it gives them a quick reference to colors they use on a website to avoid mistakes. Also, it gives them a quick list of colors that they can change if necessary.

Example 1 – Defining Custom Colors Through CSS Comments

Background: #ffffff (white)

Content: #CCCCFF (light blue)

Header h1: #000066 (dark blue)

Header h2: #333399 (mid blue)

Footer: #b5cede (dark black)

a (standard): #333333 (dark grey)

a (visited): #666666 (mid grey)

a (active): #cc0000 (pink)

Moreover, developers use the same approach to define typography. They use CSS comments to include important notes that help comprehend the thinking behind the definitions.

Example 2 – Defining Custom Typography Using CSS Comments

Body: 1.2em/1.6em Helvetica, Georgia, Verdana, Times New Roman;

Headers: 2.7em/1.4em Helvetica, Arial, “Lucida Sans Unicode”, Georgia, Times New Roman;

Sidebar heading: 1.5em Helvetica, Trebuchet MS, Arial, Times New Roman;

Input, textarea: 1.1em Helvetica, Georgia, Arial, Times New Roman;

Notes: reducing heading by 0.4em with every subsequent heading level

– Using Keywords in Comments – For Better Overview of New Changes

CSS Comments: Using Keywords in Comments Example

border-bottom: 5px solid #ddd; /* @new */

margin: 2px 0 2px 0;

padding: 4px; /* @new */

Comments in code are important. So, take time to explain components, their function, limitations, and how they are built. Avoid a scenario where others have to guess the purpose of uncommon CSS code. The comment style needs to be consistent and simple.

Conclusion

Commenting in CSS helps developers achieve sensible structuring by leaving useful notes and hints that are useful. In this article, you will find out examples on how to adopt CSS comments so that you can:

The goal of comments in CSS is to have a code that is easy to read and maintain. Using CSS comments saves you and anyone who reviews your code a lot of trouble. If you keep practicing it long-term through our guide, that will help you understand the code years later when you go through it.

CSS Comment Example – How To Comment Out CSS

Comments are used in CSS to explain a block of code or to make temporary changes during development. The commented code doesn’t execute.

You can also make your comments more readable by stylizing them:

Organizing CSS with comments

In larger projects, CSS files can quickly grow in size and become difficult to maintain. It can be helpful to organize your CSS into distinct sections with a table of contents to make it easier to find certain rules in the future:

A little bit more about CSS: CSS Syntax and Selectors

When we talk about the syntax of CSS, we’re talking about how things are laid out. There are rules about what goes where, both so you can write CSS consistently and a program (like a browser) can interpret it and apply it to the page correctly.

There are two main ways to write CSS.

Inline CSS

Specifics on CSS Specificity: CSS Tricks

Inline CSS applies styling to a single element and its children, until another style overriding the first is encountered.

To apply inline CSS, add the “style” attribute to an HTML element that you’d like to modify. Inside quotes, include a semicolon-delimited list of key/value pairs (each in turn separated by a colon) indicating styles to set.

Here’s an example of inline CSS. The words “One” and “Two” will have a background color of yellow and text color of red. The word “Three” has a new style that overrides the first, and will have a background color of green and text color of cyan. In the example, we’re applying styles to

Internal CSS

While writing an inline style is a quick way to change a single element, there’s a more efficient way to apply the same style to many elements of the page at once.

The internal CSS has its styles specified in the

The selectors shown above are extremely simple, but they can get quite complex. For example, it’s possible to apply styles only to nested elements; that is, an element that’s a child of another element.

Here’s an example where we’re specifying a style that should only be applied to div elements that are a direct child of other div elements. The result is that “Two” and “Three” will appear as red text on a yellow background, but “One” and “Four” will remain unaffected (and most likely black text on a white background).

External CSS

Learn to code for free. freeCodeCamp’s open source curriculum has helped more than 40,000 people get jobs as developers. Get started

freeCodeCamp is a donor-supported tax-exempt 501(c)(3) nonprofit organization (United States Federal Tax Identification Number: 82-0779546)

Donations to freeCodeCamp go toward our education initiatives, and help pay for servers, services, and staff.

How to Insert a CSS Comment

Including comments in your CSS code promotes effective development

pxhere.com / CC BY 0

Jennifer Kyrnin is a professional web developer who assists others in learning web design, HTML, CSS, and XML.

Every website is made up of structural, functional, and stylistic elements. Cascading Style Sheets dictate the appearance (the «look and feel») of a website. These styles are kept separate from the HTML structure to allow for ease of updating and adherence to web standards.

The Problem With Stylesheets

With the size and complexity of many websites today, stylesheets can become quite lengthy and cumbersome. This problem has grown in complexity now that media queries for responsive website styles are an essential part of design, ensuring that a website looks as it should regardless of device. Those media queries alone can add a significant number of new styles to a CSS document, making it even harder to work with. Managing this complexity is where CSS comments can become an invaluable help to website designers and developers.

Comments Add Structure and Clarity

Adding comments to a website’s CSS files organizes sections of that code for a human reader who reviews the document. It also ensures consistency when one web professional picks up where another leaves off, or when teams of people work on a site.

Well-formatted comments communicate important aspects of the stylesheet to members of a team who may not be familiar with the code. These comments are also helpful for people who have worked on the site before but haven’t recently; web designers typically work on many sites, and remembering design strategies from one to the next is difficult.

For Professionals’ Eyes Only

CSS comments are not displayed when the page renders in web browsers. Those comments are informational only, just as HTML comments are (although the syntax is different). These CSS comments do not affect the visual display of a site in any way.

Adding CSS Comments

Adding a CSS comment is quite easy. Bookend your comment with the correct opening and closing comment tags:

Begin your comment by adding /* and close it with */.

Anything that appears between these two tags is the content of the comment, visible only in the code and not rendered by the browser.

A CSS comment can take up any number of lines. Here are two examples:

Breaking out Sections

Many designers organize stylesheets in small, easily digestible chunks that are easy to scan when reading. Typically, you’ll see comments preceded and followed by series of hyphens that create large, obvious breaks in the page that are easy to see. Here is an example:

These comments indicate the start of a new section of coding.

Commenting Code

Because the comment tags tell the browser to ignore everything between them, you can use them to temporarily disable certain parts of CSS code. This trick can be handy when you’re debugging, or when adjusting webpage formatting. In fact, designers often use them to «comment out» or «turn off» areas of code to see what happens if that section is not a part of the page.

Add the opening comment tag before the code you’d like to comment out (disable); place the closing tag where you want the disabled portion to end. Nothing between those tags will affect the visual display of a site, helping you to debug the CSS to see where a problem is happening. You can then go in and fix just that glitch and then remove the comments from the code.

CSS Commenting Tips

Many coders include comment blocks at the top of any new file with code. Mimic that strategy by including a comment block with your name, relevant dates, and related information to help people understand the context of a project and not just decisions about what occurs relative to a specific code block.