derek.holloway
7502bf64a4
CodeQL / Analyze (actions) (push) Canceled after 0s
CodeQL / Analyze (python) (push) Canceled after 0s
pre-commit / pre-commit (push) Canceled after 0s
Multi-Arch CI / setup (push) Canceled after 0s
Publish build_manylinux_x86_64 images / publish_build_manylinux_x86_64 (push) Canceled after 0s
Setup (Multi-Arch) / setup (push) Canceled after 0s
Multi-Arch CI / Linux::${{ fromJSON(needs.setup.outputs.linux_build_config || '{}').build_variant_label || 'skip' }} (push) Canceled after 0s
Publish TheRock Docker image / build-and-push-image (push) Canceled after 0s
Publish no_rocm_image_ubi10 image / publish_no_rocm_image_ubi10 (push) Canceled after 0s
Multi-Arch CI / Windows::${{ fromJSON(needs.setup.outputs.windows_build_config || '{}').build_variant_label || 'skip' }} (push) Canceled after 0s
Publish TheRock Docker image / build-and-push-image (push) Canceled after 0s
Multi-Arch CI / Manifest Diff (push) Canceled after 0s
TheRock Manifest Diff Report / Generate Manifest Diff Report (push) Canceled after 0s
Multi-Arch CI / CI Summary (push) Canceled after 0s
Publish no_rocm_image_ubuntu24_04 images / publish_no_rocm_image_ubuntu24_04 (push) Canceled after 0s
Publish no_rocm_image_ubuntu24_04_ocl_rt images / publish_no_rocm_image_ubuntu24_04_ocl_rt (push) Canceled after 0s
Publish TheRock Docker image / build-and-push-image (push) Canceled after 0s
Publish TheRock Docker image / build-and-push-image (push) Canceled after 0s
Publish no_rocm_image_ubuntu24_04 images / publish_no_rocm_image_ubuntu24_04_rocgdb (push) Canceled after 0s
Publish no_rocm_image_ubuntu24_04_rocgdb images / publish_no_rocm_image_ubuntu24_04_rocgdb (push) Canceled after 0s
Publish no_rocm_image_ubuntu24_04 images / publish_no_rocm_image_ubuntu24_04_ocl_rt (push) Canceled after 0s
Publish TheRock Docker image / build-and-push-image (push) Canceled after 0s
Unit Tests / Unit Tests :: ubuntu-24.04 (push) Canceled after 0s
Unit Tests / Unit Tests :: windows-2022 (push) Canceled after 0s
Publish no_rocm_image_ubuntu24_04 images / publish_no_rocm_image_ubuntu24_04_media (push) Canceled after 0s
Unit Tests / Unit Tests Summary (push) Canceled after 0s
Publish no_rocm_image_ubuntu24_04 images / publish_no_rocm_image_ubuntu24_04_openmpi (push) Canceled after 0s
40 lines
1.6 KiB
Markdown
40 lines
1.6 KiB
Markdown
---
|
|
description: "Use when: writing or editing code comments, doxygen, help text, or any in-repo prose in amd-smi; deciding how much to comment; reviewing comment verbosity; referencing JIRA tickets in code."
|
|
---
|
|
# Output Conventions
|
|
|
|
Code-quality conventions for anything written into the amd-smi repository
|
|
(comments, doxygen, help text, docs). For commit and PR wording, use the
|
|
`amdsmi-commit-and-pr-conventions` skill instead.
|
|
|
|
## Assume Expert Readers
|
|
|
|
Write for a developer already familiar with the codebase. Do not explain what
|
|
the code plainly says or restate language/library basics.
|
|
|
|
## Comment Brevity
|
|
|
|
- Comment the **why**, not the **what**. If the code is readable, it needs no
|
|
narration.
|
|
- Explain only a non-obvious root cause or a decision that isn't visible in the
|
|
code.
|
|
- One or two lines is the norm. If a comment needs a full paragraph, that is a
|
|
signal to stop and reconsider, or to ask before writing it.
|
|
- Never let comments outweigh the code they describe.
|
|
|
|
## No Ticket References in Code
|
|
|
|
- Do not put `ROCM-NNNNN`, `SWDEV-NNNNNN`, or `AILITOOLS-NNN` in code comments.
|
|
- Do not put internal labels ("regression guard", sprint names) in code.
|
|
- Reference the behavior or root cause. Tickets belong in the PR `JIRA ID`
|
|
section only (see `amdsmi-commit-and-pr-conventions`).
|
|
|
|
## Common Mistakes
|
|
|
|
| Mistake | Fix |
|
|
|---------|-----|
|
|
| Paragraph-length comment explaining how the code works | One line on the root-cause why, or none |
|
|
| `// Fixes ROCM-12345` above a change | Drop it; describe the behavior |
|
|
| Comment restating the next line in English | Delete it |
|
|
| Tutorial-style doxygen for an obvious getter | State the contract, nothing more |
|