Commit d066c327dc for openssl.org

commit d066c327dc366fca2d524e826cc341a2c3d8b753
Author: Bob Beck <beck@openssl.org>
Date:   Wed Sep 9 13:31:04 2026 -0600

    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 <mbroz@openssl.org>
    Reviewed-by: Neil Horman <nhorman@openssl.org>
    Merge-date: Fri Oct  2 08:06:12 2026
    Merged-from: https://github.com/openssl/openssl/pull/32779

diff --git a/STYLE.md b/STYLE.md
index 2bedc42a5a..f45ae3f09d 100644
--- a/STYLE.md
+++ b/STYLE.md
@@ -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: