Forem: hexdevs

How to Improve Code Quality on a Ruby on Rails Application

Stefanni Brasil — Thu, 11 Nov 2021 21:45:59 +0000

Does it take forever to ship even small features on the codebase you're working on? Is the code hard to understand and maintain?
Are projects always running over budget? Are you constantly sacrificing code quality and not paying down technical debt?

When you change one feature, does another completely unrelated part of your app stop working? New bugs appear, even though tests never break? 🥵

Those are signs that you are suffering from working on a codebase with low code quality.

How can you get out of this mess? Is it possible to avoid getting into this situation in the first place? Yes, it is!

By the end of this post, you'll know exactly:

How to improve Code Quality on a Ruby on Rails application
Which Code Quality tools to use
How to use the Ruby Code Quality Checklist to get out of the tar pit

This post is based on a talk from Ernesto Tagwerker's talk entitled Escaping The Tar Pit at RubyConf 2019. Ernesto is the Founder & CTO at FastRuby.io & Ombu Labs.

What is Code Quality?

"Software Code Quality means it works as expected AND it isn't a PITA to maintain it" -- Ernesto Tagwerker

The simplest way to know if your codebase has enough Code Quality is if your team can easily add or change features without breaking
unrelated features.

And when the features do break, the test suite easily detects the problem before you even push the code to production.

In summary, a quality codebase is easy to read, change, and maintain. It also has good code coverage, and the test suite helps you improve and refactor the code, or change features with confidence.

How To Improve Code Quality on a Ruby on Rails application

There are four steps you need to follow:

Measure and Assess Code Quality
Measure Code Coverage with SimpleCov
Calculate Churn and Complexity with RubyCritic
Use Skunk to identify which files need urgent care

How to Measure Code Quality on a Ruby on Rails Application

You don't necessarily need a tool to assess Code Quality, and there is no silver bullet. You'll always need to evaluate what the data means. The tools help guide you so you can make the best decisions by yourself 💫

Below are some tools and services to quickly assess code quality. You can use paid services such as CodeClimate, Codacy, and CodeScene to give you some measurements and reports.

Or, use open sources tools to help you perform static code analysis, calculate code coverage and point out code smells and refactoring opportunities.

Here's a list of tools you can use:

Coverage: Ruby's built-in tool that provides coverage measurements for Ruby.
SimpleCov: a code coverage analysis tool for Ruby.
RubyCritic: a gem that wraps around static analysis gems such as Reek, Flay, and Flog to provide a quality report of your Ruby code.
Skunk: a tool that helps you find the most complicated parts of your application that also have low code coverage.
Rubocop: a Ruby static code analyzer and formatter, based on the community Ruby style guide.

How to Calculate Code Coverage With SimpleCov

Use SimpleCov to generate a report of how many statements are covered by your test suite. It won't assess the test suite quality, though.

It will affect your test suite performance, so make sure to only run it when necessary.

How to Measure Code Quality With RubyCritic

Ernesto recommends RubyCritic because it's a gem for assessing code quality that it's still actively maintained.

RubyCritic provides a score based on churn and complexity. These metrics help you identify files that are great candidates for refactoring.

Check out the talk at the minute 17:47 to see how Ernesto analyzes the report generated by RubyCritic:

How to Find Code Smells and Calculate SkunkScore with Skunk 🦨

A SkunkScore is an assessment combining code smells, code complexity, and code coverage.

Skunk's main goal is to serve as a compass for the first steps in your refactoring adventure. Focus on the files with a high skunk_score with a decent code_coverage score. That means you can get started with files that have code quality problems but also have tests, which makes this step easier.

Make sure to add a reminder to add more tests to the other files with high skunk_score and low code_coverage 📌

Tip: When working on new features, run $ skunk -b main against your feature branch to give you an idea of the features you're adding are improving or decreasing the code quality.

Ruby on Rails Code Quality Checklist

Now that you have gathered the code quality data, use this checklist to start moving out of the tar pit 🏊‍♀️

1. Delete unused files with Coverband 🪦

The best code is no code, right? Dead code is code that is never executed and is just filling up space. In larger or older applications, dead code can be a very common thing.

Find dead code with Coverband, which can be run in production.

Or add a "tombstone" inside a method you want to remove, push it to production and wait. Check again in a few weeks or months, and if the code is never executed, you can safely remove it.

Here are some other libraries to detect dead code:

2. Refactor the complex files with better code coverage first 💇‍♀️

