fmaury/seirdy.one
1
0
Fork 0
mirror of https://git.sr.ht/~seirdy/seirdy.one synced 2024-11-10 00:12:09 +00:00
Code Issues Projects Releases Wiki Activity

Add --dry-run and mention living article.

Browse source
This commit is contained in:
Rohan Kumar 2022-06-13 08:24:45 -07:00
parent c68fb1f2f8
commit 6fc1a907b4
No known key found for this signature in database
GPG key ID: 1E892DB2A5F84479
2 changed files with 8 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
content/posts/cli-best-practices.gmi
View file

@ -2,6 +2,8 @@ This began as a reply to another article by Lucas F. Costa; it lists practices t
=> https://lucasfcosta.com/2022/06/01/ux-patterns-cli-tools.html Lucas' article
This is a "living article" that I plan on adding to indefinitely. If you like it, come back in a month or two and check the "changelog" link in the article header.
Note: this article specifically concerns CLIs, not full-blown textual user interfaces (TUIs). It also focuses on utilities for UNIX-like shells; other command-line environments may have different conventions.
## Problematic patterns
@ -82,6 +84,8 @@ Avoiding reliance on color and using whitespace and/or indentation for pseudo-he
11. Be predictable. Users expect "git log" to print a commit log. Users do not expect "git log" to make network connections, write something to their filesystem, etc. Try to only perform the minimum functionality suggested by the command. Naturally, this disqualifies opt-out telemetry.
12. Be safe. If a tool makes irreversible changes to the outside environment, add a "--dry-run" or equivalent option.
Code snippet 2 (console): This is what tab-completion for MOAC looks like with fzf-tab.
```

4
content/posts/cli-best-practices.md
View file

@ -15,6 +15,8 @@ outputs:
---
This began as a reply to another article by Lucas F. Costa; it lists practices to improve user-experience (<abbr title="User Experience">UX</abbr>) of command-line interfaces (<abbr title="Command-Line Interface">CLIs</abbr>). It comes from a good place, and has some good advice: I particularly like its advice on input-validation and understandable errors. Unfortunately, a number of its suggestions are problematic, particularly from an accessibility perspective.
This is a "living article" that I plan on adding to indefinitely. If you like it, come back in a month or two and check the "changelog" link in the article header.
<p role="doc-tip">Note: this article specifically concerns CLIs, not full-blown textual user interfaces (<abbr title="Textual User Interfaces">TUIs</abbr>). It also focuses on utilities for UNIX-like shells; other command-line environments may have different conventions.</p>
Problematic patterns
@ -91,6 +93,8 @@ This is a non-exhaustive list of simple, baseline recommendations for designing
11. Be predictable. Users expect `git log` to print a commit log. Users do not expect `git log` to make network connections, write something to their filesystem, etc. Try to only perform the minimum functionality suggested by the command. Naturally, this disqualifies opt-out telemetry.
12. Be safe. If a tool makes irreversible changes to the outside environment, add a `--dry-run` or equivalent option.
{{<codefigure samp="true">}} {{< codecaption lang="console" >}} This is what tab-completion for [MOAC](https://sr.ht/~seirdy/moac) looks like with fzf-tab. {{< /codecaption >}}
```figure {samp=true}