您HTML和CSS注释有多好？

待我称王封你为后i 2022-12-03 01:52 96阅读 0赞

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.

当您开始学习基本HTML或CSS时，通常会学习的一件事就是如何在代码中编写注释。 但是，许多Web开发人员仍然没有使用注释来发挥自己的优势。 我们可能会在HTML和CSS中广泛使用注释，但是如果正确编写并有意使用注释，它们实际上可以改善我们的工作流程。

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**)** ##

1.  Comments are ignored by the browser.
    
    浏览器将忽略注释。
2.  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.

**评论可以帮助很多人。** 他们不仅可以帮助自己，而且可以帮助团队中的其他人。 在人们的源代码中看到诸如“ `DO NOT STEAL MY CODE`类的注释的日子已经一去不复返了。 虽然我们过去一直非常保护我们的代码，而不希望共享我们的“秘密”，但我们现在生活在一个人们共享代码，共同致力于项目和进行协作的世界中。 当涉及到Web项目时，我们不以Harry Harrys，Chris Coyier或Jonathan Snook之类的人为荣。 随着协作的转变，我们还应该注意我们的评论做法，并为我们的同行提供帮助。

## 评论时要避免的一些事情 **(**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:

我个人对在CSS中写一些较长的注释感到内，因为我喜欢解释和记录文档。 但是，您不应该写小说-长篇评论很难读，也很难写。 如果可以简洁，请这样做。 有时，在命名CSS类时，会给出以下建议：

*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:

我曾经在我正在处理的项目中看到一个文件，该文件的顶部显示一行：

// Update this with how many hours you have spent on this file:
    // TIME_WASTED = 438;

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.

此示例显示了一个伪元素，其中填充了`content`值。

.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;
    }

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.

可能尚不清楚伪元素的用途，尤其是当content属性显示为`content: ''` 。 在代码块上方加一个简短的注释，我们可以改善这一点。

/* 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;
    }

### 解释嵌套代码块 **(**To Explain a Nested Code Block**)** ###

While it definitely helps to use semantic classes as much as possible, it may not always be clear why a block of CSS would be nested when using a preprocessor:

尽管绝对有助于尽可能多地使用语义类，但可能并不总是很清楚为什么使用预处理器时会嵌套CSS块：

.c-segment-controls.is-active {
      .c-segment-controls__panel {
        background-color: #fafafa;
        border: 1px solid #aaa;
        opacity: 1;
        transition: opacity 0.5s ease;
      }
    }

Six words is enough for a comment to indicate what this code block does, allowing someone to be able to skim the document and either stop or skip ahead.

注释足以说明该代码块的功能，所以六个字就足够了，从而使某人能够浏览文档并停止或向前跳过。

.c-segment-controls.is-active {
    
      /* Active state for segment controls panel */
    
      .c-segment-controls__panel {
        background-color: #fafafa;
        border: 1px solid #aaa;
        opacity: 1;
        transition: opacity 0.5s ease;
      }
    }

### 解释为什么`!important`可能需要 **(**To Explain Why `!important` Might Be Needed**)** ###

We often see `!important` and assume we are looking at legacy code or a dirty hack:

我们经常看到`!important`并假设我们正在查看旧版代码或肮脏的hack：

.c-accordion-container.ng-hide {
      display: block !important;
    }

Upon closer inspection, we’re just overriding a framework’s default behavior.

经过仔细检查，我们只是覆盖了框架的默认行为。

/**
     * Overriding some rogue Angular code.
     * Forces `display: block` so that the element can be animated.
     */
    
    .c-accordion-container.ng-hide {
      display: block !important;
    }

### 解释为什么代码块被注释掉而不是简单删除 **(**To Explain Why a Code Block Was Commented out Rather Than Simply Deleted**)** ###

If we look at the code block below, we might assume deleting this is fine. Surely it isn’t being used anywhere? If I delete it, it will be in version control anyway when we need it later, right?

如果我们看下面的代码块，我们可能会认为删除它是可以的。 当然不会在任何地方使用它吗？ 如果我删除了它，那么以后需要它时，它将在版本控制中，对吗？

// .c-segmented-button__icon {
    //   transform: translateY(calc((40px - 100%)/2));
    // }

But if we delete it, someone might not even know it existed in the first place. It might be a good idea to leave this here:

但是，如果我们将其删除，则可能甚至根本不知道它的存在。 将其保留在此处可能是一个好主意：

/**
     * Calculation for vertical alignment.
     * Can be used when IE11 support is dropped.
     */
    
    // .c-segmented-button__icon {
    //   transform: translateY(calc((40px - 100%)/2));
    // }

## 其他种类的文件 **(**Other Kinds of Documentation**)** ##

Documentation is really important and not just limited to comments in code. When we are done with a task, we might get it peer reviewed.

文档非常重要，而不仅限于代码中的注释。 当我们完成一项任务时，我们可能会对其进行同行评审。

### 提交讯息 **(**Commit Messages**)** ###

When using version control (for example, Git), we can take what we know about writing useful comments in code and apply this to our commit messages.

当使用版本控制(例如，Git)时，我们可以掌握在代码中编写有用注释的知识，并将其应用于我们的提交消息。

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

错误的提交消息不会提供太多上下文。 它们看起来很草率，很难理解。 它们对发行说明没有帮助。 开发人员可能很难知道发生了什么变化。 错误的提交消息通常看起来像这样。

