apache/ofbiz-plugins/coding-standards

Skill: coding-standards

Goal

Ensure all OFBiz contributions meet production-grade standards for clarity, maintainability, and architectural alignment.

Triggers

ALWAYS read this skill when:

• Writing any code (Java, Groovy, XML, CSS).
• Reviewing PRs or auditing existing code for OFBiz alignment.
• Using OFBiz utility libraries for validation and map creation.
• Preparing a pull request or implementing new features.

General Rules

1. Explain the WHY: Code shows what happens. Comments must explain why (e.g., explaining a workaround for a legacy constraint).
2. No Internal Monologue: Delete "thinking out loud" or "maybe this works" comments.
3. Guard against Technical Debt: Avoid // TODO without a tracking reference.
4. Remove Debug Code: Clean up System.out.println, println, or excessive Debug.logInfo before completion.

OFBiz Specific Standards

1. XML Actions: Keep logic flat. If it requires complex loops or nesting, move to Groovy.
2. Naming Conventions:

• Components: kebab-case (e.g., order-management).
• Entities/Services: UpperCamelCase for entities, lowerCamelCase for services.
• Java/Groovy: lowerCamelCase for methods/variables, UpperCamelCase for classes.

1. Documentation:

• Services: Every service MUST have a <description> in services.xml.
• Java/Groovy: Use Javadoc/Groovydoc for public methods and complex logic.

1. Utility Libraries:

• Validation: ALWAYS use UtilValidate.isEmpty() or isNotEmpty().
• Maps/Lists: Use UtilMisc.toMap(...) and UtilMisc.toList(...) for concise creation.
• Logging: Use Debug.logInfo(...), Debug.logError(...) with a MODULE tag.
• Use .filterByDate() for all date-effective entities (e.g., ProductPrice, StatusItem).
• Prefer EntityQuery over delegator.findOne(...).
• Prefer shared OFBiz/domain helpers such as PartyHelper, UtilDateTime, ObjectType, and existing component helpers over local formatting or conversion helpers.
• If service XML already types a parameter as Timestamp, BigDecimal, Double, Long, or Integer, use the value directly in Groovy/Java service logic instead of re-parsing or re-casting it at the service boundary.

1. Internationalization (i18n):

• Never hardcode user-facing strings. Use uiLabelMap.LabelKey.

Guardrails

• Consistency: Follow the existing indentation and naming conventions of the component you are editing.
• Transactional Integrity: Respect OFBiz service boundaries; don't commit transactions manually.

Examples

Example: Clean documentation

// Check if the product is active based on current system time.
// We use filterByDate to ensure we only get valid price records.
GenericValue price = EntityQuery.use(delegator).from("ProductPrice")
        .where("productId", productId)
        .filterByDate()
        .queryFirst();

See Also

• prepush-readiness — the mechanical checks (Checkstyle, CodeNarc, compilation) that enforce a subset of these standards before a push.
• manage-contribution-workflow — branching, testing, commit, and PR conventions once the code itself is ready.