Code Review Guidelines

Goals:

Establish clear and transparent review process. Apply best practice of review process to each review session. Give possibility for everyone
to understand what should be performed during review process and how it should goes.

Basic requirements for review process:

1. Any changes in all our repositories should pass review process before merging with protected branches.
2. Merge request pipelines should be successfully passed before merging with protected branch.
3. Each merge request should be reviewed and approved at least by one of the developer from the team.
4. If merge request contains infrastructure changes it should be also reviewed and approved by DevOps specialist.

5. All threads opened inside merge request should be resolved by person who has started discussion before merging with protected
branch.

Rules for productive discussion:

1. If you are reviewing somebodies merge request know that developer who have prepared this merge request did his best in preparing
those changes and he worked had spent lots of time to prepare better solution he could imagine to make our project better. Take it into
the account. Be respectful for this information during your review.
2. If you know how to improve something in the merge request leave a comment but describe not only “What need to be changed?” but
also “Why you propose to change it?” (“Which benefits you see in this improvement?“). What is obvious for you generally is not obvious
for everyone. Describe it for author of review and other developers.
3. Prefer questions instead of statements. If you haven't strong understanding that something should be implemented differently according
to list of reasons then probably author had reasons to implement it in specific way according to any reasons or difficulties. Ask question
for the author why he chose such solution instead of another and probably we will be able improve it together.

4. If you can’t mentioned any reasons for changing something in review and it is only your personal preference do not comment it, author
has own preferences and they could be different from yours and could be proofed by any reasons.
5. If reviewer and author has different points of view for one problem and has similar list of reasons to implement solutions in various ways
than escalate this problem to your technical leader. Together your will be able to choose best solution.

What should be checked during code review:

1. Merge request should be prepared according to team agreements.
Naming and descriptions of branch, commits and merge request should met requirements. Ticket for merge request should be attached
and planned for development and delivery. Merge request pipelines should been successfully passed. And etc.
2. Solution should solve the initial ticket.
Prepared solution in the merge request should solve initial ticket and met all the acceptance criteria. It should be verified by reviewer.
3. Solution should cover exceptional cases and edge cases.
Reviewer can help author to make sure that prepared solution cover all the exceptional cases and edge cases. Author can miss
something during implementation try to verify it on review.
4. Solution should be implemented with high level of reliability.
Reliable code is code that is failure tolerant. When things go wrong in reliable code, the user experience is shielded from the impact as
much as possible. According to that we have to check on review that different exceptional cases do not impact user experience.
5. Solution should not generate regression scope bigger than it required for achieving task goals with good quality.
Regression scope should be verified by reviewer and it should be minimized if possible.
 6. Solution should be implemented backward compatible.
It means that solutions should not affect users or external systems during release or after it. Solution should not require maintenance or
reimplementation logic on the side of other systems. Such cases can be detected on review.
7. Solution should be implemented according to architecture of your project. All outstanding solution which is not suitable to
existing project architecture should be discussed and approved with technical leader.
During review need to verify that solution implemented according existing architecture of the project or architecture changes confirmed
with technical leader.
8. Solution should be implemented using team best practice useful patterns and should not implement something complicated
from scratch when could be used existing successful solution.
Often development require applying standard solutions to various subject areas. And possibility to apply standard solution in specific
case can be easily missed during development. Review is good place to detect such cases and help author to implement his code
using best practice and patters accepted inside team. Important notice that not all the public patterns are always acceptable for all
subject areas and projects. So discuss possibility of applying specific pattern for specific subject area and consult with tech leader if it is
required.
9. Solution should be implemented with highest level of security.
During review it is important to make sure that solution implemented with highest possible level of security and do not contain any
security vulnerabilities. Important could be everything: using of strange outdated open source libraries with possible or known
vulnerabilities access control on endpoints, user input processing, user uploads processing, executing of the code from variables,
unsafe deserialization and etc. Try to hight light potential vulnerabilities for the author.
10. Solution should be implemented with best performance we can achieve using available instruments.
During review we have to check that solution implemented to work with maximum possible speed and with consuming minimum amount
of resources. If it is possible to increase speed of processing data in the provided solution without dramatically increase of resource
consumption it could be good point for improvement. Also if we can decrease amount of used resources without impacting speed of the
solution it could be also good point for improvement.
11. Solution should be implemented with supporting scalability.
Prepared solution should be able to work in extreme conditions like: handling big number of requests to the system, processing big
amount of data and etc. It should be possible to perform some infrastructure changes for achieving similar performance using same
solution but with increased amount of loading.
12. Source code of the solution should be implemented in reusable manner when it is possible.
Source code should be structured with minimization relations between components. Components should be implemented supporting
abstractions for the components where potentially could be applied various of implementations. Dependencies should be directed from
the high level components to the low level components and dependencies with opposite direction should be avoided.
13. Source code of the solution should be implemented maintainable.
Source code always implemented once but maintained during years. Therefore very important to implement maintainable code. It
means:
- It shouldn't be tightly coupled to another system.
- Configuration should not be hardcoded on the source code level.
- It shouldn't use old source code or libraries which should be deprecated and replaced or updated to new version.
- And etc.
14. Source code of the solution should be implemented readable (understandable).
It means:
- It should be easy to understand input and output of code.
- It should be easy to understand what each line of source code doing and how it is fits into the algorithm.
- The algorithm should be flat as much as possible. Without big amount of nested logic constructions.
- It should be easy to understand role of each independent function.
- Source code should be divided to small enough pieces to do not consume a lot of memory of reader to understand full logic of one
piece.
- Classes, functions and variables should have names from which will be simple understandable which data this variable contain, which
operation this function perform and what this class describes.
15. Source code of the solution should be implemented testable and should be covered by unit tests of good quality.
Testable means that source code should not create any difficulties for implementing unit tests for him. Avoid implementation and using
static methods. Minimize dependencies of your source code. Use injection dependencies through construction instead of instantiation of
dependencies in place where they needed. Avoid direct using in/out operations like: file reading/writing, database queries, API requests
and etc. Wrap in/out operations by class abstraction and use as dependences in your source code.
Test only inputs and outputs by your unit tests. Do not test each independent operation inside implementation of your function. Use
mocking for all dependences of your source code which you are testing and replace return values on predictable.
All those aspects should be checked on review.
16. Source code of the solution should contain implementation or actualization of the documentation if required.
All annotations should be updated according to new implementation of source code. All the documentation existing in repository which
covers affected source code should be updated accordingly. In case when documentation required by team agreements for specific
functions (like API) it should be implemented together with source code.