Saltar al contenido principal

ADR-030 — English Comments Mandatory

Status: Approved | Date: 2026-06-19 | Scope: All plugins

Context​

Early plugin code mixed Spanish and English in comments and PHPDoc. This creates friction when onboarding international contributors and when Claude Code sessions need to read and reason about the code (AI tooling trained predominantly on English code).

Decision​

All code comments in all obeliOmed plugins must be written in English. This includes:

  • PHPDoc class-level docblocks
  • PHPDoc method-level docblocks (@param, @return, @throws)
  • Inline // comments explaining non-obvious logic
  • File header comments
  • SQL comments in migration scripts
  • Twig template comments ({# #})
  • JavaScript/TypeScript comments

Not covered by this ADR (separate concern):

  • User-facing translation strings (i18n.trans()) — those remain in catalogs per language
  • Documentation pages in this docs site — Spanish is the primary language for user docs

What requires a comment​

  • Every class: one-sentence description of purpose
  • Every public method: @param + @return + purpose if not obvious from name
  • Complex loops or conditionals: one // line explaining the WHY (not the WHAT)
  • Non-obvious constraints or workarounds: explain why the unusual approach was chosen
/**
 * Calculates the next available appointment slot for the given specialist.
 *
 * Respects the specialist's schedule (RRULE), existing appointments,
 * and the clinic center's opening hours configured in AdminClinicCenter.
 *
 * @param int    $idSpecialist   Internal specialist ID
 * @param string $codalmacen     Clinic center code (FS warehouse)
 * @param string $fromDate       ISO 8601 start date (YYYY-MM-DD)
 * @return \DateTimeImmutable|null  Next available slot, or null if none within 60 days
 */
public function getNextSlot(int $idSpecialist, string $codalmacen, string $fromDate): ?\DateTimeImmutable
{
    // We cap at 60 days to avoid infinite loops when the specialist has no schedule configured.
    // The 60-day limit is configurable via obelio_scheduling_settings.max_slot_search_days.
    $maxDays = $this->getSettingInt('max_slot_search_days', 60);
    // ...
}

Consequences​

  • Consistent codebase language for all contributors and AI tooling
  • PHPDoc is readable by phpDocumentor for auto-generated docs on this site
  • One-time effort to update legacy Spanish comments during refactor phases