loading...

How do you ensure your Team's code is consistent?

parkadzedev profile image Michael Parkadze ・1 min read

I think that one of the most interesting part of building a project and working with a team is making sure that you all work as one single unit and understand each other's code.

One of the least discussed subjects that I think should be talked about more is exactly that, So when building a new project with a group of developers, How do you ensure that the code will be kept consistent for a long period of time?

Discussion

pic
Editor guide
 

How do you ensure that the code will be kept consistent for a long period of time?

Our first step, was code formatting (language specific, since we use a few languages). I put a formatter together in IntelliJ that makes code readable for me and shared with the team. I also shared a couple of git pre-commit hooks (one for Windows, one for Linux), so that git will format all source just before commit. Thankfully we all use IntelliJ.

Then I've told the team "if you think we should change the formatting, lets talk about it - this is just a starting point to get us going, formatting should work for the team average."

After that, is automated code-quality metrics - we use SonarQube as part of the build/review process. As with formatting, the whole team are welcome to add/change/remove rules over time.

But that's the easy part.

The next step, was to get the team to separate commits - for each unit of work, I expect at least two commits. The first, or first few, will be "make the damn thing work" and the last, or last few, should be refactoring. Of course, if you pick up a legacy project and you're struggling to read it - refactor it first, then make it work (and then probably refactor again). There's also times when PMO are breathing down our backs, because we live in the real world, so sometimes skipping refactoring is OK, but if we're doing that too often, it's my job to tell PMO to back off a little.

The much harder part, is frameworks and design patterns. Those tend to be discussions over time, and we don't always get it right, but who does?

 

You covered some real good points here. I find it really hard to get a consciousness on these things. When a team of 7 uses 7 different editors and are not comfortable with following a single formatter its always a battle.

 

I'd suggest there that the team leadership (Lead/Architect/Manager etc) needs to adopt a "god complex" approach.

"I have spoken, therefore you will do."

When the team all pull in the same direction, consistency is easy (our discussion about code consistency lasted a grand total of 15mins). When each individual likes to impart their own personality on the code base, you'll never achieve consistency, unfortunately.

Thanks for commenting, I've found your answer very informative ;)

 

A basic way to ensure code style consistency is to pick a specific coding style and use a code style tool like eslint to make sure all the code in the project is consistent. If you aren't particularly opinionated and just want a basic ruleset to follow, there are specific configurations you can find. Assuming you're doing JavaScript development, there are packages like Standard JS and xo which basically simplify linting even further by having their own style rulesets you can plop into a project with basically no configuration. Other languages have various code style checkers as well.

Even if you don't use one of these automated tools, you should also specifically document your coding standards somewhere. If you look at any sizable open source project you'll typically find it has some kind of "Coding Standards Guide" somewhere that lists out the various standards they use for the code in the project. They probably use automated tools to check coding standards as well, but reading through a written document is much easier than parsing through JSON configuration for one of those linter tools.

Of course, having a linter tell you when your code doesn't match the basic coding style guidelines doesn't mean anything if you don't actively pursue coding consistency. If you want to make sure your team's code is consistent, you need to ensure that consistency when reviewing each other's code. If someone wants to merge a branch that doesn't match coding standards, it shouldn't be merged in until it does match those standards.

 

Thanks for commenting ;)

Checking an open source project sounds like a great idea! also about persuing consistent code, is there something that can be used to review code before it's being merged?

 

I'm not an expert in that specific area of tools, but I do believe there are tools to review code and automatically report that on pull requests or otherwise show the build as failing (as if you checked in code with failing unit tests) if code styles don't pass.

 

The most important thing is that agreed dimensions of testing are done. Minor stylistic differences are trivial compared to the harm of no tests, or tests that don't exercise the problem domain correctly.

 

I would lay down a list of standards that every member of the team should follow before committing the changes to the repository. The list could include stuff like:

  1. Setting naming convention for variables, class, method, etc, so that code written by every member looks the same.
  2. Fixing code alignment
  3. Making the team aware of OOPS and SOLID principles when writing code. This makes a developer think thoroughly what part of the code belongs to what other parts.
  4. Writing simple and readable code segments. Breaking down a complex/ a tall method into simple blocks can enhance readability and avoids potential bugs.
  5. Code review on a timely basis. Making it a practice among team members is important.

Writing clean and consistent code is an art.

 

If talking about logic and structure, that is something that is way harder to maintain consistently because we all think differently and might prefer different methodology or coding style for different things. There are many things that can be enforced, but project will never be 100% by standards if multiple developers work on it and that's ok. Something will sneak in eventually.

If you are talking about code style that can be enforced through linting tools and formatters, then you can for example add git precommit hooks that run those linting tools before each commit attempt. If there are linting errors, you just don't allow this code to be commited. This way you can automatically prevent errors from being commited into the code base and so you shouldn't have to worry about those during PR reviews because people won't even be able to commit those things you set as errors. You can also use tools to format code in this stage so all code will have consistent indentation and styling, which I find really valuable because it's easier to review and read code if it's formatted consistently (at least to me personally).
Using git hooks will also make it so that you don't have to enforce certain tools or IDEs for developers, so they can use whatever editor they want, your hooks will still run and do their job.

Of course, before that can work, you need to find linting tools you want to use and agree upon certain "standards" you want to enforce. For example, if doing JS/TS work, you will probably use ESLint and you just have to create your own ruleset or use some of the existing ones if you agree with them. Prettier can be used to format code, again if talking about JS/TS or even HTML and CSS in Prettier's case.

I think you will never be able to enforce things to achieve super clean code and that's fine. We sometimes get obsessed too much over "clean code" when many times we just need "code that works". Of course having a structured codebase helps a lot, but there is no need to get super stressed about it.
Sometimes you just don't have time and things need to get shipped so you just whip a quick fix for something and place that "TODO: Refactor this" comment that then stays in that code for 5 years without ever refactoring because it just works and that's the most important thing at the end of the day.

 

On top of what is already said, I will add :

first make it work, is your code working ? Does it solves a business problem? Is it adding the value to the company?

Since you said about teamwork, all is to about having good coding conventions ..

Every software engineer said writing the right quality code and consistent code is important but few people made a habit out of it. The problem is not knowledge but consistency.

How to make it a habit?

I will grab some concept from James Clear's book Atomic Habits:

Let me explain how to apply the 4 laws of behaviour change in coding :

1.a. Make it easy and Obvious :

  • Use automatic tools , linter, code quality reviewer like CodeClimate

  • Setup a coding style in your IDE and use auto format feature to format your code according to that style

1.b. Make it hard and invisible :

  • Using tools that block pull requests to get merged if they are not following code standards , I used HoundCI before .
    • Use pre-commit hook that block people to commit code that is not linted.
    • Add a rule to your Git tool to stop people from merging their own merge requests and for other team members to not merge a code that is not reviewed .

2.a. Make it attractive :

  • Explain to your team member the benefit of writing good quality code and how it will make them better software engineers .
  • Do the same for business stakeholders , explain them why technical debt is so bad for the product.
  • Encourage team members to contribute to open sources project to see how those projects are consistent in structure and quality.

2.b. Make it unattractive :

Explain also why it's so bad to write poor quality of code and inconsistent code, and explain how it can lead to some bugs in the future.

3.a Make it satisfying :

What is rewarded is repeated!

  • Use code coverage and congratulate people every time they merge a code that has 100 % of code coverage.
  • Rewards everyone who follow the code conventions in your team :
  • Rewards team members for their open source contributions.

3.b. Make it unsatisfying :

What is punished is avoided!

  • Setup a punishment for people who deliberately follow bad coding practice and violate the team rules