Best Practices for Software Configuration Design

Most software needs a configuration. Either because clients must set up their connections with other software (e.g. a database connection or an email account) or because the software has to be adapted to the clients environment (e.g. paths for the file system) or because the functionality of the software needs adaptions (e.g. enabling plugins or changing the layout).

In the most cases, software configuration is either modified after an installation or upgrade or after an incident.
Desktop applications often have a UI for the configuration. Expert systems often need to be configured directly.

What can go wrong?

There are many reasons, why a software configuration can get invalid. Some typical examples:

The client makes a syntactic mistake in a configuration file: this has often the consequence that the software can’t start and even fails with a cryptic error message.

Client makes a typo: e.g. instead of “100” he sets the value “1000” for a configuration parameter. This can have fatal consequences. It could break the running server or controlled machines because it requests too many resources. It could cost the client lot of money because the software calculates with wrong dimensions.

Client sets up an inconsistent configuration: this can result is wrong behavior or crashes of the software.

The single pattern for all software configuration does not exist

You must decide which approach fits your software best. Every design has pros and cons and no design fits best in all situations.

An appealing UI

Provide the client the possibility to setup his software via an UI. The advantage is that you control the storage and prevent syntactical errors. With validations you can prevent wrong settings or warn the user.

Configuration UIs are often seen in smaller and widespread software. Whereas expert systems with few clients rarely have configuration UIs. This is because expert systems need huge and regularly changing configuration setups. Also, for expert systems clients often have security and quality guidelines that require processes where a simple UI can’t be used. And of course, it is also a question of money if your clients are willing to pay for a configuration UI or not.

The configuration file format

When you think about the ideal file format, you should keep these points in mind:
• Will you provide a configuration UI? If not, consider that your client’s IT needs to write directly into the file. Readability is here more important than other quality attributes.
• Does your programming language provide a framework for the file format? Which format is best integrated into the language?
• How complex configuration structures do you need? Is a simple file format more suitable or one that has more overhead but better structuring?
• Is the format well known and accepted in your industrial sector?
• Do your clients use a version control system? Does your format allow them to see modifications easily?

XML and JSON are modern and very popular file formats for configuration files. But they are also used for data exchange. We should not mix these two usages. While JSON should be preferred for automated API transfers, the usage of JSON as configuration format has some downsides. When you have no configuration UI, you should prefer XML as configuration file format, as XML is in general more readable.

ReadabilityIncludes more metadata and makes the configuration more self-explainableMore efficient storage on the cost of readability
CommentsAllows to add comments for explanation, examples or simple historizationNo standard for comments is defined
ValidationAllows the usage of syntax verification with document type definitions (DTD)There exist tools, but no standard


Consider these qualities for any file format decision.

The configuration design strategy

There are two approaches for configuration design: the infrastructure centric approach and the user centric approach.

Developers tend to the first approach. The idea behind is that in the development phase it is impossible to predict all needs of the clients. To prevent any blocking future issues, they prefer to make as much as possible software parameter externally configurable. The downside of this is, that the configuration gets huge and unreadable. Most of the settings will never be modified and it is either harder to modify source code or configuration formats must change frequently. But the worst disadvantage is that settings that belong together are often placed in different sections in the configuration, making the risk of misconfiguration higher.

The user centric approach tries to reduce the amount of configuration parameters. When possible, different profiles are provided. Expert settings are optional extra settings. Ideally, the development team works while design together with the client.

Especially in complex expert systems a certain complexity is not avoidable and while designing the developers must find compromises, but the two strategies and their pros and cons should be always kept in mind.

Configuration as part of software rollout

We have to be honest: nobody reads installation guides and user manuals before installing a software. We expect the software to just run immediately after installation. Also, when this is not realistic, your software should be ideally able to do so. Try to provide an initial configuration that needs as less as possible adaptions. Often this is not possible because the configuration must fit the client’s environment. A help could be dynamic default settings. For example, the default setting of maximum used threads could be the number of cores.

When possible, provide the client a minimal installation wizard that navigates him through the necessary settings so that the software can start. Fine-grained adaptions and tunings can be defined at a later time.

Provide your clients always a simple to read user manual that is written in a user specific view. Think in use cases!

Configuration as part of incident handling

Sometimes we are in the unpleasant situation of a software incident. The client has to react fast and eventually revert things. The software should be able to assist the user to detect the error reason, avoid the error, resume the work, port to another system.

The solution is specific to the software, but we can find some general practices:
• Provide settings to enable extra logging in critical components.
• Design your software configuration in a way that its easily portable to other hardware.

Summary: The one and only configuration pattern does not exist. But by keeping some concepts in mind and thinking about the clients and the future usage of your software can make your software easier to use and more stable.

How useful was this post?

Click on a star to rate it!

Average rating 0 / 5. Vote count: 0

No votes so far! Be the first to rate this post.

We are sorry that this post was not useful for you!

Let us improve this post!

Tell us how we can improve this post?