How do you transition towards conventions?

twitter logo github logo ・1 min read

I've found myself in situations where we want to adopt a convention, but there is some hesitation, over-analysis or roadmap uncertainty.

When you have an idea that you want to codify or conventionalize what was once freeform, what are the steps in doing this?

twitter logo DISCUSS (8)
markdown guide

In my shop it usually goes like this

  1. Someone tries a new thing
  2. They like it and share it with the group
  3. It works really well, and someone wants to adopt it as a convention
  4. We have a group discussion, and if the group is amenable, we say we'll all do it.
  5. We write down our convention
  6. We watch whether or not we comply with the convention
  7. If compliance is low, and automation is possible, we write a code gen tool, or scripts, build something so people no longer have to refer to the wiki

In my book, steps 4, 5 and 7 are the big deals. Getting group buy in is the #1 critical priority. It doesn't have to be consensus; you can Amazon it up and disagree/commit, but the group must be willing.

Writing down the convention, or making a library, or maven archetype or whatever form the convention takes is also pretty critical. It's hard to follow a convention that can't be described or codified, and someday you'll need a place to point new folks on the team.

Step 7, for us, is an interesting one. I think we don't do it enough. Here's an example from my recent work:

We were converting a bunch (~40) of BlazeDS monolithic services to message bus micro-services. It's easy, but tedious work, lots of mappers, lots of stubbing out the existing api. The tedious work tends to be the most error prone, because people go on autopilot. Everyone did their best to follow the pattern, but little differences cropped up here and there.

About 80% of the way through it, one dev was blocked, so they wrote a code gen tool that creates a message bus service package layout, with stubbed out methods, so devs only have to create the mappers. We didn't do that earlier because we were afraid the code gen tool would take a week or two we didn't have. Turns out, it took an afternoon and would have saved us a month...

I'm not sure where to draw the line, but when adopting a convention, I think you should look long and hard at making tooling to support the convention. It depends on how many people are working on a project, though. The more people, the more the team should create tools to support themselves. Fewer people can get away with frequent communication and strong norms.


Somewhere around steps 6 and 7 we also have the option to bail out. If compliance is low because the convention is bad, we just get rid of it. Probably obvious, but it bears mentioning, especially for people working in big, ponderous company/gov't cultures


Thanks, this is an excellent guideline!


I like to do it the same way as the Agile process: Try with a small group, evaluate, iterate, repeat.


I apply DRY here. I won't make a convention unless the exact same (not just a similar) problem is faced multiple times and the same solution works well for it. And even then it stays not required for a while to see how it survives maintenance and new features. A convention is a restriction which may prevent other alternatives from being tried. It is something that I do not take lightly -- unless its implications are obvious or trivial.


Basically the same as everyone else has said. Focus on the journey together of doing something that is going to save everyone time and effort. Avoid focusing on just the benefits of doing the thing. I've seen a lot of effort put on only the destination and it typically turns out poorly.


One of the first things I do is refine my idea. That gets rid of any over-analysis. Then I outline it in a way that is easy to then conventionalize or codify.

Classic DEV Post from Apr 29 '19

Terrible Interview Questions

Job interview questions which are so bad, that they are funny.

Ben Halpern profile image
A Canadian software developer who thinks he’s funny. He/Him.

Sore eyes?

dev.to now has dark mode.

Go to the "misc" section of your settings and select night theme ❀️