| ... | ... | @@ -437,6 +437,25 @@ |
| 437 | 437 | |
| 438 | 438 | {#header_close#} |
| 439 | 439 | {#header_close#} |
| 440 | |
| 441 | {#header_open|Identifiers#} |
| 442 | <p> |
| 443 | Identifiers must start with an alphabetic character or underscore and may be followed |
| 444 | by any number of alphanumeric characters or underscores. |
| 445 | They must not overlap with any keywords. See {#link|Keyword Reference#}. |
| 446 | </p> |
| 447 | |
| 448 | {#header_open|String Identifier Syntax#} |
| 449 | <p> |
| 450 | If a name that does not fit these requirements is needed, such as for |
| 451 | linking with external libraries, the {#syntax#}@""{#endsyntax#} syntax |
| 452 | may be used. |
| 453 | </p> |
| 454 | {#code|identifiers.zig#} |
| 455 | {#header_close#} |
| 456 | {#header_close#} |
| 457 | |
| 458 | |
| 440 | 459 | {#header_open|Values#} |
| 441 | 460 | {#code|values.zig#} |
| 442 | 461 | |
| ... | ... | @@ -962,6 +981,9 @@ |
| 962 | 981 | humans and computers to do when reading code, and creates more optimization opportunities. |
| 963 | 982 | </p> |
| 964 | 983 | <p> |
| 984 | Variables are never allowed to shadow {#link|Identifiers#} from an outer scope. |
| 985 | </p> |
| 986 | <p> |
| 965 | 987 | The {#syntax#}extern{#endsyntax#} keyword or {#link|@extern#} builtin function can be used to link against a variable that is exported |
| 966 | 988 | from another object. The {#syntax#}export{#endsyntax#} keyword or {#link|@export#} builtin function |
| 967 | 989 | can be used to make a variable available to other objects at link time. In both cases, |
| ... | ... | @@ -969,22 +991,6 @@ |
| 969 | 991 | </p> |
| 970 | 992 | {#see_also|Exporting a C Library#} |
| 971 | 993 | |
| 972 | | {#header_open|Identifiers#} |
| 973 | | <p> |
| 974 | | Variable identifiers are never allowed to shadow identifiers from an outer scope. |
| 975 | | </p> |
| 976 | | <p> |
| 977 | | Identifiers must start with an alphabetic character or underscore and may be followed |
| 978 | | by any number of alphanumeric characters or underscores. |
| 979 | | They must not overlap with any keywords. See {#link|Keyword Reference#}. |
| 980 | | </p> |
| 981 | | <p> |
| 982 | | If a name that does not fit these requirements is needed, such as for linking with external libraries, the {#syntax#}@""{#endsyntax#} syntax may be used. |
| 983 | | </p> |
| 984 | | {#code|identifiers.zig#} |
| 985 | | |
| 986 | | {#header_close#} |
| 987 | | |
| 988 | 994 | {#header_open|Container Level Variables#} |
| 989 | 995 | <p> |
| 990 | 996 | {#link|Container|Containers#} level variables have static lifetime and are order-independent and lazily analyzed. |
| ... | ... | @@ -7135,15 +7141,28 @@ coding style. |
| 7135 | 7141 | {#header_close#} |
| 7136 | 7142 | |
| 7137 | 7143 | {#header_open|Refrain from Underscore Prefixes#} |
| 7138 | | <p>In some programming languages, it is common to prefix identifiers with underscores |
| 7139 | | {#syntax#}__like_this{#endsyntax#} to indicate some vague notion of privacy or danger |
| 7140 | | associated with usage of the identifier.</p> |
| 7141 | | <p>In Zig, there are no private fields, and it is better not to pretend |
| 7142 | | otherwise. Fields should be named carefully to communicate their |
| 7143 | | semantics and documentation should indicate how to use fields without |
| 7144 | | violating data invariants. Underscore prefixes serve only to make code |
| 7145 | | authors feel better about writing clumsy, overly prescriptive, poorly |
| 7146 | | documented code.</p> |
| 7144 | <p>In some programming languages, it is common to prefix identifiers with |
| 7145 | underscores {#syntax#}_like_this{#endsyntax#} to avoid keyword |
| 7146 | collisions, name collisions, or indicate additional metadata associated with usage of the |
| 7147 | identifier, such as: privacy, existence of complex data invariants, exclusion from |
| 7148 | semantic versioning, or context-specific type reflection meaning. |
| 7149 | </p> |
| 7150 | <p>In Zig, there are no private fields, and this style guide recommends |
| 7151 | against pretending otherwise. Instead, fields should be named carefully |
| 7152 | based on their semantics and documentation should indicate how to use |
| 7153 | fields without violating data invariants. If a field is not subject to |
| 7154 | the same semantic versioning rules as everything else, the exception |
| 7155 | should be noted in the {#link|Doc Comments#}. |
| 7156 | </p> |
| 7157 | <p>As for {#link|type reflection|@typeInfo#}, it is less error prone and |
| 7158 | more maintainable to use the type system than to make field names |
| 7159 | meaningful.</p> |
| 7160 | <p>Regarding name collisions, an underscore is insufficient to explain |
| 7161 | the difference between the two otherwise identical names. If there's no |
| 7162 | danger in getting them mixed up, then this guide recommends more verbose |
| 7163 | names at outer scopes and more abbreviated names at inner scopes.</p> |
| 7164 | <p>Finally, keyword collisions are better avoided via |
| 7165 | {#link|String Identifier Syntax#}.</p> |
| 7147 | 7166 | {#header_close#} |
| 7148 | 7167 | |
| 7149 | 7168 | {#header_open|Whitespace#} |
Andrew Kelley <andrew@ziglang.org> 2026-01-19 14:16:07-08:00