This blog post is all about: what are the potential benefits of a good convention & what are the conditions to make it so :), what is the most fundamental requirement for the convention to succeed & why conventions are double-edged swords ...
Programming languages are very flexible, yet low-level solution shaping tools. Their real expressive, abstraction-building power can be unleashed by building upon bare language with language-specific idioms, libraries/frameworks, meta-programming, comments & ... conventions.
What's a "convention"?
Traditionally code conventions are associated with naming, but the proper definition should be more comprehensive. "Conventions" are rules & agreements regarding particular combinations of code constructs that give them additional meaning. In other words: we map syntactical constructs (using existing syntax capabilities) into semantical constructs (new ones, based on our design needs).
Conventions can vary. For instance, conventions may express ...
- ... how we represent/structure/compose special category of abstractions (e.g., repositories, processes, unique items with an identity, messages)
- ... how abstractions interact with each other (e.g., you can access functionalities only via services, each interaction ends with a response that can be either a success, partial success or an error)
But regardless of the variety, they have some common denominators. A convention should always:
- increase the expressiveness of the code (enrich it with useful information in a concise & easily digestible form)
- have none (or very limited) impact on run-time execution
- reduce the entry threshold/learning curve for people who do work with this code
- make navigation (across the whole code-base) easier & more natural
A good convention ain't that easy to build as it has to meet several conditions to succeed:
- natural and justified (has a PURPOSE)
- easy to remember (so it doesn't bloat the cognitive load)
- worth the effort (effort is boilerplate needed)
- specified RANGE (especially in case of existing, legacy code-base)
- conventions can be checked manually, but automation helps (of course)
These are all essential points. More or less obvious ones. But the most important one is missing from the list ...
Working at the root
How so? We focus far too much on technical aspects of conventions, their "purity" & perfection, while the crucial aspect for the conventions is to be sufficiently COMMUNICATED & "SOLD" (to the fellow engineers).
What do I mean by that?
Learning, comprehending (with a context) & building a habit of using the convention is quite an effort. It can fail for several reasons, such trivial as forgetting, misunderstanding or passive aggression (silently opposing the convention).
A convention doesn't have to be perfect, but it has to be respected. To make sure it is, its creator has to make a significant effort: publishing a note on Wiki/Slack is usually FAR from enough. Articles, live presentations, real-life examples (or other referential code), hands-on workshops & pair programming, tutorials, walk-through videos, feedback sessions on how did implementation go, assigning a convention owner, automated checks - I've done all those in the past & in some cases, even all of them together did not guarantee the final success.
Double-edged sword
The main problem with conventions is that if you fail to make them work, they'll backlash & turn against you. If ...
- your conventions are just not being respected ("dead") ...
- or you have too many of them ...
- or they are inconsistent ...
- or contradictory ...
- or not-precise-enough/unclear ...
- or (at last but not least) too pricey (boilerplate/over-engineering) ...
... they can corrupt the whole code-base.
Things that were obvious before will now be very unclear (with this reducing developers' confidence). A broken window effect will appear (and that b*tch is not easy to get rid of ...). Everyone will feel free to do stuff THEIR WAY, because apparently "there's no one single way to do things here". It's a big deal because:
For a certain concern: one average convention (that addresses it) is levels of magnitude better than two nearly perfect ones.
Kill problematic conventions without hesitation.
If it can't be done quickly, strangle them by consecutively reducing their scope. Educate internally - relentlessly, FACE-2-FACE & HANDS-ON, until educated ones become the evangelists themselves. Keep repeating & re-emphasizing the purpose of the convention: knowing the "why" usually makes a big difference.
And remember - conventions are usually very opinionated & the only thing certain when it comes to opinions is that everyone has a bunch of his own ones. Be an active listener & aware observer to assess "the resistance" & adjust accordingly. One won't do much against the silent defiance of the unconvinced/misaligned group.
