Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-029 — Nommage de la surface publique : explicite, sans abréviation ; noms d’autorité conservés à l’interface

Statut : Accepté. Décline le Principe d’ingénierie 7 pour le nommage de l’API.

Catégorie : Méthode (transverse, tout le framework).

Contexte

Air produit des API destinées à des développeurs de tous niveaux, y compris des débutants qui ne connaissent pas (encore) les interfaces du kernel Linux. Un des buts du framework est de décomplexifier l’accès au système : apprendre les concepts est déjà exigeant, l’API ne doit pas y ajouter d’ambiguïté.

Or les abréviations sont une source d’erreur silencieuse pour qui ne connaît pas déjà l’API. Un sénior lit sock et pense « socket » sans effort ; un débutant qui a lu « socket » dans la documentation peut douter que sock désigne la même chose — et le doute coûte du temps et induit des erreurs. L’abréviation est invisible pour l’expert, piégeuse pour le débutant.

Cet ADR érige en règle ce que le Principe 7 (« verbosité au service de la clarté ») implique pour le nommage de l’API, et tranche les cas limites rencontrés en spécifiant le module io_uring (ADR-022, ADR-028).

Décision

Règle des deux zones

Zone 1 — la surface offerte au développeur (types, fonctions, méthodes, paramètres, champs publics que Air conçoit) : noms explicites, en toutes lettres, sans abréviation.

  • socket, pas sock ; buffer, pas buf ; address, pas addr ; length, pas len ; previous, pas prev ; completion_queue_entries, pas cq_entries ; attach_work_queue, pas attach_wq ; IoUringOpcode, pas IoUringOp ; etc.

Zone 2 — l’interface avec une autorité que le développeur peut consulter : noms conservés verbatim, pour que le développeur retrouve le même nom dans la documentation de référence et fasse le lien.

Les autorités reconnues sont :

  1. L’ABI du kernel Linux — noms de syscalls, d’opcodes, de structures et de champs (io_uring_sqe, IORING_OP_*, sqe->res, struct sock_filter, utsname, pidfd…). Le développeur les retrouve dans les man pages / le header uapi.
  2. La bibliothèque standard de Rust — types et conventions de std (OwnedFd, BorrowedFd, RawFd, IoSlice, SocketAddr, Instant…). Le développeur les retrouve dans la doc de std ; les renommer diminuerait la familiarité, pas l’inverse.
  3. Les termes universels Unix/POSIX — errno, pid, tid, fd : un vocabulaire que tout développeur système croise partout.

Le test de décision

« Ce nom, est-ce Air qui l’a inventé, ou est-il hérité d’une autorité que le développeur ira consulter ? »

  • Inventé par Air ⇒ explicite, sans abréviation (Zone 1).
  • Hérité d’une autorité (kernel / std / POSIX) ⇒ conservé verbatim (Zone 2).

Illustration cardinale :

  • Completion::sock_nonempty() est un nom coiné par Air qui abrège un concept (« socket ») → Zone 1 → à renommer (socket_has_pending_data).
  • BorrowedFd n’est pas une abréviation d’Air : c’est le nom du type de la bibliothèque standard (std::os::fd::BorrowedFd) → Zone 2 → conservé. De même struct sock_filter (nom exact du kernel) reste SockFilter — le sock y est l’ABI kernel, pas une abréviation d’Air.

Autrement dit : le même fragment sock est proscrit quand c’est nous qui abrégeons « socket » dans un nom maison, et conservé quand il fait partie d’un nom d’autorité que le développeur peut retrouver.

Nuance des types « miroir » (ex. niveau brut io_uring, Temps 4)

Un type public dont la raison d’être est de refléter 1:1 une structure kernel suit une règle mixte, déjà appliquée au Temps 4 :

  • le nom du type est explicite (Zone 1) : RawSubmissionQueueEntry (et non RawSqe) ;
  • ses champs qui miroitent la struct kernel conservent les noms kernel (Zone 2) : user_data, res, flags, addr — précisément pour que le développeur fasse le lien avec struct io_uring_cqe.

Conséquences

Bénéfices

  • API lisible et sans ambiguïté pour les débutants ; décomplexification réelle.
  • Cross-référence préservée vers le kernel, std et POSIX pour les développeurs qui creusent.
  • Règle de décision objective : tranche sans débat les cas limites (cf. cq_entries builder → with_completion_queue_entries ; attach_wq → attach_work_queue).

Coûts

  • Identifiants plus longs (verbosité assumée — c’est l’esprit du Principe 7).
  • Une passe de renommage de la surface existante (io_uring et familles couche 0) est nécessaire pour mettre l’existant en conformité.

Portée et application

  • S’applique à toute la surface publique d’Air, toutes couches.
  • Les abréviations tolérées comme mots à part entière d’usage universel (id, min, max, info) sont admises au cas par cas, mais la préférence va toujours à la forme explicite quand elle ne nuit pas à la lisibilité.
  • Un futur STYLE_GUIDE.md référencera cet ADR pour la partie nommage.

Articulation avec les autres ADRs

  • Principe d’ingénierie 7 : cet ADR en est la déclinaison opérationnelle pour le nommage de l’API.
  • ADR-021 (conventions transverses couche 0) : même esprit (lisibilité, pas de magie cachée) ; ADR-029 étend la portée à toute la surface publique.
  • ADR-022 / ADR-028 (io_uring) : les renommages de la façade io_uring (IoUringOpcode, with_completion_queue_entries, attach_work_queue, socket_has_pending_data, RawSubmissionQueueEntry…) appliquent cet ADR.

Statut futur

ADR immuable dans sa règle (deux zones + test de décision) sauf RFC. La liste des abréviations universelles tolérées peut être précisée dans le STYLE_GUIDE.md sans amender cet ADR.

Licence du document : MPL 2.0 Statut : Document de méthode, transverse au framework.