[Matthias247]

The single fact that JSON doesn't support comments makes it pretty bad choice for configuration files, where you often want to document why a specific value was chosen for a setting.

Yes - I know that some JSON parsers will allow comments and strip them, but IMHO you shouldn't rely on this, and lots of editors will complain if they encounter any non-standard JSON.

[jdc0589]

this is my single largest complaint about JSON... I NEED comments.

[shuntress]

I think the idea is that the format lends itself towards being human readable.

If the names/values are chosen well their purpose will be self evident.

[whatusername]

Names/values can tell you the what. Comments can tell you the why.

[shuntress]

These aren't dip-switches. Description of the logic behind the configuration settings doesn't need to be embedded into the config file. It can be in the manual.

[wtetzner]

I think you're still missing the point. It's not the description of the logic behind them.

Comments are useful for conveying why a particular value was chosen in this particular config file by some person. For example:

    # This is temporarily disabled until TICKET-432 is fixed.
    # It should then be turned back on.
    feature-that-should-usually-be-enabled: false

[shuntress]

Agreed this is helpful when reverse engineering something you don't have documentation for.

But, this is still information that shouldn't be embedded in the config file.

TICKET-432 should say "feature-that-should-usually-be-enabled is set to false while this issue is active. When this is fixed, set it back to true."

[jandrese]

That's just asking for the temporary fix to never be reverted because the guy who closed the ticket out didn't read it carefully enough. Or the ticket is marked as "fixed" because the workaround works and it has been open for too long. Keep the documentation next to the fix and someone may eventually find it again. Keep it apart and it can be lost forever.

[wtetzner]

Yes, the ticket should say that. However, if TICKET-432 is still open, and someone from SysOps comes along to make a change to that config file, how would they know that they shouldn't turn on feature-that-should-usually-be-enabled?

They could read through every open ticket to check, but they're only human, and things can be overlooked. If the comment lives right next to option, it's much harder to miss.

[wtetzner]

> If the names/values are chosen well their purpose will be self evident.

I don't see how. If I pick a particular value for a config setting, it's obvious what value was chosen, but there's nothing to suggest why that value was chosen.

[jamespo]

This reminds me of a a terrible programmer I knew when asked why he had no comments in his code: "inspection of the code should be sufficient".

Not for your code it wasn't.

[jandrese]

It takes many years for people to figure out what the right level of commenting is. It's more of an art than a science. Worse, the level of comments depends on the reader. An old veteran may find one distracting that a beginner finds extremely helpful. But they can also be a liability if they aren't maintained with the code or if they make statements about other code that fails to be true after awhile.

A comment like:

# Add 1 to the length of this buffer to work around an off by 1 error in this function in library foo

Can quickly go stale, but sometimes not and could otherwise be accidentally reverted by someone who notices that the buffer is 1 element too long for no apparent reason.

A better comment:

# Add 1 to the length of this buffer to work around an off by 1 error in function foo from library bar (version 1.7.3b circa Nov 1997)