Building up : Styleguide

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.

More on this

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.

Need help ?

We specialise in helping small and medium teams transform the way they build, manage and maintain their Internet based services.

With more than 10 years of experience in running Ruby based web and network applications, and 6 years running products servicing from 2000 to 100000 users daily we bring skills and insights to your teams.

Wether you have a small team looking for insights to quickly get into the right gear to support a massive usage growth, or a medium sized one trying to tackle growth pains between software engineers and infrastructure : we can help.

We are based in France, EU and especially happy to respond to customers from Denmark, Estonia, Finland, France, Italy, Netherlands, Norway, Spain, and Sweden.

We can provide training, general consulting on infrastructure and design, and software engineering remotely or in house depending on location and length of contract.

Contact us to talk about what we can do :