| ... | @@ -437,6 +437,25 @@ | ... | @@ -437,6 +437,25 @@ |
| 437 | | 437 | |
| 438 | {#header_close#} | 438 | {#header_close#} |
| 439 | {#header_close#} | 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 | {#header_open|Values#} | 459 | {#header_open|Values#} |
| 441 | {#code|values.zig#} | 460 | {#code|values.zig#} |
| 442 | | 461 | |
| ... | @@ -962,6 +981,9 @@ | ... | @@ -962,6 +981,9 @@ |
| 962 | humans and computers to do when reading code, and creates more optimization opportunities. | 981 | humans and computers to do when reading code, and creates more optimization opportunities. |
| 963 | </p> | 982 | </p> |
| 964 | <p> | 983 | <p> |
| | 984 | Variables are never allowed to shadow {#link|Identifiers#} from an outer scope. |
| | 985 | </p> |
| | 986 | <p> |
| 965 | The {#syntax#}extern{#endsyntax#} keyword or {#link|@extern#} builtin function can be used to link against a variable that is exported | 987 | The {#syntax#}extern{#endsyntax#} keyword or {#link|@extern#} builtin function can be used to link against a variable that is exported |
| 966 | from another object. The {#syntax#}export{#endsyntax#} keyword or {#link|@export#} builtin function | 988 | from another object. The {#syntax#}export{#endsyntax#} keyword or {#link|@export#} builtin function |
| 967 | can be used to make a variable available to other objects at link time. In both cases, | 989 | can be used to make a variable available to other objects at link time. In both cases, |
| ... | @@ -969,22 +991,6 @@ | ... | @@ -969,22 +991,6 @@ |
| 969 | </p> | 991 | </p> |
| 970 | {#see_also|Exporting a C Library#} | 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 | {#header_open|Container Level Variables#} | 994 | {#header_open|Container Level Variables#} |
| 989 | <p> | 995 | <p> |
| 990 | {#link|Container|Containers#} level variables have static lifetime and are order-independent and lazily analyzed. | 996 | {#link|Container|Containers#} level variables have static lifetime and are order-independent and lazily analyzed. |
| ... | @@ -7135,15 +7141,28 @@ coding style. | ... | @@ -7135,15 +7141,28 @@ coding style. |
| 7135 | {#header_close#} | 7141 | {#header_close#} |
| 7136 | | 7142 | |
| 7137 | {#header_open|Refrain from Underscore Prefixes#} | 7143 | {#header_open|Refrain from Underscore Prefixes#} |
| 7138 | <p>In some programming languages, it is common to prefix identifiers with underscores | 7144 | <p>In some programming languages, it is common to prefix identifiers with |
| 7139 | {#syntax#}__like_this{#endsyntax#} to indicate some vague notion of privacy or danger | 7145 | underscores {#syntax#}_like_this{#endsyntax#} to avoid keyword |
| 7140 | associated with usage of the identifier.</p> | 7146 | collisions, name collisions, or indicate additional metadata associated with usage of the |
| 7141 | <p>In Zig, there are no private fields, and it is better not to pretend | 7147 | identifier, such as: privacy, existence of complex data invariants, exclusion from |
| 7142 | otherwise. Fields should be named carefully to communicate their | 7148 | semantic versioning, or context-specific type reflection meaning. |
| 7143 | semantics and documentation should indicate how to use fields without | 7149 | </p> |
| 7144 | violating data invariants. Underscore prefixes serve only to make code | 7150 | <p>In Zig, there are no private fields, and this style guide recommends |
| 7145 | authors feel better about writing clumsy, overly prescriptive, poorly | 7151 | against pretending otherwise. Instead, fields should be named carefully |
| 7146 | documented code.</p> | 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 | {#header_close#} | 7166 | {#header_close#} |
| 7148 | | 7167 | |
| 7149 | {#header_open|Whitespace#} | 7168 | {#header_open|Whitespace#} |
Andrew Kelley <andrew@ziglang.org> 2026-01-19 14:16:07-08:00