Comment by Yarnage | Hacker News Reader

Comment by Yarnage | Hacker News Reader

Parent Full thread

>It's fairly common to annotate that data. While every entry in my postgresql.conf file is documented someplace, it'd be an absolute nightmare if defaults couldn't be commented inline or if I couldn't relay why a value is set to a particular value by adding a comment.

What happens when you accidentally delete a value you didn't mean to? You would refer to documentation. Honestly all configuration files _should_ be well documented, including postgres so I don't see the issue here. Why would you want to include every single possible option, probably commented out, when you could simply grab the ones you need from the documentation? I would prefer having a lean configuration file that shows exactly what I'm using rather than 400 commented options; that's a MESS to maintain.

>Even still, it can be handy to exchange annotated data over the wire.

I cannot disagree more. It is not useful AT ALL to exchange annotated data. Unless you're using an ad-hoc system (which obviously wouldn't scale), you're going to be handling this through APIs and services that already know and understand the JSON file format. So the only purpose of comments at this stage in the game is using up extra bandwidth.

> You would refer to documentation.

Right, but what if you want to document why you personally are using a particular option, rather than just what an option does? I agree that a lot of the time config comments are unnecessary, but they do have a place.

That is something that MUST exist in documentation. If you're putting it within the configuration file itself it can go stale or simply deleted one day and you would have no idea what occurred after the fact without looking at a revision history.

I'm a bit puzzled by documentation seems like a bad word around here; it has its place and I'm not suggesting writing up a huge document. It takes only a couple of minutes to drop some text in Word / Google Docs / Wiki / your flavor and put it someplace accessible for your entire team.

I'm not refuting the value of documentation, I'm just acknowledging the referential integrity issues with it. All too frequently I've encountered cases where a config file gets updated but the wiki doesn't. Since all configuration files are version-controlled, I never run into a situation where a file changes and I don't know why (well, discounting bad commit messages). But, a documented wiki wouldn't help in that case anyway. A comment is documentation too ...

Documentation isn't a bad word - I regularly make documents to describe the architecture of my projects, along with their an outline of how to get into the codebase, for example. Comments are also documentation, though, and in this case comments are the right place. If I'm looking at a configuration option and thinking 'That seems a bit odd. Why do we have that set?' I want to be able to see the reasoning right there, not have to hunt through a wiki in the hope that someone has put their reasoning somewhere.

In my experience, comments are less likely to go stale than wiki docs.

I didn't say include every possible option. But it sure is handy when I modify one and there's a nice comment telling me "hey, if you change this, you absolutely must go change this other value too, otherwise all hell is going to break loose." I'm much more apt to screw up the config if I have to look that up every time. That aside, it's really helpful to communicate to other people on the team that "this value is 768 MB because that's roughly 1/2 the total memory on this machine."

Re: transmitting annotated data. All I can say is not every application of JSON is for APIs for mobile devices. When I have a connected gigabit network and gzip data, I may not be that concerned about an extra 50 bytes of annotated data. But, again, that even presupposes that its only application is for computer-to-computer communication. The value in comments are human-to-human.

>I'm much more apt to screw up the config if I have to look that up every time. That aside, it's really helpful to communicate to other people on the team that "this value is 768 MB because that's roughly 1/2 the total memory on this machine."

JSON comments would be a short-cut, sure, but that information should be within reach and should NOT only exist within the JSON anyway. So the helpfulness seems really limiting here.

>Re: transmitting annotated data. All I can say is not every application of JSON is for APIs for mobile devices. When I have a connected gigabit network and gzip data, I may not be that concerned about an extra 50 bytes of annotated data. But, again, that even presupposes that its only application is for computer-to-computer communication. The value in comments are human-to-human.

You're right in that the value for comments are human to human; I just cannot picture a scenario where you're actually transmitting data over the wire and including comments. I am not limiting this to mobile device; any service end point should ignore any comments and they will never be seen anyway.

As I mentioned before, if you're ingesting files in a very ad-hoc manner then of course comments could be useful but that's not a typical use-case of JSON. JSON is typically used as an interchange format for end point to end point communication and comments in ANY type of file in that scenario are useless.

Reply on news.ycombinator.com