The First Code Review After Joining the 5xRuby Group

Our experience at 5xRuby is that many people create computer programs that are difficult to read or contain indecipherable logic that lead to design errors.  This is all because they failed to establish a good habit when they first learned to program. While programming for a commercial project, such an issue may turn into unforeseeable problems for subsequent product development or maintenance.

Under ideal conditions, we may rely on the Pair Programming methodology to overcome such dilemmas. However, Pair Programming requires even more time and labor costs, leaving a code review to serve as the last line of defense. The rule at 5xRuby is that programs written by newly hired engineers must be reviewed once by a technical manager or team before the programming code is submitted to the main project line.

WHY IS CODE REVIEW NECESSARY

People make mistakes. To prevent the occurrence of errors, it is best to double-check as many times as possible. In addition to reviews by oneself, getting others to review programs would help engineers to discover their own blind spots. Therefore, code reviews allow team members and the technical manager to review programming output. Engineers may obtain recommendations for the programming code design structure, make corrections of logic errors or design issues to meet the project requirement.

To make further adjustments, the Pair Programming technique may be utilized to obtain immediate review feedback. Pair Programming is a methodology with two people in a team working together, each taking turns to write code. Thus, when one member of the team writes problematic code, the other partner is usually able to discover immediately, and to discuss a plan for improvement. This technique is a big help to new employees. Through guidance provided by senior engineers and managers, new hires are able to quickly understand the company’s coding habit and process, and to receive immediate feedback and clarifications for any questions. Pair Programming helps new colleagues to quickly adapt to the work environment and improve their coding skills.

The practice of code reviews also demonstrates that the company values programming codes. Just as a sumptuous dish must begin with careful selection of ingredients, we attempt to review carefully and remove all erroneous parts before assembling modules into useful functions or software programs. We plan ahead for perfection.

Through code reviews, we can also create a standard for the engineers to follow in writing code, making the programs easier to maintain and debug. The following are examples of improvements made possible by code reviews. Although the issues seem to be minor, they end up having very big effects on the project quality.

THE DEVIL IS IN THE DETAILS: THE NAMING CONUNDRUM

One of the most prevalent and difficult problems in coding is naming. 

Most engineers should have read articles discussing the concept of anti-pattern. The article discusses the issue of naming and clearly states that meaningless names such as a, b, or c should be avoided. Instead, meaningful words such as user, cart, and line_items should be used to write programs. This way, in addition to helping others understand the programming logic, the semantic effect may be achieved using some programming languages due to the syntax characteristics. That is, “reading programming code is just like reading an article”.

Ruby is exactly this type of programming language. For example, we may use refill if bottle.empty? or similar methods to indicate that when the bottle is empty, it should be refilled. This is also the proper syntax in the Ruby language. Thus, we are extra careful with naming in code. For example, for the function to store user information, for the field “user level”, we may name it user_level to store in the database. Thus, when the function is invoked, it becomes user.user_level.  But in fact, in the concept of data, it is the entity “user” that owns the “level” attribute. Therefore, we just need to name it “level” such that the “user.level” syntax would appear naturally, making the programming code more readable.

COMPOSE HARMONIOUS MELODIES: STANDARDIZE A CODING STYLE SUITABLE FOR A GROUP

An engineer has to come to grips with the coding style in order to integrate with a team.

Using programming languages with curly brace syntax such as C/C++ as an example, there are many online discussions about whether the code should follow a brace on the same line, or begins on the next line. For the compiler, both styles are correct.  Therefore, whether or not to start code on a new line becomes an agreement between team members, and such agreements form the coding style. A unified style is very important for a new member integrating into a team.

At 5xRuby, we use Linter (meaning a syntax verification tool) to check everyone’s code. We use Rubocop (syntax verification tool for Ruby) and ESLint (syntax verification tool for JavaScript) to unify the coding style. This type of syntax verification tools may accommodate most scenarios and styles, so a few remaining issues related to personal habits or preferences will have to rely on a human reviewer.

A coding style is important because styles would affect the code-reading speed and efficiency of understanding. If irregular syntax is used often in code, or there is a lack of appropriate spacing and newlines, the code would become difficult to read. It would also be difficult to decipher the coding intention based on project standard habits and preferences.

We have also observed that internationally renowned technology companies, such as Google, GitHub, Shopify, and Airbnb all share the company’s Linter setting or style guide publicly on the internet. In this manner,  communication cost and manual inspection time may be minimized when the company’s open source projects accept social media contributions or plan an internal collaboration project with many team members.

LIMITLESS GROWTH: CULTIVATING A HABIT TO CONTEMPLATE CONTINUOUSLY

For 5xRuby, our practice of code reviews for new team members helps them quickly integrate into the company’s development methodology and culture. As a result, the first pull request usually takes one to two weeks of time to make adjustments. During the process, we discuss issues such as naming protocols, coding styles and writing test programs. The above-mentioned methods prompt newly-hired engineers to develop the habit to think about possible issues in their code, including: whether their naming method is easily understood by others, whether their syntax makes good use of white space and newlines to enhance readability, and whether they are in adherence with the company’s standard coding style.

Afterwards, they have to deal with challenges such as: using test programs to verify whether there is proper understanding of the design, having the capability to perform size-appropriate unit testing instead of load testing, and the need to perform mock designs, etc. During this process, they will be able to learn to apply techniques such as appropriate interface design and division to create single-responsibility modules, reducing the extent of object coupling while preserving flexibility.

After completing the first code review, even students that just joined 5xRuby will have learned to create functional code that is also concise and elegant. We usually spend a lot of efforts in the early stages to prepare for projects. We also continue to improve the code throughout the development process to ensure the system we develop is easy to modify and easy to maintain, such that our customers are offered the best and easily-maintained products.