Skip to content

Latest commit

 

History

History
104 lines (75 loc) · 3.86 KB

FINANCE_SERVICES_NAMING.md

File metadata and controls

104 lines (75 loc) · 3.86 KB

Finance Services Naming: Unified vs Specific

Current Approach (Specific)

Pattern:

  • Payment Gateway: {gateway}-payment-service
  • Credit Gateway: {gateway}-credit-service

Examples:

  • zarinpal-payment-service
  • sadad-payment-service
  • sibank-credit-service

Proposed Approach (Unified)

Pattern: {gateway}-finance-service

Examples:

  • zarinpal-finance-service
  • sadad-finance-service
  • sibank-finance-service

Analysis

Pros of Unified *-finance-service:

  1. Simplicity: ✅ Single pattern for all finance services
  2. Consistency: ✅ All finance services follow the same naming convention
  3. Scalability: ✅ Easy to add new finance service types without renaming
  4. Unified Category: ✅ All services in Finance Services category have consistent naming
  5. Less Complexity: ✅ No need to distinguish between payment/credit in the name
  6. Future-Proof: ✅ Can accommodate new finance service types (e.g., *-finance-service for other financial operations)

Cons of Unified *-finance-service:

  1. Less Specific: ⚠️ Name doesn't indicate payment vs credit
  2. Less Self-Documenting: ⚠️ Need to check documentation to know the service type
  3. Less Descriptive: ⚠️ "finance" is more generic than "payment" or "credit"

Pros of Specific *-payment-service / *-credit-service:

  1. Self-Documenting: ✅ Name clearly indicates service type
  2. More Descriptive: ✅ Immediately know if it's payment or credit
  3. Better Discovery: ✅ Easy to find payment vs credit services

Cons of Specific Approach:

  1. More Complex: ⚠️ Two different patterns to maintain
  2. Less Flexible: ⚠️ Need to decide pattern when adding new services
  3. Potential Confusion: ⚠️ What if a gateway does both payment and credit?

Recommendation

Recommended: Unified *-finance-service ⭐

Rationale:

  1. Category-Based Organization: Since all services are in the "Finance Services" category, the category itself provides context
  2. Simplicity: Single pattern is easier to maintain and understand
  3. Scalability: Can easily add new finance service types without renaming
  4. Consistency: All finance services follow the same pattern
  5. Documentation: Service type (payment/credit) can be documented in the service description or README
  6. Future-Proof: If a gateway provides both payment and credit, *-finance-service covers both

Implementation:

  • Pattern: {gateway-name}-finance-service
  • Examples:
    • zarinpal-finance-service (payment gateway)
    • sadad-finance-service (payment gateway)
    • sibank-finance-service (credit gateway)
    • saman-finance-service (payment gateway)
    • etc.

Documentation Strategy:

Since the name doesn't specify payment vs credit, document it in:

  1. Service Description: In repository description
  2. README: In each service's README file
  3. NAMING_STANDARD.md: List which services are payment vs credit
  4. Service Metadata: Can add tags or labels

Comparison Table

Aspect Unified *-finance-service Specific *-payment-service / *-credit-service
Simplicity ⭐⭐⭐ ⭐⭐
Consistency ⭐⭐⭐ ⭐⭐
Self-Documenting ⭐⭐ ⭐⭐⭐
Scalability ⭐⭐⭐ ⭐⭐
Maintainability ⭐⭐⭐ ⭐⭐
Flexibility ⭐⭐⭐ ⭐⭐

Final Recommendation

Use *-finance-service for all finance services because:

  • It's simpler and more consistent
  • All services are in the Finance Services category anyway
  • Service type can be documented in description/README
  • It's more scalable for future finance service types
  • It's easier to maintain a single pattern

The slight loss in self-documentation is acceptable given the benefits of simplicity and consistency.