Skip to content
Skills Library
Programming · Building & coding

programming

/programming

How code should be written regardless of language. Code organisation, naming, data modelling, error handling, security and privacy, and tests. Use when writing, changing, or reviewing source code.

Repository
sdlc ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

How code should be written regardless of language. Code organisation, naming, data modelling, error handling, security and privacy, and tests. Use when writing, changing, or reviewing source code.

Original author description

How code should be written regardless of language. Code organisation, naming, data modelling, error handling, security and privacy, and tests. Use when writing, changing, or reviewing source code.

How it works

  1. Code organisation
  2. Functions, procedures, and the like
  3. Naming
  4. Data model
  5. Error handling
  6. Reliability
  7. Security and privacy
  8. Dependencies and performance
  9. Tests
  10. Comments
Original SKILL.md headings · 112 lines, 1,880 words
SKILL.md preview
---
name: programming
description: How code should be written regardless of language. Code organisation, naming, data modelling, error handling, security and privacy, and tests. Use when writing, changing, or reviewing source code.
---
# Programming

## Code organisation

- Modules MUST be partitioned by responsibility, using whichever decomposition is idiomatic for the software and its stack (e.g., layers such as domain, data, and UI in an application; capabilities in a library). The chosen decomposition MUST be applied uniformly, and MUST be documented in the README.
- Files SHOULD NOT exceed 800 LOC, including comments and blank lines. A file of 1 kLOC or more MUST be treated as a defect to fix.
- Everything that isn't part of a module's contract MUST use the strictest visibility the language offers.
- Entrypoints (e.g., `main`) MUST contain no logic of their own: they wire dependencies together and delegate.
- An abstraction MUST NOT be introduced for a second case that doesn't exist yet, and an extension point MUST NOT be built before something extends it.

## Functions, procedures, and the like

- Each MUST do one thing, at one level of abstraction, and SHOULD NOT exceed 40 LOC or a cyclomatic complexity of 10.
- Guard clauses and early returns SHOULD be used rather than nesting. An `else` on a failure path MUST NOT be used.
- A parameter list SHOULD NOT exceed seven parameters. Beyond that, they MUST be grouped into a type that names their relationship.
- An operation that can fail MUST NOT be exposed as a constructor: use a named factory instead (e.g., `deserialise`, `generate`).
- Comparisons SHOULD use `<`/`<=` rather than `>`/`>=`, so that the operands read from the lower bound to the upper bound (e.g., `if (MAX_TTL_SECONDS < ttl)`).
- Sources of non-determinism, such as the clock, randomness, and the scheduler or thread that work runs on, MUST be injected, so that a test can control them without a mock.

## Naming

- Constants, variables, fields, and the like SHOULD be named after what they hold, rather than what they are used for, and SHOULD match the taxonomy of the user interface and the programming interface.
- Functions, procedures, and the like MUST be named in the imperative (e.g., `submitResult`) or as questions (e.g., `wasResultSubmitted`).
- Booleans, and the functions that return them, MUST be prefixed with `is`, `has`, `are`, `can`, `do`/`does`/`did`, `should`, or `was`/`were`.
- Verbs MUST be used consistently across the codebase. For example: `make*` for factories, `init*` for constructors that read their input from the environment or a serialised form, `register*` for plugins, `configure*` for process-level side effects, and `require*` for guards that return nothing.
- `serialise`/`deserialise` MUST denote conversions to and from bytes, `encode`/`decode` conversions to and from structured representations, and `parse` conversions from strings.
- Generic type parameters MUST be whole words (e.g., `ResultType`), never single letters.
- Abbreviations MUST NOT be invented (e.g., `index`, not `i`). Only those already established in the domain or the platform MAY be used.
- A term MUST be defined once, and then used verbatim everywhere: code, tests, documentation, user-facing copy, and infrastructure.
- A rename whose only benefit is a better name MUST NOT be made where it would break a published surface.
- The user-facing vocabulary MAY differ from the code's, where the product hides a detail that the code must be precise about. Each MUST then be used consistently within its own domain, and the mapping MUST be documented.

## Data model

