| ... | ... | @@ -11536,6 +11536,51 @@ this documentation along with the compiler in order to provide a point of |
| 11536 | 11536 | reference, should anyone wish to point to an authority on agreed upon Zig |
| 11537 | 11537 | coding style. |
| 11538 | 11538 | </p> |
| 11539 | {#header_open|Avoid Redundancy in Names#} |
| 11540 | <p>Avoid these words in type names:</p> |
| 11541 | <ul> |
| 11542 | <li>Value</li> |
| 11543 | <li>Data</li> |
| 11544 | <li>Context</li> |
| 11545 | <li>Manager</li> |
| 11546 | <li>utils, misc, or somebody's initials</li> |
| 11547 | </ul> |
| 11548 | <p>Everything is a value, all types are data, everything is context, all logic manages state. |
| 11549 | Nothing is communicated by using a word that applies to all types.</p> |
| 11550 | <p>Temptation to use "utilities", "miscellaneous", or somebody's initials |
| 11551 | is a failure to categorize, or more commonly, overcategorization. Such |
| 11552 | declarations can live at the root of a module that needs them with no |
| 11553 | namespace needed.</p> |
| 11554 | {#header_close#} |
| 11555 | |
| 11556 | {#header_open|Avoid Redundant Names in Fully-Qualified Namespaces#} |
| 11557 | <p>Every declaration is assigned a <strong>fully qualified |
| 11558 | namespace</strong> by the compiler, creating a tree structure. Choose names based |
| 11559 | on the fully-qualified namespace, and avoid redundant name segments.</p> |
| 11560 | {#code_begin|exe|redundant_fqn#} |
| 11561 | const std = @import("std"); |
| 11562 | |
| 11563 | pub const json = struct { |
| 11564 | pub const JsonValue = union(enum) { |
| 11565 | number: f64, |
| 11566 | boolean: bool, |
| 11567 | // ... |
| 11568 | }; |
| 11569 | }; |
| 11570 | |
| 11571 | pub fn main() void { |
| 11572 | std.debug.print("{s}\n", .{@typeName(json.JsonValue)}); |
| 11573 | } |
| 11574 | {#code_end#} |
| 11575 | <p>In this example, "json" is repeated in the fully-qualified namespace. The solution |
| 11576 | is to delete <code>Json</code> from <code>JsonValue</code>. In this example we have |
| 11577 | an empty struct named <code>json</code> but remember that files also act |
| 11578 | as part of the fully-qualified namespace.</p> |
| 11579 | <p>This example is an exception to the rule specified in {#link|Avoid Redundancy in Names#}. |
| 11580 | The meaning of the type has been reduced to its core: it is a json value. The name |
| 11581 | cannot be any more specific without being incorrect.</p> |
| 11582 | {#header_close#} |
| 11583 | |
| 11539 | 11584 | {#header_open|Whitespace#} |
| 11540 | 11585 | <ul> |
| 11541 | 11586 | <li> |
Andrew Kelley <andrew@ziglang.org> 2024-03-18 23:36:10-07:00