Blog #5 - 5 steps to Conduct Effective Code Reviews

[Priyanka Sharm1]

Embarking on the journey of mastering code reviews has significantly changed my code quality. With time, I have honed practices that prioritize clean, efficient, and maintainable code. In this piece, I will share my insights and 5 steps I use for the code review process, shedding light on the strategies that have become essential to my workflow.

By presenting a structured checklist, I aim to provide actionable steps to enhance readability, maintain high standards, and ensure consistency in every review.

5 steps to Conduct Effective Code Reviews

Below is a general Code Review Checklist, focused more on the process rather than technical errors or specific ServiceNow JavaScript details. This checklist helps ensure that your code is well-structured, maintainable, and aligns with best practices.

1. Naming Conventions

• Clear naming: Use short, clear names that indicate the variable’s purpose and type.
  • Good: `var requestDateTo`.
  • Bad: `var rdt`.
• Sentence case: Sentence case for variable names.
  • Stick to `var requestDateTo` instead of `RequestDateto`.
• Reverse notation: It helps in organizing and searching variables more easily.
  • Example: Group related variables like `employeeName`, `employeeID`, `employeeDepartment`.

2. Proper Spacing and Formatting

• Maintain readability: Readable code is maintainable code. Use proper spacing to make it clear.
  • Example:

if (condition) {     

doSomething ();

}

  Instead of: 

    if(condition){doSomething ();}

• Indentation Consistency: Stick to team standards for indentation and line breaks. Consistency is key!

3. Descriptions and Comments

• Code comments: Explain the why, not the what. Comments should clarify complex logic or decisions, not state the obvious. 
  • Example: 

    // Adjust date format to match external system’s requirements

    formattedDate = adjustDate(inputDate);

• Function Documentation: Provide a clear explanation of any function or class above it.
  • Example:

/*Description of the function

**Param 1 : Datatype - Required/Optional – Description of the parameter

**Param 2 : Datatype - Required/Optional – Description of the parameter

**Returns : Datatype – Description*/

4. Review Code Implementation

• Method reuse: Instead of duplicating code, create reusable methods where appropriate. 
  • Example: If you find yourself copying and pasting the same logic, it’s time for a method.
• Clean up after yourself: Remove any unnecessary code. No one likes debugging through dead code.
• Input Validation: Ensure user inputs are validated.
• Efficiency of Algorithms: Evaluate the algorithms and data structures for optimal performance.
  • Example: Consider whether a more efficient sorting algorithm can replace a standard one.
• Database Queries: Look for opportunities to optimize database queries.
• Security Considerations: Authentication and Authorization.
  • Confirm security measures are in place to restrict access to sensitive functions or data.
• Robust Error Handling: Ensure errors are handled gracefully with informative messages.
  • Example: Use try-catch blocks effectively and log meaningful error messages for easier debugging.

5. General Checks

• Architectural Fit: Is the code aligned with the project architecture?
  • Ensure your solution fits within the system's overall design. If unsure, check with your architect.
  • Example: Before writing a complex query, verify it fits with existing patterns used across the app.
• Happy path testing: Test under ideal conditions to ensure the code does what it should.
• Negative path testing: Don’t forget to test for edge cases and unexpected inputs - this is crucial. 
  • Example: What happens if a user enters incorrect data or null values?
• Team reviews: Review together with the team.
  • Multiple eyes on the code catch more bugs, and it builds a shared understanding of best practices.

While, I am handing over a checklist to you, I would also like to remind that Code review is more than just a checklist—it's a practice, collaborative effort to elevate the quality of our codebase and align with best practices.

Figure out what works best for your project and team as every project and team is different, feel free to add/remove pointers as they suit you.

Let these guidelines serve as a foundation for conducting effective, meaningful code reviews that improve both our code and our collective growth as developers.