Skip to main content

III. Code Quality and Standards

A. C# Code Formatting and Style​

  1. Code Style
  2. Exceptions
  3. Naming
  4. Configuration

B Typescript Code Formatting and Style​

  1. Code Style

C. Code Reviews​

Code reviews are a crucial aspect of any development process, acting as an indispensable means to ensure code quality, functionality, and maintainability. A carefully executed code review process enables teams to catch bugs early, share knowledge across the team, and maintain a consistent code base. Here are several guidelines to follow:

  1. Focus Beyond Typos and Formatting

    Code reviews should concentrate on the logic, design, and performance of the submitted code. Typos, formatting, and removal of unused code should ideally be addressed by the developer before the code reaches the review stage. Using automated tools for such aspects is recommended to ensure uniformity and let code reviews focus on higher-level concerns.

  2. Demonstration of Features

    Each code review should ideally include a demonstration of the implemented features. This ensures that the reviewer understands the functionality of the code and can assess the implementation's appropriateness. Demonstrations also provide an opportunity to verify the feature against user requirements and expected outcomes.

  3. Size of the Review

    If a feature or bug fix involves too many changes to be properly reviewed in a single pull request, it is recommended to split it into multiple smaller pull requests. This helps to keep reviews manageable and thorough. A review should be concise enough to allow a detailed inspection, but comprehensive enough to include all changes related to a specific feature or issue.

  4. Understanding the Code's Purpose

    The reviewer should have a clear understanding of the code's purpose. This includes knowing what the code is intended to do, the problem it solves, and how it fits into the larger codebase. The code's author should provide this information in the pull request description to aid the reviewer.

  5. Code Review Feedback

    Feedback in code reviews should be constructive and respectful. The objective is to improve the code, not criticize the coder. All discussions should be oriented towards the best possible solution, fostering a learning environment.

Remember, code reviews are as much about human interaction as they are about code. They are an opportunity to communicate, learn, and share knowledge in addition to ensuring high-quality code.

D. Testing Strategies​

Adopting an efficient testing strategy is crucial to maintaining a robust, reliable, and efficient codebase. Here's an overview of the various types of tests you should consider:

  1. Unit Testing

    Unit testing involves testing individual units of your code—typically functions or methods—to ensure that they behave as expected. While unit tests are powerful, it's important to strike a balance: too much mocking can dilute their usefulness. However, for critical algorithms, unit tests are invaluable to verify that they perform correctly. A Test-Driven Development (TDD) approach, where tests are written before the code, not only produces unit tests as a byproduct but also leads to cleaner, more modular code.

  2. Integration Testing

    Integration testing is the process of testing several units together to check if they work correctly as a group. These tests can often provide more information about a component's functionality than unit tests, and with less effort. While they might not pinpoint the exact source of an error, they are excellent at indicating whether a component is functioning correctly overall. Difficulty in setting up integration tests may be a sign of poor component design, implying too much coupling or not enough cohesion.

  3. System Testing

    System testing involves testing the entire system as a whole. This testing level can be more complex to set up—requiring correctly configured infrastructure—but it provides valuable insight into the system's quality attributes, such as performance, resilience, and reliability.

Remember, all kinds of tests are important to ensure quality, but they should not impede productivity. Each type of testing offers its unique advantages and should be used appropriately as per the project's needs and context. Testing is a tool, not a hindrance—it should assist development, not obstruct it.

E. Performance Considerations​

F. Security Considerations​

G. Documentation and Comments​

Documenting your code effectively is essential for maintainability and readability. While comments can help clarify complex logic, the aim should be to write self-documenting code. Here are the key guidelines to follow:

  1. Self-Documenting Code

    The code should be written in a way that it's easy to understand on its own. When extensive comments are required, it may be an indication that the code needs refactoring. Using descriptive names, small functions, and well-structured classes can make the code more readable and self-explanatory.

  2. High-Level Documentation

    README.md files serve as the starting point for other developers to understand the software. These files should give a high-level overview of the service or library, including its purpose, how to set it up, and how to use it. It's critical to write this documentation in such a way that it doesn't become outdated with every minor change.

  3. API Documentation

    When using tools like xmldoc for API documentation, focus on providing useful information rather than stating the obvious. For instance, instead of just stating that a 'fileName' parameter is a file name, document any specific expectations or constraints—for example, if the file name is expected to be an absolute path, or a parameter must be a positive number.

  4. Documenting Extension Points

    Parts of your code that serve as extension points for other components are prime candidates for detailed documentation. Here, it's important to clearly explain the expected inputs, outputs, side effects, and any architectural decisions that the extender needs to be aware of. This helps to ensure that extensions will work correctly and minimally disrupt the rest of the system.

The goal of both documentation and comments is to make the codebase as clear as possible for other developers who might need to use, maintain, or extend it. Remember, the audience of your documentation and comments is not just your current team, but also future developers who will work with the codebase.