Squeaky Clean Code: How to Develop & Adopt Better Coding Practices

 

Kristi Perreault, Principal Software Engineer at Liberty Mutual Insurance, presents her talk entitled  Squeaky Clean Code: How to Develop & Adopt Better Coding Practices. Kristi shares a little about Liberty Mutual gives a clear definition of clean code and then outlines detailed steps for implementing practices that allow you to build it from the start.

At Liberty Mutual, we actually have nearly 45,000 employees, and 5000 of them are in technology, and we’re spread out across 29 different countries. We’re one of the Fortune 100 companies. We’re also the sixth-largest global property and casualty insurer. We’ve received many awards. We were voted one of the best places to work in IT this year. We’ve had a perfect score of 100 on the Corporate Equality Index, and we’ve also been voted one of the best places to work for women, diversity, new grads, and LGBTQ equality.

Clean code is defined as code that is easy to understand, easy to change, and follows good standards. This is defined by Robert C Martin, who wrote the Clean Code handbook. Clean code answers the questions, of what, how, and why. It is also re-factorable. As we know in technology, things are changing all the time. Your code should be written in a way that it can handle these changes and these updates. It should be pretty easy to do these things in clean code. It is also maintainable. Building out features, and new aspects, and maybe building more micro-services to interact with it, should be easy if your code is clean. It should be formatted and readable. Finally, clean code is easy to test. Writing unit tests, writing integration tests, or even manually testing this out in other environments should be easy to do with clean code.

Clean code is not commenting on everything. Adding comments might make it easier to understand, but it’s not going to hit all these other things, like being re-factorable and maintainable or answering some of those questions. Making it look nice does not mean that the capabilities are going to be clean and it’s going to be easy to interact with. There’s no one way to do this. There’s no golden standard. Take what resonates with you and leave what doesn’t.

The first thing is your team’s coding standards. This is a standard document that your team will agree on and set for your code. This is different from a team working agreement. A team-working agreement would define how you run your ceremonies, how your team interacts, and maybe how you want to handle working with the business side of your team. A team coding standard should be a living document that outlines standards you set on your code specifically. You’ll want to revisit this pretty often. The most obvious times are when you gain or lose a team member, or do the same with a project. I would recommend, if your team does retrospectives, it is a good time to bring this up and revisit it.

This is something that my team likes to follow. We have a recommended toolset. What kind of programming languages do you want to use? What kind of plug-ins do you want to be associated with that? What kind of IDE do you want to use? Define your branching strategy. If you want to do feature branches, how do you want to name them? Define your testing strategy. How do you want to write your unit tests and manual tests? Define your language-specific guides. What version of JavaScript or TypeScript do you want to use? What kind of style guide do you want to follow? I have found that the Google style guide has been helpful. I’d also recommend keeping your code review policy and your ReadMe outline in your team coding standards.

The next piece is your environment setup. I would highly recommend you do this as a team and try your best to stick to the same tools. It makes it really easy to help onboard folks or to troubleshoot code. Live code sharing is another cool tool. If you haven’t heard of this, it’s basically like Google Docs, but in an IDE. VS Code has a plug-in for this called VS Code Live. It’s a great way to pair or to mob on stories. You can include this in your environment setup. Make sure you’re following your code standards. As you’re going through the environment setup, you might find that something in your code standards doesn’t line up. That’s why it’s a living document. Make sure you’re staying consistent across both things.

Let’s discuss documentation. Starting at the lowest level, comments. There are method-level comments and line comments. Method-level comments or definition-level comments are useful when you have a lot of heavy logic, or if it’s something that needs a lot of clarity. This could be in your service layers, an API, or a controller that you’re trying to define. It could be anything where it isn’t clear or there’s a lot happening. Intuitive code shouldn’t need comments. If you’re naming things appropriately, it’s very clear what they’re doing, and you’re keeping them pretty small, which are all good practices to follow, then you shouldn’t need to comment a ton. Don’t comment on everything and then say that it’s clean because in some cases, it just makes it longer and a little bit messier.

You should always include a ReadMe for your project. This is your home base for everybody. It’s for you, other developers in your code, and community contributors. It’s sometimes for the business side to understand what’s going on in your space. I would recommend that you follow a standard template for your ReadMe. There’s nothing more frustrating than having great documentation and not knowing where to find it.

One of the things we like to do is also call out some of the key resources we’re creating in this project, a short description of what each thing is doing and maybe what it’s named. It’s pretty clear right off the bat exactly what you’re generating in this project or maintaining. Probably the most important thing is to have instructions on how to build and run your project locally. It’s a good way to keep up to date with what versions and things you’re running. List out what your required installs are, the version of Python or JavaScript that you’re running, and then link out to those resources as well. It makes it really easy for folks that are just getting started with your project to do a couple of quick click downloads right away and they have everything they need right there.

Include the actual instructions for how to build and run locally. Copy and paste the exact commands that you’re running so that everybody can use it. It is also nice to copy and paste to run your command, so you don’t have to click through your command line window. Do the same thing with your tests. Write out the steps to run your unit tests, maybe you have to change into a folder to run them, or you might be testing manually. APIs are a great example of this, and this also kinda goes hand-in-hand with the endpoint documentation piece. Call out exactly what endpoints you’re trying to hit, what you would expect the request body to be, and what you would expect the response body to be. External documentation is the last piece of documentation. Make sure you’re linking them so that your documentation isn’t all over the place, and it’s all together.

Use code reviews as a learning tool. It’s good for junior and senior levels, there are great things to learn from code reviews. Ask questions and have discussions. The logical comments will come more naturally as you start to learn and get more into the code. If you’re more senior, this is a great opportunity for you to explain why or how you did something. It gets you practicing by explaining your method to more junior folks and mentoring folks. One of the biggest questions or things that I hear about clean code is, how do I get this prioritized with my product owner? My three big things here are time, cost, and security. They tend to be the three things that companies really care about as a whole. If you’re doing these things upfront, it is going to take a little bit of time, but the time and the money that it’s going to save you down the road is huge. Enjoy, be flexible, and change things up. Take what resonates here and try to apply it to yourselves and your teams.