Readable code (Was: Re: [H-GEN] Which is better?)

[Byron Ellacott]

On Wed, 2004-04-28 at 21:53, Adrian Sutton wrote:
> [ Humbug *General* list - semi-serious discussions about Humbug and     ]
> [ Unix-related topics. Posts from non-subscribed addresses will vanish. ]
> > On the subject of readable code, will I have to get used to reading 
> > code that looks like this:
> heh.   You're trying to keep me busy writing contentious emails aren't 
> you? :)  Coding style is a matter of personal preference.  Having said 

He's also trying to suck me into the thread, I swear it, it's not my
fault.

> that, there are distinct advantages to using a familiar coding style.  
> I have the firm belief that you should use the coding style most 
> prevalent for the language you're using (barring any glaringly bad 
> ideas in that style).  So for Java code I would follow the Sun Java 
> coding convention:

Not only coding style, but also naming style.  Perl programmers, as a
rule, hate receiving modules with names that are_underline_separated,
and function names that are in StudlyCaps.

I'm not sure if anyone actually LIKES Hungarian notation, but a Win32 C
program should probably use it.  Hey, there'll be more pain for you in
dealing with the Win32 API than in dealing with Hungarian notation.

> I like the consistency of using block statements for all control 
> structures.  Others prefer to save typing and/or don't like white 
> space.  The other thing I really don't like is the use of "compound 
> statements" like:

In general, so do I.  I also like that the languages I use force quite
explicit clarity on the subject.  Perl[1]'s syntax disallows a
conditional statement followed by an expression, it must be followed by
a block.  Of course, it also allows an expression to be followed by a
conditional statement, but you cannot use an else clause in that case:

if (foo) do_something();	# Illegal
do_something() if (foo);	# Legal, but you cannot apply an else
if (foo) {
    do_something();
} else {
    do_something_else();
}

> I do however try to avoid assuming that people know too much about 
> operator precedence though, but tend to balance this against how many 
> nested brackets are required to be explicit.  So I would write:
> (i / 3) * 2

This one is a tricky one.  Mathematically, (i / 3) * 2 == (i * 2) / 3. 
However, many languages don't really give you divide when you tell them
to '/' two values.  C, for example, does an integer divide, which
truncates its result.

I've had to fix code that attempted to do an increase by n% via the
expression:

val += (val / 100) * n;

I fixed this by:

val += (val * n) / 100;

However, in another part of the same program, the inverse problem bit. 
A number was being scaled down by a particular percent:

val = (val * n) / 100;

Looks good?  Trouble is, val tended to be fairly large, and n tended to
be fairly close to 100.  As a result, the first operation would
regularly overflow past maxint, and the result of the expression would
change sign!

In both cases, typecasting val to a float (or preferably, double) will
make the order of the operators irrelevant.  Alternatively, typecasting
to a long and always explicitly forcing a multiplication first will also
give you a fair degree of safety[2].

> even though (in Java at least) the brackets could be omitted without 
> changing the effect of the statement.  (Expressions are evaluated left 
> to right and division and multiplication have the same precedence 
> level).

I don't like to go any closer to Java than I absolutely have to, so I
don't have anything Java-like anywhere accessible to see how it handles
division of integer values.

In short, I parenthesise anything where operator precedence might
conceivably have an effect.  If it's the same operator, or operators for
which order (practically!) has no effect, I won't parenthesise.

> Anyway, I would be interested to hear from people who like different 
> styles to these as to why their preference goes that way, even if it's 
> a very informal "I find whitespace makes it harder to parse chunks of 
> code".

I like Python[3].  Python means noone's going to give me a piece of code
with unindented blocks, not unless they're also saying, "My Python code
doesn't even compile, let alone run!"

-- 
bje

[1] I know, I know, Perl's syntax does not lend itself to readability,
even when you're careful.  I don't think I could recommend Perl for
programs of more than a few hundred lines.  Not with a straight face,
anyway.

[2] I did enough hand optimization trying to squeeze the last erg of
speed out of an old 386SX processor that I still somewhat cringe at
floating point operations - even though modern processors eat fp ops for
breakfast.

[3] A lot.  It's a very tidy little language.  Few keywords, unambiguous
syntax, and plenty of functional programming goodies to help us avoid
those nassty side effects that modifying state implies.