DEV Community: Packmind

From Code Reviews to Team Growth: Unlocking the Power of Practice Reviews

Cédric Teyton — Thu, 31 Aug 2023 20:08:10 +0000

In 2008, GitHub revolutionized how we approached code by introducing its Pull-Request model for code reviews. Initially adopted by open-source projects, they were used as checks to review the code from possibly anonymous contributors and make sure they made the product better. Fast forward to today, while this model has been widely adopted, its potential is not fully harnessed, as reviews continue to be used as mere checks. For high-performing teams, the stakes are higher. Beyond checking code quality, they foster collaboration, continuous learning, and knowledge sharing. These are first-class concerns for engineering managers and tech leaders.

Knowledge sharing is the engine driving efficiency, agility, innovation, and growth. Rethink your approach to code reviews. View them not just as a procedural step, but as a platform to amplify knowledge sharing:

Prioritize discussions on coding standards and best practices, primarily in Pull/Merge Requests’ comments. Remember: Every comment is an opportunity to elevate, not just evaluate.
Limit immediate discussions to issues that hinder code from being production-ready. File away secondary discussions for later, asynchronous engagements.

Imagine if every code review taught something new to your whole team.

Maximizing the Impact of Code Reviews

Previously, we did a deep dive into the 'Ship/Show/Ask' framework, which empowers Pull Request authors to determine one of the following next steps:

No review is needed for trivial changes (Ship)
Share code changes with peers for feedback (Show). Note: feedback can be provided after the merge.
Seek a review for significant/critical code changes (Ask)

In code review, spotlight potential bugs, security/legal concerns, ensuring resolution before deployment. One oversight? Code review feedback often remains confined to the author, leaving the team in the dark. Relevant insights should be accessible to all. Moreover, tech leaders often complain about the need to explain the same concepts in 1:1 threads repeatedly.

Furthermore, discussions on code readability or maintainability should ideally be deferred. Why? These conversations typically involve broader team perspectives and, when prematurely debated, can derail the development flow, and increase the lead time for change.

So, when's the ideal time for these high-stake discussions? Enter: Practice Reviews.

Harnessing the Power of Practice Reviews

Think of practice reviews as collaborative spaces for developers, whether in teams or broader communities (guilds, community of practice, …), aimed at:

Fostering knowledge-sharing and discussions about coding practices
Formulating and aligning with new coding standards
Leveraging and sharing developer expertise

NB: Note that a coding practice can address topics such as a programming language, a framework, security, architecture, design, performance, and more.

Scheduled regularly (perhaps weekly or bi-weekly) and clocking in at around an hour, practice reviews are disconnected from the code release process, and address source code that may have been already pushed into production. Unlike code reviews, they have no impact on the lead time.

The practices review’s agenda includes source code snippets annotated with a suggestion of coding practices, a discussion topic, or a question. These insights can come from code reviews, coding session, or virtually anywhere.

Each insight is introduced by its contributor, paving the way for team discussions, clarifications, and collective learning. By session end, the team not only adopts new coding standards but also amplifies its shared technical expertise. To go further, check how Ubisoft gets value from these practice reviews.

Code Reviews and Practice Reviews: A Synergy

Code reviews are focused 1:1 discussions, ensuring code-readiness for production, typically multiple times weekly. They drive asynchronous interactions. As code reviews block the delivery process, they pressure developers and prevent them from diving into deeper discussions about coding practices, so they lose a chance to elevate as a team.

In contrast, practice reviews are team-centric workshops. Held weekly or several times per month, they combine asynchronous code insights from code reviews or code changes with synchronous discussions. This approach enhances knowledge sharing and refines coding standards. Inversely to code reviews, they don’t block the delivery process, so developers are freed from any constraint and can dive deep into technical discussions with their team.

Over time, practice reviews not only improve the overall code quality but streamline subsequent code reviews. Ensuring all developers know your coding standards brings confidence that the source code will gain consistency and will be easier to maintain.

For engineering managers and tech leaders, practice reviews are a powerful ally to foster collaboration, continuous learning, and knowledge sharing among software engineers.

Introducing Packmind for practice reviews

Recognizing the huge upside for development teams, we have built Packmind (ex-Promyze) as your partner to foster knowledge sharing and manage coding practices. Seamlessly integrated with your IDEs, code review platforms, and code repository, it offers a platform for sharing insights and curate coding practices. Example: A coding practice queued for a practice review:

In addition, the Packmind platform proactively scans for coding practices within your IDEs or during code reviews, providing an immediate feedback loop to developers. The development team remains in sync with the evolving best practices, fostering a culture of continuous learning.

Discover more about Packmind and embark on your practice review journey here 🚀.

7 frustrations to avoid with code review best practices

Cédric Teyton — Fri, 26 May 2023 08:55:19 +0000

Code review is one of the most established processes in software engineering. Recent studies indicate that almost 90% of IT companies practice it. The emergence of AI technologies brings since 2022 new tools to improve the code review experience.

While its maturity has unveiled some common best practices for code reviews, it also emphasized several frustrations for developers in this context. At Packmind, we discussed their code review process with many technical leaders, engineering managers, and developers for several years. We’re especially interested in their improvement fields and what pains they still have. This post summarizes our findings.

Frustration 1: Spend too much time to understand the context and the code

Lucas submitted a Pull Request to Sara. She realizes it contains 800 lines (”whao!”) scattered among 40 files. There are 3 commits with the respective messages: 1/ “Add new feature” 2/ “Fix bug” 3/ “Fix bug for good”. The PR description simply indicates “Add new features on product listing”. “I have no idea what I’m gonna read”, sighs Sara.*

What frustrates Sara is the lack of clear context, leading to a more significant effort from her to dive into the code and understand it. Also, its size is an issue. There is tons of web content about what should be the ideal size of the code review. It depends on the context, and there’s no silver bullet. As the submitter, you should preview the Pull Request to gain empathy for the reviewer. This person will have a diff-based perception of your changes, which is not your vision of your changes.

As a submitter, soon as you start working on your code, think about how this code will be reviewed. Try to build atomic commits will clear and concise messages, and give a proper description to the PR. This context will help the reviewer understand what you’ve achieved and save precious time, avoiding frustrations. If the commit messages are too long, that’s a bad smell of a commit that encompasses too many changes.

Frustration 2: Bikeshedding and debating about standards

Sara reads the review comments made earlier by Sofia. One is about a coding style that “doesn’t change the behavior, but I prefer like this”. Sara is annoyed because she wrote the code like many other parts of the software, so she wanted to keep consistency. She tells Sofia, “Both solutions are okay, but maybe it’s better to keep the current way of doing this?”. But Sofia argues it’s a chance to bring a new evolution in our coding practices. Sara gets frustrated because this debate delays the review completion.

Sometimes, don’t you regret that code reviews tools don’t limit the length of discussion threads? While some reviews might be critical and require a deep analysis, most of the time they do not. If the review is a discussion space to improve a piece of code, the scope of the suggestions made should be limited and known by all reviewers. In the scenario below, the problem is that Sofia began a discussion that goes beyond the scope of the review because it’s about a coding standard; this should involve the whole team in making such a decision.

Comments should target what’s necessary to update in the code before it gets merged. All other discussion topics should be addressed in a dedicated session gathering all developers in the team. That’s the framework suggested by Packmind, whose code review extensions offer a smooth way to convert code review comments into coding practice suggestions; this practice will be discussed and validated (or not) during a workshop.

Frustration 3: Spend time reviewing trivial code

Sara starts reviewing a pull request from John, including two modified files and less than 20 lines of code changed. She’s in the middle of an emergency, but still took the time to do the review to avoid a latency for John. She approves the PR, but wonders why she was called to review that code. John could have done it himself!

Rigorous process right? A solution is to consider that not all code changes deserve the same attention. Some changes will be pretty basic and target non-critical parts of the system. Inversely, some changes will be more complex, impacting the application's core logic, or requiring strong attention regarding security concerns. We met several companies that have a rigorous process of code review, including, for instance, three reviews before validation. But does it make sense to follow this process every time without consideration of the review material?

Depending on the code submitted, we could imagine that developers are free to merge if they consider there’s no risk and need to assign a reviewer, and they should ask for two reviewers if the code changes are critical. That’s the idea promoted by the Ship Show Ask model. With solutions like Reviewpad, you can implement your assignment and merge rules depending on the content of the review.

Frustration 4: Getting few valuable feedbacks

Sara carefully submitted the review: she created isolated commits with clear messages and added detailed context in the PR description. It was the first time she had worked on this part of the software, so she took care to avoid any mistakes and expected to get constructive feedback. The PR contains about 400 hundred added lines. Stefan took the review but only wrote on comment: “LGTM”. Sara is relieved but expected a bit more material.

Maybe Sara just did the job perfectly, right? Even if it’s true, a good practice during the code review is to provide positive feedback on the code, to highlight what’s been done correctly. People often emphasize what’s “bad” and forget to comment when the work done is fine. This refers to empathy: Sara paid attention to the quality of the submission, and Stefan probably felt that, so he should also show empathy towards her.

To optimize the quality of the feedback, the reviewers must allow a sufficient amount of time for the review. Otherwise, they’ll extract only shallow and superficial content. And the submitter will feel that. So better don’t do the review if you’re in a hurry or not in the mindset for that. Ask a colleague to replace you this time. Also, adapt your expectations depending on who’s gonna make the review (her technical skills and expertise on the code, …). If the reviewer has few knowledge of the context, maybe it’s best to ask for a second review from a more advanced developer.

Frustration 5: The latency until the review gets completed

Sara opens a pull request at 01:00 pm. She asks her team if someone can review her changes. Bob will show up at 3:40 pm. and, after spending 5 mins reviewing, will suggest one minor change. Sara immediately takes 2 min to apply the change and asks Bob to approve the new version of the code. Bob approves at 5:00 pm, and the code is shipped in production. The whole process lasted 4 hours, but stuff happened only for 7 minutes. Fortunately, only one reviewer was required!

The first step is to focus on the root problem: why is this latency significant during the process? Do reviewers lack time because they’re overwhelmed? Don’t they pay enough attention to their notifications from the code review tool? Or is it because you don’t like to review, so they procrastinate as much as possible? The whole completion time indeed depends on the availability of the reviewer. There’s no silver bullet here, but this problem must be discussed internally to identify how to improve this process.

Between the PR creation until it’s merged, the majority of the time, nothing will happen. We wait for the next step to happen. Unfortunately, that idle time hurts the delivery time (the lead time for changes). While they wait for a review, developers will be tempted to start another task, leading to context-switching. Practicing mob programming can prevent such latencies. Also, a solution like Axolo offers a Slack application to manage GitHub pull requests and reduce the Pull Request merge time.

