Clear API

Ryan Sonnek bio photo By Ryan Sonnek

Let me start by saying that I like clear and concise code. I promote best practices and design patterns whenever possible and use tools like PMD help identify code that maybe too complex for it’s own good. However, I think it’s more importantto have a clear API over a clear implementation.

The API is your contract to clients. It needs to be expressive and understandable. I can’t count the number of bugs caused by developers using an existing API incorrectly and saying “I didn’t know it did that!?”. That’s why it’s so important to have a strong domain model with a clean and expressive API. This is one skill that seperates the programmers_from the _architects.

In the end, all I care about is that your code does what it’s supposed to do. If it’s implementation is ugly, but does what it’s supposed to, that’s okay with me. This is easily verified using unit tests, and is yet another reason I think reviewing test cases is more important than actually reviewing code. If you have a un-clear API with a muddled implementation and no unit tests, I guess you’re in a bit of trouble.