Developer Best Practices Guide
1) Introduction
This document defines the standard development practices to be followed across the codebase to ensure consistency, maintainability, and high-quality deliverables. It serves as a reference for all developers and provides clear guidance for new joiners to align with established engineering standards.
2) Purpose
The objective of this guide is to establish a consistent development approach that enables:
- High code quality and maintainability
- Uniformity in coding standards across projects
- Efficient collaboration among team members
- Faster onboarding and knowledge transfer
3) Code Documentation Standards
Documentation is not an optional activity but a core part of development. Code without documentation creates dependency on individuals and slows down future development and debugging.
Every module, class, and function must include docstrings following the Google Docstrings Style Guide. Documentation should clearly explain:
- What the code does
- Why the implementation exists (where necessary)
- Input parameters and expected data types
- Return values
Possible exceptions or edge cases
Example :-
4) Naming Conventions
Consistent naming conventions must be maintained across all code components.
Variables, functions, and file names should follow the snake_case format. Naming should be descriptive and meaningful, avoiding unclear abbreviations.
5) Code Quality Standards
Before merging any changes into the main branch, developers must ensure compliance with defined quality standards.
5.1) Pylint
Code must be validated using pylint prior to raising or merging a pull request. A minimum score of 9.30 must be maintained.
Pylint checks should be performed once the pull request is ready for review to ensure that the code adheres to project standards and does not introduce maintainability issues.
5.2) Documentation Validation
Every file must contain appropriate docstrings. Files without proper documentation are considered incomplete and should not be moved forward in the review process.
Docstring validation should be part of the final review checklist before submitting code.
6)Software Design and Coding Principles
Developers are expected to follow established software engineering principles to ensure that the codebase remains scalable, efficient, and easy to maintain.
6.1) Pythonic Coding Practices
Code should follow Pythonic conventions and avoid unnecessary complexity. Repetitive logic must be eliminated by adhering to the DRY (Don't Repeat Yourself) principle. This ensures cleaner and more maintainable code.
6.2) Readability and Maintainability
Code should always prioritize readability. Proper structuring, meaningful naming, and logical organization are essential to ensure that other developers can easily understand and extend the codebase.
6.3) Asynchronous Programming
Where applicable, asynchronous programming paradigms should be used to improve performance and efficiency, especially in I/O-bound operations.
6.4) Object-Oriented Design
Developers must follow object-oriented programming principles such as encapsulation, modularity, and separation of concerns. This improves code structure and reusability.
6.5) Design Patterns
Appropriate design patterns should be used while implementing solutions. Choosing the right pattern helps in solving recurring problems efficiently and improves system scalability.
6.7) File Structure
Each Python class should be defined in a separate `.py` file wherever applicable. This promotes modularity and improves code organization.
6.8) Simplicity in Logic
Code logic should be kept simple and straightforward. Overly complex implementations should be avoided, as they increase maintenance effort and introduce potential bugs. Clear and simple logic leads to better readability, easier debugging, and faster development cycles.
