Official Methods and Best Practices for Adding Comments to package.json

JSON Format Limitations and Comment Requirements

As the core configuration file for Node.js projects, package.json adheres to standard JSON format. The JSON specification explicitly does not support comment syntax like JavaScript's // or /* */, which presents challenges for developers needing to add configuration explanations. In practical development, comments are essential for explaining dependency purposes, version selection rationale, or special configuration intentions.

Officially Recommended Comment Methods

According to explicit statements from npm creator Isaac Schlueter on the Node.js mailing list, the "//" key is permanently reserved for comment purposes, with npm never using it for any functional用途. This approach has become the official standard for adding comments to package.json.

Single-Line Comment Implementation

Directly using the "//" key at package.json's root level enables single-line comments:

{
  "//": "This is a project configuration description comment",
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.18.0"
  }
}

Multi-Line Comment Implementation

For situations requiring more detailed explanations, array format can implement multi-line comments:

{
  "//": [
    "Line 1: Project core dependency explanations",
    "Line 2: Development environment special configurations",
    "Line 3: Production deployment considerations"
  ],
  "name": "my-project",
  "scripts": {
    "start": "node server.js"
  }
}

Important Limitations and Considerations

When using the "//" key for comments, strict adherence to placement restrictions is mandatory:

Valid Root-Level Comments

{
  "//": "Project global configuration description",
  "dependencies": {
    "react": "^18.0.0"
  }
}

Invalid Nested-Level Comments

{
  "dependencies": {
    "//": "This comment will cause parsing errors",
    "lodash": "^4.17.0"
  }
}

Using the "//" key within nested objects causes JSON parsing errors, as the JSON specification prohibits duplicate key names within objects.

Alternative Solution Analysis

Beyond the officially recommended "//" method, the community has proposed other commenting approaches, each with limitations.

Structured Comment Approach

Organizing comments through corresponding *Comments fields:

{
  "name": "package-name",
  "dependencies": {
    "ajv": "^8.0.0"
  },
  "dependenciesComments": {
    "ajv": "JSON Schema validator for API data validation"
  }
}

This method's advantage is full compliance with JSON specifications, but increases configuration structure complexity.

Risks of Key Duplication Approach

Leveraging JSON parsing behavior where later key-values override earlier ones:

{
  "devDependencies": "mocha should be globally installed, here for explanation only",
  "devDependencies": {
    "jest": "^29.0.0"
  }
}

While technically feasible, this method violates JSON best practices and may cause toolchain compatibility issues, making it unsuitable for production environments.

Tool Compatibility Considerations

When using package managers like npm, yarn, or pnpm, root-level "//" comments are properly ignored. However, some build tools or IDEs may have incomplete support for non-standard JSON features, recommending unified comment standards in team collaboration projects.

Best Practice Recommendations

Based on official recommendations and practical project experience, we suggest:

• Prioritize root-level "//" single-line or multi-line comments
• For complex configurations, consider external documentation or README files
• Establish clear comment standards in team projects to ensure consistency
• Regularly clean outdated comments to maintain configuration file conciseness

By following these practices, you can effectively enhance package.json file readability and maintainability while preserving JSON validity.