The writing method and purpose of annotations

Annotations are an indispensable part of code. While they do not affect program execution, they help developers understand code logic, maintain projects, and collaborate. HTML comments have simple syntax but versatile applications, ranging from temporarily disabling code to adding documentation.

Basic Syntax of HTML Comments

HTML comments are wrapped in <!-- and -->, and browsers completely ignore this content. Comments can be single-line or multi-line:

<!-- This is a single-line comment -->

<!-- 
  This is a multi-line comment,
  spanning multiple lines
-->

Comments cannot be nested. The following will cause errors:

<!-- 
  Outer comment
  <!-- Inner comment --> 
  This will prematurely end the outer comment
-->

Common Uses of Comments

Code Explanation & Documentation

Add comments for complex structures or special logic to clarify intent:

<!-- Main navigation bar starts -->
<nav class="main-nav">
  <ul>
    <!-- Menu items are dynamically generated via JavaScript -->
    <li id="menu-container"></li>
  </ul>
</nav>

Temporarily Disabling Code

Quickly disable code blocks during debugging without deletion:

<!--
<div class="deprecated-widget">
  This component is deprecated but kept for reference
</div>
-->

Conditional Comments (Historical Usage)

Legacy syntax for early IE browsers (now obsolete but worth knowing):

<!--[if IE 6]>
  <link rel="stylesheet" href="ie6-fixes.css">
<![endif]-->

Advanced Commenting Techniques

TODO Markers

Use keywords for easy tracking:

<!-- TODO: Optimize image lazy-loading logic -->
<div class="gallery"></div>

<!-- FIXME: Mobile layout misalignment issue -->
<section id="feature"></section>

Documentation Tool Comments

Some tools support special comment formats:

<!-- 
  @component: card
  @description: Reusable card component
  @props:
    - title: Card title
    - content: Card content
-->
<div class="card"></div>

Commenting Best Practices

Avoid Over-Commenting

Good code should be self-explanatory. Only comment when necessary:

<!-- Bad example: Redundant -->
<!-- This is a div -->
<div></div>

<!-- Good example: Explains special handling -->
<div class="text-container">
  <!-- Extra margin compensates for parent padding -->
  <p>Content</p>
</div>

Maintain Comment Relevance

Outdated comments are worse than no comments:

<!-- Legacy: Previously required for IE7 hack -->
<!-- <div class="clearfix"></div> -->

Avoid Sensitive Information

Never include sensitive data in comments:

<!-- NEVER DO THIS! -->
<!-- Admin account: admin, Password: 123456 -->

Comment Processing in Toolchains

Build tools often handle comments. For example, in webpack:

new HtmlWebpackPlugin({
  minify: {
    removeComments: true // Remove comments in production
  }
})

Comments and Accessibility

Screen readers typically skip comments, but some syntax may be read:

<!-- This comment might be read by some screen readers -->
<div aria-hidden="true">
  <!-- Content here won't be announced -->
</div>

Performance Impact

While comments don't affect rendering, excessive comments increase file size:

<!-- Thousands of legacy comments significantly bloat HTML -->
<!-- Consider removing comments in production builds -->

Team Commenting Standards

Establish unified team guidelines:

<!-- 
  TEAM-STYLE-GUIDE:
  1. Module comments use heading levels
  2. Changes marked with @modified
  3. Critical issues flagged with !
-->

<!-- !WARNING: This solution involves browser compatibility hacks -->
<div class="legacy-support"></div>

Creative Uses of Comments

Debugging Markers

Temporary markers during development:

<!-- DEBUG-POINT-1 -->
<div class="debug-border">
  <!-- Temporary border for layout inspection -->
</div>

Version Tracking

When formal version control isn't used:

<!-- VERSION 1.2.3 -->
<!-- Changelog:
  2023-01-01 Fixed login page layout
  2023-01-05 Added new API endpoint
-->

Comments and SEO

Search engines generally ignore comments, with exceptions:

<!-- Keyword stuffing won't improve SEO -->
<!-- Buy house property real estate -->

Multilingual Project Comments

Mark translation strings in i18n projects:

<!-- L10N: Button requires dynamic translation -->
<button data-i18n="welcome_button">Welcome</button>