Learning culture in software engineering teams: Wikis & Linters (4/7)

#5 Wikis

Wikis are tools for sharing and centralizing knowledge within an organization. They are often generic and used beyond the Tech professions, such as by sales, marketing, HR teams, etc…

Confluence or Notion are among the solutions most commonly used. Some teams prefer to use the Wiki tools integrated into GitLab or GitHub. We can find several types of content in those tools:

• Technical procedures: setup on a project, release, organization on Git,…
• Guidelines on best practices and architecture rules in the organization
• Learning resources, onboarding guides, …

These wikis are free to access, and their collaborative nature means that each person can, in theory, contribute to enriching the knowledge base. Although these tools embody a wealthy knowledge base, with practice, several limitations are observed:

• Being collaborative in nature, updating the knowledge base is very often restricted to a group of writers (technical leaders), concentrating the effort on a small group of people. In addition, it makes other people feel that they are not involved and cannot contribute to the process.
• The content of the knowledge base requires rigor and organization to be kept up to date. It is not uncommon to find outdated pages on wikis, yet we try to avoid that some coding practices are applied despite they should not be.
• The content produced in wikis remains static and is not integrated into the tools used daily by development teams (IDEs and web browsers in particular). It is challenging to juggle from one tool to another. There is an obvious problem of knowledge dissemination, as there is a lack of an effective method to encourage teams to consult wikis.
• There are generic practices within an organization, an entity, and specific ones within a project, a team… it is not trivial to organize this efficiently to find one’s way around. Moreover, there can be duplication from one team to another if we work on common subjects.

If they are efficient to centralize knowledge, wikis have certain limitations if you want to tailor them fully to the context of a development team. And this phenomenon is even more accentuated if we consider that it takes place in each team if we are in an organization of several tens or even hundreds of teams!

#6 Linters and code analysis tools

These tools have several objectives: to detect potential defects, and vulnerabilities automatically, Code Smells, non-compliance with specific standards, and to provide an overview of these problems on a project. They are mainly used at two levels:

• In developers’ IDEs;
• In the continuous integration process, on the different development branches.

Each linter uses its source code analysis mechanisms. There are tools specific to programming languages (EsLint for JavaScript and TypeScript, CheckStyle for Java, …) and others that are more generic like SonarQube. Some offer the possibility to write custom rules, but they propose a repository of rules in all cases by default.

Highlighting best practices when they are not followed has an educational side. A person who does not know a given rule will be warned: this instant feedback loop helps developers to get appropriate with coding rules.

One must also be aware of certain limitations with these tools. They are generally based on low-level syntactic rules, and will sometimes be inefficient to detect high-level patterns. A solution such as Promyze can address this issue by providing the ability to highlight such rules, which in some cases are impossible to identify automatically. Also, these tools need to be configured upstream with the project context, at the risk of seeing many false positives. Finally, the audited practices must also be well documented to help developers understand how to solve an identified problem.

Linters should be seen as a support for teams, able to cover a defined spectrum of problems in the code. They should not be seen as the only support that can ensure the team’s code quality. Bad code can slip through the cracks of these tools!