• Cartoon showing how convention simplifies understanding. Source: Geek & Poke 2008.
• Examples of CoC in Ruby on Rails. Source: Krzywda 2020.
• Some benefits of CoC. Source: Văn 2014, 1:26.

# Convention over Configuration

kkris
757 DevCoins

arvindpdmn
11 DevCoins
Last updated by kkris
on 2020-07-18 06:16:31
Created by kkris
on 2020-07-15 15:23:33

## Summary

It's often necessary to configure a software project correctly before it can be used. For example, the IDE or the build tool should know where to find the source files. It should know where to look for dependencies or save the output of a build. In web applications, it should know how to connect URL paths to application logic, and database tables and columns.

In a configuration approach, all this information is supplied via configuration files, often as XML/YAML/JSON files. However, writing and maintaining these files can be tedious. In a convention approach, reasonable defaults are used. The conventions are well defined. Once developers learn and use these conventions, they can focus on more important tasks instead of maintaining configuration files.

Many frameworks have adopted Convention over Configuration (CoC) while also giving developers means to override the defaults.

## Milestones

2005

First version of Ruby on Rails is released. Convention over configuration is one of the pillars of Ruby on Rails. It brings "default structures for web pages, databases, and web services". Inspired by this, Sensio Framework is launched as a PHP MVC framework that adopts CoC. This is later renamed to Symfony.

May
2006

Enterprise JavaBeans (EJB) 3.0 is released. To overcome the complexity of earlier releases, EJB 3.0 adopts CoC by way of annotations.

2009

Microsoft releases the first version of ASP.NET MVC. Although ASP.NET itself started in 2002 and the MVC pattern was common by 2003, ASP.NET MVC formalizes it. ASP.NET MVC adopts CoC, taking inspiration from Ruby on Rails. It's in response to declarative XML configuration that's being overused.

May
2010

Jimmy Bogard releases v1.0 of AutoMapper that's described as "a convention-based object-object mapper in .NET".

## Discussion

• Could you explain convention over configuration with some examples?

In ASP.NET MVC, the convention is to have the folders Controllers, Models and Views. Accessing the homepage routes to HomeController class in file Controllers/HomeController.cs where the Index() method is called. This method returns a view that's in file Views/Home/Index.cshtml. All this "magic" happens due to conventions on folder structure and naming. No configuration files are needed to tell the framework how all these parts are "wired together".

In a Java project built with Gradle, with a single line of code we can apply the Java plugin to this project. Gradle then automatically looks for source code in /src/main/java. It creates a /build folder where the compiled class and JAR files are saved. This is all by convention. We don't have to tell Gradle these mundane details via configuration files.

In pytest, a Python-based test framework, test cases are automatically discovered. The framework looks at the current directory for test_*.py or *_test.py files. In those files, it picks out functions or methods with prefix test. For methods, it picks out classes with prefix Test.

• In what aspects of software is convention over configuration applicable?

In Ruby on Rails, CoC can be seen in many areas within its Model-View-Controller architecture. Model class names are derived from database table names. Class attributes are based on database column names. View filenames and templates are based on controller action names. A web URL is mapped to controller class by CoC.

Many other design patterns benefit from CoC. By implementing an ASP.NET interface according to a defined convention, we can easily create a message handler without any further configuration. To support dependency injection, many frameworks adopt CoC to greatly simplify wiring of dependencies.

Build systems such as Maven make use of CoC. For example, paths to source code, resources, tests and many others are specified by defaults. Maven's core plugins also apply defaults for "compiling source code, packaging distributions, generating web sites, and many other processes".

API endpoints designed by different developers can look and behave differently. By adopting CoC, APIs become more standardized and simpler to use. JSON-API is an example that specifies shared conventions.

In test frameworks such as pytest, conventions are used to discover test cases.

• What are the benefits of convention over configuration?

CoC frees developers from making mundane decisions, such as whether to name a database column id, postId, posts_id or pid. Developers can focus on application logic or develop deeper abstractions. CoC makes it easier for beginners to get productive without having to read a lot of the existing codebase. It's easier to collaborate since developers follow the same conventions.

When applied to design patterns (such as dependency injection), CoC makes code less verbose, more readable, and more maintainable. Code that does only "housekeeping" can be eliminated. Ultimately, CoC lets developers focus on delivering functionality rather than deal with low-level infrastructure.

Often adding new functionality is easier. There's no need to update configuration files. Conventions either at the language level or framework level take care of the "wiring".

The CoC philosophy can be extended to engineering disciplines. An example is model-driven engineering (MDE). The idea is to abstract away low-level details so that developers can focus on higher-level design and implementation decisions. Code generators can use conventions to generate low-level code.

• Which are some frameworks that adopt convention over configuration?

Among MVC web frameworks that adopt CoC are Ruby of Rails, ASP.NET MVC, CakePHP, Laravel, Symfony, Yii, Grails, Ember.js, Meteor, Nest.js, and Spring Framework.

Among build systems using CoC are Maven and Gradle.

• What are some criticisms of convention over configuration?

Frameworks that adopted CoC are called opinionated. One common criticism is that you're forced to follow a convention you may not like. However, frameworks often allow developers to customize.

Too much convention leads to confusion and a steeper learning curve. Too little convention gives more freedom but at the cost of complexity. The key is therefore to achieve the right level of convention.

Unless you know the framework well, reviewing other people's code is harder; and searching through files won't help. For example, finding out how a URL maps to a controller or a view can be challenging. For beginners, the code may not be obvious. As a solution, it's better to limit CoC to conventions that are commonly understood and frequently used. If you override conventions, document them explicitly.

CoC can lead to unexpected behaviour. For example, ASP.NET finds classes inherited from a base Controller class. If the project references an assembly that has controllers, we may unknowingly expose those endpoints. This is one instance why some prefer explicit configuration, such as in Python and Django.

## Milestones

2005

First version of Ruby on Rails is released. Convention over configuration is one of the pillars of Ruby on Rails. It brings "default structures for web pages, databases, and web services". Inspired by this, Sensio Framework is launched as a PHP MVC framework that adopts CoC. This is later renamed to Symfony.

May
2006

Enterprise JavaBeans (EJB) 3.0 is released. To overcome the complexity of earlier releases, EJB 3.0 adopts CoC by way of annotations.

2009

Microsoft releases the first version of ASP.NET MVC. Although ASP.NET itself started in 2002 and the MVC pattern was common by 2003, ASP.NET MVC formalizes it. ASP.NET MVC adopts CoC, taking inspiration from Ruby on Rails. It's in response to declarative XML configuration that's being overused.

May
2010

Jimmy Bogard releases v1.0 of AutoMapper that's described as "a convention-based object-object mapper in .NET".

Author
No. of Edits
No. of Chats
DevCoins
5
0
757
1
2
11
1094
Words
2
Chats
6
Edits
1
Likes
327
Hits

## Cite As

Devopedia. 2020. "Convention over Configuration." Version 6, July 18. Accessed 2020-08-12. https://devopedia.org/convention-over-configuration
• Site Map