From e5dc5a6eb5608c100e78d6116942a4cd17f56d00 Mon Sep 17 00:00:00 2001
From: Andrew Kelley <andrew@ziglang.org>
Date: Sat, 17 Jan 2026 14:32:14 -0800
Subject: [PATCH] langref: refrain from underscore prefixes

---
 doc/langref.html.in | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/doc/langref.html.in b/doc/langref.html.in
index b3c5576ca7..a6ef8fa53e 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -7134,6 +7134,18 @@ coding style.
       cannot be any more specific without being incorrect.</p>
       {#header_close#}
 
+      {#header_open|Refrain from Underscore Prefixes#}
+      <p>In some programming languages, it is common to prefix identifiers with underscores
+      {#syntax#}__like_this{#endsyntax#} to indicate some vague notion of privacy or danger
+      associated with usage of the identifier.</p>
+      <p>In Zig, there are no private fields, and it is better not to pretend
+      otherwise. Fields should be named carefully to communicate their
+      semantics and documentation should indicate how to use fields without
+      violating data invariants. Underscore prefixes serve only to make code
+      authors feel better about writing clumsy, overly prescriptive, poorly
+      documented code.</p>
+      {#header_close#}
+
       {#header_open|Whitespace#}
       <ul>
         <li>