Référence › Règles de style

Référence

Bien écrire en Arche

Cette page explique comment écrire un modèle qui se lit comme tous les autres. Le langage (spec.md) dit ce qui est permis. Cette page dit ce qui est bien.

L’essentiel est fait pour vous. archec fmt --write écrit la mise en forme, et archec vet signale le reste. Chaque section ci-dessous correspond à un code de vet, et archec explain <code> affiche cette section.

Un premier essai#

Ce modèle utilise un ancien mot-clé (msg), met deux éléments sur une même ligne, et nomme une part avec la mauvaise casse (Desk) :

msg GO: bool

component Lamp "Lamp" {
  in cmd: can receives GO; kind ecu
}

system Room "Room" {
  part Desk: Lamp
}

Enregistrez-le sous main.arche. Laissez d’abord archec fmt écrire la mise en forme :

archec fmt --write main.arche
formatted main.arche

Le fichier contient maintenant message GO: bool, et kind ecu est sur sa propre ligne. Demandez ensuite le reste à archec vet :

archec vet main.arche
main.arche:9:8 hint 'Desk' is a part: `desk` (rename it in the editor — every use follows) [naming]
1 style finding(s) — `archec fmt --write` fixes the layout ones

archec vet renvoie le code 1 quand il a une remarque, et le code 0 quand il affiche ✓ vet: nothing to say.

La forme d’un projet#

  • Un dossier par projet, avec le fichier principal à sa racine (main.arche). Puis un dossier par domaine du système :
    • models/ ;
    • spec/ : les exigences et les fonctions ;
    • verification/ : les plans de test et les scénarios ;
    • app/ : ce que montre l’application Arche.
  • La structure dans les .arche, le comportement dans les .py, les traductions à part.
    • Un fichier de modèle dit ce qu’est le système.
    • Son Python vit à côté. archec fmt --extract-code l’y déplace.
    • Les textes dans une seconde langue vivent dans translations/<lang>.arche. archec refactor translations --extract en les y déplace.
  • Écrivez d’abord le cœur : composants, ports, liens, messages, exigences, plans de test. Ajoutez les autres jeux quand vous en avez besoin : déploiement, analyse fonctionnelle, sûreté et sécurité, l’application.

long-form#

Il y a une seule façon d’écrire chaque chose. Une forme plus ancienne ou plus longue se lit encore, mais archec fmt écrit la forme standard :

  • message, et non msg ;
  • out tx: can, et non port tx: can out ;
  • unit m/s, et non unit "m/s".
bad:   msg GO: bool                      good:  message GO: bool
bad:   port tx "TX": can out             good:  out tx: can "TX"

same-line#

Un élément par ligne. N’utilisez ; entre des éléments qu’à l’intérieur d’un bloc écrit sur une seule ligne :

bad:   kind ecu; layer physical          good:  kind ecu
       tags safety                              layer physical
                                                tags safety
fine:  widget title { type text; at [0, 0, 12, 1] }

property-order#

Écrivez les propriétés d’un élément dans le même ordre dans chaque fichier. L’œil sait alors où regarder. L’ordre est le suivant :

  1. ce qu’il est : description, text, objective ;
  2. comment il est classé : kind, layer, tags, status, priority… ;
  3. son type : provides, sends, unit… ;
  4. le reste ;
  5. ses traces : satisfies, verifies, derives… ;
  6. sa place sur le canevas : at, size.

archec fmt les remet dans cet ordre.

property-group#

Quand trois propriétés ou plus vont ensemble, écrivez-les sous forme de groupe : timing { latency 2ms; jitter 100us; bitrate 1Mbps }. Le groupe signifie la même chose que les trois lignes. Les groupes sont timing, delivery, compute, physical et errors.

declaration-set#

Les déclarations de l’application Arche vivent dans app/*.arche, à part du modèle. Ce sont les pages, les panneaux, les widgets, les stories, les benchmarks et le menu. Ainsi, un fichier de modèle ne contient que le système.

naming#

La casse d’un nom dit ce qu’il désigne, comme en Go :

Quoi Casse Exemple
une définition, un système, un type, une interface PascalCase BrakeEcu, Car, Speed
une part, un port, une fonction, une variable snake_case brakes, can0, regulate, target_speed
un message, une constante, un littéral d’énumération SCREAMING_CASE BRAKE_CMD, MAX_SPEED, AUTONOMOUS
une exigence, un plan de test, un cas tel que son document l’écrit REQ-BRK-001, TP-AEB, TC-AEB-01

Un nom importé garde son identifiant Arche grâce à as, par exemple component flash_memory "FLASH" as c-1793752253957. Pour renommer, utilisez l’éditeur (F2) : chaque utilisation suit.

code-in-model#

Un bloc Python de plus de quelques lignes, c’est du comportement. Il se lit mieux dans le fichier .py placé à côté du modèle. archec fmt --extract-code --write l’y déplace, et la fonction y reste liée.

arche-body#

Certains corps Python ne font que ce que fait le langage d’action : if, goto, send, return, des affectations, des comparaisons, wait, log, et des appels aux fonctions de la part. Un tel corps se lit mieux en corps ```arche. archec le vérifie alors, et le traduit en C, en Rust et en Go, et pas seulement en Python.

Le correctif rapide Convert to arche body l’écrit, tout comme archec fix --only arche-body. Un corps qui en fait plus reste en Python : une liste, une bibliothèque, un nom que le modèle ne déclare pas.

Petites choses#

  • Un libellé, c’est ce que les gens lisent. Écrivez-en un sur chaque déclaration qu’un lecteur rencontre : component BrakeEcu "Brake ECU".
  • Écrivez une garde entre crochets : Idle -> Run on GO [speed > 0].
  • Écrivez une trace là où elle part : satisfies REQ-1 sur la part, verifies REQ-1 sur le cas. archec refactor move-traces déplace les traces écrites à part.
  • Les cas qui ne diffèrent que par leurs valeurs vont dans une seule table cases.
  • archec signale un texte invérifiable, comme « as fast as possible » ou « TBD » (vague-word). Donnez le nombre, ou marquez l’exigence tbc.