Hacker News new | ask | show | jobs
by wtetzner 3551 days ago
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
1 comments
shuntress 3551 days ago
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."

link
jandrese 3551 days ago
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.
link
wtetzner 3551 days ago
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.

link