Refactoring wars and how to avoid them: what is "simplicity" in programming?

What kind of abstractions are the most trustworthy?

In my experience, the ultimate in abstraction is anything that works solely with immutable data. This includes, obviously, pure functions, but also objects which have no mutable state. Such things are trivial to test and perfectly composable. It's easier to gain trust in them as you rarely need to know exactly what they do, only whether they appear to work or not.

Obviously immutability alone is not enough for many abstractions, but I would still like to see it used more. The current object-oriented models seem to encourage encapsulating state, rather than encapsulating data, which seems to lead programmers to use mutable things even when they are unnecessary.

Unless the abstraction requires it (eg. IO), I think any state held within an object is, in a way, leaky abstraction. As long as there is state within an object, it is not obvious whether you can, at any one time:

1) call its methods 2) hold a reference to it 3) delete it, or your reference to it (Mostly applies to non-GC languages) 4) Pass it as a parameter to something

All these worries disappear with immutable values.

Pure functions have one problem - they don't have state, and sometimes you need state.

What's needed is pure functions for logic, and dumb objects holding data, and function pointers.

> When you trust the abstraction

I agree. I would also say that in cases where the abstraction doesn't make sense you have to know what's going on inside the box in order to trust it.

In your example, the file system as an abstraction makes sense because once you understand that it's a tree, you are pretty much good to go.

I remember working on some projects early in my career with a very senior developer who had a habit of making the strangest abstractions possible on a problem. For example, need to use a class to define a triangle? His constructor might take 7 arguments! The center of the triangle on the screen, and the distance from the center as well as the degrees of rotation from the center (with the bottom of the screen being 0 degrees). Oh, and actually, it didn't take 7 arguments, it took 4, but three were some special object type containing a tuple of radians plus a mishmash of other parameters and a coordinate on screen. Because he wanted to, you know, reuse that code again. So in order to build a triangle, I had to define a center point on screen (with 0,0 in the middle of course because that's how his code worked) and then calculate the coordinates of the three triangle points from the distance I wanted, then convert degrees into radians or some such....bah! I don't remember all of the details, this was a long time ago, but it was horribly obfuscated and made no intuitive sense. He explained that it was all to avoid some singular edge case that he had encountered once, and he thought it was a good trade-off because all of the new edge-cases it introduced were manageable.

When I received this code (without documentation or useful comments), he was on vacation for two weeks.

Naively, I assumed it was an easily understandable abstraction in that I could simply supply 3 coordinates in some order to the library and get a triangle. I spent a couple days trying to figure out the order I was supposed to issue the coordinates to get it to draw before giving up and just reading the code to figure it out. Worse yet, the internals were abstracted all to hell in a similar obfuscated fashion and I literally got nowhere in trying to figure it out.

I actually just waited for him to get back to walk me through the code, peppering him with question like "do we really need to define the z coordinate as 0 all the time since the display is always 2d?" before proceeding on that work. Once I understood it, I just wrote some wrapper code to translate three normal 2d coordinates into his craziness to simplify my life.

I ran into this kind of thing with his abstractions all the time. From the most insane string class you have ever seen to a home rolled virtual memory library that pickled objects onto disk, but all of your objects had to be built around a base class that was full of useless virtual functions that you had to implement.

Be carefull with what you wish. Ill motivated attempts of refactoring more often than not disrupt an entire team rythm. I come to appreciate the simplicity of lazy spirits.

Code that falls in line with your expectations and caters to your mental toolkit is easy to understand. It also helps when code works well with your existing programming environment. I work with Java programmers and C++ programmers, and they both have ways of jumping quickly to class and method definitions, but the C++ programmers' way -- incremental search -- only works within a single file. The Java programmers barely notice that they're hopping around in the filesystem like Q-bert. The C++ programmers, working in emacs and vi, come to a grinding halt when they need to hop around to many different files in different directories, probably because they almost never need to do that.

(It may seem like the Java programmers simply use more capable tools, but most of them don't use incremental search at all, so they're much slower at finding something that they don't have a hop-to-X button for. Why? Because they get by fine without it, just like the C++ programmers get by without learning whatever emacs or vi extension would help them navigate Java-style source directory hierarchies.)

Obviously some kinds of tools and programmers will be more common than others, so one style can be empirically better than another yet be worse for a particular group of programmers. There won't be one better way of writing code until everybody has the same expectations and the same tools. I don't think we ever want to reach that kind of consensus.