Preserving Comments When Converting Properties to JSON

Comment Preservation

Comments in .properties files (lines starting with # or !) contain valuable documentation: section headers, author notes, deprecation warnings, and configuration instructions. The comment preservation feature captures these in the JSON output.

Example with Rich Comments

# ===========================================
# Application Configuration
# Author: DevOps Team
# Last Updated: 2024-12-01
# ===========================================

# Server settings
server.port=8080
server.host=0.0.0.0

! WARNING: Do not change in production
! without approval from the security team
server.ssl.enabled=true
server.ssl.key-store=/etc/ssl/keystore.jks

# Database Configuration
# See: https://wiki.internal/db-setup
spring.datasource.url=jdbc:postgresql://db:5432/app
spring.datasource.pool-size=10

JSON Output (Comments Preserved)

{
  "_comments": [
    "# ===========================================",
    "# Application Configuration",
    "# Author: DevOps Team",
    "# Last Updated: 2024-12-01",
    "# ===========================================",
    "# Server settings",
    "! WARNING: Do not change in production",
    "! without approval from the security team",
    "# Database Configuration",
    "# See: https://wiki.internal/db-setup"
  ],
  "server": {
    "port": 8080,
    "host": "0.0.0.0",
    "ssl": {
      "enabled": true,
      "keyStore": "/etc/ssl/keystore.jks"
    }
  },
  "spring": {
    "datasource": {
      "url": "jdbc:postgresql://db:5432/app",
      "poolSize": 10
    }
  }
}

When to Use Comment Preservation

• Documentation generation: Extract comments as documentation alongside configuration
• Audit trails: Preserve author and timestamp annotations
• Migration: Keep warning comments visible during format migration
• Code review: Include configuration comments in JSON-based review tools

Note: Comment positions relative to specific keys are not preserved (all comments are collected into a single _comments array). For position-aware comment handling, consider keeping the original .properties file as the source of truth.