Convention over Configuration

Convention over configuration has been out in mind-space for a couple years now, yet unlike the Agile Manifesto, I have not seen any roadmap on how a project can achieve it. This is a gap in human knowledge. Since I love nothing more than to fill gaps on my free time, here are a few principles recurrent in my work with two of the top CoC-based projects: Ruby on Rails and Apache Maven.

I. Conventions are emergent.

Sitting down beforehand and designing a convention is only useful as a touchstone, a point of reference, and should only appear out of practical experience with many real-world examples. Any convention not born of real use-cases is doomed to failure. Don't be afraid to throw away "flexibility" in the beginning. Maven 2 had to fight through the pain of Maven 1 before it got it's modern architecture, and Rails stood on the backs of years and years of experience, the dynamics of the Ruby language, and still several versions.

II. Lack of a real example for a convention is the strongest argument against it.

The burden for denying change should not depend on counter-examples - the lack of an example is enough for denying a convention creation/change.

Here is an example: someone recently wanted to make a fundamental change to Maven but could not provide a valid use-case for it to be so. The arguer would not let the matter drop until someone came up with a counter-example on why the change would not be good. This should not be the case. The fact that the arguer could not come up with an example for the change should always be enough to discount the idea. Hypothetical "well - in the future we may want to..." answers are not examples - they are hypotheticals... refer to point 1.

III. A convention should provide as few ways to do a single task as possible.

This is the exact opposite of configuration - which states that the best configurations allow you the flexibility to do whatever you want. Convention should have an opinion - this is the correct way to do this action.

Fewer options are easier to communicate and learn. There are already a Vast scope of options - it is simpler to conceive and convey when there is only one or two ways to execute a specific task.

IV. Conventions should have a narrow scope.

Don't go too far. A large complex convention must be managed, and managing them requires more configuration, which negates the purposes of the conventions, to wit.

Ruby on Rails is a great example of this. They provided a few useful tools and a way to extend those tools via third party plugins. Rails itself is surprisingly simple - it is the large number of plugins that makes it powerful.

V. When in doubt, simplicity.

This should go without saying - but it doesn't. A simple convention should always win out over an equal but more complex one - despite the perceived add power. Assuming conventions are emergent and should have a narrow scope then conventions will, over time, become more focused on solving precise use-cases. Complex conventions which attempt to solve a wide-berth of problems are harder to manage, and thus, the convention is wiped-out due to necessary configuration complexity. Good conventions should work out of the box.