platform/.pkb/5_development_process/pkb-coding-standards.md

Protevus Platform Coding Standards

This document outlines the coding standards and conventions followed in the development of the Protevus Platform. Adhering to these standards ensures consistency, maintainability, and readability across the codebase, facilitating collaboration and knowledge sharing among contributors.

Code Formatting

The Protevus Platform follows the Dart Style Guide for code formatting and style. To ensure consistent formatting across the codebase, the project utilizes the following tools:

1. dartfmt: The official Dart code formatter, which automatically formats Dart code according to the style guide. All code contributions should be formatted using dartfmt before submission.

2. dartanalyzer: A static analysis tool that identifies potential issues, errors, and style guide violations in Dart code. The project enforces the use of dartanalyzer to maintain code quality and adherence to best practices.

Naming Conventions

The Protevus Platform follows the naming conventions outlined in the Dart Style Guide, with some additional project-specific conventions:

1. Classes: Class names should be in UpperCamelCase and should be descriptive and meaningful.

2. Interfaces: Interface names should be in UpperCamelCase and should be prefixed with I (e.g., IUserRepository).

3. Variables: Variable names should be in lowerCamelCase and should be descriptive and meaningful.

4. Constants: Constant names should be in lowerCamelCase for const declarations, and UPPERCASE_WITH_UNDERSCORES for final declarations.

5. Functions: Function names should be in lowerCamelCase and should be descriptive and meaningful.

6. Packages: Package names should be in lowercase_with_underscores and should be descriptive and meaningful.

7. Directories: Directory names should be in lowercase_with_underscores and should be descriptive and meaningful.

Code Organization

The Protevus Platform follows a modular and layered architecture, with each component or module organized into its respective directory or package. The codebase should be organized in a way that promotes separation of concerns and maintainability.

1. Packages: Each major component or feature should be organized into its own package, with a clear separation of responsibilities and dependencies.

2. Directories: Within each package, the code should be organized into directories based on their responsibilities or concerns (e.g., models, controllers, services, utils).

3. File Structure: Each file should contain a single class, interface, or set of related functions, with a clear and descriptive name that reflects its purpose.

4. Imports: Imports should be organized into sections (e.g., Dart core imports, package imports, relative imports) and should be sorted alphabetically within each section.

Documentation

The Protevus Platform emphasizes the importance of clear and comprehensive documentation, both at the code level and in the form of user guides and API documentation.

1. Code Comments: All classes, interfaces, functions, and complex code blocks should be documented using Dart's documentation comments (///). These comments should provide a clear description of the purpose, parameters, return values, and any other relevant information.

2. User Guides: The project should maintain comprehensive user guides and tutorials to assist developers in understanding and using the platform effectively.

3. API Documentation: The project should generate and maintain up-to-date API documentation for all public interfaces and classes, using tools like dartdoc.

Testing

The Protevus Platform promotes a test-driven development approach, with a focus on writing unit tests, integration tests, and end-to-end tests to ensure code quality and reliability.

1. Unit Tests: All classes, functions, and components should have corresponding unit tests to verify their behavior and functionality.

2. Integration Tests: Integration tests should be written to ensure the proper integration and interaction between different components and modules.

3. End-to-End Tests: End-to-end tests should be written to simulate real-world scenarios and ensure the overall functionality of the application.

4. Test Organization: Tests should be organized in a way that mirrors the structure of the codebase, with each test file corresponding to the file or component being tested.

5. Test Naming Conventions: Test names should be descriptive and follow a consistent naming convention (e.g., test_ClassName_methodName_scenario).

6. Test Coverage: The project should strive for high test coverage, with a minimum target coverage percentage defined and enforced.

By adhering to these coding standards, the Protevus Platform ensures consistency, maintainability, and readability across the codebase, facilitating collaboration and knowledge sharing among contributors. These standards serve as a foundation for producing high-quality, reliable, and maintainable code within the project.