011-black-jack/.agents/skills/coding-conventions/SKILL.md

name, description

name

description

coding-conventions

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.