| ... | @@ -11536,6 +11536,51 @@ this documentation along with the compiler in order to provide a point of | ... | @@ -11536,6 +11536,51 @@ this documentation along with the compiler in order to provide a point of |
| 11536 | reference, should anyone wish to point to an authority on agreed upon Zig | 11536 | reference, should anyone wish to point to an authority on agreed upon Zig |
| 11537 | coding style. | 11537 | coding style. |
| 11538 | </p> | 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 | {#header_open|Whitespace#} | 11584 | {#header_open|Whitespace#} |
| 11540 | <ul> | 11585 | <ul> |
| 11541 | <li> | 11586 | <li> |
Andrew Kelley <andrew@ziglang.org> 2024-03-18 23:36:10-07:00