⏱ Estimated reading time: 9 minutes

Table of Contents

Ingredients for an efficient code review

By Thibaut Cointet, Frontend developer @ ekino

Definitions

A code review is a delicate balancing exercise where multiple parties must interact to evaluate contributions in order to merge them to a larger contribution base. The parties participating to a code review are contribution authors and reviewers.

  • Authors are the individuals who contributed their knowledge to the project and created a Merge Request or a Pull Request, which is a way to signal that their contributions are nearing or have reached a state that qualify them for a merge;
  • Reviewers are the individuals who check the contributions and validate that they work, work well and follow the standards. They share responsibility for the submitted contributions with their authors.

Merge / Pull Requests usually contain a title, a description, comments and additional information from CI/CD and reporting tools. Merge Requests and Pull Requests are interchangeable terms: the former can be usually encountered around GitLab communities while the latter appears everywhere else.

Why do we need code reviews? To improve code quality, share skowledge across the team, get a higher-level view of the project, detect anomalous behaviors and edge cases before they occur and validate code as in “share the responsibility” and “trust that it works”.

Typical process

The code review process works in iterative cycles like so:

  1. Authors push a list of contributions to the repository;
  2. One of the Authors creates a Merge / Pull Request with a proper title and description and assigns it to Reviewers;
  3. Reviewers review the contents of the Merge / Pull Request and send comments and reactions;
  4. Authors process the comments, make changes to the contributions if necessary and notify Reviewers if need be;
  5. Unless Authors and Reviewers come to an agreement that the contributions are good enough to be merged, return to step 3;
  6. Once the contributions are ready to be merged, one of the Authors proceeds to merge them.

There is always the option to decline a Merge / Pull Request if it is outdated, genuinely irrelevant or cannot be easily fixed into shape. Use this option sparingly.

A code review process that is not flawlessly conducted leads to friction and delivery slowdown.

Good practices

To avoid slowing down code reviews, there are a few good practices that are akin to general communication rules of thumb that we can apply as both Authors and Reviewers of code reviews. As an Author, you should:

  1. Carefully review your contributions before submitting them for a code review. This includes commented code, debug statements, console printing, test failures, syntax issues, etc. Easy fixes and TODOs can be included in this non-exhaustive list;
  2. Give context so that Authors know what they are reviewing: define a title and a description;
  3. Reduce the scope of your changes: nobody wants to read through thousand of lines of changes spanning multiple code modules or multiple commits fused into one big change;
  4. Diplomacy: you are not your code, accept that it is not perfect and that Reviewers are here to help you improve it;
  5. Be clear, short and precise: tone and facial expressions are harder to convey through text;
  6. Be efficient: reduce cycle time by notifying and asking and giving precisions.

As a Reviewer, you should:

  1. Share sources, documentations and code extracts. Code reviews are learning experiences and you can be surprise about what you too can learn;
  2. Pictures are worth a thousand words: add a schema instead of carefully describing a process, as a visual aid;
  3. Use in-code suggestions;
  4. Do not drown the authors in suggestions. In case there are too many things to report, focus on critical stuff initially.

Questions and Answers

Should code reviews include a functional review?

Reviewing the functional aspect of the contributions can be time-consuming, especially if you need to check for regressions. This should be last resort if the contributions are obtuse and cannot be made clearer. The alternative is to write relevant tests to prove that the contributions follow the specifications.

Is Conventional Comments recommendable?

Conventional Comments is the equivalent of Conventional Commits for Merge / Pull Request comments. This convention adds structure to comments to convey intention to the reader and to make them easily parseable.

What goes against Conventional Comments is that this convention is still obscure in the tech community and the tooling is scarce if existent at all.

How many approvals is enough?

There is no clear answer to that question. However, it is recommended assigning people that are more experiences than you with the product and/or the technology you are contributing to if possible. If your code review spans a product owned by another team, make sure they are at least informed of your changes.

How to proceed when the code review would generate too many feedbacks?

CommitStrip: The secret of a successful code review

Unlike this comic from CommitStrip states, the point of the code review is to make sure contributions integrate with the rest of a contribution base. Put yourselves in the receiving end of thousands of comments, how would that make you feel?

Should this happen, here are some pieces of advice:

  • Write most of the feedback on your side, do not communicate it on the Merge / Pull Request;
  • Switch to pair programming. Remember code reviews are a learning opportunity;
  • Support the contributors.

A NestJS service deconstruction

By Antoine Brette, Java Developer @ ekino

Interesting watch: Webeleon’s NestJS course [FR]
Interesting read: Build the future with TypeScript and NestJS

Framework

NestJS is a JavaScript framework for backend applications. Its documentation is well-designed and its community is active and ready to help!

A framework is a tool that simplifies complex application development. Frameworks add structure and features that improve development experience. NestJS itself has been developed in TypeScript for seamless integration with the ecosystem. It encourages the Controller -> Service -> Repository pattern, i.e. the separation of concerns between “Routing, request response management”, “Business logic” and “Data access” respectively. Each layer implements an airgapped level of abstraction.

NestJS also supports a certain amount of tools such as @decorators, Exception Filters and Guards. NestJS development teams made strong decisions to guide the communities relying on their framework.

Modules

A class can depend on other classes to do specific tasks. Enters Dependency Injection, which simplifies dependency management. NestJS supports Dependency Injection through their Modules. Injectable services must be declared as such through the @Injectable() class decorator then added to a Module that serves as a Dependency Injection Container. When a class A requests an injectable class I, the Dependency Injection Containers tries to fulfil the request by checking if it manages I, it is can provision an instance of I then keeps that instance in memory and returns it.

Dependency Injection has a sweet side effect: the inversion of control caused by the self-service model where classes request instances of other classes simplifies test execution. NestJS even simplifies that by providing TestModule, which can replace modules with mocks!

Last drops of features

Instead of having to implement request handling yourselves, you can let NestJS do that for you: argument-scoped decorators can extract request components such as query, path or body parameters. You can even validate data using Pipes. You can also provide you own classes, which can also be used in conjunction with route and method declarations to generate your OpenAPI specification!

Questions and Answers

Does NestJS ship with an ORM?

NestJS does not natively ship with its own Object Relationship Manager but instead provides integrations with TypeORM, Sequelize and Mongoose. You can however still provide your favorite ORM.

Are there any major flaws to know about with NestJS?

Not really, except the fact that people can get confused by the name similarity with NextJS. You could say that some integrations are not yet perfect such as Passport with OIDC.

How well is NestJS integrating with testing tools?

Particularly well: quality documentation and out-of-the-box support for Jest and Supertest. The only downside is testing feels less opinionated than the rest of the framework, which makes developer experience uneven.

How does OpenAPI specification generation work in NestJS?

To generate OpenAPI specifications with NestJS, you would have to use the framework decorators, additional annotations and the OpenAPI Plugin. Plugins extend what NestJS can do natively by plugging in the compilation process in order to require less boilerplate code. However, the further you wish to go with OpenAPI specifications, the more verbose it will get.