Frustration 6: Getting unpleasant or hurtful comments

The egoless programming principles stand as core concepts for doing great code reviews. One stipulates that “You’re not your code”. Code review, such as any other discussion space in a Tech organization, should be respectful among the participants. So we’re all kind to each other, and we formulate constructive comments about how to improve the code. Even though you’re uncomfortable with the code you’re reading, there’s no reason to write something like: “This is a non-sense, and this code should be thrown away”. Be constructive instead: “What do you think about this alternative instead?”. If developers are stressed or feel bad before getting review comments, your team has a severe problem to solve.

Frustration 7: The source code has obvious bugs

If you review a code and immediately say, “Hey, how this code possibly works?”, this does not smell like a great start. But you might be wrong and have missed something. So you politely ask to code author: “I’m possibly wrong, but I think this code has an issue and does not have the expected behavior since …”. If the answer is, “Oh yes, my bad, I didn’t run it actually.” I can definitively understand your frustration ;-) This is an apparent lack of rigor and empathy from the code author. To avoid this, set guidelines and rules before submission; for instance: code must have been tested (manually) and/or covered by unit tests, linters should have been executed, and the CI/CD pipeline is checked, …

Feel free to share with us your main frustrations when doing code reviews; we’d be happy to read them. To go further, we suggest you read our dedicated post on how to accelerate the code review process. Thanks for reading ;)

Don't let your coding standards die in a wiki

Cédric Teyton — Tue, 25 Apr 2023 13:54:15 +0000

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 Packmind, 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.

Raising and maintaining the practices repository is complex

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:

It takes time to identify and raise the practices, write them, and find the appropriate positive and negative examples (Do/Don’t);
This feeling that content gets a few hits and engagement from other developers (so why should I continue?)

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.

Engaging engineers is too neglected

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:

Hey, I’ve added new 4 React coding practices to follow in our Wiki. Take a look here!

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:

Hey, I came up with 4 React coding practices that I think could be helpful in our context. I want to introduce them to the team, discuss them, and decide if we validate or discard them. Would you be available for a short 30-min meeting this Friday?

More engaging right? Developers feel more involved in the construction process. And maybe they’ll have great suggestions to make!

Static content is not appropriate when coding

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?

Create Living Coding Practices

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 Packmind, our ambition is to design a dedicated solution to this coding standards-sharing challenge. Our platform allows to:

Raise coding standards from IDE and during code reviews thanks to our extensions;
Validate them during collective workshops;
Create a living coding practice by enriching it with patterns (regular expressions, SemGrep patterns, …), and making it available for developers when they write or review source code;
Support onboarding of new engineers with interactive challenges to learn the current practices in the organization.

Learn more on packmind.com to find more on this.

35 Knowledge base tools for developers in 2023

Cédric Teyton — Fri, 14 Apr 2023 11:37:25 +0000

In 2023, there should be no debate about the added value of great documentation in software projects. Software engineers should have access to the appropriate knowledge base, depending on the resource type and when they need it. Technical documentation for software developers can take many forms, including evergreen documentation (e.g., procedures for setting up a project), architectural principles that developers should follow in their projects, release documentation, coding standards and guidelines, onboarding guides, and more.

Documentation for technical audiences is a tough challenge for many reasons: it requires a rigorous organization to be kept up-to-date. It can quickly be put aside by engineers who often dislike spending time on maintaining documentation. One common mistake is to consider all categories of documentation at the same level: an ever-green procedure to install software is not the same as a coding standard, for instance, which regularly evolves. You don’t need this knowledge at the same time and frequency. Once you understand that, you can define different processes and channels to manage your technical documentation

In this post, we provide an overview of 35 existing tools for managing technical knowledge, which can be scattered into these main categories:

Wiki-like tools where engineers write documentation in the tool’s UI (ex: Notion, Confluence, …)
Living knowledge tools, where knowledge emerges from developers’ tools and become then dynamic, are used for instance, in code analysis and onboarding sessions (ex: Packmind);
Communication tools, such as Questions/Answers platforms (ex: StackOverflow for Teams, …)
Generated-wiki tools where developers will typically write documentation in markdown, and then all the magic will happen (ex: ReadTheDocs, …)

This post does not consider tools that provide end-user documentation, such as self-service portals (Zendesk, Intercom, etc.). We focus on documentation made by developers for developers. We also exclude API documentation tools, which belong to a specific domain that deserves its article.

Acreom

Capture notes, break down issues, track your progress, create a knowledge base.

AnswerHub

Empowering developers and teams to learn, share, and succeed through online communities and knowledge sharing.

AppFlowy

Open Source Notion Alternative

Archbee

Build better product documentation — faster

Bit.ai

Next-Gen Document Collaboration Platform for Teams!

BookStack

(Open Source) BookStack is a simple, self-hosted, easy-to-use platform for organizing and storing information.

ClickUp

Save time with the all-in-one productivity platform that brings teams, tasks, and tools together in one place.

Coda

The all-in-one doc for teams.

CodeStream

New Relic CodeStream is a free open-source extension for VS Code, Visual Studio, and JetBrains.

Confluence

Confluence is your remote-friendly team workspace where knowledge and collaboration meet.

Daux.io

(OpenSource) The Easiest Way To Document Your Project.

DeveloperHub.io

All-in-One Platform for Online Documentation.

Docusaurus

(OpenSource) Build optimized websites quickly, focus on your content.

Flarum

(Open Source) Forums made simple. Modern, fast, and free!

Forem

(Open Source) Forem is an open source platform for building modern, independent, and safe communities.

GitBook

Where software teams break knowledge silos. (We use it at Promyze for our public documentation)

GitHub Pages

Websites for you and your projects.

Hugo

(OpenSource) The world’s fastest framework for building websites.

Jekyll

Transform your plain text into static websites and blogs.

mdBook

static site generator from Markdown files.

MkDocs

(Open Source) Project documentation with Markdown.

Notion

The all-in-one workspace — for your tasks, notes, wikis, and calendar.

Notaku

Build a full-featured Docs website in minutes, using Notion as CM

Nuclino

A modern, simple, and blazingly fast way to collaborate — bring knowledge, docs, and projects together in one place.

Papyrs

The easiest way to create an online for your company.

Read The Docs

(Open Source) Read the Docs simplifies software documentation by automating building, versioning, and hosting of your docs for you.

SkyDocs

(OpenSource) SkyDocs is a lightweight static documentation builder with MarkDown.

Slab

Build a culture of knowledge-sharing today.

Sphinx

(OpenSource) Sphinx makes it easy to create intelligent and beautiful documentation.

Stack Overflow For Teams

Knowledge sharing and collaboration without distractions.

Swimm

Documentation Platform Built for Engineers.

TechDocs

Spotify’s docs-like-code plugin for Backstage.

Tettra

The best way to organize and share knowledge with your teammates.

Wiki.js

(OpenSource) The most powerful and extensible open source Wiki software

Promyze

Connect Developers’ Knowledge and share best coding practices, fully integrated in developers tools.

That’s all, folks; we hope that post gave you an overview of the current landscape of the knowledge base tools for software developers.

Among the ones quoted above, at Promyze, we use Notion to gather material such as procedures to create new releases of our IDE extensions. We use GitBook to publish the user documentation of our platform. Finally, we use our tool Promyze internally to raise new coding standards continuously. We bring these standards directly in IDEs & during code reviews since we consider this is the moment developers need this knowledge. You don’t code with a Wiki opened in a tab.

For each kind of documentation, you must define who should update it, when, and how other engineers will be notified of this change.

How a start-up implemented hexagonal architecture – The case of Packmind

Cédric Teyton — Mon, 27 Mar 2023 15:19:00 +0000

Our platform Packmind is developed in a Client-Server model with a Front side developed in TS and React, while our back-end relies on Node.js. To give some context, the code base started 3 years ago, and we’ve always been a small team with max. 4 developers working on the code simultaneously. We currently have 156 KLOC in our back-end and 154 KLOC on the front-end.

Our motivations for implementing concepts from hexagonal architecture were to support the maintainability of our code base, and ease our life when working on it to add new features. When we discovered concepts from Domain-Driven Design, Clean & Hexagonal Architecture, we liked the idea of building separate bounded contexts and having in our code domains that encapsulate the business logic, being free of any third-party framework and technical implementation.

As we also use TDD (Test-Driven Development) in our coding process, we thought that applying ideas from hexagonal architecture and TDD would help to produce consistent hexagons covered by tests. This post shares how we currently implement a hexagon in our Node.js back-end.

This is how we do it in March 2023. Our practices have evolved for 2 years, and they’re likely to be improved in the future; if it’s the case, we’ll share a digest in a new post ;)

The key concepts

In our context, a hexagon targets a specific domain of our app, for instance, the automatic suggestions or the notifications. We enforce to make it self-sufficient and ensure it can be easily enabled or disabled at runtime. Each hexagon contains 4 distinct modules:

Domain: Contains the entities and aggregates specific to a domain and the repository interfaces (abstractions) to manipulate these entities.
Application: Contains the services offered by the hexagon. This layer directly manipulates the Domain.
Infrastructure: Implements the domains’ repository with concrete back-ends such as a database, files, in-memory, and more.
UI: Handles how the rest of the world interacts with the application (Rest API, CLI, …).

Illustration

Let’s take a concrete example with a hexagon handling the Knowledge Hexagon, the core concept being the BestPractices, used to raise coding standards from our IDE & Code review extensions. We’ll skip irrelevant details for readability. Note that we’ve still included the folder structures if it can help some readers to understand how to organize their code.

Domain & Infra

First, let’s zoom in on the Knowledge Hexagon on the relationship between the Domain and the Infra layers. In our context, we use a MongoDB implementation:

The domain is simple and only contains entities and the repositories interfaces. As you can notice, the domain has no link with the Infra layer. We’ve chosen to use a “main” interface KnowledgeRepositories, that will expose all the repositories of our domain. In the Infra layer, we use Converter components to transform objects from Infra to Domain, and inversely. This is optional, and it all depends if you rely on an ORM or not.

Instantiating the Infra Layer looks like this:

const bpMongoRepo = new BestPracticeRepositoryMongo();
const knowledgeRepositories: IKnowledgeRepositories = new KnowledgeRepositories(bpMongoRepo);
const infra: KnowledgeInfra = new KnowledgeInfra(knowledgeRepositories);