Refactor complex files that have at least 60% or more code coverage.

Sandi Metz's "Polly Want a Message" talk has an approach for refactoring classes with lots of responsibilities.

Tip: Compare code quality improvements by running $ skunk -b main. It will show you how much it improved. Such a great metric to share with your team! 🎊

3. Write tests for the files with high skunk_core and low code coverage 🧹

Writing tests will decrease a file's skunk_score. Skunk gives you a list of good candidates for your next test-writing efforts.

Keep track of Code Quality by analyzing the SkunkScore Average. It's recommended to run the report every 3 weeks to evaluate the team's engineering practices and if the project is moving in the right direction.

4. Celebrate tiny wins often 🥳

Improving code quality is a hard task! Make sure to celebrate every tiny improvement along the way with your team. Enjoy the relief of working on a great Ruby codebase.

We highly recommend you watch the talk. The best part of this talk is to feel like there's hope and that getting out of a tar pit is possible.

The questions he asked such as "What is code quality anyway?" are helpful to change the perspective on how to approach technical debt more humanely.

After all, technical debt has the name technical in it but it's more a result of social/cultural problems in a team.

Judging past decisions is easy and unhelpful. That's our default. Embracing the challenge and being open to the opportunities for improvement is the real challenge.

Now, go follow the checklist to assess your Ruby Code Quality and create a livable environment for your code.

We watched Ernesto's talk at a previous Watch Party. We host tech talks watch parties every 4 weeks, on a Saturday morning 📺

New job, new codebase. How do you even get started?

Thiago Araujo — Fri, 22 Oct 2021 00:55:55 +0000

One of my readers asked:

How do you get started when you join a new company? How do you add features to a codebase that is massive, scary, and completely new to you?

The first day at your new developer job is just like the first day at a new school. 🚸

A sea of stranger's faces watching your every move. Unfamiliar smells in the hallway.

Every chair is uncomfortable and makes weird noises when you sit. "Eek, there's chewed-up gum under the seat!"

The cafeteria, as expected, serves undrinkable coffee.

Just like the first zoom meeting with your new team.

Are they friendly and cool people? Will they think your code sucks?
What about that Github link they've just sent you? Urgh, look at all that foreign code!

Your first day at your new job can be quite scary.

But what if you could feel confident, supported, respected, and comfortable collaborating with your new team?

What if you knew how to find your way around any codebase?

What if you could be so focused and productive that you don't even notice time passing? Your working day goes like a breeze!

After you read this post, you will know what strategies to use so you feel comfortable and know exactly how and where to get started 🌟

Before You Join, Take Time Off

This might not be possible in every situation. Do your best to take some time for yourself.

Take some time off before you start at a new job. Two weeks at the very least. Take this opportunity to start fresh and spend a couple of weeks relaxing and clearing your head.

Having this extra headspace will help on your first week as you learn new things and get to know your teammates.

The reason you feel so tired on your first week even has a scientific name: it's called Acculturation. It's hard for anyone.

Companies might try to pressure you into starting as soon as possible, but it's always your choice.
Assertive communication and taking care of yourself are qualities of a confident software engineer.

Ask for Onboarding Materials or Documentation

Ask if the company has any kind of onboarding materials you can look at the day before you join.
Try to learn more about the stack, the codebase, and how the team works.

For a startup, it's always good to look at their pitch deck so you can understand the problem they are solving and what kind of customers they are serving.

Some companies won't be able to share anything with you before your first day for confidential or security reasons, while others might.

In the past, one of my colleagues was given access to our codebase and got paid to work on it as part of the interview, which is a very neat way to get people onboarded more easily.

Onboarding Buddy

When the company has some form of onboarding process plus good documentation, it makes things so much easier. Take advantage of it.

Having an onboarding buddy helps a lot in your first few weeks, as you get to know your team, the company's culture, how the product helps customers, and how people collaborate.

Having someone to talk to and support you on your first week is very important.

This onboarding buddy should also help you set up your dev environment. If there's no onboarding process in place, you can always ask for an onboarding buddy. Help them understand the value of good onboarding and get the ball rolling.

I've managed the onboarding process for one of my past employers and we've onboarded dozens of software engineers. Every one of them said that having a good onboarding process made them feel much more confident, welcomed, and productive.

If there's no go-to person to ask your questions, or you don't feel comfortable asking for someone to help you in your first few weeks, read on. There are a couple of other things you can try.

