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
1.6 KiB
1.6 KiB
description
| 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, orAILITOOLS-NNNin 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 IDsection only (seeamdsmi-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 |