// const knowledgeRepositories: IKnowledgeRepositories = new KnowledgeRepositories(new BestPracticeRepositoryinMemory())) would allow to use an in-memory implementation instead

Application

Still in the Knowledge Hexagon, Now let’s zoom in on the Application layer and how it interacts with the Domain layer:

The application will stand as an API, containing all the services the hexagon offers to manipulate the domain, both entities and repositories. As domain repositories in the domain layer are abstractions (e.g., interfaces), they need concrete implementations at runtime. So we can reuse the one instantiated for the Infra layers.

const bpMongoRepo = new BestPracticeRepositoryMongo();
const knowledgeRepositories: IKnowledgeRepositories = new KnowledgeRepositories(bpMongoRepo); 
const knowledgeServices: KnowledgeServices= new KnowledgeServices(knowledgeRepositories);

UI (Presentation)

Finally, let’s zoom in on the UI layer, which helps the rest of the world to interact with our hexagon:

In our context, we have two types of interactions:

From our end-users that interact with the app from their IDE/Code review plugins or their web browsers. The express framework is used in this context.
From other parts of our API (e.g., others hexagons) to avoid re-implementing business logic in a hexagon. We call them InternalExposedMethods. As we don’t use micro-services in our context, we considered that using such HTTP calls does not make sense. Instead, using these exposed methods works fine and fills our needs.

The big picture

Finally, if we all put things together, here is the big picture from the macro-level perspective. Again, we’ve included one concept (BestPractice) from the Knowledge Hexagon, but we could have added more in this context (such as CodeExample listed above in the Infra layer).

Here is how the hexagon can be started programmatically:

class KnowledgeHexagonApp {
     constructor() {
       //Infra
       const bpMongoRepo = new BestPracticeRepositoryMongo();
       const knowledgeRepositories: IKnowledgeRepositories = new KnowledgeRepositories(bpMongoRepo); 
       const infra: KnowledgeInfra = new KnowledgeInfra(knowledgeRepositories);

      //Application
      const knowledgeServices: KnowledgeServices= new KnowledgeServices(knowledgeRepositories); 

      //UI
      const routers = [new BestPracticeRouter(knowledgeServices), ...];
      const exposedMethods = new InternalKnowledgeExposedMethods(knowledgeServices);
  }
}

You can adapt this example to change the infrastructure layer to something different than MongoDB dynamically. If you want to use SQL or in-memory, this could be injected at runtime as a dependency of the KnowledgeHexagonApp constructor.

Managing tests

Each hexagon embeds a test suite resulting from the TDD practice. For the record, we use Mocha and Chai to write and run our tests. In our context, our tests layer has two main parts:

The first is to test the Application Layer and its functions, using Fake repositories defined in the Infra folder and using in-memory implementations (basic TypeScript List/Map/…).
The second targets our concrete MongoDB implementation of the repositories. We’re not testing the Mongoose framework or the MongoDB infrastructure, but we ensure we have the right behavior when interacting with the repositories. It would be a pity to have a bug in production just because we misuse our ORM, right? We use the mongo-unit library that runs an embedded in-memory MongoDB server for that purpose. We use hard-coded fixtures in specific files, which mongo-unit will ingest before the beforeEach call.

Events management

It does not appear above, but in our API we’ve implemented a custom event management system. We have two requirements:

we want to track core events in our system (a best practice has been created) and record them in our database;
each hexagon should be able to react to specific events (a user has been deleted)

We’ve developed a lightweight system that relies on the EventEmitter provided by NodeJS. We’ve decided to centralize all our events in a shared module outside hexagons as payload objects, such as BestPracticeCreatedPayload emitted when a best practice is created. Here is how it’s implemented in the hexagon:

In the UI layer, we can find the Listeners that react to events emitted by others hexagons in the API.

In the Application layer, the events will be emitted and handled by other hexagons.

In the Infra layer, we implement the services that will perform the event messaging. Instead of using EventEmitter from Node, we could use other alternatives, such as sending a message to a RabbitMQ channel.

Other discussions

One important point is that most hexagons use shared concepts like BestPractice or Users. We voluntarily chose to duplicate their definitions in the Domain and Infra layers. One cool thing with Mongoose is that, when writing the mapping model, we can specify only the fields we need in the hexagon. And if you ask, “what happens when the model evolves ?”, I’d say this does not happen very often; when it does, only a few hexagons are impacted, so we don’t consider this a main concern for us.

This version currently fills our need, especially because we’re a small team, and we want each of us to be able to work on any component of the app. We ban knowledge silos, and our weekly workshops to discuss coding standards are helpful. So we’re all responsible for the code, and no one is in charge of a particular domain. So if we radically change how best practices are designed, we can easily discuss this. Our monolith works fine with a single database instance, and if we need in the future to deploy micro-services, we’ve prepared the ground for that. Plus, as we use TDD, we’ve built a security net to prevent possible regressions.

Finally, our main specificity was to build the ExposedServices when it made sense for each hexagon. As we run in monolithic approach, we considered a relevant solution. If, in the future, our system evolves and we need to run micro-services, we’ll need to replace the methods calls with class HTTP calls.

Adapt generic concepts in your context

As said earlier, the way we wrote hexagons has evolved and might still evolve. We continuously train our skills on that topic and don’t claim we’re experts in that field (feel free to share your thoughts with us; we’d be happy to take them! :-)).

To keep our coding standards aligned, we use our platform Packmind to share and discuss our best practices. If you also want to define your tailored coding standards, not only on hexagonal architecture, but also on Security, JavaScript, Performance, or whatever topic that matters to you, Packmind might be a good ally for that.

In a future post, we’ll focus on how we’ve implemented concepts from the clean architecture in front-end, still using TDD, to remain independent as much as possible from the underlying framework (React in our context) and the API.

Simple knowledge-sharing sabotage field manual

Cédric Teyton — Thu, 16 Mar 2023 08:16:42 +0000

In 1944, the OSS — Office of Strategic Services — of the USA shared with their Europe-based agents a sabotage manual designed to create friction, frustrations, slow-downs, and disturbances in Nazi organizations.

80 years later, it’s interesting that the guidelines look familiar in many large companies. For instance:

Insist on doing everything through “channels.” Never permit short-cuts to be taken in order to expedite decisions.

I recently could have the chance to give a talk at the Bordeaux JS Meetup about how this sabotage manual could be applied to knowledge sharing in tech companies. This post summarizes its content.

Context

Our common goal is to harm the company *Deforest Corp*. They have a bad ecological impact as their primary mission is to massively destroy natural forests to favor intensive agriculture. As a software developer, you’ll join a feature team working on an app used by employees that drive deforestation sites. This app has undergone recent bugs so software quality is a major concern.

Your mission will be to degrade code quality (or at least, not improve it), increase bugs risks, and negatively impacts the relationships among members in the team. So we choose a smooth, subtle, and (almost) pacific approach. If you’re too radical, you’ll probably be fired immediately, so no interest.

Your action plan: hurt everything related to knowledge-sharing. Why so? It’s one of the factors that fuels business performance, developers still spend a lot of time answering questions and looking for answers, and knowledge-sharing is still a challenge for developers. More generally, it breaks knowledge silos; still need to be convinced of the value?

Let’s see how to do it?

The guidelines

Don’t share the root causes of the bugs you fix. You increase the risk that someone else performs the mistake related to the root cause, and the bug will happen again.
Don’t share the code improvements you made. Any best practice that has a positive impact on the code (readability, performance, …) should be kept for you, preventing others to apply them in their code. Don’t be too greedy about that.
Don’t update obsolete documentation. If you spent a lot of time finding an answer because the Wiki was outdated, ensure your colleagues will also face troubles. Leave it as it is.
Make yourself unavailable for onboarding sessions. Onboarding new developers is a great exercise for sharing knowledge with a newcomer. Make sure that won’t happen.
Don’t read or react to content shared by your colleagues. Someone just shared a nice post on Slack? Of course, you’re too busy to read it. But don’t even ask for a short digest, and don’t react at all. They’ll get tired.
Support the idea that aligning your coding standards is pointless. Everyone should write code in their own way. YOLO, right? This will bring heterogeneity in the source code, leading to potential quality issues.
Decline all pair/mob programming sessions. Pair and Mob programming sessions optimize the output while fostering social interactions. You don’t want that.
Pretend you didn’t see you’ve been asked to do a code review. Oh, you saw this notification for reviewing a pull request? We already received too many notifications, right? So I’m sure you missed that. This will create a good latency.
Postpone the code review by pretending a huge workload. Sometimes, you’ll see the notifications. But guess what? You’re too busy, you also have work to do. So wait 2-3 days. And finally, just be honest with your colleague and say “I did my best but unfortunately could find the time. Can you ask to someone else?” Precious time lost, we love that.
Validate the review without reading the code. Free LGTM distribution at random locations. Don’t take that chance to improve the code, identify possible bugs, or share valuable tips. People will think you did a review. Send code as it is in production.
Suggest conflicting best practices from one review to another. You’ve suggested one coding standard the last time? Suggest now the opposite. This will bring confusion, friction, and heterogeneity in the code.
Feed endless discussions during code reviews about coding standards. GitHub/GitLab provides features to create comment threads, right? Use it as much as you can. This will create latency in the process. And of course, disagree with your interlocutor.
Make comments on source code NOT updated during the review. Run discussions on the code that have not changed at all (you know, these lines of code not starting with “+” or “-” in the diff). Why not? Huge frustration coming in.
Decline any help coming from someone external to the team. 1. A technical coach is about to bring new best practices and methodology to the team? Decline it. We can’t impose a coach, they need your adhesion. Don’t give them.
Don’t share anything related to your technology watch. Did you go to a great Tech conference? Don’t talk about that to your team, don’t share any replay. Don’t talk about some nice blog posts you’ve read. Keep them for you.
Question the ROI of the community of practices. Don’t you think it’s strange, these people gathering several times per month, to share common problems and feedback that would be interesting to everyone? They’re just talking, and we have features to implement. Don’t learn from others teams that share common problems with you.
Ensure the company won’t pay for the books read during Book Clubs. So that people will be discouraged 1. from participating and thus won’t read that book that still looked interesting.
Ask a lot of questions during Coding Dojos. The size of the room, the exercise statements, the schedule, and more. Complain about everything. Ensure this 90min-session won’t be optimized.
Call for BBL boycott. Brown-Bag Lunch is scandalous. At that time, everyone should eat alone and not have a chance to learn while sharing a meal.

The summary

Of course, reasoning by absurd is a voluntary choice I made. If knowledge-sharing matters in your context, of course you should consider doing the opposite ;). If some of the guideline remind you some experiences you lived, sorry to hear that and I hope it’s past!