Update the documentation and onboarding materials (optional)

When you are getting started, it's always good to update the documentation being used for onboarding. It's often out-of-date, so it's a good opportunity to make things better for yourself
and your team in the future.

That's an easy way to show your peers you are a team player and you are committed to making things better for everyone.

Issues and Feature Requests: Make Sure You Understand Them

First and foremost, you have to understand what a new feature is supposed to do, and what would it mean for it to be "done and complete." Teams often have different interpretations of done.

For some, 'done' means 'tested and shipped to production'. Other times it just means 'ready for QA'.

Work with the person that created the issue or
feature request to make sure you understand it well.

Not every team is good at writing and explaining things well on paper. Trying to understand what you need to do just by looking at the issue description or feature request can be challenging. You will be missing a lot of context as a new member of the team.

Don't be afraid to ask questions if you're not sure what needs to be done, and take notes. Updating the issue/feature description always helps.

Write well, be kind to your future self.

I love writing good and descriptive user stories even if it's just for me to read. They help me a lot a week from now when I don't even remember what I'm supposed to build. Happens all the time. 🤷‍♂️

Latest Merged Pull Requests: A Gold Mine of Information

After trying the usual stuff such as looking at the documentation and potentially outdated READMEs, you can move on to the next step:

Look at the latest merged Pull Requests

One thing that helps the most is going through the latest merged pull requests and seeing what happened and how they look.

This is the best way to see how people approach building new features on your team. Pull Requests usually have linked issues or feature requests you can read as well.

This shows which parts/modules/classes/files in the system usually need to be changed in order to ship feature X or Y.

For example: let's say the latest PR shipped the orders endpoint.

You look at the diff, you might see this:

a new database migration
a new model
a new controller
a new policy
changes to the routes.rb file
a new serializer and/or views
new tests: feature tests, request tests, model tests, etc.
a new factory
documentation updates
etc.

Sometimes a feature touches infrastructure code as well (terraform files, CI stuff). Some teams ship database migrations in a separate PR.

Looking at the diff/code changes helps you see what needs to be done.

Collaboration

You will also get a sense of how the team works.

For example, you might get answers to these technical aspects:

How much test coverage is good enough?
What's the coding style people follow?
What are the conventions and best practices being followed?
Which libraries are being used?
Which patterns are being used and how code is organized?
Do people open large Pull Requests or small ones?
Do people split changes into frontend and backend changes?
Is the project organized as a monorepo or a multi-repo?
How does the CI/CD look like?
How code gets deployed (manual vs automated deployments)?
How and when do database migrations get merged?
Does the team refactor code and pay down technical debt? When?

You will learn how people give feedback. How much do they nitpick on the small stuff. How much bikeshedding is allowed.
How technical discussions are conducted.

Some teams care about good architecture and design. Others like to do incremental changes, refactoring, and paying down technical debt when needed.
While others don't really care about any of this stuff and prefer to move fast and break things.

These are useful things to know and expect when you submit your first PR. That will give you more confidence.

Take a peek at `routes.rb`

One simple trick is to look at config/routes.rb first.
Routes give you a sense of the endpoints and features that are available without having to go too deep into the codebase.

By looking at the routes, you will know if the project has an external API or not, which is very useful information.

Read Related Code

Take a look at code related to the feature you're working on. Models, Controllers, and the Schema or related migrations are good places to look.

Let the Team Help You: Submit Your PR and Ask for Feedback

Your new team wants you to be successful. That's why they hired you in the first place: because you're a great developer and you kick ass!

Let them help you be successful.

You can always submit your PR as is and wait for feedback. Let people help you finish it. You'll never know everything up front, there's no point in trying to make it
perfect on the first try.

If you get stuck, ask for help. Let people help you! There's no shame in that.

Remember to add enough context in the Pull Request description so people can understand what you are trying to do.

How to receive feedback

Constructive feedback is always valuable. Listening to constructive criticism is how you learn and get better.

Ask: what can I learn from the feedback I've received?

Ask questions so you can understand their point of view. Be curious and open-minded.

Don't worry too much if people request changes or point to you things that could be improved. Don't be afraid to make mistakes.

Ask: did I add enough context in the Pull Request description?

Sometimes they don't have enough context into what you are doing. In that case, add more context to help them.

Sometimes they have a point and they are right. Be flexible and open, as they are giving you feedback so the team can ship good code. They could be asking you to follow some of the team's conventions that you might not know of.

