The best_practices.md file helps your team stay aligned by documenting and sharing coding guidelines directly within your project.
Qodo IDE plugin reads this file and uses it as a reference to guide its suggestions and decisions, keeping everyone on the same page.
Why It Matters
The best practices file gives your AI assistant a shared understanding of your team's standards.
Whether you're reviewing code, generating tests, or writing new features, Qodo will use your documented practices to offer more accurate, consistent, and context-aware help.
# Qodo Best Practices
## General Code Structure
- **Consistent Naming Conventions**: Use descriptive and consistent naming for variables, functions, and classes. For example, use camelCase for variables and functions, and PascalCase for class names.
- **Documentation and Comments**: Ensure all functions, classes, and modules have comprehensive docstrings. Use the `/docstring` command to generate or improve documentation.
- **Code Modularity**: Break down large functions into smaller, reusable components. This enhances readability and maintainability.
## YAML Configuration
- **Navigation Structure**: Organize navigation in YAML files using nested lists for hierarchical structures. Ensure each section is clearly defined and logically grouped.
```yaml
nav:
- 'index.md'
- Installation:
- 'installation/index.md'
- 'installation/vscode.md'
```
- **Theme Customization**: Define custom themes and palettes in the YAML configuration to maintain a consistent look and feel across the documentation.
```yaml
theme:
name: material
palette:
- media: "(prefers-color-scheme: light)"
scheme: default
```
## Markdown and Documentation
- **Use of Admonitions**: Utilize admonitions for highlighting important information, such as tips, warnings, and examples. Use custom icons and colors to differentiate types.
```markdown
!!! success "Available in"
- [:fontawesome-solid-file-code: Current File focus](../focus/current-file.md)
```
- **Image Integration**: Include images in documentation to enhance understanding. Use lazy loading for performance optimization.
```markdown
{loading=lazy}
```
- **Code Blocks**: Use fenced code blocks for syntax highlighting and clarity. Ensure code snippets are relevant and concise.
```python
def example_function(param1, param2):
"""Example function with parameters."""
return param1 + param2
```
## Python Scripting
- **Error Handling**: Implement try-except blocks to handle exceptions gracefully. Log errors for debugging purposes.
```python
try:
with open(file_path, 'r') as file:
content = file.read()
except FileNotFoundError as e:
print(f"Error: {e}")
```
- **Path Management**: Use `pathlib` for file and directory operations to ensure cross-platform compatibility.
```python
from pathlib import Path
docs_path = Path(__file__).parent / "docs"
```
## GitHub Actions
- **Workflow Configuration**: Define clear and concise workflows in `.yml` files. Use environment variables and secrets for sensitive information.
```yaml
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Python
uses: actions/setup-python@v2
```
- **Branch Management**: Use descriptive branch names for feature development and bug fixes. Automate pull request creation and notifications.
```yaml
- name: Create pull request
uses: actions/github-script@v6
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
```
## Chat Commands
- **Command Usage**: Use chat commands to automate repetitive tasks such as generating commit messages or describing changesets.
```markdown
### Command:
`/commit`
```
- **Focus Selection**: Select appropriate focus modes (e.g., Current File, Git-Diff) to tailor command responses to the relevant context.
```markdown
- **Select Your Focus**: Choose between Current File or Git-Diff for contextually relevant responses.
```
## Test Generation
- **Behavior Analysis**: Leverage behavior analysis to identify and categorize test scenarios. Use the advanced panel for managing test generation.
```markdown
## Behavior Categories
- **Happy Path**: Ideal and expected use cases.
- **Edge Case**: Unusual or extreme scenarios.
```
- **Test Refinement**: Continuously refine and customize generated tests to align with project requirements. Use example tests to guide style and consistency.
```markdown
## Refining Your Tests
- **Manual Editing**: Directly edit test code for quick adjustments.
```
## CSS Customization
- **Custom Styles**: Define custom CSS rules for branding and visual consistency. Use CSS variables for easy theme adjustments.
```css
:root {
--md-primary-fg-color: #765bfa;
}
```
- **Responsive Design**: Ensure styles are responsive and adapt to different screen sizes. Use grid layouts for flexible content arrangement.
```css
.md-typeset .grid {
grid-template-columns: repeat(auto-fit, minmax(10rem, 1fr));
}
```
By adhering to these best practices, you can maintain a consistent and high-quality codebase that is easy to understand, extend, and maintain.
