The common garden variety configuration file is generally terrible; hard to write, hard to read, and hard to use. That's because they've generally been designed wrong, with the wrong purpose.

Much like programming languages, very few people create configuration systems with the goal of communicating with both the program and other people; instead they are almost always aimed just towards communicating with the program. When you are just communicating with the program, all sorts of things can be implicit, cryptic, and focused on the mechanics of what the program needs to do.

But this leaves you with the problem of assembler language. Although you're describing precisely what the program should do, you're not describing why it does these things or even what they are; you can't, because there is no mechanism for it (except comments, and we all know the problems with them). In addition to readability for other people (including your future self), leaving off the higher level logic of what is going on leaves you open to various issues.

In short: configuration files need to be designed for people to read, not just for programs to parse and use.

(This is very similar to some modern attitudes on programming language design, where a good part of the purpose of a language is to enable clear communication of your intentions with other developers, not just instructing the computer on what code to execute.)

This problem can't be solved by slapping some generic high-level features into your configuration system and calling it done, or by making your program be configured through a full general purpose programming language. Good configuration systems are program specific, because they start from a high level description of what you're doing and then figure out how to write that out clearly in a way that the program can use too.

(You can and should include low-level features in your configuration system; sometimes they'll be needed. But they should not be routine, any more than people should routinely be dropping to assembler in a good programming language.)

This is hard work, and worse it is hard UI work. But doing it right is important. For programs complex enough to need them, configuration files are not an afterthought, they are an integral part of how people use your software. Treating them as an afterthought where you don't have to care about readability or anything short of what's easiest for the program is an abrogation of your design responsibilities.

(This is an expansion of a paragraph from this entry, because sometimes I have insights in passing that deserve to be expanded to full entries.)