Why to make your variable names undescriptive

Software Design Tip: Things on the inside can be "external"

We're taught early on to make variable names descriptive.

But descriptive variable names, according to Lambda-Conf founder John De Goes, should be are a code smell. Why?

Making variable names descriptive embeds a lot of knowledge about the data they represent. And, as we've discussed on this list before, knowledge is bad.

Having a lot of information about your types means there are many operations you can do. There are more ways to mess it up. But making the types more general restricts what you can do. John demonstrates on an example: he had struggled to implement a function groupByJoinKeys, but it became easy when he generalized it to groupBy.

Most code is not doing list and set operations that can be generalized easily. But there's a deeper lesson here.

Most programmers know about hiding an implementation from the outside world. This is related to existential quantifiers in logic: the outside world sees an interface, but doesn't know the details. Fewer know about its dual, corresponding to universal quantifiers: hiding the outside world from a module.

For example, a couple days ago, one of my students was presenting me his design for a todo list app. His TodoList class took great pains to prevent the outside world from ever touching a TodoItem.

public class TodoList {
  private List<TodoItem> items;
  public void markItemDone(int itemId);
  public void setItemPriority(int itemId, Priority p);
  // ...
}

"Why," I asked him. "I figured I shouldn't let the rest of the app know about the internals."

But there's some part of his app that needs to edit individual TodoItems. And it should probably not have to deal with TodoLists.

It would be a bit cumbersome to actually break TodoList and its capabilities into a type parameter. But the deeper principle applies: most of the code in TodoList should be written in a way that makes no assumptions about TodoItem, and will continue to work for future implementations.

So, it's not the case that TodoItem should be hidden from the rest of the app. A TodoItem may be inside a TodoList, but it's still external. It's closer to the truth that TodoItem should be hidden from TodoList itself.