It all start with style in which one writes code. It's the form, not the function that is first apparent when one looks at a code base. This form is the style used by the authors of the code base : the specific way to write using the programming language(s), the way to name and organize files.
That's where a team starts actually : when team members start to define a way to write the code. It can be done in a very purposeful manner but it can also be happening without any specific attention to it. Nuances to the existing patterns are added with each new member of the team. For each of them the resulting patchwork might be harder to read and start on.
Guiding with some soft touches
Many teams will have a set of guidelines and styleguides included in the welcome package of any new engineering person. The aim is to give something to browse to catch up on how the team is doing things so that new comers can fit it more easily.
A small team probably doesn't have that, except if it's full of senior people. With some years of experience we usually bring our stylesheets and guidelines from one team to another. In such cases it's part of the starting points of the project.
It's never too late to adopt and adapt one. Of course there is a big pile of code that needs to be altered. It's a mountain that can be climbed one step after another, one recommendation after another.
Linting tools can be configured to only apply a very limited set of rules and checks first. It's probably wise to start with rules and checks that are already pretty much in place, that way the first set of patches to put everything "green" for those won't be too big.
Then, as time passes, other checks can be activated, as the team tackle the relevant code. And so on. At some point it will be all done, and the code base will match the guidelines devised by the team.
Linters can be run locally (even through your favorite editor) or in a continuous integration pipeline (CI). Having the latter running linting checks for every commit is good practice, it will give a quick feedback on how the commit is, and it will be a step of automatic code review.
Reducing cognitive fatigue
Beyond making a code base "look nice", linters help reduce the cognitive fatigue. By agreeing and checking automatically a certain coding style the team removes a lot of hurdles for its members.
Having an agreed upon coding style let developers focus on what the code is doing rather than the different nuances of how it's written.
And if the coding style is also attached to a set of guidelines of how most things are architectured and done in the project it's even better as the developers can simply build bricks following the patterns.
Such guidelines are usually broad but give a good sense of what kind of brick is doing what and how the files are arranged accordingly.
If a style guide is about the form of the syntax, the guidelines would be more about how different kind of classes or modules of code are organized in the folders, how and where clients to external services are written, and so on. Those guidelines can come out as practical example files or projects, or documentation.
Guiding, not forcing
As with many things it's good to remember this is a starting point, there is no need to be rigid with all this. Change take time, and change is constant. There just need to be a start, things will proceed from there, we just have to tag along.
Such an approach falls directly into the ideas behind Agile practices, and other like it. Any efforts by the team members will for sure evolve in time, based on the context team members evolve in. Retrospectives and day to day operations will provide opportunities to adjust any styleguide and guidelines along the way.
It all starts with one first step though.
- a set of styleguides around Ruby : https://ruby.style/
- python PEP8 : https://pep8.org/
- Github's set of style guides : https://styleguide.github.com/
Fancy talking more on this topic ? Contact me to discuss how I can help your team establish or refresh a styleguide and some guidelines in your projects.