Readable Code

Readable code means that the code has a good balance of being easy to understand in terms of what it is doing, and of being concise.

Why does readable code matter?

When code is easy to read, it’s easy to debug, maintain, and extend. 

It’s not uncommon for a developer to write code at the beginning of a system development process, and then realize a year later that they don’t understand their own code and thus will need to re-teach themselves their own system. 

If someone else wrote the code, and it’s unreadable, it’s not uncommon for developers to re-write the entire system as a result, which is an inefficient way to build software.


Structure Your Code

Classes and methods should be consistent, easy to understand, and easy to navigate.

Simplify Your Code

Aim to make your code elegant—simple to read, orderly, and easy to understand. Don’t try to over-complicate things with elaborate tricks. Keep your classes a reasonable size and most of your functions short. 

Stick To The Style Guide

If the repository you’re working in has standard code formatting and style guidelines, use them. Stick to the maximum length per line used in other code in that repository, etc.

Names Should Be Self-Explanatory

A big aspect of making your code easy to read lies in the names you choose. The names of your functions should clearly describe their purpose. Name your variables, function, and methods in a way that describes what they do or what they are. 

For example, if your variable gets something, consider including “get” in its name. If you can’t name the method or function without using many words, the function may be too complicated. Consider going back and breaking complicated functions into smaller functions to simplify.

Ensure Blocks Are Self-Contained

The single responsibility principle means that every building block does only one thing. All building blocks, including methods, variables, and classes, follow this rule so it’s easy for the person reading the code to understand their responsibility. 

When your code follows this principle, it’s easier to maintain and more scalable. When concerns are separated, you can focus on what features you actually want to work on rather than having to navigate interconnected lines of code.

Ensure Comments Are Minimal

Comments shouldn’t tell us what we already know. They should tell us why things are happening. You shouldn’t have to write more than 1-2 lines in a comment to explain what the code is doing. If you have to, consider rewriting the code until it is more readable. If the code is obvious, avoid comments altogether. The code should be able to speak for itself in many cases. 


How to Review a PR (Pull Request)

This post is about reviewing Pull Requests (PRs) on a software engineering team, often submitted in a source code system like Github. It’s meant to be a concise guide.

Goals of a PR Review

  • Catch issues in the code that the submitter may have missed
  • Offer advice in making the code submission better
  • Complete any team-specific PR review required steps

For many PRs, you don’t need to be an expert in the stack or programming language that is used in the PR. 

The time it takes to review a PR is directly related to how long the PR took to create and how many changes it includes. You should expect to spend more time reviewing a large PR than a small PR.

Required Steps When Reviewing

The steps below apply to PRs with changes to code. If it’s a non-code PR (e.g. a wiki update), the reviewer should just check for typos and that the changes make sense to them.

  1. Confirm that the PR description contains at least 1-2 items describing the changes being made and the reason for those changes.
  2. If there aren’t automated tests, confirm that the PR description contains at least 1-2 items describing how the changes were tested.
  3. Check each changed file for potential bugs that the submitter may have missed.
  4. Check to see if the code is readable.
  5. Check for typos in the comments and readmes.
  6. If you’re not proficient with the programming language or framework used, make a note of that in your review.
    1. For example, “I’m a beginner when it comes to JavaScript. This PR looks good to me, but if you have any doubts about your code or would like a more in-depth review, please consider requesting a second review in ___ channel.”
    2. You don’t have to be an expert in the system which the PR is changing, but you should have a basic understanding of what’s going on. If you have absolutely no clue, it’s best to either loop in someone who does, suggest that the submitter bump their request for a review, or ask for a review in another channel. 
  1. If there are any parts that are particularly difficult to understand, consider suggesting that the submitter refactor or add a comment.


🎉 Lgtm!

My gitlab CI configuration experience level: beginner.

I did not see any obvious errors, everything looks readable and elegant.

If at all possible, try to make future PRs smaller. If not possible, please note that in the PR description.

  • If many files are being renamed, I suggest making a separate PR just for the renaming.
  • There were also formatting/lint updates in this PR. In the future, I suggest a separate PR or including automatic changes like that in a separate renaming PR.


  • Is it possible to move the configuration constants (e.g. ROLE_PREFIX) to a config file or AWS systems manager? If yes, no need to change this PR, but please consider for a future PR.

It looks like there are some major changes to the gitlab pipeline in this PR. I reviewed the testing methodology, and it looks pretty good, but due to the size of this PR, please take a second look at the tests you did to make sure these changes wont break anything before merging the PR.

Great work 🔥. Thank you for making these gitlab CI improvements!