xmtpd — Cursor Rules

• Follow Go style guide for styling Go Code. It outlines the foundation of Go style at Google. This document is definitive and is used as the basis for the recommendations in Style Decisions and Best Practices. • Follow Go best practices to write code with the patterns that have evolved over time that solve common problems, read well, and are robust to code maintenance needs.

There are a few overarching principles that summarize how to think about writing readable Go code. The following are attributes of readable code, in order of importance: Clarity: The code’s purpose and rationale is clear to the reader. Simplicity: The code accomplishes its goal in the simplest way possible. Concision: The code has a high signal-to-noise ratio. Maintainability: The code is written such that it can be easily maintained. Consistency: The code is consistent with the broader Google codebase.

The core goal of readability is to produce code that is clear to the reader. Clarity is primarily achieved with effective naming, helpful commentary, and efficient code organization. Clarity is to be viewed through the lens of the reader, not the author of the code. It is more important that code be easy to read than easy to write. Clarity in code has two distinct facets: What is the code actually doing? Go is designed such that it should be relatively straightforward to see what the code is doing. In cases of uncertainty or where a reader may require prior knowledge in order to understand the code, it is worth investing time in order to make the code’s purpose clearer for future readers. For example, it may help to: • Use more descriptive variable names • Add additional commentary • Break up the code with whitespace and comments • Refactor the code into separate functions/methods to make it more modular • There is no one-size-fits-all approach here, but it is important to prioritize clarity when developing Go code. Why is the code doing what it does? The code’s rationale is often sufficiently communicated by the names of variables, functions, methods, or packages. Where it is not, it is important to add commentary. The “Why?” is especially important when the code contains nuances that a reader may not be familiar with, such as: • A nuance in the language, e.g., a closure will be capturing a loop variable, but the closure is many lines away • A nuance of the business logic, e.g., an access control check that needs to distinguish between the actual user and someone impersonating a user An API might require care to use correctly. For example, a piece of code may be intricate and difficult to follow for performance reasons, or a complex sequence of mathematical operations may use type conversions in an unexpected way. In these cases and many more, it is important that accompanying commentary and documentation explain these aspects so that future maintainers don’t make a mistake and so that readers can understand the code without needing to reverse-engineer it. It is also important to be aware that some attempts to provide clarity (such as adding extra commentary) can actually obscure the code’s purpose by adding clutter, restating what the code already says, contradicting the code, or adding maintenance burden to keep the comments up-to-date. Allow the code to speak for itself (e.g., by making the symbol names themselves self-describing) rather than adding redundant comments. It is often better for comments to explain why something is done, not what the code is doing. The Google codebase is largely uniform and consistent. It is often the case that code that stands out (e.g., by using an unfamiliar pattern) is doing so for a good reason, typically for performance. Maintaining this property is important to make it clear to readers where they should focus their attention when reading a new piece of code. The standard library contains many examples of this principle in action. Among them: • Maintainer comments in package sort. • Good runnable examples in the same package, which benefit both users (they show up in godoc) and maintainers (they run as part of tests). • strings.Cut is only four lines of code, but they improve the clarity and correctness of callsites.

Your Go code should be simple for those using, reading, and maintaining it. Go code should be written in the simplest way that accomplishes its goals, both in terms of behavior and performance. Within the Google Go codebase, simple code: • Is easy to read from top to bottom • Does not assume that you already know what it is doing • Does not assume that you can memorize all of the preceding code • Does not have unnecessary levels of abstraction • Does not have names that call attention to something mundane • Makes the propagation of values and decisions clear to the reader • Has comments that explain why, not what, the code is doing to avoid future deviation • Has documentation that stands on its own • Has useful errors and useful test failures • May often be mutually exclusive with “clever” code • Tradeoffs can arise between code simplicity and API usage simplicity. For example, it may be worthwhile to have the code be more complex so that the end user of the API may more easily call the API correctly. In contrast, it may also be worthwhile to leave a bit of extra work to the end user of the API so that the code remains simple and easy to understand. When code needs complexity, the complexity should be added deliberately. This is typically necessary if additional performance is required or where there are multiple disparate customers of a particular library or service. Complexity may be justified, but it should come with accompanying documentation so that clients and future maintainers are able to understand and navigate the complexity. This should be supplemented with tests and examples that demonstrate its correct usage, especially if there is both a “simple” and a “complex” way to use the code. This principle does not imply that complex code cannot or should not be written in Go or that Go code is not allowed to be complex. We strive for a codebase that avoids unnecessary complexity so that when complexity does appear, it indicates that the code in question requires care to understand and maintain. Ideally, there should be accompanying commentary that explains the rationale and identifies the care that should be taken. This often arises when optimizing code for performance; doing so often requires a more complex approach, like preallocating a buffer and reusing it throughout a goroutine lifetime. When a maintainer sees this, it should be a clue that the code in question is performance-critical, and that should influence the care that is taken when making future changes. If employed unnecessarily, on the other hand, this complexity is a burden on those who need to read or change the code in the future. If code turns out to be very complex when its purpose should be simple, this is often a signal to revisit the implementation to see if there is a simpler way to accomplish the same thing.