What about you?

I’ll end by sharing this 3-min test to evaluate how your current engineering teams are performing in terms of knowledge-sharing, hoping it will give you some insights :)

How to accelerate your code reviews?

Cédric Teyton — Tue, 14 Feb 2023 15:47:21 +0000

Code reviews through Pull/Merge Requests have become an essential process for the majority of tech companies. A recent study in 2022 unveils that 84% of the surveyed companies use it. Several years of practice allowed practitioners to take a step back on this methodology to identify pain points and how to overcome them. Besides, code reviews should always be continuously evaluated internally to improve how it’s done. In this post, we discuss how to add more flexibility to the Pull Request process and, thus, improve the delivery time.

The lead time for change is the amount of time it takes a commit to get into production, and is part of the 4-key metrics defined by the DevOps Research and Assessment (DORA). Engineering teams seek to optimize this delay to deliver sooner value to their customers. But before bringing solutions, let’s first define the problem:

During code reviews, what can slow down the whole process, create bottlenecks, and grow the lead time for change?

Packmind's CPO Arthur Magne recently discussed this topic with Freddy Mallet and Marcelo Sousa from Reviewpad during a webinar, and we summarized the main thoughts here.

Narrowing the context and purpose of code reviews

The most often quoted obstructions to code reviews are the lack of human resources and the workload of engineers that don’t allow enough time for code reviews. A common reaction consists in adding more human resources to address the issue. Not so fast!

First ask yourself:

Is each code review truly necessary? Can we affirm that all the discussions within reviews are relevant and should happen there?

Indeed, what we observe in practice is that code reviews often lack a clear context and purpose. If you’ve opened a merge/pull request, what do you expect from that? From our point of view, we propose two primary purposes for a Pull Request.

#1 Code approval

I need to ensure my code is okay before merging ⇒ I need your approval

In this case, it may raise friction from both sides, as reviews come late in the process. Authors can feel reviews as a constraint that slows down their delivery, and a frustration to get many comments, with which they won’t always agree. Reviewers can also adopt defensive behavior. What if they think: “I wouldn’t have done [the code] this way. Should I tell this? Should it be blocking for merging? My colleague waits for 2 days; how will my feedback be welcome?” So you can see that frictions can emerge from code reviews, mainly because we have the pressure induced by the quest for a satisfying lead time for change.

#2 Get help to improve the code

I’d like to show you my code and get your feedback to improve it ⇒ I need your help.

Compared with item #1, we’re looking to improve our code and learn from a peer. In this context, it’s worth considering whether this review is part of the delivery process. We may be convinced this code could be merged first. That’s something commonly observed in trunk-based development.

The workflows and policies are different based on the context of the PR, so it makes sense to define it clearly.

Another problem we observe during code reviews is the long discussion threads about implementation choices, design, and best coding practices. And there, discussions get emotional and passionate: this is precisely what we want to avoid during reviews.

Do we still need code reviews?

Aside from this discussion, you may ask whether doing code reviews still make sense in 2023, in an era where we can find plenty of “DevOps automation” tools on the market.

We consider that, yes, indeed, code reviews are still necessary. Even though automatic tools have become increasingly powerful, they’re good at detecting known problems. They can’t prove the absence of problems. Think about this Dijkstra quote:

“Program testing can be used to show the presence of bugs, but never to show their absence!”

So during a Pull Request, we seek for what tools can’t detect.

Now let’s go back to our main point: how to address the aforementioned issues?

Do code reviews only when it makes sense

The concept of Fluid Pull Request

To answer the question: “Do all Pull Requests require a code review?”, we can explore the model Ship Show Ask. In this approach, PR authors are considered free of trust to evaluate themselves if:

The code doesn’t require a code review since the changes are trivial (Ship)
They’d like to show the code changes to colleagues and get their feedback (Show); This mode can sound totally counternatural as the feedback can be provided after the merge. This is part of the paradigm shift.
The code requires a review (Ask)

So instead of adding more human resources to review the code, we reconsider the necessity for each PR to be approved; This is how we can positively impact the lead time for change. This concept is also called Fluid Pull Request.

Next generation pull requests with Reviewpad

Reviewpad is a GitHub app designed to automate your code review process and which implements the Fluid Pull Request concept. A single configuration file in your Git repository will contain all your workflows and policies for your Pull Requests. Based on the context, you’ll define rules to enforce or relax your security net. With Reviewpad, you can define rules such as:

If a file in this folder is edited, one person from this group should approve the code.
If the PR includes a new method in the code with an annotation @Critical, add a label ‘security, and require a double-validation.

Rules can decide whether PRs can be automatically merged or refused, define a validation workflow, and more. Rules can address syntactic patterns in the code changes.

Here is an example of workflow to automatically raise awareness when a critical change is introduced:

api-version: reviewpad.com/v3.x

labels:
  critical:
    description: Modifications to critical changes
    color: "#294b75"

groups:
  - name: owners
    description: Group of owners
    kind: developers
    spec: '["marcelosousa", "ferreiratiago"]'    

workflows:
  - name: changes-to-critical-code
    always-run: true
    if:
      - rule: '$hasAnnotation("critical")'
      - rule: '$hasFileName("runner.go")'
    then:
      - '$addLabel("critical")'
      - '$assignReviewer($group("owners"), 1)'
      - '$info("@marcelosousa: you are being notified because critical code was modified")'

Discuss best practices and design outside code reviews

Knowledge sharing should be collective

If you request a review to improve your code or show it, this shouldn’t be done under pressure before merging the code. Engineers should instead find dedicated time to discuss code design and best practices, avoiding friction. If you’re having a 1:1 conversation and debating about a best practice, you hold a discussion that may impact your whole team. Indeed, if you come up with a decision, shouldn’t everyone agree with that? We can assume that you seek code uniformity and practice alignment.

So maybe it’s time to consider running dedicated workshops on your best coding practices, as 1:1 conversations should not be the right place for that purpose.

Best practices sharing with Packmind

Packmind is a knowledge-sharing platform for developers and provides integrations with IDE and code reviews (GitHub, GitLab, Azure DevOps, Bitbucket, and Helix Swarm). With the code review plugins, you can create a best coding practice from a comment, and the code is sent to Packmind along with your best practice proposal. You thus avoid long 1:1 discussions during code reviews.

Then, Packmind helps your team regularly run dedicated workshops to review contributions from developers (made during code reviews or within IDE). It’s a suitable time to share knowledge and make technical decisions together and ensure everyone is aligned with the appropriate gestures to apply in the code. This is a continuous improvement process for your best coding practices and to grow developers’ skills.

Want to accelerate your code reviews?

If you feel your engineering team has bottlenecks in their code reviews, we hope you found in this post some insights to improve your process:

Consider the necessity to approve each code change;
Consider dedicated sessions to avoid never-ending discussions during reviews.

We also showed that Reviewpad and Packmind can be complementary to accelerate the code reviews while fostering knowledge sharing.

Tell us if you’ve improved your lead time for change in your context and how you made it; we’d be happy to learn!

33 how-to questions if you develop a JetBrains extension

Cédric Teyton — Mon, 13 Feb 2023 10:53:00 +0000

Are you about to start developing a JetBrains extension? Or maybe you’re currently working on that? As you may already know, once you develop a JetBrains extension, it’s available in the marketplace for all the IDEs maintained by the editor, such as JetBrains, PyCharm, Rider, WebStorm, and so on.

At Packmind, we’ve built a JetBrains extension that helps developers to share their best coding practices in their organization. We had to dive into the JetBrains SDK, and from that work, we wanted to build a ‘how-to’ list of use cases that might be helpful for you. We wish we had such one when we started working on that extension! Of course, feel free to ask any more questions! 🙂

NB: We also produced a similar post for VSCode if you consider a VSCode extension.

ℹ️ All the Java imports have not been included for readability purposes. Still, we added some of them to ensure you’re on the right way ;)

#1 How to access the visible lines in the current editor?

What if you’d be interested in computing stuff only for the content in the visible screen?

FileEditorManager fileEditorManager = FileEditorManager.getInstance(project);
Editor editor = fileEditorManager.getSelectedTextEditor(); 
// Instantiate the editor above as it suits the most for you

Document document = editor.getDocument();
Rectangle visibleArea = editor.getVisibleArea();

int startLine = document.getLineNumber(visibleArea.y);
int endLine = document.getLineNumber(visibleArea.y + visibleArea.height);

for (int line = startLine; line <= endLine; line++) {
    int startOffset = document.getLineStartOffset(line);
    int endOffset = document.getLineEndOffset(line);
    String lineText = document.getText(new TextRange(startOffset, endOffset));
    //Do smth with it, add to a list, or concatenate to a string.
}

#2 How to get the selected text?

Here're two examples of how to get the selected text in the editor:

Editor editor = FileEditorManager.getInstance(project).getSelectedTextEditor();;
SelectionModel selectionModel = editor.getSelectionModel();

if (selectionModel.hasSelection()) {
    String selectedText = selectionModel.getSelectedText();
    // do something
}

// Alternative
if (selectionModel.hasSelection()) {
    int start = selectionModel.getSelectionStart();
    int end = selectionModel.getSelectionEnd();
    String selectedText = editor.getDocument().getText(new TextRange(start, end));
    // do something
}

#3 How to add a marker to a line with a custom image?

You’ll need to extend the GutterIconRenderer class.

import com.intellij.openapi.editor.markup.GutterIconRenderer;
// ...
Editor editor = ...;
int lineNumber = ...; // the line number where you want to add a gutter

Icon icon = IconLoader.getIcon("/icons/youricon.png");
GutterIconRenderer renderer = new GutterIconRenderer() {
    @Override
    public Icon getIcon() {
        return icon;
    }

    @Override
    public boolean equals(Object obj) {
        return obj instanceof GutterIconRenderer && ((GutterIconRenderer) obj).getIcon() == icon;
    }
};

EditorGutter gutter = ((EditorEx) editor).getGutter();
gutter.registerTextAnnotation(lineNumber, renderer);

Override the equals method ensures that the marker won't be duplicated when the line is repainted.

#4 How to get the programming language of the current editor?

Easy one when you have access to the current Document:

import com.intellij.openapi.fileTypes.FileType;
//...
Editor editor = ...;
FileType fileType = ((EditorEx) editor).getDocument().getFileType();
String language = fileType.getName();

#5 How to add a menu on the right-click event?

To add a menu to the right-click event, you need to create a custom AnAction :

import com.intellij.openapi.actionSystem.AnAction;
//... 
public class MyMenuAction extends AnAction {
    public MyMenuAction() {
        super("My Menu Action");
    }

