diff options
| author | Bob Beck <[email protected]> | 2026-09-09 21:31:04 +0200 |
|---|---|---|
| committer | Tomas Mraz <[email protected]> | 2026-10-02 10:05:59 +0200 |
| commit | d066c327dc366fca2d524e826cc341a2c3d8b753 (patch) | |
| tree | 918cf32a79207f42f2011b7b6a54b80289e87404 /STYLE.md | |
| parent | Add an mfail test for rsa_multiprime_keygen() (diff) | |
| download | openssl-d066c327dc366fca2d524e826cc341a2c3d8b753.tar.gz openssl-d066c327dc366fca2d524e826cc341a2c3d8b753.zip | |
Say that comments state facts about the present code
A comment is read without the change that introduced it, so one
that records the author's reasoning -- what was tried, rejected,
or done before -- is confusing once the code it contrasts with is
gone. AI coding agents produce these readily, so let's document
that this is undesirable, so both humans and AI agents don't
do it as readily.
Reviewed-by: Milan Broz <[email protected]>
Reviewed-by: Neil Horman <[email protected]>
Merge-date: Fri Oct 2 08:06:12 2026
Merged-from: https://github.com/openssl/openssl/pull/32779
Diffstat (limited to 'STYLE.md')
| -rw-r--r-- | STYLE.md | 26 |
1 files changed, 20 insertions, 6 deletions
@@ -217,14 +217,28 @@ exception, and the per-field commenting requirement on structures. Use the classic `/* ... */` comment markers. Do not use `// ...` markers. -Comments should describe *what* the code does and *why*. Do not -parrot the effect of each statement; well-written code is its own -description of *how*. As the complexity of the code increases, the -size and detail of comments should also increase. Err in favour of -more comments rather than fewer: code that is *obvious* to you -today will not necessarily be obvious to someone else two years +Comments describe *what* the code does and, where the code does +not make it evident, *why*: the requirement, invariant, or +external constraint it satisfies. Do not parrot the effect of each +statement; well-written code is its own description of *how*. The +more subtle the code, the more a comment is needed -- code that is +obvious to you today will not be obvious to someone else two years later. +A comment is a fact about the code as it is, for a reader who has +seen no other version of the file. Write the minimum that conveys +the fact; a comment that can lose words without losing meaning is +too long. + +Your reasoning while making a change is not a fact about the code. +What the code used to do, what you considered and rejected, and +why you chose this do not belong in comments. +Before submitting, check every comment in your diff for "we", +"no longer", "previously", "now", "instead of", "so that", "rather +than" and "unlike", and for the shape "we do not do X here because +...". Each marks a decision being narrated. Delete it, or replace +it with the constraint the code satisfies. + ### Multi-line comment blocks The preferred style for long (multi-line) comments is: |