Tirsvad
304ec7751b
New criteria, appended after the existing ones (nothing renumbered or changed): - DRY in all five qc-programming-* checklists (python, c, cpp, csharp, shell) - dependency rule in all but shell (imports, includes or references point inward, no cycles; in C also one responsibility per module) - SOLID in python, cpp and csharp - qc-dcd.md criterion 9: dependencies between classes and packages point inward (cycles stay with criterion 8) Each is tagged with an ISO/IEC 25010 characteristic, and the criterion Notes name the rule in the framework's coding-conventions skill, which defines it once. Each checklist has a new Proposed Version History row for S02, who accepts coding-standard changes. Common Defects gain a bullet per criterion.
63 lines
4.2 KiB
Markdown
63 lines
4.2 KiB
Markdown
# Quality Criteria: Shell Script (bash)
|
|
|
|
## Metadata
|
|
| Key | Value |
|
|
| --- | --- |
|
|
| ID | QC-SH-001 |
|
|
| CrossReference | [QC-DCD-001], [QC-ADR-001] |
|
|
|
|
## Version History
|
|
| Date | Status | Author | Reviewer | Change | Commit |
|
|
| --- | --- | --- | --- | --- | --- |
|
|
| 2026-10-02 | Accepted | Jens Tirsvad Nielsen | S07 | Initial version | — |
|
|
| 2026-10-09 | Proposed | Jens Tirsvad Nielsen | S02 | Added criterion 15 (DRY) | pending |
|
|
|
|
---
|
|
|
|
## Purpose
|
|
|
|
Shell scripts automate steps that change files, repositories and remote systems, so a defect often does damage quietly. This checklist confirms that a bash script follows the shell conventions (strict mode, quoting, error handling, safe defaults), so that it is predictable, maintainable and safe to run.
|
|
|
|
## Quality Criteria Checklist
|
|
|
|
Level: **Mandatory** criteria are the baseline every instance must meet; **Optional** criteria are advanced and may be deferred.
|
|
|
|
| # | Criterion | Level | ISO/IEC 25010 Characteristic(s) | Notes |
|
|
| --- | --- | --- | --- | --- |
|
|
| 1 | Starts with `#!/usr/bin/env bash` and `set -euo pipefail` (or a comment explains the exception) | Mandatory | Reliability | |
|
|
| 2 | Every expansion is quoted; lists are arrays; tests use `[[ ]]` and `$(...)` | Mandatory | Reliability, Security | Unquoted expansions break on spaces and globs |
|
|
| 3 | Names follow the conventions: `kebab-case.sh` files, `snake_case` functions and variables, `UPPER_SNAKE` constants and environment variables | Mandatory | Maintainability, Usability | |
|
|
| 4 | Passes `shellcheck` and `bash -n` with no unexplained `disable` comments | Mandatory | Maintainability, Reliability | State the tool versions used |
|
|
| 5 | Errors go to standard error with an `error:` message and a non-zero exit code; bad or missing arguments print a usage line | Mandatory | Reliability, Usability | |
|
|
| 6 | Temporary files use `mktemp` with a `trap ... EXIT` cleanup; no fixed `/tmp` names | Mandatory | Security, Reliability | |
|
|
| 7 | No secret is written in the script, echoed, or put on a command line; secrets come from the environment or a gitignored file | Mandatory | Security | |
|
|
| 8 | A script that changes state outside its own directory defaults to a dry run or needs an explicit flag, and says so in its header | Mandatory | Reliability, Security | |
|
|
| 9 | A header comment states purpose, usage, options, environment variables and exit codes | Mandatory | Usability, Maintainability | |
|
|
| 10 | The script implements a task or design it cites; deviations are recorded | Mandatory | Functional Suitability, Maintainability | |
|
|
| 11 | Behaviour is tested for success, failure and any disabled or bypass path | Mandatory | Reliability | Tests may be a recorded manual run |
|
|
| 12 | Formatted with `shfmt` (or the project's formatter) | Optional | Maintainability | |
|
|
| 13 | Safe to re-run: a second run does not duplicate or corrupt what the first did | Optional | Reliability | |
|
|
| 14 | Bash version and external tools it needs are stated; GNU-only options are named | Optional | Portability | |
|
|
| 15 | A command sequence, constant, path or message used more than once is defined once (a function, a variable or a sourced helper); a helper is shared between scripts only where it expresses the same knowledge | Mandatory | Maintainability | Modularity, Reusability. Rule: `coding-conventions` skill, “State each piece of knowledge once” |
|
|
|
|
## Common Defects
|
|
|
|
- Unquoted `$var` that breaks on a space or an empty value
|
|
- Missing `set -euo pipefail`, or `|| true` hiding a real failure
|
|
- Parsing `ls` output instead of using globs or `find -print0`
|
|
- A script that deletes or overwrites by default with no dry run
|
|
- A token echoed to the terminal or kept in the script
|
|
- No usage message, so a wrong call fails with a cryptic error
|
|
- A script that implements nothing in any task or design
|
|
- The same path, option list or message pasted into several places in one script, or copied between scripts
|
|
|
|
## Traceability Rule
|
|
|
|
- Backward: Design Class Diagram checklist ([QC-DCD-001]) where the script implements a design; Architecture Decision Record checklist ([QC-ADR-001]) for the decisions that constrain it
|
|
- Forward: none, source code is the end of the QC checklist chain
|
|
|
|
---
|
|
|
|
[QC-DCD-001]: ./qc-dcd.md
|
|
[QC-ADR-001]: ./qc-adr.md
|