Effective Arche
This page says how to write a model that reads like every other one. The language (spec.md) says what is allowed. This page says what is good.
Most of it is done for you. archec fmt --write writes the layout, and
archec vet reports the rest. Each section below is one vet code, and
archec explain <code> prints that section.
A first run#
This model uses an old keyword (msg), puts two items on one line, and names a
part in the wrong case (Desk):
msg GO: bool
component Lamp "Lamp" {
in cmd: can receives GO; kind ecu
}
system Room "Room" {
part Desk: Lamp
}
Save it as main.arche. First let archec fmt write the layout:
archec fmt --write main.arche
formatted main.arche
The file now says message GO: bool, and kind ecu is on its own line. Then
ask archec vet for the rest:
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 exits with 1 when it has a finding, and with 0 when it prints
✓ vet: nothing to say.
The shape of a project#
- One folder per project, with the main file at its top (
main.arche). Then one folder per area of the system:models/;spec/: requirements and functions;verification/: test plans and scenarios;app/: what the Arche app shows.
- Structure in
.arche, behaviour in.py, translations apart.- A model file says what the system is.
- Its Python lives beside it.
archec fmt --extract-codemoves it there. - The texts in a second language live in
translations/<lang>.arche.archec refactor translations --extract enmoves them there.
- Write the core first: components, ports, links, messages, requirements, test plans. Add the other sets when you need them: deployment, functional analysis, safety and security, the app.
long-form#
There is one way to write each thing. An older or longer form still reads, but
archec fmt writes the standard one:
message, notmsg;out tx: can, notport tx: can out;unit m/s, notunit "m/s".
bad: msg GO: bool good: message GO: bool
bad: port tx "TX": can out good: out tx: can "TX"
same-line#
One item per line. Use ; between items only inside a block written on one
line:
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#
Write the properties of an element in the same order in every file. Then the eye knows where to look. The order is:
- what it is:
description,text,objective; - how it is classified:
kind,layer,tags,status,priority…; - its type:
provides,sends,unit…; - the rest;
- its traces:
satisfies,verifies,derives…; - its place on the canvas:
at,size.
archec fmt puts them in this order.
property-group#
When three or more properties go together, write them as their group:
timing { latency 2ms; jitter 100us; bitrate 1Mbps }. The group means the same
as the three lines. The groups are timing, delivery, compute, physical
and errors.
declaration-set#
The Arche app's declarations live in app/*.arche, apart from the model. These
are the pages, panels, widgets, stories, benchmarks and the menu. So a model
file holds only the system.
naming#
A name's case says what it is, as in Go:
| What | Case | Example |
|---|---|---|
| a definition, a system, a type, an interface | PascalCase |
BrakeEcu, Car, Speed |
| a part, a port, a function, a variable | snake_case |
brakes, can0, regulate, target_speed |
| a message, a constant, an enum literal | SCREAMING_CASE |
BRAKE_CMD, MAX_SPEED, AUTONOMOUS |
| a requirement, a test plan, a case | as its document writes it | REQ-BRK-001, TP-AEB, TC-AEB-01 |
An imported name keeps its Arche id with as, for example
component flash_memory "FLASH" as c-1793752253957. To rename, use the editor
(F2): every use follows.
code-in-model#
A Python block of more than a few lines is behaviour. It reads better in the
.py file beside the model. archec fmt --extract-code --write moves it there,
and the function stays bound to it.
arche-body#
Some Python bodies do only what the action language does: if, goto, send,
return, assignments, comparisons, wait, log, and calls to the part's
functions. Such a body reads better as a ```arche body. archec then
checks it, and translates it to C, Rust and Go, not only to Python.
The quick fix Convert to arche body writes it, and so does
archec fix --only arche-body. A body that does more is left as Python: a list,
a library, a name the model does not declare.
Small things#
- A label is what people read. Write one on every declaration a reader meets:
component BrakeEcu "Brake ECU". - Write a guard in brackets:
Idle -> Run on GO [speed > 0]. - Write a trace where it starts:
satisfies REQ-1on the part,verifies REQ-1on the case.archec refactor move-tracesmoves the traces written apart. - Cases that differ only in their values go in one
casestable. - archec points out a text that cannot be verified, such as "as fast as
possible" or "TBD" (
vague-word). Say the number, or mark the requirementtbc.