Other times, the reviewer just thinks differently than you. This is also fine. No two developers would ever write code in the same manner or style all the time. For these types of requests for change, you can politely disagree.

With time you will learn how to separate changes that are "nice to have" but don't make any real difference, and changes that are really important.

Having integrity and being assertive are hallmarks of a confident coder. Be graceful when receiving feedback. Even if people do criticize you for no good reason, don't take it personally.

Be kind, be gentle, and remember: your work does not define your value as a person.

Asking questions is an effective way to change your approach to receiving criticism. By asking a question, you stop judging yourself or others, and you start to be more curious.

The Confident Developer Onboarding Checklist

Here's a quick checklist you can use for self-onboarding ✅

[ ] Ask for some time off before I start
[ ] Ask for documentation or onboarding materials
[ ] Take advantage of the onboarding process
[ ] Find an onboarding buddy
[ ] Understand the issue or feature request I'm working on
[ ] Look at the latest merged Pull Requests
[ ] Take a peek at the routes.rb file, or any code related to my work
[ ] Let the team help me
[ ] Get out of code perfectionism paralysis
[ ] Ask for feedback
[ ] Learn from the received feedback

If you have other ideas that helped you in the past and want me to add them here, please let me know! 💡

Hope you apply these strategies to give you more confidence in your first few weeks at your new developer job.

Print your checklist and don't forget to use it! Bookmark this post and share it with any friends who need to read this ⭐

Before I forget: congratulations on getting a new job, that's awesome! I wish you all the best!

Do you want to become an expert developer?

I write about how to build expertise on the hexdevs newsletter. We do live-coding and live stream events with some software industry experts. Sign up and be the first to hear about it.

Open Source Thursdays Expert Session with Rafael França on August 5th

Thiago Araujo — Thu, 29 Jul 2021 12:00:00 +0000

Open Source Thursdays is a project from hexdevs. We’ve been making Open Source contributions more inclusive.

On August 5th at 5 PM EST, Rafael França will join us as our expert guest. Rafael França is a Rails Core team member and Principal Engineer at Shopify. He is working to define the future of Ruby and Rails at Shopify.

He will teach you all you need to know to get started with contributing to Ruby on Rails.

In this session, Rafael will do a deep-dive into the Ruby on Rails codebase.

You will learn:

How to filter and understand issues
The best practices for contributions
How to ask for help
How to help the Ruby on Rails Community.

We will also have a Q&A session at the end.

If you want to join the Livestream session, click here to RSVP!

Share this event with a friend or a colleague who wants to contribute to Ruby on Rails.

This event is sponsored by Shopify Engineering.

Learn Ruby on Rails Best Practices With One Exercise

Thiago Araujo — Wed, 30 Jun 2021 20:00:00 +0000

You want to write smooth professional-looking code.

You're craving some squeaky-clean code. But all you have for lunch every day is a big bowl of legacy spaghetti code.

You consider yourself a decent developer, but you're never sure how to organize a project. How to name things. Where some piece of business logic should live.

How can you become a Ruby on Rails expert if the code you read every day stinks? 🦨

Is it possible to learn and follow best practices when you're trapped in a big ball of stale legacy code?

Of course, it is!

Start changing your coding diet today by consuming something healthier.

Yes, it's going to take some work. But don't get discouraged. If you want to advance your skills, you've gotta try something different.

Ready to get started?

First: Be Careful When You Ask for Advice

You're committed to advancing your skills. When you ask people for guidance, they tell you to read a bunch of books and start throwing these terms at you:

Skinny controllers, fat models, service objects, design patterns, DRY, SOLID, OOP...

The list goes on.

Is this information really helpful to you? What are you supposed to do with all of that?

The problem is that it's not actionable information, just a bunch of ideas and vague suggestions.

There is a more practical way to learn all this stuff. Here's how.

One Exercise to Teach You Ruby on Rails Best Practices

Instead of reading another book or watching youtube videos about pasta making during your lunch break, do this exercise instead:

Exercise

Set a timer for 10 minutes.
Open this link in another tab: practice.rb from Upcase by Thoughtbot
Read the app/services/practice.rb class.
Ask yourself: What's going on here?
Come back here when the time is up! ⌛

Sounds good?

Okay, now go do it!
I'll wait for you.

...

⏰ beep! beep! beep! beep!

Now that the time is up, answer at least one of these questions:

