Complete Guide to Code Commenting in Vue.js Files: From Basic Syntax to Best Practices

Basic Vue.js Comment Syntax

During Vue.js development, code comments are essential for improving readability and maintainability. According to the best answer from the Q&A data, standard HTML comment syntax should be used within the <template> tag: <!-- Comment content -->.

This commenting approach is not only syntactically correct but also automatically removed during final rendering, ensuring no impact on page performance. Let's illustrate this with a concrete example:

<template>
    <div class="media">
        <!-- This is a comment about conditional rendering of the like button -->
        <like-button :post="post" v-if="post.likedByCurrentUser === false && post.canBeLikedByCurrentUser === true"></like-button>
        
        <div class="media-left">
            <a href="#">
                <!-- User avatar display with Gravatar source explanation -->
                <img class="media-object" v-bind:src="post.user.avatar" v-bind:title="post.user.name + ' image from Gravatar'">
            </a>
        </div>
    </div>
</template>

Comment Methods in Different Sections

Vue.js single-file components consist of three main sections, each with corresponding comment syntax:

Template Section Comments

As mentioned earlier, the template section must use HTML comments. A common mistake developers make is attempting to use JavaScript's // or /* */ syntax, which are invalid in HTML environments.

Script Section Comments

Within the <script> tag, standard JavaScript comments can be used:

<script>
// Single-line comment: User data initialization
/*
 * Multi-line comment:
 * Handles user like logic
 * Includes permission verification and status updates
 */
export default {
    data() {
        return {
            post: {}
        }
    }
}
</script>

Style Section Comments

Within the <style> tag, use CSS comment syntax:

<style>
/* Basic media object styles */
.media {
    display: flex;
    align-items: flex-start;
}

/*
 * Responsive design
 * Mobile adaptation rules
 */
@media (max-width: 768px) {
    .media {
        flex-direction: column;
    }
}
</style>

ESLint Comment Format Standards

The reference article provides ESLint rule configurations for HTML comment formatting. Through the vue/html-comment-content-newline rule, comment styles can be unified across teams:

{
    "vue/html-comment-content-newline": ["error", {
        "singleline": "always",
        "multiline": "always"
    }]
}

This rule supports the following configuration options:

• singleline: Controls line breaks for single-line comments (always/never/ignore)
• multiline: Controls line breaks for multi-line comments (always/never/ignore)
• exceptions: Defines exception cases, such as documentation comments

Practical Application Scenarios

In actual development, comments should serve specific purposes:

Conditional Rendering Explanations

<!-- Conditions for showing like button: user hasn't liked and has permission to like -->
<like-button v-if="!post.likedByCurrentUser && post.canBeLikedByCurrentUser"></like-button>

Complex Logic Clarification

<!-- 
 * User avatar display logic:
 * 1. Priority to uploaded avatar
 * 2. Fallback to Gravatar default
 * 3. Final fallback to system default
 -->
<img :src="getUserAvatar(post.user)">

TODO Markers

<!-- TODO: Add image lazy loading functionality -->
<!-- FIXME: Mobile layout needs optimization -->

Best Practice Recommendations

Based on Q&A data and practical development experience, we summarize the following best practices:

1. Keep comments concise and clear: Comments should explain why something is done, not repeat what the code is doing
2. Update comments promptly: When code is modified, corresponding comments should be updated
3. Avoid excessive commenting: Clear code often requires minimal comments
4. Use consistent comment styles: Ensure team consistency through ESLint rules
5. Distinguish between temporary and permanent comments: Temporary comments should be cleaned up promptly

By properly using comments, you can significantly improve the maintainability of Vue.js projects and team collaboration efficiency. Remember, good comments are important documentation for your future self and other developers.