    @Override
    public void actionPerformed(AnActionEvent e) {
        // Your implementation here
    }
}

And register it as a popup menu action:

import com.intellij.openapi.actionSystem.ActionManager
//...
ActionManager actionManager = ActionManager.getInstance();
actionManager.registerAction("myMenuActionId", new MyMenuAction());

#6 How to set a custom shortcut to perform an action?

Following tip #5, declare first an AnAction class. Then we will use the Keymap class to add a shortcut to the action:

import com.intellij.openapi.keymap.Keymap;
//....
Keymap keymap = KeymapManager.getInstance().getActiveKeymap();
String actionId = "myActionId";
MyAction action = new MyAction();
keymap.addShortcut(actionId, KeyStroke.getKeyStroke(KeyEvent.VK_1, InputEvent.CTRL_DOWN_MASK)); // Ctrl+1

#7 How to list the JetBrains extensions pane opened in the IDE?

If your extension needs to know that information, here you are:

import com.intellij.openapi.wm.ToolWindowManager;
//...
ToolWindowManager toolWindowManager = ToolWindowManager.getInstance(project);
for (String id: toolWindowManager.getToolWindowIds()) {
    ToolWindow toolWindow = toolWindowManager.getToolWindow(id);
    if (toolWindow != null && toolWindow.isVisible()) {
        System.out.println("Opened tool window: " + id);
    }
}

The isVisible method determines if the tool window is currently open.

#8 How to retrieve all the JetBrains extensions installed?

This information can be complementary to the previous tip #7:

import com.intellij.openapi.extensions.ExtensionPoint;
// ...
ExtensionPoint<PluginDescriptor> extensionPoint = Extensions.getRootArea().getExtensionPoint(Extensions.getExtensionPointName("com.intellij.pluginsList"));
for (PluginDescriptor pluginDescriptor : extensionPoint.getExtensionList()) {
    System.out.println("Installed plugin: " + pluginDescriptor.getName());
}

#9 How to underline a line of code?

You can use the EditorGutterComponent class and the GutterIconRenderer class:

import com.intellij.openapi.editor.markup.GutterIconRenderer;
import com.intellij.codeInsight.daemon.LineMarkerInfo;
//...
public class MyLineMarkerProvider extends LineMarkerProvider {
    @Nullable
    @Override
    public LineMarkerInfo getLineMarkerInfo(@NotNull PsiElement element) {
        if (element instanceof PsiMethodCallExpression) {
            int startOffset = element.getTextRange().getStartOffset();
            int endOffset = element.getTextRange().getEndOffset();
            TextRange textRange = new TextRange(startOffset, endOffset);
            GutterIconRenderer gutterIconRenderer = new MyGutterIconRenderer();
            return new LineMarkerInfo<>(element, textRange, null, Pass.UPDATE_ALL, null, gutterIconRenderer, GutterIconRenderer.Alignment.RIGHT);
        }
        return null;
    }
}

And this is the GutterIconRenderer implementation, where we took as an example the notification icon, but you’ll be welcome to add your icon:

private static class MyGutterIconRenderer extends GutterIconRenderer {
    @NotNull
    @Override
    public Icon getIcon() {
        return AllIcons.Ide.Notification.Info;
    }
}

#10 How to retrieve the file name of the current tab?

Here you are:

import com.intellij.openapi.vfs.VirtualFile;
//...
FileEditorManager fileEditorManager = FileEditorManager.getInstance(project);
Editor editor = fileEditorManager.getSelectedTextEditor();
if (editor != null) {
    VirtualFile virtualFile = FileEditorManagerEx.getInstanceEx(project).getFile(editor);
    if (virtualFile != null) {
        System.out.println("Current file name: " + virtualFile.getName());
    }
}

Note that the FileEditorManagerEx class provides additional functionality for managing editor tabs.

#11 How to listen when a tab has been closed?

You can implement a listener for when a tab is closed:

FileEditorManager.getInstance(project).addFileEditorManagerListener(new FileEditorManagerListener() {
    @Override
    public void fileClosed(@NotNull FileEditorManager source, @NotNull VirtualFile file) {
        System.out.println("File closed: " + file.getName());
    }
});

#12 How to listen when a tab has been opened?

In the same spirit as tip #11:

FileEditorManager.getInstance(project).addFileEditorManagerListener(new FileEditorManagerListener() {
    @Override
    public void fileOpened(@NotNull FileEditorManager source, @NotNull VirtualFile file) {
        System.out.println("File opened: " + file.getName());
    }
});

#13 How to listen when the current tab has changed?

Again, same approach:

FileEditorManager.getInstance(project).addFileEditorManagerListener(new FileEditorManagerListener() {
    @Override
    public void selectionChanged(@NotNull FileEditorManagerEvent event) {
        VirtualFile newFile = event.getNewFile();
        if (newFile != null) {
            System.out.println("Current tab changed to: " + newFile.getName());
        }
    }
});

#14 How to add and access a JetBrains extension setting?

The Settings class and the State class will help you. In our case in Promyze, we had to use the current user API Key:

public class PromyzeSettings {
    private static final String SETTING_KEY = "promyzeApiKey";

    @State(name = SETTING_KEY, storages = {@Storage(value = "promyzeSettings.xml")})
    public static PromyzeSettingState settingState = new PromyzeSettingState();

    public static PromyzeSettingState getInstance() {
        return ServiceManager.getService(MySettings.class).settingState;
    }
}

public class PromyzeSettingState {
    public String promyzeApiKey = "";
}

To access the setting, you can use the following code:

String userApiKey = PromyzeSettings.getInstance().promyzeApiKey;

#15 How to implement a Caret Listener?

This is useful if your extension needs to run an analysis when the caret moves. The CaretListener interface will be your alley:

import com.intellij.openapi.editor.CaretListener;
//...
Editor editor = FileEditorManager.getInstance(project).getSelectedTextEditor();
CaretModel caretModel = editor.getCaretModel();
caretModel.addCaretListener(new CaretListener() {
    @Override
    public void caretPositionChanged(CaretEvent e) {
        System.out.println("Caret position changed: " + e.getNewPosition());
    }
});

The getNewPosition method of the CaretEvent class returns the new position of the caret.

#16 How to get the current line of the caret?

Here you are:

Editor editor = FileEditorManager.getInstance(project).getSelectedTextEditor();
CaretModel caretModel = editor.getCaretModel();
int lineNumber = editor.getDocument().getLineNumber(caretModel.getOffset());.

#17 How to listen when the current editor is saved?

You’ll need to add a listener:

Editor editor = FileEditorManager.getInstance(project).getSelectedTextEditor();
Document document = editor.getDocument();
document.addDocumentListener(new DocumentListener() {
    @Override
    public void beforeDocumentChange(DocumentEvent event) {
        // Called before the text of the document is changed.
    }

    @Override
    public void documentChanged(DocumentEvent event) {
        // Called after the text of the document has been changed.
    }
});

#18 How to listen when a specific shortcut is called?

This is how you can listen to the keyboard shortcut CTRL + X.

import com.intellij.openapi.actionSystem.KeyboardShortcut;
//...
KeyboardShortcut keyboardShortcut = new KeyboardShortcut(KeyStroke.getKeyStroke(KeyEvent.VK_X, InputEvent.CTRL_DOWN_MASK), null);
AnAction anAction = new AnAction() {
    @Override
    public void actionPerformed(AnActionEvent event) {
        // handle shortcut event
    }
};
anAction.registerCustomShortcutSet(new CustomShortcutSet(keyboardShortcut), event.getData(CommonDataKeys.EDITOR_COMPONENT));

#19 How to change the logo of my JetBrains extension?

Add your icon to the resources directory of the project (in one of the following formats: .png, .jpeg, or .gif). Next, in the plugin.xml file, you need to specify the path to the image file in the icon attribute of the idea-plugin tag like this:

<idea-plugin>
  ...
  <icon path="icon.png"/>
  ...
</idea-plugin>

#20 How can I display a modal form after a command is sent from a right-click menu?

Assuming you’ve implemented an action in the contextual menu, you can then display a modal form thanks to the*DialogWrapper* class:


public class MyAction extends AnAction {
  @Override
  public void actionPerformed(AnActionEvent e) {
    MyDialog dialog = new MyDialog(e.getProject());
    dialog.show();
  }
}

public class MyDialog extends DialogWrapper {
  public MyDialog(Project project) {
    super(project);
    init();
    setTitle("My Dialog");
  }

  @Nullable
  @Override
  protected JComponent createCenterPanel() {
    JPanel panel = new JPanel();
    // Add components to the panel here
    return panel;
  }
}

#21 How to prompt a warning notification?

The Notification class will help you with that purpose:

import com.intellij.notification.Notification;
//...
Notification notification = new Notification("MyGroup", "My Title", "My Content", NotificationType.WARNING);
Notifications.Bus.notify(notification, project);

On the Notification object, you can also set the setListener property to provide a listener that will be notified when the notification is clicked.

You can use as well NotificationType.INFO and NotificationType.ERROR for informative and error messages.

#22 How to get the IDE name?

As said earlier, this value can be "IntelliJ IDEA", "PyCharm", "WebStorm", etc., depending on the product being used:

import com.intellij.openapi.application.ApplicationInfo;
**//...**
String ideName = ApplicationInfo.getInstance().getFullProductName();

#23 How to get the current version of the IDE?

Related to tip #22:

String ideVersion = ApplicationInfo.getInstance().getFullVersion();

The full version string typically has the format "major.minor.build".

#24 How to get the current compilation issues in the opened file?

In case your extension needs them:

import com.intellij.codeInspection.ex.HighlightManager**;
//...**
FileEditorManager fileEditorManager = FileEditorManager.getInstance(project);
Editor editor = fileEditorManager.getSelectedTextEditor();
if (editor != null) {
    Document document = editor.getDocument();
    PsiFile psiFile = PsiDocumentManager.getInstance(project).getPsiFile(document);
    if (psiFile != null) {
        List<ProblemDescriptor> problems = new ArrayList<>();
        GlobalInspectionContext globalContext = InspectionManager.getInstance(project).createNewGlobalContext(false);
        for (InspectionToolWrapper toolWrapper: globalContext.getInspectionTools(psiFile)) {
            ProblemsHolder problemsHolder = new ProblemsHolder(InspectionManager.getInstance(project), document, false);
            toolWrapper.processFile(psiFile, problemsHolder, globalContext);
            problems.addAll(problemsHolder.getResults().getResultItems());
        }
        // Do something with the problems list
    }
}