Why is this class so short? It's less than a hundred lines!
Why is the variable trails being passed down to the initialize constructor?
Did you notice these methods promoted_unstarted_trails and unpromoted_unstarted_trails? Why do you think they were given these names, and what's the difference between them?
What is this class responsible for? 🤔
What else picked your interest?

Write down the questions and your answers to make them stick.

Last but not least:

Repeat this exercise tomorrow, but pick a different class from the same repository.
Add a daily reminder to your calendar so you don't forget about it. 📅

It's okay if you don't understand anything

The goal of this exercise is to notice some patterns. Not to understand every single line of code.

Use your answers to the questions above as a study guide. Even if you answered "I don't know", that's useful information.

It's okay if you feel uncomfortable

Feeling uncomfortable means you're doing something different. You're challenging yourself. You're learning and growing.

If you're thinking "OMG this code is too clean and my code is super dirty!" or "I'll never be able to work on such a clean codebase!", don't worry!

That's okay. That's not the point of this exercise.

The point of this exercise is to read the code and notice anything that looks different or any interesting pattern.

How am I going to learn anything just by reading one class?

It might seem like it's not much.

If you do this every day, here's what's going to happen:

At the very least, you're going to learn how the Upcase codebase works.
You will pick up new ideas and patterns.
You will end up with a list of things you don't understand. That's a great guide on what you need to focus on.
You will see how other experts structure a project to make the code neat and clean.
You will learn how to find answers to your own questions and how to read source code.

That's pretty good, right?

All professional developers and experts have these skills. It comes from practice.

Why Pick a Well-Written Codebase?

Good question. You have to be exposed to good code if you want to advance your skills. Especially if you don't have this opportunity at work.

If your goal is to learn best practices, you have to read a well-written codebase.

Thoughtbot, the company behind Upcase, is well-known in the Ruby on Rails community for setting industry standards and following good coding practices.

What if I get stuck?

When that happens, ask one of your colleagues for help.

If that doesn't work or you don't feel comfortable doing that, ask Rails Forum or Reddit.

You can also send me a DM on Twitter and I'll be happy to help.

Now that you've done this exercise, you will improve your Rails skills every time you practice.

It's just a matter of consistently exposing yourself to good code. Keep using the suggested questions as a guide, or come up with different ones. Pick a different class every day, and keep going.

You've already done the hardest part: getting started. Now keep practicing.

Let me know what you've learned by practicing this exercise.

Bookmark this post to keep the questions on hand. Share it with a friend who will find this exercise helpful. ⭐

Happy learnings! 📓

Do you want to become an expert developer?

I write about Ruby and Software Development on hexdevs and on Twitter. Let's connect!

Forem: hexdevs

How to Improve Code Quality on a Ruby on Rails Application

What is Code Quality?

How To Improve Code Quality on a Ruby on Rails application

How to Measure Code Quality on a Ruby on Rails Application

How to Calculate Code Coverage With SimpleCov

How to Measure Code Quality With RubyCritic

How to Find Code Smells and Calculate SkunkScore with Skunk 🦨

Ruby on Rails Code Quality Checklist

1. Delete unused files with Coverband 🪦

2. Refactor the complex files with better code coverage first 💇‍♀️

3. Write tests for the files with high skunk_core and low code coverage 🧹

4. Celebrate tiny wins often 🥳

New job, new codebase. How do you even get started?

But what if you could feel confident, supported, respected, and comfortable collaborating with your new team?

Before You Join, Take Time Off

Ask for Onboarding Materials or Documentation

Onboarding Buddy

Update the documentation and onboarding materials (optional)

Issues and Feature Requests: Make Sure You Understand Them

Latest Merged Pull Requests: A Gold Mine of Information

Collaboration

Take a peek at routes.rb

Read Related Code

Let the Team Help You: Submit Your PR and Ask for Feedback

How to receive feedback

The Confident Developer Onboarding Checklist

Do you want to become an expert developer?

Open Source Thursdays Expert Session with Rafael França on August 5th

Learn Ruby on Rails Best Practices With One Exercise

First: Be Careful When You Ask for Advice

One Exercise to Teach You Ruby on Rails Best Practices

Exercise

It's okay if you don't understand anything

It's okay if you feel uncomfortable

How am I going to learn anything just by reading one class?

Why Pick a Well-Written Codebase?

What if I get stuck?

Do you want to become an expert developer?

Take a peek at `routes.rb`