In software engineering organizations, there’s this challenge to define, record and spread best coding practices and standards across teams. This brings consistency to source code and improves its maintainability. It also avoids bottlenecks and endless discussions during code reviews on a given coding practice.
A common approach to this challenge is building a knowledge base in a Wiki-like tool, such as Confluence or Notion.
Although the idea makes sense and is relevant, at Promyze, we’ve talked with companies that shared the pitfalls and drawbacks of this approach for managing their coding standards.
We discuss them in this post.
The most observed pattern can be summarized with the following picture:
There are 2 details here that reflect the pitfalls of most wikis: The “TODO” section and the “Last update” property.
Keeping an up-to-date wiki requires energy and effort from a group of people (mainly technical leaders). Most of the job is often achieved when bootstrapping the process since there is a solid motivation to build a knowledge base of coding practices.
But this motivation tends to lower after several months, mainly because:
As a consequence, most of the companies we talked with shared with us the “outdated wiki” pattern when we discussed their best coding practices management.
Knowledge has value only if it’s shared and understood by others. But having great content in your Wiki does not guarantee that people will interact with it. Do they even know it exists?
If not, they won’t search for it. It’s common that engineers looking for answers to their questions receive as answer a link to the appropriate Wiki page because they’ll be more likely to directly ask their colleagues instead of searching in the knowledge base.
Coding practice shouldn’t be built independently by a small group of engineers without collaboration and discussion with others engineers. Think about how best practices are shared once written down in a Wiki. If a developer receives a message saying:
Coding practice shouldn’t be built independently by a small group of engineers without collaboration and discussion with others engineers. Think about how best practices are shared once written down in a Wiki.
If a developer receives a message saying:
Do you think it’s engaging? We’ve got plenty of stuff to do, and you’ve already decided they’re all valid. So I’ll wait until someone tells me in a future code review that I don’t follow them.
What if, instead, the same developers get this:
More engaging right? Developers feel more involved in the construction process.
And maybe they’ll have great suggestions to make!
Developers seldom code in their IDE while interacting with the knowledge base to see if they follow or not a coding standard. Ideally, they need to get the right information when they need it. They should be notified if their code is not compliant with a practice. But Notion or Confluence are not designed for this specific use case. And when coding, we want to stay focused on our IDE.
That’s why static should become dynamic instead: how to push a coding practice when it’s relevant? How to create a bi-directional flow between developers and the knowledge base?
If this post reminds you of your current context, you’re likely looking for alternatives to improve how you manage your best practices. Here is one for you. At Promyze, our ambition is to design a dedicated solution to this coding standards-sharing challenge. Our platform allows to:
Learn more on promyze.com to find more on this.
Promyze, the collaborative platform dedicated to improve developers’ skills through best practices sharing and definition.
Crafted from Bordeaux, France.