This is another post motivated by Twitter: It’s about those cheat sheets, for example those showing C++ operator precedence, that some people have stick to their monitor or cubicle wall. Unless they contain something you are just learning and almost everybody else knows, you should get rid of them.
Here is the Tweet that triggered my thoughts on the topic:
All finite floats successfully round-tripped through iostreams with my patch, in just under 8 hours! pic.twitter.com/71YZDUwfCi
— Stephan T. Lavavej (@StephanTLavavej) January 31, 2016
My first reaction was “Neat! I need one of those too!”. But then something dawned on me: why would anyone truly need something like this?
Cheat sheets can lead to unreadable code
If you need a cheat sheet to write a piece of code, then you are probably something unusual. Otherwise you would not need the cheat sheet. But if you need the cheat sheet to write the code, there is a good chance that whoever will read it also needs some source of information to decipher it.
In the case of the operator precedence, Stephan is probably well aware of the precedence of multiplicative operators over additive ones. Maybe the information he needs now and then is about the pointer-to-member operators versus shift operators, or binary or versus logical or. My point is, if he does not clarify his intent by using parentheses, most people who read his code will have to look up the very same information as well to fully understand it.
Maybe Stephan does not use his cheat sheet to actually write code, but he needs it to decipher what someone else has produced. We won’t know. But unless there is a very harsh requirement on compile time performance that does not even allow for some redundant parentheses to be parsed, the code that needs this cheat sheet should be improved by making the intended precedence obvious.
In Stephan’s case, that requirement may well be in place. He maintains the standard library shipped with Visual Studio, so his code will be compiled millions of times a day around the world.
Some cheat sheets are Ok
Cheat sheets about language basics
With “basics” I mean stuff that you need for a few weeks while you are learning something new. Stuff that everybody else who has been using that language, library or feature for some time already knows. Those cheat sheets help you learn by actually using the stuff you can’t remember at once, and they will be obsolete in a few weeks, once you learned their content. They save some time you’d otherwise spend googling the same thing again and again. I am building a basics cheat sheet myself while I learn to work with Unity3D and C#, and another for Python.
Cheat sheets for tools
Tools are a great area for cheat sheets as well. We all want to get more productive, so the cheat sheets with all the keyboard shortcuts and less frequently used git commands can only help. They help because we’re the only ones that actually see the information on the in action and nobody gets confused by the weird wizardry we are doing.
Cheat sheets are not always worth the effort
Unless we are in the process of learning something we often need, producing cheat sheets can be a waste of time, ink and tree lives. If we don’t need them frequently, we probably even forget that we have them or that the information we need is on them. We just launch our browser and google for the information again.
On the other hand, if we need the information frequently, it’s only a matter of time before we have memorized it and can get rid of the cheat sheet. If you actually write cheat sheets yourself instead of just downloading and printing them, that action alone can be a huge help in memorizing the information. I have written many cheat sheets that I never had to look at, just to throw them away a few weeks later. They have served their purpose.
The art in programming is to write great stuff with code that everybody could write. Don’t be too smart. Avoid producing code for which you need a cheat sheet to write and decipher it. Except if your initials are STL.