Convention over Configuration

Cartoon showing how convention simplifies understanding. Source: Geek & Poke 2008.
Cartoon showing how convention simplifies understanding. Source: Geek & Poke 2008.

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.

Discussion

  • Could you explain convention over configuration with some examples?
    An introduction to CoC in ASP.NET MVC. Source: VTC 2018.

    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?
    Examples of CoC in Ruby on Rails. Source: Krzywda 2020.
    Examples of CoC in Ruby on Rails. Source: Krzywda 2020.

    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?
    Some benefits of CoC. Source: Văn 2014, 1:26.
    Some benefits of CoC. Source: Văn 2014, 1:26.

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

References

  1. AutoMapper GitHub. 2020. "AutoMapper/AutoMapper." AutoMapper, on GitHub, July 7. Accessed 2020-07-18.
  2. Bozhanov, Bozhidar. 2015. "A Problem With Convention-Over-Configuration." DZone, November 19. Accessed 2020-07-16.
  3. Cabot, Jordi. 2017. "Convention over configuration – key selling point for MDE." Modeling Languages, March 15. Accessed 2020-07-16.
  4. Chauhan, Shailendra. 2013. "A Brief History of ASP.NET MVC Framework." DotNetTricks, July 21. Updated 2020-01-15. Accessed 2020-07-18.
  5. Garcia, Daniel Jimenez. 2019. "The History of ASP.NET – Part I." DotNetCurry, April 26. Accessed 2020-07-18.
  6. Geek & Poke. 2008. "Simply Explained - Part 18: Convention Over Configuration." Geek & Poke, June 4. Accessed 2020-07-16.
  7. Governor, James. 2012. "Opinionated Infrastructure, Convention over Configuration, Rails, IoS and Systems Design." RedMonk, September 28. Accessed 2020-07-16.
  8. Hansson, David Heinemeier. 2016. "The Rails Doctrine." Ruby on Rails, January. Accessed 2020-07-16.
  9. Heath, Mark. 2017. "Convention Over Configuration." Blog, Sound Code, May 20. Accessed 2020-07-16.
  10. Huang, Michael. 2015. "Building Java with Gradle (I)." Blog, August 30. Accessed 2020-07-16.
  11. JSON API. 2020. "Homepage." JSON API. Accessed 2020-07-17.
  12. Krzywda, Andrzej. 2020. "Examples of Convention over Configuration in Rails apps." Twitter, March 31. Accessed 2020-07-16.
  13. Miller, Jeremy. 2009. "Patterns in Practice - Convention Over Configuration." MSDN Magazine, vol. 24, no. 2, February. Accessed 2020-07-16.
  14. Poczwardowski, Michał. 2018. "Pros and Cons of Django - When to Use Python Framework." Blog, Netguru, July 19. Accessed 2020-07-16.
  15. Pytest Docs. 2020. "Good Integration Practices." Pytest. Accessed 2020-07-17.
  16. Seemann, Mark. 2012. "When to use a DI Container." ploeh blog, November 6. Accessed 2020-07-16.
  17. Sonatype. 2008. "1.2. Convention Over Configuration." In: Maven: The Complete Reference, Sonatype, Inc. Accessed 2020-07-16.
  18. Switchbox. 2015. "JSON-API: Convention over Configuration with Standardization." Blog, Switchbox, November 17. Accessed 2020-07-16.
  19. Sáez, Francisco. 2015. "Convention Over Configuration." Blog, FacileThings. Accessed 2020-07-16.
  20. Tromholt, David. 2019. "On Frameworks and What is “Convention Over Configuration”?" TechStacker, November 20. Accessed 2020-07-16.
  21. VTC. 2018. "0307 - Convention Over Configuration." Virtual Training Company, on YouTube, November 22. Accessed 2020-07-16.
  22. Viktoria K, and Vlad. 2016. "Where Do Ruby /Ruby on Rails 4 and PHP /Symfony 2 Come From?" Blog, RubyGarage, June 20. Updated 2020-03-18. Accessed 2020-07-18.
  23. Văn, Kính Hồ. 2014. "[ASP.NET MVC 5] 1.4. Convention Over Configuration." YouTube, September 12. Accessed 2020-07-16.
  24. Wikipedia. 2020. "Convention over configuration." Wikipedia, July 15. Accessed 2020-07-16.
  25. Wikipedia. 2020b. "Jakarta Enterprise Beans." Wikipedia, July 12. Accessed 2020-07-18.
  26. Zajíček, Tomáš. 2014. "Use of principles of IoC/DI in modern web applications or 'you get what you need'." Blog, Web Integration, July 25. Accessed 2020-07-16.

Further Reading

  1. Heath, Mark. 2017. "Convention Over Configuration." Blog, Sound Code, May 20. Accessed 2020-07-16.
  2. Spring Docs. 2009. "16.10 Convention over configuration." In: Spring Framework: Reference Documentation, version 3.0.M3. Accessed 2020-07-16.
  3. Bogard, Jimmy. 2019. "AutoMapper's Design Philosophy." March 25. Accessed 2020-07-16.

Article Stats

Author-wise Stats for Article Edits

Author
No. of Edits
No. of Chats
DevCoins
User avatar kkris
5
0
1357
Avatar of user arvindpdmn arvindpdmn
1
2
11
DevCoins due to articles, chats, their likes and article hits are included.
1094
Words
2
Authors
6
Edits
2
Chats
3
Likes
13K
Hits

Cite As

Devopedia. 2020. "Convention over Configuration." Version 6, July 18. Accessed 2023-11-12. https://devopedia.org/convention-over-configuration
Contributed by
2 authors

Last updated on
2020-07-18 06:16:31
design standardization conventions opinionated configuration

See Also