Not so rhetorical question: Why the common practice of writing lines of code without white space?

I wanted to ask this of MathWorks, because they start the habit in their docs, but I didn't find a place to ask them... so...

I am working with new MATLAB students at the undergrad and grad levels, and they all cram their lines of code together without white space. When I ask them why, in light of other written materials, such as their texts, journals, etc., that use white space effectively, they use no white space in their MATLAB code, they invariably reply that they see it that way in the MATLAB docs, and assume that it is the "correct" way to write MATLAB code. Whilst it is easy enough for the author of a code fragment to read his own code, readability for others suffers significantly when white space is removed.

Is this

    scDSI(:,theta+1)=scRadius*[cosd(theta);sind(theta);0.0]

really as easy to read as this

    scDSI (:, theta+1) = scRadius * [ cosd(theta); sind(theta); 0.0 ]?

If I copy an example from the docs to use as my template for a command that is new to me (so I don't already know the syntax by heart), I get, for example,

    set(findobj(control_fig_handle,'Type','uicontrol'),active)

I'm pretty sure that the use of white space for readability in code is a recommended practice, so why does MathWorks foster the opposite in their docs?

And if this should be a question for MathWorks, where do I send it?

[Stephen Cobeldick]

If you edit your question and format the text correctly (hint: use the {} Code button above the text field), then your examples would make a lot more sense.

[Andreas Goser]

There is a team at MathWorks looking at programming standards for code in demos, doc, etc. If the responses here are not sufficient for you, please send me a PN or email and I will try to get you in touch with that team.

Answer 1

[John D'Errico]

I think the point is whitespace is good. Well, good to some extent. Gosh, like whitespace, water is good for me, or so my doctor says. But too much water, and it can kill a person. To extend the simile, some of us need more water than others.

So, yes, whitespace is good to the extent it makes your code easier to read. Tightly packed code is difficult to read, especially if it is complicated code. Your example however, overdoes it for me.

scDSI (:, theta+1) = scRadius * [ cosd(theta); sind(theta); 0.0 ]

I prefer to use some white space, but NEVER between a function and the parens in a function call. So I would eliminate the first blank you had in there, and maybe a few more. I'll usually have space between operators and their operands. So for me, + and - deserve spaces around them. I tend not to use whitespace around * and ^ operators.

scDSI(:,theta+1) = scRadius*[cosd(theta); sind(theta); 0.0]

Anyway, you were inconsistent! If you want a space after scDSI, then why not want to put one after the calls to sind and cosd? Of course, that screws up the parser. Remember that when you use whitespace it is also the equivalent of a comma. So you might also cause confusion by too much whitespace. How should this next line be interpreted?

X = [ cosd (1:10) ];
Error using cosd
Not enough input arguments.

Yes, MATLAB gets upset there. So my point is, for consistency, whitespace between a function and the paren that follows it is a bad idea, because it may SOMETIMES be interpreted incorrectly.

Similarly, see my answer to this recent question. There, we saw the line:

temp2=[13.796, 13.863, 13. 865, 13.893, 13.881];

Clearly there is a typo in the line. It might better have been written as:

temp2=[13.796, 13.863, 13.865, 13.893, 13.881];

But arguably, the typo would have been even easier to see if no whitespace at all was inserted!

temp2=[13.796,13.863,13. 865,13.893,13.881];

WHOOPS! To me, that seems a clear typo now.

Whitespace is good. But don't overdo it. And recognize that everyone has a different tolerance for whitespace. Just like comments in code, and in a function header. Personally, I like them. I think more of them are better than less. But some people think I overdo it, that I write too much, too complete help. Either way, it is not worth getting upset over because we need to recognize that everyone is different, and has different programming styles.

Answer 2

[dpb]

...Is [compactline] really as easy to read as this [brok en line]?

In my view, yes, the compact version is as legible (or, more precisely, I think the suggested line is less legible).

I do NOT like excessive spaces such as the introduction of a space between the variable name and the subscripting expression particularly; that destroys imo the association.

I don't mind separating the RHS and LHS and, judiciously applied, separating (say additive) terms in a long expression can be of some benefit but to do so excessively just because there is a '+' sign present adds nothing in my view; use the spacing as one would commas in a sentence--sparingly and to make a specific lexical point.

It's far better to have more consistency whatever the style chosen than any arbitrary number of spaces or placing of same. The biggest gripe I have with much of the code posted is the seemingly interminable length of variable names and the penchant to not break long lines of code into either multiple lines via a few temporaries or by the continuation ellipses.

You can submit suggestions to TMW for updates/modifications to documentation via the CONTACT point on the www.mathworks.com main page.

[Image Analyst]

I guess I'll have to disagree on this. I like the white space, with the exception that for functions, I never put a space between the function name and the opening/left parenthesis. And I like descriptive (long) variable names rather than an alphabet soup of single letter variable names where you don't know what's what.

[dpb]

Which shows why style is "style"--everybody has their own preferences. :)

One might as well discuss which is the "best" programming editor...

On the naming convention--

I use descriptive names where they're appropriate but the trend I see towards 20- and 30-character names that by the time you've gotten two of them on a line the line won't fit the screen plus they simply obfuscate more than clarify is just, imo, a wrongheaded approach to coding clarity.

ADDENDUM

It becomes even more a problem in my view with o-o coding where object names plus methods plus inheritance become excessive very quickly if a great deal of effort isn't taken to prevent bloat. Same goes with nested data structures.

I find the love of the repeated name with the only distinguishing characteristic being the last few (or notsofew) letters being the distinguishing mark as particularly difficult to keep track of in reading code. Just a trivial example; many are much worse than these but it's the idea of the thing...

>> figure, get(gcf)
>>
  ...
  WindowButtonDownFcn = 
  WindowButtonMotionFcn = 
  WindowButtonUpFcn = 
  ...

What does the repetitive "WindowButton" string add, really, that couldn't be much shorter and still as meaningful? After all, while human legibility is significant in code maintenance and I get naming the properties as something other than "Tom, Dick, Harry", wouldn't

    ...
    WinButtonDownFcn = 
    WinButtonMotionFcn = 
    WinButtonUpFcn = 
    ...

or

    ...
    WinBtnDownFcn = 
    WinBtnMotionFcn = 
    WinBtnUpFcn = 
    ...

be just as effective? Do you really have trouble in deciphering what they are? And do the other names make it that much easier to read code when they take up so much room and become so prevalent and keeping them apart is only a few characters buried in the middle?

I don't do these kinds of studies as a profession but I really can't believe this convention would have any support in actual research on legibility and comprehension in testing.

ThenAgainMaybeIAmWrong.WouldntBeFirstTime :)