#25 How to get the content of the Output Tab?

To retrieve the output content of the app, you can use this trick:

import com.intellij.openapi.wm.ToolWindow**;
//...**
String outputContent;
ToolWindow toolWindow = ToolWindowManager.getInstance(project).getToolWindow("Output");
if (toolWindow != null) {
    Content content = toolWindow.getContentManager().getContent(0);
    JComponent component = content.getComponent();
    if (component instanceof JTextArea) {
        JTextArea textArea = (JTextArea) component;
        outputContent = textArea.getText();
    }
}

You can see the tab name is dynamic so you can retrieve the content for another tab.

#26 How to get the current editor theme?

It might impact the way you want to render your components:

import com.intellij.openapi.editor.colors.EditorColorsManager**;**
//...
EditorColorsManager editorColorsManager = EditorColorsManager.getInstance();
EditorColorsScheme currentScheme = editorColorsManager.getGlobalScheme();
String themeName = currentScheme.getName();

#27 How to listen when the IDE is opened?

You must create a class that implements StartupActivity and add it as an extension in your plugin.xml file:

import com.intellij.openapi.startup.StartupActivity;
// ...
public class MyStartupActivity implements StartupActivity {
  @Override
  public void runActivity(@NotNull Project project) {
    // your code here, it will be executed when the IDE is opened
  }
}

And in your plugin.xml file:

<extensions defaultExtensionNs="com.intellij">
  <startupActivity implementation="your.package.MyStartupActivity"/>
</extensions>

#28 How to listen when the IDE is closed?

Similar to tip #27:

public class MyApplicationListener implements ApplicationListener {
  @Override
  public void beforeApplicationQuit(@NotNull boolean isRestart) {
    // your code here, it will be executed before the IDE is closed
  }
}

And in the plugin.xml file:

<extensions defaultExtensionNs="com.intellij">
  <applicationListener implementation="your.package.MyApplicationListener"/>
</extensions>

#29 How to run an asynchronous task in background?

This is recommended to avoid blocking operations for the users. You can be sure they won’t hesitate to uninstall your extension if it’s too annoying ;)

You can create a class that extends Task.Backgroundable and override the run method to perform the task in the background. Here is an example:

import com.intellij.openapi.task.Task.Backgroundable;
//... 
public class MyBackgroundTask extends Task.Backgroundable {
  public MyBackgroundTask(@Nullable Project project, @NotNull String title) {
    super(project, title);
  }

  @Override
  public void run(@NotNull ProgressIndicator progressIndicator) {
    // your code here, it will be executed in the background
  }
}

To run it:

MyBackgroundTask task = new MyBackgroundTask(project, "My Background Task");
ProgressManager.getInstance().run(task);

#30 How to get the current language of the IDE?

Here you are:

Locale locale = Locale.getDefault();

The language code of the locale by using the getLanguage() method:

String language = locale.getLanguage();

#31 How to listen when an application is run?

The Run feature in your IDE:

import com.intellij.openapi.application.ApplicationListener;
import com.intellij.openapi.application.ApplicationManager;

public class MyApplicationListener implements ApplicationListener {

  public void init() {
    ApplicationManager.getApplication().addApplicationListener(this);
  }

  @Override
  public void applicationStarted() {
    // your code here, executed when the application starts
  }
}

#32 How to listen when an Extract Method operation is called?

You can also listen for specific code operations; here, we take the Extract Method operation:

import com.intellij.refactoring.RefactoringEventListener;
import com.intellij.refactoring.RefactoringEventData;

public class MyRefactoringEventListener implements RefactoringEventListener {

  public void init() {
    RefactoringEventListener.DEFAULT.addListener(this);
  }

  @Override
  public void refactoringStarted(String refactoringId, RefactoringEventData data) {
    if (refactoringId.equals("Extract Method")) {
      // your code here, executed when the Extract Method operation is called
    }
  }
}

#33 How to know if the current editor has defined the "LF" or "CRLF" mode for line breaks?

For the record, LF is more on Unix/Mac, while CRLF is used on Windows. Trust me, if you need to parse the source code, it can spare you some trouble ;)

Editor editor = EditorHelper.getCurrentEditor();
if (editor != null) {
  Document document = editor.getDocument();
  String lineSeparator = document.getUserData(Document.LINE_SEPARATOR_KEY);
  if ("\n".equals(lineSeparator)) {
    System.out.println("Lf mode");
  } else if ("\r\n".equals(lineSeparator)) {
    System.out.println("crlf mode");
  }
}

Wrapping up

That’s all, folks! We hope it can help you start working on your JetBrains extension. In case you work with your team, it can make sense to define best practices when developing a JetBrains extension. Packmind can help you with that; feel free to try it.

Writing clean code in Python

Cédric Teyton — Wed, 08 Feb 2023 08:46:54 +0000

Python is a programming language that offers a high level of flexibility. The counterpart is that developers can easily use different tricks that will lead to heterogeneity in the source code, decreasing its readability and maintainability. As with any programming language, it’s important to define best practices in a team to bring consistency to the source code, avoid bugs, and save time during code reviews.

At Packmind, we recently ran a webinar with our partner Arolla (the replay is in French) on How to write clean code in Python? We share in this post an extract of the discussed practices.

NB: Please note that we don’t claim the following practices are always valid, and the “don’t” examples are always bad. Trust yourself ;)

#1 Use Counter to count occurrences

Using the Counter from the collection library is more efficient at run time when you want to count different occurrences of elements in a list, tuple, or another hashable iterable:

from collections import Counter
array = [1, 1, 2, 3, 4, 5, 3, 2, 3, 4, 2, 1, 2, 3]
counts = Counter(array)
print(counts)
# Will print => Counter({2: 5, 3: 4, 1: 3, 4: 2, 5: 1})

#2 Use "in" to simplify if statements

The keyword “in” is an elegant, readable and maintainable way to check the presence of a specific element in a sequence :

detectives = ["Sherlock Holmes", "Hercule Poirot", "Batman"]
person = "Batman"

# Don't
if person == "Batman" or person == "Hercule Poirot" or person == "Sherlock Holmes":
    print("That person is a detective")

# Do 
if person in detectives:
    print("That person is a detective")

#3 Put actual before expected in assertions

Assertions will be easier to read in this order:

def test_big_stuff():
    actual_result = ...
    expected_result = ...

    assert actual_result == expected_result

#4 Use properties when relevant

Sometimes, when we create a class, we will have a field whose value stems from one or multiple other ones. For example, in a class Person, we can have a full_name field which concatenates the values of first_name and last_name .

In such cases, it is important to protect the content of the composite field by defining a property with the annotation @property. Going back to our example with the class Person, this will prevent a user to set the value of the full_name from outsite by writing person.full_name = ... .

class Person:
      def __init__(self, first_name, last_name):
            self.first_name = first_name
            self.last_name = last_name

      @property
      def full_name(self):
          return f"{self.first_name} {self.last_name}"

#5 Use fully qualified, absolute imports

This makes the code more readable and maintainable, so that when it’s time to modify the code, it is easier to figure where each object in the code comes from.

Performance-wise, it is basically the same as importing the full module (ex. import foo ) as Python always loads the full module, whether or not we import just an object of that module.

That is to say if when we write from foo.bar import Bar , Python loads the entirety of the module foo.bar and then proceeds to pick Bar

from foo.bar import Bar
from spam.eggs import Eggs

def main():
    bar = Bar()
    eggs = Eggs()

#6 Use iterators instead of explicit lists

Avoid creating a new list when it’s not relevant.

def get_max():
    iterable = ["a", "bbb", "c"]
    # Don't
    max_len = max([len(x) for x in iterable])
    # Do
      max_len = max(len(x) for x in iterable)
    assert max_len == 3

get_max()

#7 Use list comprehensions

A list comprehension is a way of creating a new list by transforming elements from an existing iterable (such as a list, tuple, or dictionary), and we want to, filter some elements, and perform operations on each element.

# Don't
def get_even_nums_squared():
    nums = [1, 2, 3, 4, 5, 6]
    res = []
    for num in nums:
        if num % 2 == 0:
            res.append(num * num)
    return res

# Do
def get_even_nums_squared():
    nums = [1, 2, 3, 4, 5, 6]
    return [x * x for x in nums if x % 2 == 0]

#8 Prefer using keyword-only arguments

Many times, especially when there is no logical order between the parameters of a function or method, it is recommended to call the function or method by specifying the name of the parameters (ex. make_coffee(with_sugar=True, with_milk=True) ).

It is possible to force the parameters to be named when the function/method is called. We can do that by using the “*” at the beginning of the parameters.

This avoids many possible issues and confusion.

However, it is not something to do all the time but rather when it makes sense.

Instead of:

def make_coffee(with_sugar=False, with_milk=False):
    pass

make_coffee(True, True)

We’d prefer:

def make_coffee(*, with_sugar=False, with_milk=False):
    pass

make_coffee(with_milk=True, with_sugar=True)

#9 Use ABCMeta for abstract classes

This practice can be relevant if you work with developers who are not expert in Python, but are more familiar with Java or C#. They’ll be more comfortable with the “abstract” concepts for classes and methods.

ABCMeta is a metaclass (a class that creates classes) in Python. It stands for "Abstract Base Class Meta".

Instead of:

class Fooer:
    def foo(self):
        raise NotImplementedError() 

class Spam(Fooer):
    def foo(self):
        print("spamming")

We’d prefer:

from abc import ABCMeta, abstractmethod

class Fooer(metaclass=ABCMeta):
    @abstractmethod
    def foo(self):
        pass

class Spam(Fooer):
    def foo(self):
        print("spamming foos")

#10 Use a main() function

Avoid global variables and, in general, source code outside functions.

Instead of:

from server import Server

HOST = "127.0.0.1"
PORT = 8080

SERVER = Server()

if __name__ == "__main__":
    SERVER.start(HOST, PORT)

We’d prefer:

from server import Server

def main():
    host  = "127.0.0.1"
    port = 8080

    Server = Server()
    Server.start(host, port)

if __name__ == "__main__":
    main()

#11 Do not use empty lists as default arguments

This can lead to unexpected and very weird behavior.

Instead of:

def add_player_to_team(player, team=[]):
    team.append(player)
    print(team)

We’d prefer::

def add_player_to_team(player, team=None):
    if team is None:
        team = []

    team.append(player)
    print(team)

#12 Prefer f-strings to string concatenation

F-strings allow writing sentences in a far more natural (and admittedly less annoying) way than what string concatenation can provide.

Do:

first_name = "Jake"
last_name = "Sully"
age = 28

