Code is read much more often than it is written, so plan accordingly

Raymond Chen

Design for readability. Even if you don’t intend anybody else to read your code, there’s still a very good chance that somebody will have to stare at your code and figure out what it does: That person is probably going to be you, twelve months from now. When I advised against the use of BOOL function parameters, one commenter pointed out that Intellisense shows you what the parameters are. Sure, that’s a great help when you’re writing the code, but you write the code only once. You read it a lot. An anonymous commenter pointed out that hovering over the offending function in the IDE shows the function declaration. While that may be true, it’s still not a great solution. First, it means that you have to read code with your hand on the mouse. Second, it means that you can’t skim code because you’re going to hit a CreateEvent and then have to wait a little while for the tooltip to appear and then read and parse the tooltip and match the parameters up to what you have on the screen. This throws off your rhythm. Imagine if you had to read code that had gone through a ROT-13 filter. Sure, the IDE might help you by decoding the text under the cursor if you hover over it, but even instant help isn’t fast enough.

And finally, another commenter pointed out that this doesn’t help you if you’re reading code anywhere outside your IDE. It might be in a magazine, in a printout, in a bug report, on an overhead projector, on a web page, in a Usenet message, or in an email message. Good luck getting Intellisense to help you out there.


Comments are closed. Login to edit/delete your existing comments