Maybe I'm just showing my age and "oldgoats~=newtricks"

[dpb]

Poster child for difficulties in coding formatting w/ excessive variable name length...I just spent about 15 minutes or maybe even longer, getting this as is---original had no line wraps to speak of...

http://www.mathworks.com/matlabcentral/answers/169659-execution-of-while-loop-iteration-times-vary-hugely-or-the-loop-gets-stuck

[Guillaume]

The problem with using abbreviations is that there are many readable ways to abbreviate the same words. Combine that with matlab poor tab completion, and you'll often find yourself having to look in the documentation or code for the proper spelling of the abbreviation. In your example, how do I remember if it's

WinButtonDownFcn
WinBtnDownFcn
WnBtnDwnFn
%or something else?

The only non-ambiguous writing is to spell each word completely

WindowButtonDownFunction

Or, another example, can you tell me without looking it up which of the following is the right spelling to get the equivalent diameter returned by regionprops? matlab's tab completion won't be any help.

regionprops(x, 'EquivalentDiameter') %is it right?
regionprops(x, 'EquivalentDiam') %or is it this?
regionprops(x, 'EquivDiameter') %or maybe this?
regionprops(x, 'EquivDiam') %maybe this one?
regionprops(x, 'EqDiameter') %how do you know?
regionprops(x, 'EqDiam') %without looking it up?