message = f"{first_name} {last_name} is {age} years old now"
print(message)

Don’t:

first_name = "Jake"
last_name = "Sully"
age = 28

message = first_name + " " + last_name + " is " + str(age) + " years old now"
print(message)

#13 Prefer enumerate() to range(len()) when you want keep the index of iterable items

This practice contributes to code readability as well as its performance while still keeping the index around. The performance gain is because enumerate() creates an iterator for the collection, which is more efficient than looping through each item

Don’t:

ages = [1, 2, 18, 24, 8]
for i in range(len(ages)):
    if ages[i] >= 18:
        print(f"I'm client n°{i+1} and I'm {age} years old, I'm an adult now.")

Do:

ages = [1, 2, 18, 24, 8]
for i, age in enumerate(ages):
    if age >= 18:
        print(f"I'm client n°{i+1} and I'm {age} years old, I'm an adult now.")

All these best practices can be defined in Packmind from our IDE and Code reviews plugins. We’re compatible with VSCode, JetBrains suite, and Eclipse. So if you code Python with VSCode or PyCharm, you can go for it! Each practice you create will then be validated as a team during dedicated workshops, and the final result looks like this:

You can provide syntactic patterns to provide suggestions while coding or reviewing code and use this practice during onboarding workshops in Packmind.

The whole catalog is also available on our public Hub of best practices, where users can share practices on various domains and use them in Packmind.

You can start creating your practices now for free.

20 knowledge types and information sources for developers

Cédric Teyton — Fri, 03 Feb 2023 10:19:29 +0000

In a previous post, we bootstrapped some thoughts about what knowledge was useful for developers in their work. Also, we discussed that each piece of knowledge has its specificities (when and how it’s hit, how often it’s updated, how critical it is to notify the audience, …).

In this post, we propose a cartography of 20 different types of knowledge and information sources that developers interact with during their work. This might help you structure your team’s onboarding process of new developers and ensure they have access to the data they need to succeed. Or, if you just joined a new company, you can use it as a checklist to see if you’ve got all the access you need. This isn’t exhaustive, and you may identify more knowledge sources — Let us know! Also, we list a few examples of tools; some more exist.

#1 The How-to procedures, tutorials, and Get started guides

Helpful for setting up software or project on a laptop, when configuring your IDE for the first time, when we need to connect to a remote database, bootstrapping a new project according to a specific skeleton, or how to ship a new version of the app. A small group maintains this documentation, which is often a one-time read procedure, as you won’t need it every day. But we’re happy to have it when we need it. We also call them evergreen content. Tools: Confluence, Notion.

#2 Best coding practices

Developers’ gestures in writing source code according to the team practices. This is about properly writing the source code in the developer’s context. These best practices should be precisely defined in a team and at the company level, continuously maintained, and regularly discussed. Integration during code reviews and in the IDE are a must-have. Tools: Packmind.

#3 Code documentation

Get insights on the code base, a sub-part, or a particular code snippet. It can help to understand complex behavior, a past non-intuitive technical choice, or an implementation detail that needs explanations. Use it carefully, as it’s best practice to have a self-explanatory code where comments don’t bring value. This code documentation is usually contextual, and developers should keep it up-to-date. Tools: Swimm, Read the Docs.

#4 Tests suites

Test code is a powerful documentation of the code, and we could quote it in the previous bullet #3. Reading test code gives an overview of the core methods of your software and gives concrete examples of usage, especially if your team writes tests using the Given/When/Then or Arrange/Act/Assert patterns. If you dive into a new module, looking for tests is a great start to becoming more familiar with the code base. Tools: your favorite test framework, JUnit, Mocha, PyTest.

#5 API Documentation

An unavoidable one, it helps you understand how to use an SDK or an API, discover the available services and their purpose, and how to interact with them programmatically. The code examples give you confidence in using the API and handling situations when errors happen. At first glance, you should detect whether or not the API satisfies your needs. Otherwise, go your way. Tools: Swagger, Doxygen, apiDoc, Readme.

#6 The code quality issues

Check if the source code contains security issues, bad smells, formatting troubles, readability improvements, and more, with source code static analysis. You can have feedback on your IDE during a code review and a global overview in a dedicated dashboard. These linters are available for all programming languages and help keep the code syntax consistent. Tools: SonarQube, Codiga, EsLint.

#7 User Stories

Help understand a future feature to be implemented, its intent, and the purpose for the users. A user story (US) contains the requirements and specifies the acceptance criteria to clarify how to consider the feature ready. The US is a communication bridge between a product owner and a developer, as all content is recorded. A must-have to start coding! Tools: Jira, Trello, Asana.

#8 Bug reports

They have two main goals: 1) Get information about a newly notified bug, how it impacts the users, what its consequences are, what the error messages available are, and how to reproduce it 2) Find information on a previously fixed bug, as we currently investigate a similar one; you search how this previous bug was fixed, to help you in your work. They’re crucial to ensure the bug is fixed and to implement countermeasures. Tools: Linear, Jira.

#9 Executable specifications

Behavior-Driven Development (BDD) helps generate scenarios that illustrate business domain use cases from which you can establish business rules. Business experts, developers, and stakeholders (such as QA engineers) have co-built the concrete behavior examples. You can formulate these examples with the Gherkin syntax. During your onboarding, these examples help you to get familiar with the business domain. It drives the coding process, especially when using TDD. Tools: Cucumber, Cukedoctor.

#10 Architectural schemas

This high-level material can sum up a software project's big picture, the main components, and how they interact together. It’s useful when onboarding a new project to understand better how things work. Diagram flows or UML schemas can also document the software at a high level of abstraction. It can be inappropriate for some software, as you can self-document an adequate code architecture. Retro-engineering and code analysis can also provide insights into the code's architecture. Tools: Notion, CodeSee.

#11 The technical debt overview

I take a shortcut with the term “technical debt” to consider the parts of the code that require a rework — not only because the code is complex, but because the implementation, as it is, might raise issues in the short/middle term if nothing changes. The overview of the source code parts annotated as tech debt can help prioritize remediation and estimate the effort to provide. Tools: StepSize, CodeScene.

#12 Answers to a technical issue

Not easy to categorize, but here I refer to every blocking issue we face when coding or building the application, such as a compilation issue. When you’re stuck and can’t find an answer in the documentation, you can use async channels to ask if someone has met a similar problem. The answer unblocks the workflow, and you can resume your job. You can find the answer inside the company or over the internet. Tools: StackOverflow, Slack, CodeStream.

#13 Architectural Decision Records (ADR)

An ADR is a document that captures essential decisions such as design choices, trade-offs, and rationales related to the architecture of the software. It serves as a historical record and provides transparency and accountability for architectural decisions. An ADR also gives information about its context and its consequences. Helpful when you join a project to get insights into the architecture evolution. Tools: Markdown files embedded in the Git repo.

#14 UI Prototypes

Front-end developers are keen on consuming UI prototypes that reflect what’s expected regarding user interface and screens. It helps understand the user workflow and provides a clear overview of the user experience on the feature under development. They’re necessary to get started with the design implementation, accessing CSS elements, and producing a result that matches precisely the prototypes. Tools: Figma, Adobe XD.

#15 Design System

A system to centralize and reuse components related to the design of a product, a domain, or a company. Mainly helpful for front-end developers to ensure they ship source code with up-to-date design elements (logo, font, icons, …). Known as a central place where we can find information related to design decisions. Tools: Storybook.

#16 Runtime logs

They give valuable information on the runtime behaviors of your code. They help you investigate a bug report or analyze the performance of your software. Logs are essential for the observability of our software, and they provide precious insights into what happens in practice (how many times a service is called, how long last a service execution, …). All developers should have access to the logs in production. Tools: Logtail, Logz.io, Loggly.

#17 Code history

Helpful when you need to understand how a piece of code came up to its current state or if you realize the state has changed from the last time you saw this code and would like to know what happened. Versioning with Git provides excellent support and sometimes brings you to archeology work. You can identify the latest editor of a code and get in touch with him/her for further questions. The previous commits also give visibility to the current work. Tools: Any Git client*,* GitHub, GitKraken, GitLab.

#18 Build statuses

Hit by a developer to check if the branch merging doesn’t raise any issues or to get more information about a broken build (likely to be a failed test). This information is read on-demand and usually not on every push on the Git repository since alerting systems send notifications when there’s an issue (and not when all is fine). The build status indicates whether the code is ready for production. Tools: Jenkins, GitLab CI, GitHub Actions.

#19 Learning resources

Developers can learn from their current projects and grow personal skills in specific concepts in parallel. E-learning resources allow async learning sessions to be completed when it suits your planning. Practice sessions are helpful in training on a new language you’d like to progress on. For instance, we also include blog posts shared in internal channels within a Community of Practice. It’s part of the continuous improvement process and the learning culture. Tools: Pluralsight, Udemy, Internal wikis, books.

#20 Product documentation

Often forgotten, it still gives precious information on how the software behaves and helps to understand the application's different use cases and user workflows. It makes sense if the software is quite complex. Technical writers maintain this documentation; you might do it in some context. Tools: GitBook, Intercom, Zendesk.

Wrapping up

We’re done with this list! One last question for you now: how many sources do you have access to among this list? Do you have more suggestions? We’d be happy to add them, especially if you regularly hit some information or knowledge not mentioned in this post. Thanks!

What’s a best coding practice, and when to create it?

Cédric Teyton — Wed, 01 Feb 2023 08:36:47 +0000

A best coding practice is a specific action in a particular context, it’s a way of doing things to achieve a specific result. These practices differ between companies and sometimes even between teams within the same company.

Unfortunately, it’s rare that static analysis tools (linters) can automatically identify all these coding practices, which go beyond the syntax of the code. That's why it's crucial the whole team is aligned with them.

With this in mind, we created Packmind, a solution that centralizes your team’s best coding practices.

A coding practice in Packmind is made of:

a name
a description
categories
code examples (positive, negative, and refactoring)

Why define and share best coding practices?

As companies aim to deliver value as quickly as possible and avoid bugs that are harmful to their business, they must capitalize on the collective intelligence of all their teams.

Accelerate has highlighted in its study that the most successful companies from an IT point of view have implemented a "Learning Culture," which promotes continuous learning and knowledge sharing. This helps to cope mainly with:

Heterogeneity of skills in teams — everyone can learn from the skills of their colleagues and thus strengthen the team's skills as a whole.
Turnover — newcomers can quickly become familiar with the company's practices, which reduces adaptation time and the risk of losing skills when they leave.
Rapidly evolving technologies — best practices are constantly being renewed, new languages and frameworks appear regularly, so it is important to stay up to date with this. Moreover, on a personal level, this allows developers to remain competitive in a constantly evolving market.