- Illegal states MUST be unrepresentable. A parameter that selects between behaviours MUST be an enum or a set of named factories, never a boolean; a value drawn from a closed set MUST be an enum, never a string.
- Invariants MUST be enforced where the value is constructed, so that an invalid instance cannot exist. Deserialisers MUST validate before constructing.
- Types MUST be immutable by default. Mutability MUST be confined to where it's needed, and MUST be evident in the type.
- The unit of a constant MUST be part of its name (e.g., `TOKEN_TTL_MINUTES`), unless the underlying data type abstracts the unit away (e.g., time deltas).

## Error handling

- Failures that the caller is expected to reason about MUST be returned as values (e.g., a result type carrying the reason). Programming errors and protocol violations MUST be raised.
- The cause MUST always be chained. Discarding a cause MUST be syntactically deliberate.
- Third-party errors MUST NOT escape the module that provoked them: catch them and re-raise them in the module's own vocabulary.
- A failure MUST be logged where its outcome is decided, and MUST NOT be logged again at each level it propagates through.
- The documentation of each error type MUST tell the caller what to do about it, starting with whether retrying is likely to help.
- Messages MUST state the expectation and the offending value (e.g., "TTL exceeds the maximum (got 3600)"), and MUST NOT carry secrets or personal data.
- Where a test asserts on the text of a message, that wording is part of what the module promises, and MUST NOT be reworded unless the meaning it conveys has changed.

## Reliability

- Every operation that can be repeated MUST be safe to repeat.
- Where a sequence of side effects cannot be atomic, it MUST be ordered so that a retry after any partial failure converges on the intended state, and a comment MUST explain why that order was chosen.
- A write MUST rely on a uniqueness constraint in the store to reject a duplicate, rather than check for an existing record first, because two matching writes can happen at once.
- The process MUST be able to die at any point without corrupting what it owns, and MUST recover from durable state rather than from anything held in memory.

## Security and privacy

- Input crossing a trust boundary MUST be validated before use, including the responses of services we operate and of those we don't.
- Every untrusted input MUST have an explicit size limit and a deadline for arriving in full, and every outbound call MUST have a timeout. Each MUST be a named constant, and where the figure was derived rather than chosen, the derivation MUST be commented.
- A value that a security decision depends on MUST be re-validated wherever it re-enters the code, even where it was validated when it was issued.
- Where the input or the configuration is ambiguous or incomplete, the code MUST fail closed and refuse to proceed, rather than guess what was intended.
- A security control MUST NOT have an off switch. Where skipping it would be legitimate, offer a narrower operation that does less, rather than a flag that checks less.
- Secrets MUST NOT be written to disc, nor interpolated into a message. A credential scoped to a single run MUST be generated per run and held in memory.

## Dependencies and performance

- A new dependency, internal or external, MUST be justified against what the platform already offers. Where only an older, still-supported platform version lacks it, the code SHOULD degrade gracefully rather than take the dependency.
- The faster option MUST be taken where it costs nothing in clarity. Where clarity is traded away, the change MUST cite the measurement that justified it.
- Instrumentation MUST be emitted through a vendor-neutral API, with the exporter chosen at start-up and hidden behind an adapter, so that no vendor's types appear elsewhere. A library MUST leave that choice to the application embedding it.
- Synchronous I/O MUST NOT block a path that serves a request or a user interface.
- Setup that only some code paths need MUST run when those paths run, rather than when the module loads. An implementation chosen at runtime, such as a storage or key-management adapter, MUST be loaded only after it has been chosen.

## Tests

