🤝 Why should developers agree on best practices?
Stripe's Developer Coefficient report in 2018 stated that 42% of the developers' time is dedicated to refactoring existing code, understanding it, or fixing maintainability issues. A research paper from 2017 shows that developers spend about 58% of their time reading code on average.
To keep code consistent and easy to maintain, developers need to align their way of coding so that they don't waste time understanding and cleaning the code they're working on. It's also a great way to prevent technical debt in the project.
Reach the expected time to market is easier if you strive to maintain the source code in a clean state permanently.
📘 Use a Wiki to share knowledge
Developers often deploy Wiki tools to define and share best coding practices, such as Confluence, Notion, Github Pages, or even Markdown embedded in Git repositories. The idea is to build a centralized place where best practices will be recorded and available for everyone.
Practices are often organized according to their topics: languages, frameworks, architecture, security. By nature, they are collaborative tools so that everyone could contribute to the Wiki.
🧲 Limits of wikis
While such initiatives are relevant, they undergo several limitations in practice :
- Complex to feed and maintain: Developers need to contribute to the Wiki to add and update best practices. But how do you start this process from a clean sheet? Do you brainstorm to come up with all your practices? And then, which process do you set up to update the Wiki regularly, add new practices and make sure all of them are still relevant? That's the main challenge, as it is for any technical documentation in general.
- Best practices are complex to document: The common drawback of best practices' documentation is the lack of contextual examples, which make more sense than "hello world" ones. Developers need to dig into their source code to document their best practice.
- Hierarchical structure not suited for contextual and global practices: Most of the best practices relevant in one context are not relevant for some other contexts. Each project may have some specificities while still adopting global practices. Should each team maintain its own Wiki and maintain references to a higher-level wiki (but not for all the content)? That's sounds tricky.
- Hard to use daily: Developers tend to use only their IDE or Github-like platform every day. Other tools should provide tight integrations to be used by developers. However, keeping open a Wiki page is not really convenient. That's why developers quickly lose the habit of reading best practices documentation, and a have few interactions with it.
- The circle is not complete: ****Developers feed the Wiki, but what do they get in return? Wiki is just textual context. For instance, it does not scan the source code to help developers checking their best practices. That's also why it's hard for developers to keep motivation over time.
🚀 Share best coding practices with Packmind
Packmind is a collaborative solution to define and share best practices for developers. It overcomes all limits listed above, and brings even more capabilities. The solution is designed to :
- Let developers identify best practices while coding in their IDE or during their code review and contribute to the best practices repository in Packmind.
- Help teams to discuss about best practices, validate some and discard others. Practices are documented with concrete examples and counter-examples from the team's projects. Packmind's Craft Workshops is a discussion space to exchange knowledge regularly and take technical decisions.
- Get automatic suggestions of best practices in IDE or their code review tool. This recommendation system prevents time-wasting during code reviews and allows a faster learning curve for developers.
- Share best practices across teams or communities of practices. It's a great way to capitalize on knowledge within an IT company.
Discover more https://packmind.com
Top comments (0)