Best Practices
What Is the best_practices.md File?
best_practices.md File?The best_practices.md file helps your team stay aligned by documenting and sharing coding guidelines directly within your project.
Qodo Gen 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 Gen will use your documented practices to offer more accurate, consistent, and context-aware help.
How to Create It
Qodo Gen includes a built-in workflow that generates a suggested best_practices.md file for your project. You can customize this file at any time by editing or replacing its contents with your own team’s standards.
Once created, place the file at the root of your project directory so Qodo Gen can read it automatically.
What It Can Include
The best_practices.md file is flexible. It can include guidelines on:
Code style and naming conventions
Documentation standards
Python and scripting best practices
YAML and configuration structures
GitHub Actions setup
Testing strategies
Chat command usage
CSS or front-end rules
Any other practices specific to your team
Use Cases
Better Suggestions: When Qodo Gen writes or reviews code, it follows your documented rules.
Team Alignment: Everyone uses the same standards, even across different projects or services.
Faster Onboarding: New developers quickly understand your practices.
Less Back-and-Forth: Review cycles improve when everyone codes the same way.
Technical Details
File must be named:
best_practices.mdMust be placed in the root of the project directory
Up to 1,500 lines will be processed
If the file exceeds 1,500 lines, Qodo Gen will read only the first portion.
Tip: Keep It Living
You can continue refining the file over time. Ask Qodo Gen to help add, rewrite, or clean up sections as your project evolves.
Example
# Qodo Gen 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.Last updated
Was this helpful?