docs: add best practices file

[ruromero]

User description

replace #557

---

PR Type

Documentation

---

Description

• Add comprehensive best practices guide with four key patterns

• Pattern 1: Clean up dead code after feature removal

• Pattern 2: Guard nullable fields and handle exceptions consistently

• Pattern 3: Centralize branding and configuration in single source

• Pattern 4: Cache only successful results and report accurately

---

Diagram Walkthrough

flowchart LR
  A["Best Practices Guide"] --> B["Pattern 1: Code Cleanup"]
  A --> C["Pattern 2: Null Safety & Error Handling"]
  A --> D["Pattern 3: Configuration Centralization"]
  A --> E["Pattern 4: Caching Best Practices"]
  B --> F["Remove dead code paths"]
  C --> G["Guard nullable fields"]
  D --> H["Centralize defaults"]
  E --> I["Cache successful results only"]

Loading

File Walkthrough

	Relevant files
Documentation	best_practices.md Add four best practices patterns with examples                      best_practices.md Introduces four architectural and coding best practices patterns Each pattern includes before/after code examples References relevant GitHub PR discussions for context Covers code cleanup, null safety, configuration management, and caching strategies +145/-0

---

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Add code block languages Add language identifiers (e.g., java, properties) to the fenced code blocks to enable syntax highlighting. best_practices.md [6-15] -``` +```java // Code path still assumes a provider exists from("direct:scan") .split(exchangeProperty("providers")) .aggregate(constant(true), new ProviderAggregator()) .to("bean:osvProvider"); // Deployment/config still injects unused infra vars %prod.redis.hosts=redis://${REDIS_HOST}:${REDIS_PORT} - [ ] **Apply / Chat** <!-- /improve --apply_suggestion=0 --> <details><summary>Suggestion importance[1-10]: 5</summary> __ Why: The suggestion correctly points out the missing language identifiers in code blocks, and adding them significantly improves code readability through syntax highlighting, which is crucial for a document demonstrating code patterns. </details></details></td><td align=center>Low </td></tr><tr><td> <details><summary>Improve caching logic for better performance</summary> ___ **To improve performance, iterate over the <code>misses</code> list and get items from the <br><code>response.items()</code> map, instead of iterating over all response items and checking <br>for inclusion in <code>misses</code>.** [best_practices.md [129-135]](https://github.com/guacsec/trustify-dependency-analytics/pull/562/files#diff-10fe161b5a3240b52893b3258849112844da07a8d0fa5d6d95b52793ed0007caR129-R135) ```diff int cached = 0; -for (var entry : response.items().entrySet()) { - if (misses.contains(new Ref(entry.getKey()))) { - cache.set("items:" + entry.getKey(), entry.getValue()); +for (Ref r : misses) { + Item item = response.items().get(r.key()); + if (item != null) { + cache.set("items:" + r.key(), item); cached++; } } Apply / Chat Suggestion importance[1-10]: 4 __ Why: The suggestion offers a valid performance optimization for the example code, which is more efficient if the misses list is smaller than the response.items() map. While the existing code is functionally correct, this improves the quality of the best practice example.	Low
	✅ Use markdown headings Suggestion Impact: The commit removed the ... wrapper and replaced it with a markdown level-3 heading (###) for "Pattern 1". code diff: -<b>Pattern 1: After removing or decommissioning a feature/provider/integration, delete all related configuration, deployment wiring, and code paths (routes, aggregations, env vars, constants) to avoid dead code and misleading operational setup. -</b> +### Pattern 1: After removing or decommissioning a feature/provider/integration, delete all related configuration, deployment wiring, and code paths (routes, aggregations, env vars, constants) to avoid dead code and misleading operational setup. Replace HTML tags with markdown ### headings for better document structure and consistency. best_practices.md [2-3] -<b>Pattern 1: After removing or decommissioning a feature/provider/integration, delete all related configuration, deployment wiring, and code paths (routes, aggregations, env vars, constants) to avoid dead code and misleading operational setup. -</b> +### Pattern 1: After removing or decommissioning a feature/provider/integration, delete all related configuration, deployment wiring, and code paths (routes, aggregations, env vars, constants) to avoid dead code and misleading operational setup. [Suggestion processed] Suggestion importance[1-10]: 3 __ Why: This is a valid suggestion that improves the markdown file's structure and semantics by using native markdown headings (###) instead of HTML <b> tags, which is a best practice for markdown documents.	Low
	Update