When to create a best coding practice?

For the whole team to contribute to this knowledge sharing, everyone must have in mind "when" he can create a practice.

In order not to leave the working environment, it must happen when you’re writing code (from your IDE) or when you’re reviewing code (on a merge request in GitLab, for example).

Packmind plugins make this creation easier by allowing the team to create these practices in seconds.

2 main scenarios should lead to best practice creation:

A bug has been identified that stems from a poor design or code error;
An improvement has been made to the source code

A bug has been identified that stems from a poor design or code error;

“One should always learn from your mistakes.”

Strongly linked to the "Dantotsu" approach, the idea is to use each bug as a learning source. Each problem is then presented to the team, and one or several practices can emerge from these discussions.

This is obviously also true for potential bugs that could be avoided, for example, if they’re identified during a code review; in this case, the Packmind plugins allow you to create this practice directly when you add a comment during the code review.

For example: A bug is identified in an AngularJS component, a disconnection should have occurred when the component is destroyed.

And here is the associated fix to follow the best practice.

An improvement has been made to the source code

Because the source code is constantly evolving, our practices are constantly being challenged. When a practice evolves, it’s rare to modify the entire source code of the product to follow it. It’s, therefore, common to find many different ways of doing things in the same source code.

When a practice evolves, it must be presented to the whole team, and this change must be recorded somewhere. Otherwise, it’s only local and doesn’t last over time.

These practice changes can be of multiple natures, for example:

A new concept is introduced in the codebase

Adding a new system in the app, to call when adding a new object.

Improvements in the code architecture

Setting up a new pattern to highlight the infrastructure layer level.

An example that features the outdated convention.

Performance, security, and accessibility improvements
Maintainability improvements (such as better readability of the source code).

Sure, we could list a few more, but these four examples are the main ones that would make your team want to start sharing best coding practices.

Wrapping up

In conclusion, it’s key to share practices within the team to improve the lead time and reduce the change failure rate. Tech leads must be the drivers and ambassadors of this approach to boost the involvement of the rest of the team.

It’s important not to overestimate the knowledge of other team members. Known as the Curse of knowledge, this phenomenon translates into the tendency to think that other people know the same things as we do, so we limit the practices to be presented, even though some of them are probably unknown to our colleagues.

These practices should be shared with all the teams in the company and not only with your team. They’re also valuable for the next team members, so we must think beyond our team when we identify a coding practice.

Want to discover a new way to share your best coding practices as a team? Start now for free with Packmind.

Dantotsu method: from bug to best practice

Cédric Teyton — Thu, 26 Jan 2023 09:42:23 +0000

During autumn 2022, I had the chance to attend the great FlowCon conference hosted in Paris, France, whose core topic targets stream delivery in software engineering. Lean, Agility and Continuous delivery are thus highly represented in the conference. One of the talks caught my attention, and I was far from disappointed when I saw it; The talk was realized by Woody Rousseau and Flavian Hautbois (The replay is in French here, but there’s a talk in English on the same topic made at the Craft Conference 2022). I can translate its title to “Radical Quality - from Toyota to IT.” In this post, I share some insights from this talk, especially the Dantotsu method, which was new to me.

Introducing Dantotsu and Radical Quality at Toyota

The talk relates the story of Sadao Nomura, who worked at Toyota between 2006 and 2015 to solve a pain point on quality issues. Before he joined Toyota, the company had a non-satisfying number of internal defects in its factory chains. Because of these bugs, it was common that the requirements to ship cars outside the factory weren’t met. Toyota really wanted to work on that to make sure the expected levels of quality were satisfied more frequently. And so Sadao Nomura came in.

Sadao Nomura aimed to generate a 50% reduction in the number of defects on the factory chains for three years (meaning an overall ~88% of the global reduction for the full period). He told the full story in his book The Toyota Way of Dantotsu Radical Quality Improvement.

Dantotsu means “Better than the best.” This radical approach challenges what companies usually settle to tackle quality issues. What are these ideas?

Eradicate defects and ensure they won't happen again

Why use the radical term when referring to Dantotsu? Because the philosophy isn’t about quickly fixing a defect, it's also about deeply understanding why this defect happened, what's been done to resolve it, and how to avoid this occurring again in the future. These are the core principles of Dantotsu.

In the book, Nomura explains different aspects of the approach, particularly the importance of visual management and the training programs (Dojos), where workers can practice the right gestures to avoid defects. He also provides an interesting classification of the defects. In Tech, we often use the priority (Low/Medium/High…). He suggests using the four following types of bugs:

Type A: The defect is caught within the team and has no impact outside ;
Type B: The defect goes to another team within the company ;
Type C: The defect is undergone by a third party or subcontractor ;
Type D: The defect is undergone by the customer/final user (the worst situation, of course).

Now, what happens when a defect is identified? In the context of Toyota, when a single unit has an issue:

the team leader in charge of the area first makes sure that no other pieces have the same issue;
the root cause of the issue is identified and fixed;
counter-measures are taken to avoid the defect from happening again;
a report is shared with the whole team to explain the 3 previous points;
It doesn’t stop here. The team leader also reports to other team leaders of areas where a similar defect can occur, and they’re trained to fix the issue as well.

(The process has 8 steps for the record, which I’ve summarized for simplicity).

And all this process happens in 24 hours. Radical right? Speed is key. When we see a defect, don't just fix it. We don't want to see him again. This approach turned out to be successful in practice at Toyota.

Dantotsu in Software Engineering?

The second part of the talk was about how the Dantotsu method was implemented in two tech companies. They recall that, in software engineering, there’s still work to do to convince people that doing things right costs less than non-quality (surprising, right?). If you’re skeptical about this statement, we recommend you to read The Economics of Software Quality which precisely demonstrates the cost of bad software quality. The Accelerate book closes the discussion on that question if it's still needed.

The two speakers in the talk explain that to reach the zero-defect (utopian) ambition, the key part is to train developers to produce source code with no defects. They also transpose the bug categorization into the software engineering world, so, for instance, Type A is a defect caught by developers locally or during the continuous integration step. In their respective company, they've both implemented a new process where defects are documented, especially the investigation and the countermeasure. Here's a capture of one slide that encompasses all the information:

Here, we can see the deep level of details where they go to document what's been wrong, and indicate that the countermeasure was to consolidate the tests. (Disclaimer: not surprisingly, consolidating the tests is a common countermeasure). NB: the two quoted companies in the conference used wiki-like systems to document these defects.

Also, in their companies, they've set regular meetings dedicated to bugs. In these sessions, someone can present to the other participants a bug report and goes deep into the root cause and how to prevent it again. Similar to what happened in the Toyota factories, someone is showing the right gestures to avoid a problem happening again. If the sessions can be opened to anyone, it can also gather the Tech leaders, who will ensure the message is broadcasted to their respective teams.

What were their conclusions after the implementation of this methodology? I won’t mention all the details, but here are some interesting insights:
Pros:

A strengthened culture of software quality and more open discussions around bugs;
One of the speaker’s team achieved an 81% decrease in defects in production in 3 quarters. The trend is less visible at the company level, even though it is positive, but it’s a longer-term goal to show results at this level;
For the other speaker, they had a 50% reduction of new bugs in production in 3 quarters, and also, they got twice more bugs resolved in less than 24 hours.

Challenges:

Hard to address the stock of bugs, especially if they were introduced several months ago. Speakers talk about doing Archaeology sometimes;
A deep analysis of a bug requires time (~2 hours) for someone trained, but Tech Lead has others duties in their work. So there’s a balance to find;
Sometimes discussions go beyond technical aspects, to address collaboration issues related to communication or pressures on delivery (that still need to be solved as well).

So yes, the Dantotsu philosophy can be transferred to the Software industry. It’s easier to fix a defect in our code when others developers have met it before. The overall method won’t be smooth and easy initially, but it’s worth a shot!

From Defect to Coding Best Practice

We saw that when a bug is found in the source code and fixed, this should be turned into shared knowledge for the team (so that it won't happen again, remember?). That's what's shown in the screenshot above. An easy way to perform this operation is to use the Packmind platform, which aims to ease best practices sharing in engineering teams with deep integration in developers’ tools (IDE & Code Reviews). Developers are keen on sharing best practices in many situations, such as performance improvement, security fixes, better readability, or bug fix.

Let's see an example of how to proceed with a concrete example of a defect fixed in late 2022 internally. In our staging environment, before a final release, we spotted an error when our application started and performed patches on the MongoDB database. In our code, a method from the Mongoose framework was called to regenerate the indexes of a collection. We observed runtime issues and found this method should rather not be called in our context (this last point is an important precision; I'm not saying you should never call this method, but in short, it wasn’t compatible with our system).

Let’s see how we propose to adapt the Dantotsu process to Packmind.

1. Identify the defect & fix it

The defect has been spotted in the code, and we removed the call to reIndex(). Before that, we created a best practice from VSCode using the Packmind extension: Selection of code → Right Click → Packmind → Identify a new best practice. Just put a name, and this is sent to the Packmind application.

2. Report with the team & beyond

Then, with Packmind, our team (a project team, feature team, or even a community of practice) runs regular workshops to review best practices proposals. Each contributor explains the intent behind the suggested practice. In our case, Arthur explained to the whole team the issue met with the reIndex function call, and everyone could indicate if this was clear to them.

Once the best practice has been validated, it can be shared with others teams in the organization, or within a community of practice. The knowledge is spread beyond teams.

3. Implement countermeasures

Once a best practice has been validated, you can set regular expressions that match the pattern you want to avoid to push notifications in developers’ IDE and Code reviews (a linter-like behavior). This will be possible if your pattern can be matched by the syntax of the code. It will reduce the risk that this method will be used in the future.

This is what it looks like when configuring a regex in Packmind, and then getting suggestions in VSCode:

4. Train people

When new developers join your organization, they need to get familiar with your best coding practices, and also the patterns to avoid defects. In Packmind, there is a feature called onboarding workshop for new hires, where they can train on your knowledge base. As each best practice has associated code files, each recruit will be invited to locate the area where the best practice has been followed (or, inversely, not applied). In the example below, they’ll need to highlight line number 6:

What happened here is that we caught a bug and fixed it, and in addition, we capitalized on our work and generated a new best coding practice from it. We tried to follow the Dantotsu philosophy!

If you have never heard about it before, I hope this short introduction helped you to get a better overview of Dantotsu. I'd be happy to have your feedback. Have you implemented the Dantotsu in your context? Please share!