[Image Analyst]

Of course, much/most of the rest of the world calls it ECD for Equivalent Circular Diameter. Not sure why MATLAB used this term.

[dpb]

... how do I remember if it's [one of various spellings]...

How do you remember when it's spelled out in its entirety what the next word is? It's all got to go back to the documentation anyway.

Answer 3

[Stephen Cobeldick]

I have a different hypothesis: perhaps this is a mathematician vs. programmer characteristic?

It is programmers who obsess about whitespace, the lack or the meaning thereof, and this is reflected in many programming languages' codes of best practice, and the endless flamewars about Python. This could be due to the structure and overall flow of the text being seen as a parallel to the structure of the program itself, and a reflection of a good algorithm implementation, therefore careful use of whitespace is used to show the flow of the whole program.

Mathematicians are perhaps much more used to keeping things together, particularly operators and arrays, where the conceptual groups are seen as some kind of atomic unit: it represents one abstract thing that is being manipulated or assigned, and so the visual importance is to represent it as one thing.

A*B

• a programmer sees "this is value A times value B" (and so uses whitespace to make it clear that this is an operation on two variables)
• a mathematician sees "this is the product of values A and B" (and so groups them together into one atomic concept).

This hypothesis also explains the tendency in MATLAB to use very short (one letter!) variable names, so while most programmers have a heart attack at the mere thought of this, all of mathematics is taught using x, y, k, A, B,... as typical variable names. The code that then gets written naturally reflects these norms and traditions, because people want to see on their computer as they can see in the book on the table in front of them.

[dpb]

I agree there's a lot of the "what's in the book" direct implementation; perhaps that's even more so for those of us of a certain age for whom the only computer language was FORTRAN (yes, long before "Fortran") on punch cards with the inviolate 72 columns starting in column 7 rule.

Answer 4

[Image Analyst]

Here's how tutorial creator Doug Hull of the Mathworks views it. See #6 on http://blogs.mathworks.com/videos/2010/03/08/top-10-matlab-code-practices-that-make-me-cry/, also #5 and the others.

[Stephen Cobeldick]

His entire comment about whitespace reads as follows:

6.) Not using white space to good effect in code.

Even though you can put several commands on one line if separated by a semicolon, these lines can often be hard to notice. Not putting blank lines between sections of code can also make it harder to read.

White space is free, use it to make your code look good.

Interestingly he does not mention any of the points that have been brought up in this thread: space after commas, around operators or assignment signs, between variables and subscripting indices, and between function names and the following parentheses. His only concrete point is against multiple commands on one line, which is not quite the same topic as the OP is questioning.

[Star Strider]

I hadn’t seen Doug’s blog on that. Thanks.

Appropriate use of parentheses is another style point I would emphasize. I use them around logic tests so that I know what I intend, the compiler knows what I intend, and anyone else who reads my code knows what I intend:

(a <= b) && (b ~= c)

even if there is only one logic test. It makes my code easier for me to read.

The Editor complains when I put brackets around vectors, but I know immediately by looking at my code that a variable is a vector:

v = [1:10];

My sympathies are with you on your Comments here as well.

[John D'Errico]

I completely agree with Star here. Those spare parens and brackets make the code easier to read, at least for me. Others might find them an excessive use of characters. Whatever floats your boat...

Answer 5

[Iain]

When it comes to making code readable,

 scDSI (:, theta+1) = scRadius * [ cosd(theta); sind(theta); 0.0 ];

Is not as readable as:

 scDSI(:, theta+1) = scRadius * [cosd(theta) sind(theta) 0.0]' ;

But:

 scDSI(:, theta+1) = [cosd(theta)
                      sind(theta)
                      0.0]         * scRadius;

Is better....

[dpb]

I'd contend

 scDSI(:, theta+1) =  scRadius * [cosd(theta)
                                  sind(theta)
                                          0.0];

is "better" yet given that the multiplier is a constant.