SourceLevel

12 Ruby Gems We use at SourceLevel and Why:

Text Handling & Formatting

We are heavy Markdown users! We produce internal documentation in Markdown. The docs page is a static site entirely written in it (and built with Middleman).

In the main app, we use markerb to parse markdown content and convert it to HTML. Comments to Github, issue explanations and repository badges are examples of markdown usage. Although its repository is archived and doesn’t accept contributions anymore, it does a pretty good job. It works with both kramdown and redcarpet. We chose redcapet as our processor.

Another useful gem is charlock_holmes. As accurate as Sir Arthur’s character Sherlock Holmes, this gem detects character encoding for given files or chunks of text. Under the hood, charlock_holmes benefits from the set of libraries from ICU.

Database & Storage

We love PostgreSQL! It is reliable, open-source and has lots of functionalities that make it attractive. The ability to create materialized views is one of them.

Working with views in Rails is kind of messy. That’s why we added scenic to the SourceLevel main app. This gem adds methods to ActiveRecord::Migration that allow managing views in migrations.

We use materialized views to scope content. If you don’t know what it is, here it goes: it’s a SQL query whose results work as stored in a regular table. Long-running queries or segmented results can be fetched from appropriate views reducing both time and code complexity.

pghero gem, besides the ability to kill them if you need, also ships with a UI for you to monitor other performance indicators.

Another essential dependency is dalli. It does an incredibly good job of storing and retrieving memcached records. It’s thread-safe and allows us to run Rails.cache smoothly throughout the codebase.

Read more in our blog post :)

To communicate isn’t just getting rid of syntax errors and making code work. The code should communicate ideas to people through a programming language that computers can also understand.

You should adopt semantic variables, classes, modules, and methods names. For instance, in Ruby, we avoid using particular prefixes such as is_paid, get_name and set_name. In their places, we use directly paid?, name, and name=.

My advice is to use idiomatic and features that the programming language you use offers to you whenever possible, and figure out ways to better pass the message.

Why wouldn’t we be worried about semantics, typos, and styles? We should care for the quality of our code, and the many concepts that define it. You can start by using a #linter to collect some issues from your codebase automatically.

Do you review your Pull/Merge Request before assigning Reviewers?

If you work in a team opening a Pull Request (or Merge Request) looks appropriate. However, have you ever thought about opening a Pull/Merge Request when working by yourself? Here's a checklist of things you can review in your own:

• Pick the correct target branch
• Make Drafts explicit
• Name things properly
• Ask help for tools
• Remove the noise
• Fetch necessary data
• Understand Mergeability
• Pass the message
• Add screenshots
• Be found in the future
• Comment inline in your changes

Read the blog post for more detailed explanation for each item :D

What else do you review before asking for code review?

Using an inclusive language is crucial for fostering a diverse culture. Git has changed the naming conventions to be more language-inclusive, and so you should change. Our development tools, like GitHub and GitLab, already supports the change.

SourceLevel deals very nicely with repositories that changed the master branch to a more appropriate word. Besides, you can use the grep linter the look for exclusive terms contained in the source code.

As the inclusive language gap may happen in other aspects of our lives, have you already thought about them?

One of the magic tricks git performs is the ability to rewrite log history. You can do it in many ways, but git rebase -i is the one I most use. With this command, It’s possible to switch commits order, remove a commit, squash two or more commits, or edit, for instance.

It’s particularly useful to run it before opening a pull request. It allows developers to “clean up” the mess and organize commits before submitting to review. If you follow the practice 3 and 4, then the list of commits should look very similar to a task list. It should reveal the rationale you had, telling the story of how you end up with that final code.