- Every public/exported function, procedure, and the like MUST be unit tested against every branch a caller can provoke, every failure it documents, and both boundaries of every range it validates.
- Tests MUST assert on the values that a unit produces, rather than merely that it completed or returned a success status.
- Tests of the same unit whose arrange, act, and assert (AAA) blocks overlap substantially MUST be generated dynamically from data (aka _parameterised testing_).
- Where a parameterised suite supplies the unit under test as a case parameter, each case MUST assert something that distinguishes it from the others.
- **Private/internal** functions, procedures, and the like SHOULD NOT be unit tested directly: test them through the public/exported counterparts that use them. Where visibility is widened for testability, that concession MUST be documented on the member.
- Tests SHOULD use real dependencies, including cryptographic operations, rather than test doubles.
- Test doubles MUST be confined to the I/O boundary and to sources of non-determinism. Mocks and spies MUST NOT be used to make one of our own units testable: a unit that needs them MUST be redesigned instead.
- Where a double is unavoidable, it MUST be a working implementation whose failures are injected explicitly, and whose state is exposed so that tests assert on outcomes rather than on interactions.
- Test doubles MUST NOT have tests of their own, as the tests that use them already exercise them.
- A test that replaces a collaborator with a double MUST assert on the arguments that the double was given, because coverage doesn't check that a caller passes what the callee expects.
- Functional tests MUST exercise the deployed system over the network, MUST NOT import the code under test, MUST NOT touch backing services directly, and MUST NOT use mocks or spies.
- Functional tests MUST NOT contribute to the unit test measurements, so that the two signals stay separable.

## Comments

- You MUST NOT add or augment code comments unless the rationale for a particular block of code could not be inferred by carefully analysing the surrounding code. Typically, that means a workaround for an upstream bug (with a link to it), a spec ambiguity resolved one way rather than another, the derivation of a non-obvious constant, a deliberate trade-off, or the absence of code that a reader would expect to find.
- A comment MUST explain why the code is as it is, and MUST NOT paraphrase what it does.
- All comments MUST be succinct, and MUST NOT reference specific files/lines in the project.
- `TODO`, `FIXME`, and `HACK` markers MUST NOT be committed. Track the work in the issue tracker instead.
- A suppression of an automated check MUST be at the narrowest scope the tool offers, placed at the line it excuses, and MUST state its reason. Where the reason is an upstream defect, the suppression MUST link to it.

## Documentation

- A document (e.g., a spec) MUST state its conclusions, leaving out how they were reached, and SHOULD give the reasoning behind one only where the reader needs it to trust or challenge it (e.g., a consequential decision).

## Additional guidelines

### By artefact

- [Published libraries](references/libraries.md): The repository publishes a package that other codebases depend on.
- [Server-side applications](references/server-side-apps.md): The repository produces an application that runs on servers.
- [End-user applications](references/end-user-apps.md): The repository produces an application installed on a device the user controls.

### By concern

- [Cryptography](references/cryptography.md): The change uses a cryptographic primitive, or handles a key, a credential, or a token.
Files in this package (5)
  • SKILL.md 11 KB
  • references/cryptography.md 1 KB
  • references/end-user-apps.md 1 KB
  • references/libraries.md 2 KB
  • references/server-side-apps.md 2 KB

Versions

RepositoryScoreLicence
This page · gnarea/sdlc100MIT
soneta/soneta-erp-skills100MIT
wesleyegberto/software-engineering-skills100MIT
i9wa4/dotfiles90MIT

Database snapshot: 13.11.2026 · package version 420cdb25625c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100universal-patterns
    Code organization, error handling, data flow, naming and anti-patterns in any language. Use while writing or reviewing everyday code. Do not use to choose a system shape or a design pattern — read the architecture skill instead.
  • 85swift-engineering
    Expert Swift programming, modern language features, concurrency, type safety, error handling, and maintainable Apple-platform code. Use when writing, reviewing, refactoring, or debugging Swift.
  • 100coding-principles
    Use during implementation — loaded by build-loop before each task — whenever code is being written and should hold to universal quality standards, regardless of language or stack. Active while writing, not a post-hoc review checklist.
  • 100rust-programming
    Use when writing, reviewing, or refactoring Rust code, especially workspace crates, public APIs, error handling, async code, ownership choices, or performance-sensitive paths.
  • 95pact-coding-standards
    Clean code principles, error handling patterns, and coding standards for PACT Code phase. Use when: implementing features, refactoring code, reviewing code quality, establishing coding conventions, or handling errors and exceptions. Triggers on: code quality, clean code,…
  • 100aif-best-practices
    Code quality guidelines and best practices for writing clean, maintainable code. Covers naming, structure, error handling, testing, and code review standards. Use when writing code, reviewing, refactoring, or asking "how should I name this", "best practice for", "clean code".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.