Should default values be explicitly stated in configuration files for libraries or frameworks?

Question

In one of the projects I work for, we have just added karma to run unit tests. When reviewing the MR of a coworker, I noticed the karma.conf.js (the configuration file) has 120 lines, which seems to be a lot for me.

While reading each configuration, I noticed many of those configurations are the already default values.

Some configurations examples

//address that the server will listen on, '0.0.0.0' is default
listenAddress: '0.0.0.0',
//hostname to be used when capturing browsers, 'localhost' is default
hostname: 'localhost',
//the port where the web server will be listening, 9876 is default
port: 9876,
browserDisconnectTimeout: 5000,
//how long will Karma wait for a message from a browser before disconnecting from it, 10000 is default
browserNoActivityTimeout: 10000,
// timeout for capturing a browser, 60000 is default
captureTimeout: 60000,

and there are few more. The config file is about 120 lines, but removing default settings it will be less than 70 lines (and more if we remove comments)

Is it a good practice, in general, to explicitly write down the default values? Or is it preferrable to only state what's not changed and rely on defaults? (That might change in the future)

I feel the second way is more declarative (we only configure what needs to be configured)

Note The karma thing is just an example, it can be applied to other configurations of other libraries that require so

Answer 1

Ultimately I think this might be opinion based, but given that you are using a specific framework (Karma) and this framework has documentation, it is fine to omit default values.

An exception would be if those default values get overridden in different build or deployment configurations. If the default is overridden by a different build config, I would still put them in the config file with a comment that other build configurations override this default setting.

It's also not a bad idea to put a URL to the documentation for the configs as a comment at the top of the file.

So my guidelines are:

1. Put a comment at the top of the file pointing developers to the official documentation:

   # Documentation for Karma configs: http://example.com/karma
   

2. Include default values if they are overridden by other build or deployment configurations

   # Default value is below, but is overridden on CI server
   listenAddress: '0.0.0.0'
   

3. Omit default values if they never change when running the tests locally or on build servers. Developers should RTFM if they want to change things further.

4. If someone already wrote the code, is it really worth it to remove the code? After all, it is just a config file.

Answer 2

I wouldn't say its good practice either way, but I would love this config file as everything is written out for me and clearly commented.

Sure its a pain as a user to have to specify every single value. If its a command line application it may be next to impossible!

But if someone else has written it all out for you in advance then its super easy to see all the options and what they do.

One futher point to note is that if you are replacing config values via an automated deployment, it can be easier to have the default setting present. As you can always replace and not have to worry about adding OR replacing