Configuration mode command definitions

From VyOS Wiki
Revision as of 21:04, 26 November 2018 by Dmbaturin (talk | contribs) (Created page with "Configuration mode command definitions (also known as "interface definitions") are XML files that define the syntax of configuration mode commands, as well as completion help...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Configuration mode command definitions (also known as "interface definitions") are XML files that define the syntax of configuration mode commands, as well as completion help strings and set-time value validation rules.

Command definitions are purely declarative, and cannot contain any logic. All logic for generating config files for target applications, restarting services and so on is implemented in configuration scripts instead.

Command syntax guidelines

Command words

Use of numbers

Use of numbers in command names should be avoided unless a number is a part of a protocol name or similar. Thus, "protocols ospfv3" is perfectly fine, but something like "server-1" is questionable at best.

Help string guidelines

To ensure uniform look and feel, and improve readability, we should follow a set of guidelines consistently.

Capitalization and punctuation

The first word of every help string must be capitalized. There must not be a period at the end of help strings. Rationale: this seems to be the unwritten standard in network device CLIs, and a good aesthetic compromise.

Examples:

  • Good: "Frobnication algorithm"
  • Bad: "frobnication algorithm"
  • Bad: "Frobnication algorithm."
  • Horrible: "frobnication algorithm."

Use of abbreviations and acronyms

Abbreviations and acronyms must be capitalized. Examples:

  • Good: "TCP connection timeout"
  • Bad: "tcp connection timeout"
  • Horrible: "Tcp connectin timeout"

Acronyms also must be capitalized to visually distinguish them from normal words:

Examples:

  • Good: RADIUS (as in remote authentication for dial-in user services)
  • Bad: radius (unless it's about the distance between a center of a circle and any of its points)

Some abbreviations are traditionally written in mixed case. Generally, if it contains words "over" or "version", the letter should be lowercase. If there's an accepted spelling (especially if defined by an RFC or another standard), it must be followed.

Examples:

  • Good: PPPoE, IPsec
  • Bad: PPPOE, IPSEC
  • Bad: pppoe, ipsec

Use of verbs

Verbs should be avoided. If a verb can be omitted, omit it.

Examples:

  • Good: "TCP connection timeout"
  • Bad: "Set TCP connection timeout"

If a verb is essential, keep it. For example, in the help text of "set system ipv6 disable-forwarding", "Disable IPv6 forwarding on all interfaces" is a perfectly justified wording.

Prefer infinitives

Verbs, when they are necessary, should be in their infinitive form.

Examples:

  • Good: "Disable IPv6 forwarding"
  • Bad: "Disables IPv6 forwarding"