

Textual configuration has comments, GUIs don't. - raganwald
http://machinesplusminds.blogspot.com/2011/06/textual-configuration-has-comments-guis.html

======
synnik
"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
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.

------
rlpb
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.

~~~
nodata
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.

~~~
rlpb
> 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.

~~~
nodata
> 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 don't agree with this part. The best way of learning about a program is to
play with it. Knowing how a program is expected to behave is key, and without
defaults you don't.

Even if someone knows the defaults, they will change.

(I agree with the rest of what you wrote)

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

~~~
orangecat
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
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>).

------
rauljara
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.

~~~
burgerbrain
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
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.

~~~
burgerbrain
Yes, I am revering to point 2 of the GP.

------
Hoff
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
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.

------
albertzeyer
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.

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

