Principle of least surprise

I spend a lot of time complaining about technology and when things don't work. Today is different.I just spent maybe a day or so rewriting a library that read in ion and converted them to some objects. Ion is a JSON-like format we came up with at Amazon. (I'm perfectly OK talking about ion -- we've open-sourced it!)The library was a bit more complicated because of additional dependencies. But suffice to say that bulk of the code was doing mundane parsing.I ripped out a couple thousand lines of code and replaced it with maybe a hundred lines -- and used Jackson for the reading in of the (now) JSON. The thing that struck me is that Jackson was so obvious in how things are supposed to work. With the obviousness came code that worked the first time around.The fact that I'm surprised when things work as expected is revealing. So often I see code that's written in a "smart" way that shows the reader how smart they are.Then I'm surprised at how things work. Maybe I'm just not that "smart."Obviousness and non-surprising are very related. But you can make something that's obvious that doesn't work the way you expect.