Frappe Development Standards and Guidelines

Table of Contents

• Introduction
• DocType Standards
• Field Standards
• DocType Properties
• Best Practices
• Common Patterns
• Additional Notes

Introduction

This document outlines comprehensive standards and guidelines for developing applications using the Frappe Framework. Following these standards ensures consistency, maintainability, and optimal performance across your applications. Whether you're creating new DocTypes, defining fields, or implementing business logic, these guidelines will help maintain high-quality code standards.

DocType Standards

DocType Naming Rules

Basic Naming Standards

1. Use Title Case for DocType names

   • ✅ Correct: Customer Profile, Sales Order, Inventory Item
   • ❌ Incorrect: customer_profile, Sales_order, inventoryitem

   Why? Title Case makes DocTypes easily distinguishable from fields and provides better readability in the UI.

2. Use clear, descriptive names that indicate the purpose

   • ✅ Correct: Purchase Invoice, Employee Attendance, Project Task
   • ❌ Incorrect: PI, EmpAtt, Task1

   Why? Clear names reduce confusion and make the codebase self-documenting.

3. For child DocTypes, append "Item" or a relevant descriptor

   • ✅ Correct: Sales Order Item, Purchase Invoice Item, Task Checklist Item
   • ❌ Incorrect: SalesOrderLine, PurchaseInvoiceDetail, TaskChecks

   Why? Consistent naming for child DocTypes makes relationships clear and helps maintain a standard pattern.

4. For activity or transaction logs, append "Log" or "History"

   • ✅ Correct: Payment Log, Inventory Transaction History, User Activity Log
   • ❌ Incorrect: PaymentRecord, InventoryTransactions, UserActions

   Why? Clear distinction of log tables helps in data organization and querying.

Field Standards

Field Naming Conventions

1. Use snake_case for all field names

   • ✅ Correct: first_name, tax_amount, shipping_address
   • ❌ Incorrect: firstName, TaxAmount, shipping-address

   Why? Consistent with Python naming conventions and database field naming practices.

2. Use descriptive prefixes for boolean fields

   • ✅ Correct: is_active, has_attachments, can_login
   • ❌ Incorrect: active, attachments, login

   Why? Boolean field prefixes make code more readable and self-documenting.

3. Use clear relationship indicators for link fields

   • ✅ Correct: customer_id, parent_category, assigned_to
   • ❌ Incorrect: customer, parent, assignee

   Why? Clear relationship indicators help in understanding data relationships.

Field Property Standards

1. Mandatory Fields Every DocType should include these basic fields:

   - title_field (name to be displayed)
   - creation_date (automatic)
   - modified_date (automatic)
   - owner (automatic)
   - status (if document follows a workflow)
   

2. Field Labels

   • Use Title Case for labels
   • Keep labels concise but clear
   • Include units in parentheses if applicable
     • ✅ Correct: "Weight (kg)", "Duration (Hours)", "Distance (km)"
     • ❌ Incorrect: "Weight in KG", "Duration_Hours", "Distance"

3. Field Types Choose appropriate field types based on data requirements:

   - Data: Short text without formatting
   - Text Editor: Formatted text content
   - Link: References to other DocTypes
   - Select: Predefined options (limit to 10)
   - Table: Child tables
   - Code: Code content
   - JSON: JSON content
   - Attach: File attachments
   - Signature: Signature captures
   

   Why? Using the correct field type ensures data integrity and provides appropriate UI elements.

DocType Properties

Basic Properties

1. Module Settings

   - Choose appropriate module
   - Set proper naming series
   - Configure document numbering
   

2. Permission Settings

   - Define role-based permissions
   - Set user permissions if needed
   - Configure sharing settings
   

3. View Settings

   - Configure search fields
   - Set up quick entry fields
   - Define default sort field
   

Advanced Properties

1. Automation Settings

   - Configure workflows (if needed)
   - Set up auto-repeat (if applicable)
   - Define track changes settings
   

2. Integration Settings

   - Enable API access if needed
   - Configure webhook settings
   - Set up email alerts
   

Best Practices

Documentation

1. Add comprehensive descriptions to DocTypes

   - Purpose of the DocType
   - Key relationships
   - Important business rules
   

2. Field Organization

   - Group related fields in sections
   - Order fields logically
   - Use tabs for distinct categories
   

3. Performance Considerations

   - Index frequently searched fields
   - Limit number of mandatory fields
   - Optimize table fields
   - Keep child tables focused
   - Limit fields (aim for < 30 per DocType)
   

Common Patterns

Status Management

Standard status flow for most DocTypes:

Draft → Active → Inactive → Cancelled

Audit Fields

Always ensure these fields are included for tracking:

- Created By
- Created Date
- Modified By
- Modified Date
- Workflow State (if applicable)

Relationship Fields

Standard fields for organizational structure:

- Company (multi-company setups)
- Branch (multi-branch operations)
- Department (departmental segregation)
- Cost Center (accounting purposes)

Additional Notes

Layout Elements

1. Adding a Column

   - Add row without label
   - Choose Type → Column Break
   Purpose: Creates a new column in the form layout
   

2. Adding a Section

   - Add row without label
   - Choose Type → Section Break
   Purpose: Creates a new section with optional collapsible behavior
   

3. Adding a Tab

   - Add row with descriptive label
   - Choose Type → Tab Break
   Purpose: Creates a new tab in the form
   

Special Model Settings

1. Track Changes

   Check "Track Changes" to:
   - Enable Git tracking
   - Allow GitHub pushes
   - Maintain version history
   

2. Single DocType

   Check "Is Single" for:
   - Configuration/Settings DocTypes
   - System preferences
   - Single-record DocTypes
   

3. Tree DocType

   Check "Is Tree" for:
   - Hierarchical data structures
   - Parent-child relationships
   - Organizational structures
   

Important Considerations

1. Field Limitations

   • Keep field count under 30 per DocType when possible
   • Use child tables for repeating data
   • Consider breaking large DocTypes into smaller, related DocTypes

2. Naming Requirements

   • Only label and type are mandatory for fields
   • Use meaningful, self-documenting names
   • Follow naming conventions consistently

3. Performance Tips

   • Index frequently queried fields
   • Use appropriate field types
   • Optimize table relationships
   • Consider data volume in design decisions

Note: These standards are guidelines. While they should be followed in most cases, there might be situations where deviating from them makes sense. Always document the reasoning behind any deviations.