Textual configuration has comments, GUIs don't.

http://machinesplusminds.blogspot.com/2011/06/textual-configuration-has-comments-guis.html

by raganwald • 15 years ago

72 25 15 years ago

machinesplusminds.blogspot.com

pohl• 15 years ago

Unless the config file uses JSON as a format. Then no comments for you!

amalcon2• 15 years ago

Ack! You're right, but why is this the case? JavaScript obviously has comments, so someone must have made the decision to deliberately leave them out.

What possible reason could there be for that?

FooBarWidget• 15 years ago

JSON is meant to be a serialization language, not a config file language. Therefore it strips out all the things that it doesn't need. If you want a config file language then use YAML which is a much better candidate.

orangecat• 15 years ago

I've done something like this:

{"height": 100, "width": 150", "__comment__": "This is a comment"}

Of course depending on the implementation details this may keep the comment string in memory. I agree JSON should have native comments, as well as optional trailing commas.

alavrik• 15 years ago

I don't think JSON as a _data interchange format_ should have comments. Key factors contributing to JSON's popularity and great practical value is simplicity and the fact that JSON is a final specification (i.e. no versioning, no extensions, no backward compatibility requirements).

Although JSON is human-readable, it wasn't specifically designed for human interaction. There are other projects and languages that address this specific topic. For example, Yaml and Piq. (Piq is the one that I'm working on as a part of the Piqi project -- http://piqi.org).

ootachi• 15 years ago

You can simulate comments this way:

{ "width": "comment goes here", "width": 50, "height": 30 }

Yes, it's a terrible hack, but it works in every JSON parser I've seen.

rauljara• 15 years ago

While I do prefer text configuration over guis, I had two thoughts that kind of run counter to his point:

1) There's nothing inherent about guis that prevents them from having a space for comments. Perhaps gui designers should consider leaving spots for comments in complex config situations.

2) A lot of the comments I see in config files are little notes about what this or that setting actually does... comments that are generally not needed in a well designed gui. But then again, I am not a sysadmin. YYMV.

burgerbrain2• 15 years ago

Comments in configuration files are approximately equivalent to those "tooltip" things GUIs sometimes have. I think comments are a much better method though since GUIs often seem to be missing their equivalent and even when present, it's a pain in the ass to use.

Someone• 15 years ago

I disagree. Comments in configuration files can serve (at least) two purposes:

- to explain what a setting does.

- to document why you chose a value for the setting.

Tooltips can do the former, but not the latter.

synnik• 15 years ago

"There is no good way to put comments into GUI."

Maybe he hasn't seen any, but this seems a harsh conclusion. Whoever wrote the GUI could track history of changes, make comments required, and show it in the GUI.

There is a vast difference between "there is no way", and "I haven't seen it done right"

bradleyland• 15 years ago

We've solved this type of problem before with a set of meta-config entries. Each field gets an entry in the meta-config table. There is a small mouse-over widget next to each config field that allows you to view/edit comments for that specific config item.

It's no where near as simple as comments in a text file, but it's more "user" friendly, where the user is someone other than a programmer.

The primary reason one builds a GUI around a configuration is for guidance. Text based configuration is great if you're accustomed to reading error messages that contain line numbers, but GUI interfaces are able to provide a lot clearer direction for visually oriented people. With a GUI, you can highlight the issues using color, weight, and even motion. You can also provide guidance for correcting the error directly next to the item with the issue.

thisrod• 15 years ago

The ultimate graphical configuration editor, Smalltalk, does all of this. It even puts text fields labelled "comment" where the user is likely to want them. Which is configurable, in case the user wants them elsewhere.

rlpb2• 15 years ago

A bigger feature missing in most GUIs is that I can't tell what has changed from the defaults. On the other hand, most text configuration files contain only what has changed from default, which is exactly what I want to know.

nodata3• 15 years ago

I would say the biggest problem with text configuration files is that you can't ever be sure what the default is.

The problem is that:

1. Config files need _visible_ defaults

2. Config files need to show current values

3. _Config files need comments_

4. Config files need to be small or they get unreadable

Doing all four is tricky. Postfix gets close:

postconf will show you all config entries. Add -d to get defaults instead. Or try -n to show settings which have been changed.

Even with Postfix you have the big file/comments problem, so what you do is refer to a copy of the original main.cf file, or one stored in the docs under /usr/share/doc/postfix for a thorough explanation of all settings and keep a bare minimum config file with comments in /etc/postfix.

rlpb2• 15 years ago

> I would say the biggest problem with text configuration files is that you can't ever be sure what the default is.

Arguably defaults are always there, whether configurable or not. Thus you cannot claim to be familiar with an application unless you know how it behaves in its default configuration (whether that is in a GUI or a text file).

I think this is fundamental and not an issue that configuration (text, GUI or otherwise) needs to deal with.

> 1. Config files need _visible_ defaults

I agree, but I don't see that this should be in the config file. I do think that there should be a way to see what these are. Your postconf example is perfect for this.

Like you, I'm in favour of keeping the bare minimum config file only. Comments should only describe something local about the site (just like "i += 1 # add one to i" is wrong). Documentation of configuration variables should be somewhere else.

rickmb• 15 years ago

The problem of making the defaults transparent has been solved a long time a go.

Standard convention for a lot of software is to have one config file (for instance often with the extension .dist) with all the default settings, and lots of comments about them, and a local config which is the one you edit.

Hoff• 15 years ago

Use whatever is appropriate and suited for your needs. GUI. Text. Front-panel register toggle switches. Wire wrap. Jumper boards. Whatever. Each of these has its adherents, of course.

A single problematic XML configuration editor is not a sufficient justification to cling to the morass that a manually-edited configuration file can provide; to paint a whole class of tools. It's probably a better justification for making improvement in the tools you're using; annoyance is a powerful motivator.

If the current configuration editor is insufficient for your needs, consider fixing it.

There are good configuration editors, and there are bad ones, and configuration file errors can run from subtle to blatant, and have definitely introduced legions of errors.

And as with most everything UI in this industry, there are trade-offs between what an experienced user needs or wants here (or the pain such a user is willing to endure, depending on your perspective) and a UI that will utterly drown a new user.

(And these days, and beyond a classic GUI configuration file editor, tossing the underlying configuration file settings into a DVCS certainly has its appeal. Consider the ability to do a git bisect on a buggy startup file, for instance. Possibly through the GUI, or at the command line. )

hollerith• 15 years ago

Loosely related: a lot of the directories on my hard drive contain comments about the directory in a file named .header, and I redefined ls to cat .header if it exists. A graphical file browser could do the same thing.

jasongullickson• 15 years ago

I myself have definitely learned more about something from reading it's configuration files than clicking through a "Wizard".

albertzeyer• 15 years ago

We at OpenLieroX actually tried to solve this for game settings. OLX is a 2D shooter-like game.

In the game settings dialog, for each setting which was changed by the user, it shows a 'reset' button next to it. Also there is a way to just show the changed settings.

You can also filter the settings by how advanced you want to go (a bit similar like in VLC but with more levels).

And when you hover one setting, there is a comment section below the dialog which describes the setting.

Textual configuration has comments, GUIs don't.

Related Stories