2026-06
- I should be able to install your piece of software without installing the compiler of the programming language that you used to implement this piece of software. It's great if I _can_ do that, but I shouldn't _have_ to. Ideally, provide a pre-built binary. For example, in order to install `cloud-provider-kind`, a piece of tech to make the `kind` kubernetes distribution work more like cloud kubernetes, I have to install the Go compiler: https://github.com/kubernetes-sigs/cloud-provider-kind . I came here for cloud-provider-kind, I do not want to install Go!
- Barring some exceptions, a user should be able to undo every action that they are able to perform. Doing then un-doing an operation should leave the application in the same state as not doing the operation in the first place (modulo two log entries). When I install an application, I should also be able to uninstall it. When I create a file, I should be able to delete it. I sometimes see authorization systems getting tripped over this. Permission to delete feels scarier than permission to create and so cautious systems sometimes prevent a user from deleting a resource that they created. Obvious exceptions are when operations are by their nature irreversible or cause a change in a remote system - a banking app cannot let a user undo a transfer, a detonation control system cannot un-detonate.
- If the case of a user error, provide a human-readable error message. If I enter the wrong thing into your tool, I do not want a traceback, an exception, a memory dump, or whatever other ugliness your runtime provides. I want a short, grammatically correct sentence telling me what I did wrong and what I should try next. I once wanted to try out HTTPie CLI (https://github.com/httpie/cli), a supposedly user-friendly alternative to curl. Let's say I want to retrieve some JSON from an API: `http GET --json https://carrythefire.net/some-api`.
Traceback (most recent call last):
File "/usr/bin/http", line 7, in <module>
sys.exit(main())
~~~~^^
File "/usr/lib/python3.14/site-packages/httpie/__main__.py", line 9, in main
exit_status = main()
File "/usr/lib/python3.14/site-packages/httpie/core.py", line 162, in main
return raw_main(
parser=parser,
...<2 lines>...
env=env
)
File "/usr/lib/python3.14/site-packages/httpie/core.py", line 77, in raw_main
parsed_args = parser.parse_args(
args=args,
env=env,
)
File "/usr/lib/python3.14/site-packages/httpie/cli/argparser.py", line 190, in parse_args
self._guess_method()
~~~~~~~~~~~~~~~~~~^^
File "/usr/lib/python3.14/site-packages/httpie/cli/argparser.py", line 430, in _guess_method
assert not self.args.request_items
^^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError
What the hell happened? I can make an educated guess that the `--json` flag is used in the wrong position. But there's nothing in the error message that would tell me that! Instead I get a Traceback from Python which is less than useless to me as a user. It may be useful to the _developer_ of the tool but to the user of the tool, it is just confusing. In general, I feel a good rule of thumb is "the user should not be able to guess which programming language was used to implement the application they are using". (This does not apply to software libraries, frameworks, etc., of course.)