When I write the method names for a class, I think carefully about what names to provide that will lead the reader in the right direction for understanding how

When I write the method names for a class, I think carefully about what names to provide that will lead the reader in the right direction for understanding how everything fits together. I provide examples that give a few options for how the reader might achieve various goals. And I keep the number of methods small enough to be digestible as a single unit. That is to say, a class is basically a “view” for interrogating one aspect of how the program works. If I didn’t care about the user interface of it, I wouldn’t bother picking names, writing documentation, or providing examples. HATEOAS is an interesting thing to bring up, because I’ve always felt that it’s biggest benefit was for programmatic interrogation of an API. If it has a good UI, then the endpoints it references will make sense to me by reading the names, sure, but I can also get that from, say, the documentation. And what is the purpose of documentation? Discoverability. A bad user interface for an API looks like this: the names don’t make sense, the collections are inconsistent, there is no documentation, and it’s difficult to find examples where it is used. Each one of these areas are the areas where you are creating a specifically user-oriented interface for your program. Some of them may happen to a degree by accident, like having a working example simply because it is not dead code. But if, say, it is a metaprogramming API, it may be difficult to find where the working example actually exists without some guidance. The way you structure your code will make stumbling onto the example easier or harder for your APIs user.