Channels ▼

Andrew Koenig

Dr. Dobb's Bloggers

Readability and Familiarity

October 19, 2011

Looking at the comments on my recent Elegance or Trickery? articles, I am struck by how many commenters have made what seem to be objective statements. For example, one reader said, "Trickery is when you game the language to achieve unobvious effects."

My immediate reaction to this statement is to ask: Unobvious to whom?

I touched on this point in the first article in this series, when I used the example

*p++ = *q++;

I said then, and still believe, that most C and C++ programmers will find this usage more familiar (hence easier to understand) than the alternatives — and that I believe this even though figuring out exactly why this statement does what it does is far from trivial. I think that what goes on in the minds of people who see such examples is similar to what happens when they read: Most people read a word — and sometimes even a phrase — at a time, rather than a letter at a time. The code

*p = *q;
 p = p + 1;
 q = q + 1;

has the same effect as the previous example, but to understand it, you have to make sense out of a larger number of conceptual symbols. Which of these alternatives is easier to understand depends on whether the extra effort to understand the more compact symbols makes up for the smaller number of such symbols. If you know that *p++ means the same as *p, except that it increments p afterward, it is easier to read the first example; if you have to think about it, the second example is easier to understand. To me, at least, this disparity means that whether you consider a particularly compact piece of code to be tricky depends on whether you're used to it — in other words, on how much similar code you have seen.

If I'm correct in believing that trickery is closely related to unfamiliarity, then this belief exposes a problem: Useful programming techniques may be rejected because they are unfamiliar, and may be unfamiliar because they are rejected. Consider the following common technique for reading the contents of the standard input stream a line at a time:

string line;
       while (getline(cin, line)) {
                  // Process a line of the file

This code is straightforward enough, but it has a disadvantage: After it finishes, the variable line is still around, just waiting to be used by mistake. We can avoid that disadvantage by adding braces:

   string line;
   while (getline(cin, line)) {
                 // Process a line of the file

but doing so takes up an extra level of indentation. If we don't indent it, the braces can be hard to see.

Walter Brown at the Fermi National Accelerator Lab suggested a nice alternative:

for (string line; getline(cin, line); ) {
   // Process a line of the file

Once one gets over its unfamiliarity, one can see that it looks like what it does, namely to iterate over the lines of a file. Moreover, the local variable line now goes out of scope at the end of the for statement.

I think this is a good example of usage that appears to be tricky only so long as it is unfamiliar. Not only that, but it seems to me to be clearly better than all the alternative ways I've seen of writing this particular loop. However, I'm as curious as ever to know what readers think about this technique.

Related Reading

More Insights

Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.