Articles

Concise writing

In Language design on January 5, 2009 by Matt Giuca Tagged: ,

I’ve been known to ramble a lot in my writing. Being more concise is something I know I have to work on. Apologies for some of the long posts on this blog.

I was working on the spec for my language, Mars, just now. Writing language specs, it turns out, is pretty hard. You have to precisely capture the semantics of the language in a way that’s clear and understandable. I got up to that awfully mundane bit where you explain the really basic things like if statements and while loops. Things for which everybody knows how they work, but they have to be there anyway, because it is, after all, a formal language spec. And here’s what I wrote under the heading “If statements”:

The if statement conditionally executes a sequence of statements:

if_stmt ::=  "if" expression ":" NEWLINE
                 INDENT statement+ DEDENT
             [ "else" ":" NEWLINE
                 INDENT statement+ DEDENT ]

The expression on the first line is called the “condition”. The condition’s type must be Int, or the compiler MUST reject the program.

The condition is evaluated, and any side-effects of evaluating the expression take place during the execution of the if statement, and before the execution of any sub-expressions.

The first nested block of statements is called the “then” clause. If the optional else part is supplied, then the second nested block of statements is called the “else” clause. One of these clauses, but not both, will be executed, by executing each of the sequence of statements in order.

If the condition’s value is not 0, the “then” clause is executed.

If the condition’s value is 0, then the “else” clause, if supplied, is executed. If it is not supplied, the if statement has no effect, besides the evaluation of the initial expression.

Quite a mouthful! Then I went to the Python language reference, which I absolutely idolise, and have been referring to periodically for guidance. And here’s what Python says on the matter:

The if statement is used for conditional execution:

if_stmt ::=  "if" expression ":" suite
             ( "elif" expression ":" suite )*
             ["else" ":" suite]

It selects exactly one of the suites by evaluating the expressions one by one until one is found to be true (see section Boolean operations for the definition of true and false); then that suite is executed (and no other part of the if statement is executed or evaluated). If all expressions are false, the suite of the else clause, if present, is executed.

“Right!” I said, “If they can describe it in a paragraph, then so can I!” I said, and rewrote mine to a much more condensed version, which I believe describes the same logic:

The expression on the first line is called the “condition”. The condition’s type must be Int, or the compiler MUST reject the program. The first nested block of statements is called the “then” clause. If the optional else part is supplied, then the second nested block of statements is called the “else” clause.

The condition is evaluated, and any side-effects take place immediately. If the value is not 0, the “then” clause is executed. If the value is 0, then the “else” clause, if supplied, is executed.

My point is that if you read my original version, it’s a lot more stiff and formal, and dare I say, condescending? It is clear but not concise. It tells you every little detail about how an if statement works!

The way the Python language reference is written is really assuming some intelligence on the part of the reader. It uses more conversational phrases such as “one by one until one is found to be true; then that suite is executed”. There’s no formal notion of “one by one”, nor do they formally describe what is meant by “that suite”. But of course, any reader with an ounce of sense will know what is meant by “one by one” and “that suite”.

It almost seems counter-intuitive, but assuming some intuition or thought on behalf of your readers can actually make documents easier to read, not harder.

If you compare the size of, say, the C++ language spec (~1300 pages), or even the C language spec (~500 pages) to Python (~100 pages), you can see the difference this style makes.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: