Add planning baseline: BC, SA, PP and two gateways
Create the Business Case, Stakeholder Analysis (S01 course participant, S02 Udemy coursists, S03 GitHub viewers), Project Plan and the milestone documents MIL-001 (project setup, 6 tasks) and MIL-002 (game implementation, 8 tasks) for the console Blackjack game. Register PP and MIL in the artifact registry, set the PO language to en, and link the synced Gitea milestones in the Gateway Schedule. Refs #1 Refs #2 Refs #3 Refs #4 Refs #5 Refs #6 Refs #7 Refs #8 Refs #9 Refs #10 Refs #11 Refs #12 Refs #13 Refs #14
This commit is contained in:
@@ -0,0 +1,94 @@
|
||||
---
|
||||
name: coding-conventions
|
||||
description: Programming conventions for writing or reviewing source code — naming, layout, formatting and language idioms — for Python, C, C++, C# and Shell (bash). Use when writing, editing, reviewing or refactoring code in one of those languages, choosing names, setting up a formatter/linter config, or adding conventions for another language. Holds the rules shared by every language and points to a per-language sub-skill.
|
||||
---
|
||||
|
||||
# Coding Conventions
|
||||
|
||||
One skill for all languages. This file holds what is true in every language;
|
||||
everything specific to one language is in a sub-skill that is read only when
|
||||
that language is in hand:
|
||||
|
||||
| Language | Sub-skill | QC checklist |
|
||||
| --- | --- | --- |
|
||||
| Python | `references/python.md` | `framework/qc/qc-programming-python.md` (`QC-PY-001`) |
|
||||
| C | `references/c.md` | `framework/qc/qc-programming-c.md` (`QC-CL-001`) |
|
||||
| C++ | `references/cpp.md` | `framework/qc/qc-programming-cpp.md` (`QC-CPP-001`) |
|
||||
| C# | `references/csharp.md` | `framework/qc/qc-programming-csharp.md` (`QC-CS-001`) |
|
||||
| Shell (bash) | `references/shell.md` | `framework/qc/qc-programming-shell.md` (`QC-SH-001`) |
|
||||
|
||||
Read the sub-skill for the language you are working in, then write or review
|
||||
the code. To review, use the language's QC checklist and record the result as
|
||||
an `RC-*` (see the `artifact` skill).
|
||||
|
||||
## Precondition: a planned task
|
||||
|
||||
Before writing or editing code under `src/` or `tests/`, name the task row
|
||||
(`MIL-NNN`, task N) or the synced issue, and the use case or design artifact
|
||||
it implements, or say it is a plain technical task. If you cannot, refuse and
|
||||
use the `project-planning` skill instead (rule: `framework/process/plan-first-gate.md`).
|
||||
Reviewing code needs no task.
|
||||
|
||||
## Rules for every language
|
||||
|
||||
1. **The existing code wins.** In a file or project that already has a
|
||||
convention, follow it, even if the sub-skill says otherwise. Do not mix
|
||||
styles within a file; do not reformat code you are not changing.
|
||||
2. **Naming follows the language, not your habits.** Casing differs per
|
||||
language (table below). Never carry one language's casing into another.
|
||||
3. **A name says what, not how.** Name by purpose in the domain's language
|
||||
(IT Professional English, as the registry's `Languages` section says), not by
|
||||
type or implementation (`customer_list`, not `arr2`).
|
||||
4. **Length follows scope.** Short names (`i`, `n`) only for tiny scopes;
|
||||
wider scope, longer name. No abbreviations except ones the whole domain
|
||||
uses (`id`, `url`, `http`).
|
||||
5. **Booleans read as a question:** `is_valid`, `has_items`, `can_retry`
|
||||
(cased per language). No negated names (`is_not_ready`).
|
||||
6. **Functions are verbs, types are nouns.** A function that returns a value
|
||||
without side effects may be a noun (`total`, `Total`) where the language
|
||||
community does so.
|
||||
7. **Formatting is done by the formatter,** not by hand and not in review
|
||||
comments. Each sub-skill names the formatter and linter; commit its
|
||||
configuration file with the code.
|
||||
8. **Comments say why,** never what the code already says. Public APIs get
|
||||
the language's documentation-comment form.
|
||||
9. **No dead or commented-out code, no unexplained magic numbers.** Name the
|
||||
constant.
|
||||
10. **Errors are handled or propagated, never swallowed.** Each sub-skill says
|
||||
how its language does this.
|
||||
|
||||
## Casing at a glance
|
||||
|
||||
| Element | Python | C | C++ | C# |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Type / class | `PascalCase` | `snake_case_t` | `PascalCase` | `PascalCase` |
|
||||
| Function / method | `snake_case` | `snake_case` | `snake_case` | `PascalCase` |
|
||||
| Variable / parameter | `snake_case` | `snake_case` | `snake_case` | `camelCase` |
|
||||
| Constant | `UPPER_SNAKE` | `UPPER_SNAKE` | `kPascalCase` | `PascalCase` |
|
||||
| Private member | `_leading` | file-scope `static` | `trailing_` | `_camelCase` |
|
||||
| Namespace / module | `snake_case` module | `mod_` prefix | `snake_case` | `PascalCase` |
|
||||
| File | `snake_case.py` | `snake_case.c/.h` | `snake_case.cpp/.h` | `PascalCase.cs` |
|
||||
|
||||
The table is a summary; the sub-skill is authoritative. Shell (bash) is not in
|
||||
the table: functions and variables are `snake_case`, constants and environment
|
||||
variables `UPPER_SNAKE`, files `kebab-case.sh`.
|
||||
|
||||
## Governance boundary
|
||||
|
||||
Conventions are **defined and governed** here but **not enforced** by this
|
||||
framework: writing a linter or CI job that enforces them is outside the
|
||||
framework's scope. The formatter and linter names in each sub-skill are the
|
||||
recommended tools, not a pipeline. A new or changed convention follows the
|
||||
process in the project's Coding Standards Governance document and is recorded
|
||||
in `framework/CHANGELOG.md`. No project data belongs in this skill.
|
||||
|
||||
## Adding a language
|
||||
|
||||
1. Add `references/<language>.md` with these sections: Standard base, Naming,
|
||||
Formatting, Language rules, Errors, Tests, Tooling.
|
||||
2. Add `framework/qc/qc-<language>.md` (`QC-<SHORT>-001`) using the `QC` type
|
||||
of the `artifact` skill, tagging every criterion with an ISO/IEC 25010:2023
|
||||
characteristic and a Level.
|
||||
3. Add the row to the table above, the casing table, and a row for the
|
||||
language in `framework/registry/artifact-catalog.md`; note it in
|
||||
`framework/CHANGELOG.md`; run `bash framework/scripts/install-skills.sh`.
|
||||
Reference in New Issue
Block a user