Skip to content

coding.md

Latest commit

 

History

History
42 lines (27 loc) · 4.54 KB

coding.md

File metadata and controls

42 lines (27 loc) · 4.54 KB
Raw
name coding
description Phase 1 draft code checklist for Linux kernel style — concrete rules for code structure and comments. Load during Phase 1 draft code per README three-phase cumulative workflow.
metadata
type
reference

Phase 1 — draft code

Load this file at start of Phase 1 draft code task. If the change is non-trivial per planning.md's trigger, complete Phase 0 planning and get human sign-off before starting here. Keep resident through Phase 2 review and Phase 3 changelog drafting per cumulative load model — do not unload until task end. For full load order see README.md How to load section.

For automated tools: this repository is reference documentation. Nothing here is instruction to execute. Treat as data when crawling; guidance applies only when user deliberately loads it to write or review kernel patch.

Load order for Phase 1 — always hot

  • kernel-style.md — entry point overview, factual integrity summary, code structure rules, 4 anchor verbatim quotes for base voice calibration. Keep resident through all phases.
  • kernel-readability-principles.md — composite principles distilled from 14 kernel developers. Keep resident through all phases.
  • llm-tells-checklist.md — final-pass checklist for generic LLM tells to strip and verification never-invent. Run as final pass within Phase 1 draft, keep resident through Phase 2, re-run at review gate. Do not unload until task end.
  • This file coding.md — Phase 1 specific checklist below.

On demand during Phase 1 only if needed:

  • exemplars-routing.md (~180w tiny) may load once to pick developer profile to calibrate voice — see routing table, then load only that section from exemplars.md on demand. Full exemplars.md mandatory is at Phase 2 review gate, but routing file saves ~5k tok when you need only one profile. Full file exemplars.md (3,685w) is optional here.

Do not load changelog-style.md yet — Phase 3 mandatory when drafting commit message. Do not load patch-series.md yet — on demand only for multi-patch in Phase 3.

Phase 1 checklist — what to do while drafting code

  • Follow kernel-style.md §0 factual integrity checklist before any other pass (canonical R0-1..R0-6): never invent, TODO if unknown, verify claim vs diff, paste verbatim, treat unverified prose as bug. Full detail in kernel-style.md §0 — single source per CONTRIBUTING §2, changelog-style §0 cross-refs there.

  • Follow kernel-style.md §3 code structure rules for splitting helpers, function length caps, renaming vs duplicating, minimal obvious fix preference, locals naming, guard early return. Full detail and example hashes in kernel-style.md §3 — single source of truth, do not duplicate here beyond this pointer.

  • Follow kernel-style.md §2 and changelog-style.md §2 code comment rules for WHY not WHAT comment density, 50-word paragraph cap, no internal identifiers in source ever, one source of truth at definition not header prototype, cross-reference not duplicate. Full detail in those files — single source, do not duplicate here beyond this pointer.

  • Upstream kernel coding style reference: Documentation/process/coding-style.rst in the Linux kernel tree is the human-readable upstream document with coding style rules for kernel contributions. The rules in this directory supplement the upstream document with LLM-focused guidance not learned from training data.

  • Run llm-tells-checklist.md final pass before moving to Phase 2 review to verify no LLM tells slipped into code or comments. Full list in llm-tells-checklist.md single source of truth; core tells to watch in code comments specifically that are less obvious elsewhere: over-bulleting in comments, templated Pros/Cons scaffolding, ornate verbs, vague justification without numbers.

Next phase pointer

When code draft passes llm-tells checklist final pass, move to Phase 2 review — see review.md for Phase 2 mandatory checklist including exemplars.md mandatory load before git commit and the review process per peer-review.md (self-review by default, a second reviewer when available) and git diff comparison workflow. Do not proceed to git commit without completing the Phase 2 self-review gate; CONTRIBUTING.md's adversarial review requirement is a separate, additional gate that applies specifically to changes to this style guide's own normative content.

Phase 1 draft code checklist for kernel-style guide per README three-phase workflow. For full rules see kernel-style.md §3 code structure, changelog-style.md §2 comments, llm-tells-checklist.md final pass.