Orientation: Clarify Basics

1. Ensure MR metadata is appropriately defined based on project convention (assignee, milestone, labels, etc.). If the project uses an MR template, make sure it’s filled out appropriately.
2. Understand the issue the MR is solving by reading or reviewing any linked work items. If the MR fully addresses the work items, make sure they’re closed by the MR merging (as appropriate for project workflow).
3. Confirm code passes any automatic checks defined in CI (build, automatic tests, formatting, etc.).
4. If code isn’t fully covered by automatic testing, clearly identify the testing approach and who performed it. If code is easy to test, test it yourself!
5. Read the MR’s description to understand the high-level approach to the issue (if no description, ask reviewee to populate).
6. Confirm that the source and target branches are appropriate, and that MR sequencing is clearly defined or not needed (branch structure in the repository graph may reveal that this MR should merge before or after another one).

First Review: Refine Design

Note: this step may not be necessary for small MRs or ones you’ve been closely involved with already.

Glance it over

First, skim the files to understand the high-level scope of the changes.

1. Review structural elements (interfaces, header files, dependencies, etc.) to understand the relationship between modules.
2. If one or more new packages have been added, review to understand the functionality they add, confirm that a package addition is warranted, confirm that the license is appropriate for the project, and confirm that the package chosen is the best choice.
3. Get a sense of how complex these changes are to assess how long it will take you to fully review.
4. Consider taking a quick look at minor changes to check them off the list and focus future passes.

Take a pass

Go through the code changes and review them, focusing on items 1-3 (System, Structure, Function) from the list in the previous blog.

1. Review the full diff (don’t look at individual commits unless you’re answering specific questions).
2. If your structural review revealed new dependent elements, consider starting your review at the “bottom” of the dependency tree (a module without any dependencies, or only existing dependencies) to understand how functionality builds up. This may be challenging unless you’re quite familiar with the existing architecture.

Middle Review(s): Check Details

This will happen after the developer responds to your comments from the first review, or you can skip directly to this stage on your first review if there are no large comments on the design.

1. When the developer pushes the review back to you, first look at the comments included in your previous review to ensure all have been addressed (code changed or additional discussion).
2. It can be helpful to look at what has changed since the last review by filtering the commit list.
3. Take a full pass on the code, focusing on items 4-6 (Patterns, Style, Ready) from the list in the previous blog, and send a review.

Final Pass: Pre-merge

1. Make sure all pipelines are passing.
2. Make sure code will merge without conflicts.
3. Once the code looks good to you, Approve it! This means you’re happy with it (depending on the project, you might merge it or have the developer merge).

That wraps up our guidance for code reviews — we hope this is helpful in reviewing your next request.

The post Code Review Procedures appeared first on DMC, Inc..

In this blog, we focus on general best practices for text-based code reviews. DMC also uses a number of graphical programming languages, which have unique challenges in the code review process — some of these ideas apply, but not all. In a follow-up blog, we’ll look more closely at some specific procedures DMC follows.

Code review is always a little bit different from project to project, but our experienced code reviewers have collected a set of practices that improve the efficiency and efficacy of our process. Whether you’re getting ready to review your first line of code or merge your thousandth request, this blog is for you!

Focus on Value

While reviewing, stay focused on the value added by the code review process. The remainder of this guide includes lots of specific recommendations, but not all recommendations should be followed on every review. Focus on using the review as an opportunity to confirm functionality and ensure maintainability, not to debate an optimal solution. Make sure that time spent on reviews balances the quality and efficiency expectations of the project — a quick internal tool shouldn’t be reviewed as carefully as a business-critical data processer. 

Use your Tools

All major source control platforms include features designed to facilitate the code review process, so learning and employing those tools can give you a big boost. DMC uses GitLab as our preferred platform for source control, so the following discussions reference some specific features of GitLab, but most source control platforms have analogous capabilities. We particularly recommend the following features in GitLab:

• Whenever leaving comments, use the review feature.
• Change your settings as needed to facilitate reading changes easily.
• Mark files as viewed to avoid duplicate review time.

Prioritize it

Reviewing code early and often is important and worth prioritizing. Delayed code reviews can leave developers waiting or cause them to forget why they made technical decisions. If appropriate, move larger comments and reworks into follow-up issues to merge the primary MR more quickly. 

Timing matters

Before spending time reviewing code, determine whether a synchronous or asynchronous review will be more valuable. Asynchronous reviews use GitLab comments to allow reviewers and developers to alternate their focus on the review and are most common at DMC. A synchronous review (where the reviewer and reviewee meet) allows for richer interactions but is sometimes less time efficient. It’s often preferred in situations that include new engineers, complex changes, or engineers where a verbal discussion has low overhead. A hybrid option (an async review with a follow-up meeting) is also common in the case that there are outstanding questions, or the reviewer wants to provide more context. You can do this differently for different review passes (a synchronous first review with async follow-up is common).

Look high and low

There’s a lot to think about when reviewing code! We use the following list to organize our reviews and make sure we don’t miss anything.

1. System: Are any changes to the system design reflected in the code handled appropriately? Examples:
   1. Will the design changes have any unintended consequences on other system elements?
   2. Do any of the changes warrant updates to documentation in the repo (like a README) or project-level documentation?
2. Structure: Does the code have good structure? Examples:
   1. Is functionality broken up into understandable modules?
   2. Is code repetition minimized?
   3. Can code intent be clearly understood?
   4. Could the same functionality be achieved with less complexity?
3. Function: Does the code work correctly? Examples:
   1. Will the code behave as expected even in corner cases?
   2. Are errors and alarms handled appropriately?
   3. Will the changes cause any regression in existing functionality?
4. Patterns: Are project patterns followed well? Examples:
   1. Are comments useful (provide information beyond what’s in the code) and clear?
   2. Are log levels appropriate?
5. Style: Does code follow language style guidelines?
6. Ready: Is the code ready for the branch it’s being merged into? Examples:
   1. If merging into a main or production branch, is any test code removed?
   2. Are TODOs appropriately captured in follow-up issues?

Talk about it

When you find something while looking for the above items, discuss it with the reviewee. For async reviews, this should take the form of a GitLab comment; for synchronous reviews, make sure that suggested changes are noted (in a comment or elsewhere).

• If what you find violates clear-cut best practices, provide directive feedback to change it (and reference the source). Example: “Microsoft recommends PascalCase for class names. Please change this variable to match.”
• If you don’t understand why a piece of code is written the way that it is, ask! You can instead spend time digging in, but, if it’s not clear to you, it could likely be written more clearly regardless. Example: “Can you talk me through why we need separate methods here?” Once you understand the code, recommend restructuring, renaming, or adding comments as appropriate to make it easier to understand.
• If multiple solutions may be appropriate and worth consideration, enumerate them to start a discussion. Example: “I see that you structured this as an interface, but an abstract class would also work. Why did you prefer an interface?”

That’s all for our recommended practices! If you’d like to learn more, check out our companion on the process: Code Review Procedures.

The post Code Review Best Practices appeared first on DMC, Inc..