commit 2faa2
        wip
    commit 591ad
        tried to fix some weird box
    commit af830
        made the triangle thing work
    commit bd02a
        refactor
    commit bed4b
        hotfix navigation
    commit 22fe0
        oops

A better example would describe, using a verb, the task completed in a commit. Different minor tasks would be spread out across different commits.

一个更好的示例将使用动词描述一次提交中完成的任务。 不同的次要任务将分散在不同的提交中。

commit 2faa2
        Adding form component housing
    commit 591ad
        Fixing box-sizing issue
    commit af830
        Implementing triangle for notification bubble
    commit bd02a
        Refactoring list item for smaller viewports
    commit bed4b
        Fixing navigation float issue
    commit 22fe0
        Fixing typos in class names

[Karma][] has a pretty simple guide to writing better commits, whereas Chris Beams has a [very in-depth guide][]. David Demaree even wrote an article titled [‘The Art of the Commit’][The Art of the Commit]. Commit messages definitely deserve some attention.

[Karma][]有一个非常简单的指南来编写更好的提交，而Chris Beams有一个[非常深入的指南][very in-depth guide] 。 David Demaree甚至写了一篇题为[“提交的艺术”][The Art of the Commit]的文章。 提交消息绝对值得关注。

### 拉取请求 **(**Pull Requests**)** ###

After writing a handful of commits, you usually create a pull request for one of your peers to look at. I’ve seen one too many pull requests that have very little detail or no description at all:

编写少量提交后，通常会创建一个拉取请求，供您的一个同行查看。 我已经看到太多的拉取请求，这些请求很少有细节或根本没有描述：

![An example of a poorly written pull request][]

When you are writing a pull request you are usually expecting someone to review your code. To assist that person and help ease the process, you should write a description of what the pull request includes. This is my mental checklist:

在编写请求请求时，通常希望有人检查您的代码。 为了帮助该人并帮助简化该过程，您应该编写关于拉取请求包括的内容的描述。 这是我的心理检查清单：

*  Ticket number, task number or issue number
    
    工单号，任务号或发行号
 *  Mention the task in a few words
    
    用几句话提到任务
 *  Mention what types of files I changed
    
    提及我更改了哪种文件类型
 *  If it was a bug, mention what the bug was like before and after the changes
    
    如果是错误，请说明更改前后的错误状态
 *  Describe the expected behaviour after the changes (Should it be the same?)
    
    描述更改后的预期行为(是否相同？)
 *  List any steps that need to be taken to check the changes, either in-browser or in the code
    
    在浏览器内或代码中列出检查更改所需采取的所有步骤
 *  Note anything that should be ignored, for example a bug addressed in another branch
    
    注意任何应忽略的内容，例如另一个分支中解决的错误
 *  Include screenshots of the interface as necessary
    
    包括必要的界面截图

This example is relatively simple, and you definitely don’t have to include everything in the above list if it is not necessary:

此示例相对简单，如果没有必要，您绝对不必在上面的列表中包括所有内容：

![An example of a pull request with enough, but not too much, detail][An example of a pull request with enough_ but not too much_ detail]

## 结论 **(**Conclusion**)** ##

Although I have provided some examples of where to include comments and some suggestions on what to avoid, there are no hard and fast rules about how to format comments in your code. The number of lines, words, or what information to include is up to you, or can be decided between you and your peers. As long as you keep the format consistent, it will keep things tidy and encourage other people working with the code to do the same.

尽管我提供了一些在何处包括注释的示例以及关于应避免的一些建议，但是对于如何在代码中设置注释格式没有硬性规定。 行数，单词数或要包含的信息取决于您，或者可以由您和您的同伴决定。 只要您保持格式一致，就可以使事情保持整洁，并鼓励使用该代码的其他人也这样做。

There are many benefits associated with making comments a part of your development process. It’s good to get into the habit of including them where you see fit, especially when you have many people working on the same files. It also helps to consider other forms of documentation that are embedded in workflows – such as commit messages and pull requests – and not simply an external document of guidelines.

将注释作为开发过程的一部分有很多好处。 养成将它们包括在您认为合适的地方的习惯，这是很好的，尤其是当您有很多人在处理同一文件时。 它还有助于考虑工作流中嵌入的其他形式的文档(例如，提交消息和请求请求)，而不仅仅是准则的外部文档。

**Do you follow any guidelines for commenting code? Or maybe you work in a company that has an different but effective kind of documentation?**

**您是否遵守任何注释代码的准则？** **还是您在一家拥有不同但有效的文档类型的公司工作？**

> 翻译自: [https://www.sitepoint.com/how-good-are-your-html-and-css-comments/][https_www.sitepoint.com_how-good-are-your-html-and-css-comments]

[Karma]: https://karma-runner.github.io/0.13/dev/git-commit-msg.html
[very in-depth guide]: http://chris.beams.io/posts/git-commit/
[The Art of the Commit]: http://alistapart.com/article/the-art-of-the-commit
[An example of a poorly written pull request]: /images/20221123/c35eb3b38f6e4217949ce4c0a5f97036.png
[An example of a pull request with enough_ but not too much_ detail]: /images/20221123/1c868e04298a4ca1b1e7d0c2ec021231.png
[https_www.sitepoint.com_how-good-are-your-html-and-css-comments]: https://www.sitepoint.com/how-good-are-your-html-and-css-comments/