Mental mapping

Why it's bad to use names that need to be mentally translated to other names

Here’s an extract from Robert C. Martin’s Clean Code, which applies to science as well (p. 25):

Smart people sometimes like to show off their smarts by demonstrating their mental juggling abilities. After all, if you can reliably remember that r is the lower-cased version of the url with the host and scheme removed, then you must clearly be very smart.

One difference between a smart programmer and a professional programmer is that the professional understands that clarity is king.

Robert C. Martin says it’s hard to mentally translate one name (e.g. “r”) to another, and you can avoid it by using a better name (e.g. “urlPath”). But the problem is not just lost brainpower; it can also be misunderstanding. I’ve seen experienced Python programmers trying to teach Python “metaclasses”—one of the most difficult concepts of Python—by explaining that a metaclass is the class of a class—which it isn’t. They wouldn’t misunderstand, and the concept wouldn’t be difficult, if it was called “class creators” instead.

If a process is sensitive to the initial conditions, call it “sensitive to the initial conditions”—don’t use “chaotic” or “nonlinear”.