I agree that interface is key to not just software design, but design in general. Designing parts in isolation, you can do pretty much whatever you want. But people being able to gracefully handle where and when two parts collide is what makes the software world go round. One of my favorite bits on interfaces is this Rust Koan[0], which has a funny twist of pragmatism at the end.<p>It's a shame too many developers think this huge idea is just the interface keyword, or OOP, or even just the `object.method()` syntax. I hear dot-autocomplete come up in conversation almost every day now. When I was in college people asked me "How can you even <i>use</i> C? It doesn't even have classes...?", the implication being you couldn't encapsulate your code at <i>all</i>, and I get the same shrinking feeling when people talk about dot-autocomplete as if it's synonymous with interface discoverability. But it's really just one particular implementation (heh) of a much broader and more abstract (heh) idea. It's like calling all tissues Kleenex or all sodas Coke.<p>0. <a href="https://users.rust-lang.org/t/rust-koans/2408/3" rel="nofollow noreferrer">https://users.rust-lang.org/t/rust-koans/2408/3</a>
>Great product designs require no manual, and similarly, great interfaces need no documentation. Imagine having to read a manual on how to use a coffee mug.<p>This could not be more wrong.<p>Not everything is easy. If a library is addressing a complicated domain, solving by definition a complicated problem, it is fine if it requires some learning.<p>When did expertise and learning become bad things? If software is an engineering discipline, why would people in it ever promulgate the idea that any random cog can step in to any “engineer”s shoes?<p>Rich Hickey analogizes this mentality to the world of music, where it taken for granted that learning an instrument requires a lot of study:<p>“ We start with the cello. Should we make cellos that auto tune? Like, no matter where you put your finger, it's just going to play something good, play a good note.<p>“[Audience laughter]<p>“Like, you're good. We'll just fix that.<p>“ Should we have cellos with, like, red and green lights? Like, if you're playing the wrong note, you know, it's red. You slide around, and it's green. You're like, great! I'm good. I'm playing the right song. Right?<p>“ Or maybe we should have cellos that don't make any sound at all. Until you get it right, there's nothing.<p>“ [Audience laughter]”<p><a href="https://github.com/matthiasn/talk-transcripts/blob/master/Hickey_Rich/DesignCompositionPerformance.md">https://github.com/matthiasn/talk-transcripts/blob/master/Hi...</a><p>If something can be made easier without undermining its integrity, great. Not everything can be made as easy as drinking from a cup, something most 3 year olds can handle. If you think hitting dot in your IDE and choosing among the options is as much as you should be required to learn, you are asking to use NERF toys instead of power tools. Sometimes you need to read things, welcome to adulthood.
> His advice contradicted my idea that a great senior dev should learn better communication or management.<p>What are interfaces if not ways to communicate?
You never come up with the right interface at first because there is no right interfaces. There are better interfaces, but you usually need to encounter more situations to find it. Balancing up front time designing an interface with velocity to test it is a principle problem of software development.
One of my favorite relevant quotes, whether you’re talking about code or user interfaces:<p><i>The purpose of abstraction is not to be vague, but to create a new semantic level in which one can be absolutely precise. — Edsger Dijkstra</i>
I love citing this one (from <a href="https://spacecraft.ssl.umd.edu/akins_laws.html" rel="nofollow noreferrer">https://spacecraft.ssl.umd.edu/akins_laws.html</a>):<p>> 15. (Shea's Law) The ability to improve a design occurs primarily at the interfaces. This is also the prime location for screwing it up.<p>While this is about hardware interfaces, software interface fulfill the same exact role, and the same exact principle applies. The design is in the interface. The implementation is just grinding until it's done, because the decision of how something will be implemented are already determined by the interfaces and the information we have on the infrastructure we'll be doing the implementation in.
It took me until the last 3 paragraphs to realize they meant ux and not Java interfaces. Maybe I've been writing too much Java recently but I feel like it could be clearer.
A good interface guides the user to doing the right thing. To quote Brad Adams (who borrowed it from Rico Mariani)[1]:<p><pre><code> Rico called this the Pit of Success. That concept really resonated with me. More generalized, it is the key point of good API design. We should build APIs that steer and point developers in the right direction. Types should be defined with a clear contact that communicates effectively how they are to be used (and how not to).
</code></pre>
This concept is also tied closely with the concept of "making illegal states unrepresntable," popularized by Yaron Minsky[2].<p>For example, a document workflow system might naively model Document as a single entity that has all possible fields for all possible states. This could result in the need to raise exceptions (or return error codes) when the Document state is invalid, e.g. you can't approve a draft document until it's submitted. A better API models each state separately (e.g. using a union type, if your language supports it); so you'd have `DraftDocument`, `SubmittedDocument`, `ApprovedDocument`, `RejectedDocument`, where only `DraftDocument` would offer a `submit` method, and `SubmittedDocument` offer a `approve` and `reject` methods, returning an `ApprovedDocument` or `RejectedDocument`, respectively.<p>[1] <a href="https://learn.microsoft.com/en-gb/archive/blogs/brada/the-pit-of-success" rel="nofollow noreferrer">https://learn.microsoft.com/en-gb/archive/blogs/brada/the-pi...</a><p>[2] <a href="https://blog.janestreet.com/effective-ml-revisited/" rel="nofollow noreferrer">https://blog.janestreet.com/effective-ml-revisited/</a>
> Great product designs require no manual, and similarly, great interfaces need no documentation. Imagine having to read a manual on how to use a coffee mug.<p>It's a fallacy to assume a perfect interface needs no documentation, just as it's a fallacy to assume perfect code needs no comments. Most interfaces are far more complex than a coffee mug. In reality, the more complex something is, the more documentation is needed to describe how it works, how to use it, how <i>not</i> to use it, and why it works that way.
I wrote an ebook [1] about interface design for engineers after seeing time and time again that the best interfaces I worked on all came about when engineers and designers both contributed to the process.<p>[1] <a href="https://uidesignforengineers.com/" rel="nofollow noreferrer">https://uidesignforengineers.com/</a>
Have we reached adaptive interfaces yet? The kind that mold to the users preference based on the setup of other interfaces they us? Would be nice to have one interface to rule them all, tailored for everyone.
In my experience, applying the same mindset and efforts to interfaces for which the principal user is not a developer also yield similar benefits.<p>Good interfaces are retroactively obvious. Not like my modern microwave.
I should also point out that comments are a code smell. The vast majority of the time you feel the need to add a comment, you should probably refactor your code into a well-named function — whether a closure or a method. Your code should read well even without comments!<p>(There are some exceptions, that have to do with notes eg for security implications, or optimization techniques, or side effects. And also to document parameters in duck-typed languages. But even those should be put into structured comments, like DocBlock or YUIdoc or whatever kids use these days.)<p>I have learned this with time. Like when you are procrastinating and putting off doing something, that’s a sign you need to attract partners.