Indentation styles


S

Stefan Ram

markspace said:
I don't see why code can't be formatted for its intended audience either.

The formatting too is part of the message I want to convey,
so to me it would not be the same message anymore.

If someone is paying me to write code, he can get any format
from me that he likes. But on the Usenet I enjoy the freedom
to use the indentation style that I deem best, as explained below:

One Way to Format Parentheses

There are several different ways to format texts with braces
and parentheses. One of them is being described here.

Indentation within Braces

An indentation of just one space often is too small to be seen
clearly, because the natural width and form of characters
often varies by an amount that is not very much smaller than a
space. Therefore, the indentation should amount to at least
two positions. In order not to waste horizontal spaces, an
indentation of exactly two positions is chosen. This means,
that the left position of the next level is two larger than
the position of the directly enclosing level.

Indentation by two positions within a block

{ ++x;
++x; }
^ ^
0 2

Bad: A small indentation by one position is not always visible
clearly

{++x;
++x; }

Good: The indentation by two positions is visible clearly

{ ++x;
++x; }

Bad: A large indentation by more than two positions wastes
horizontal space with no additional benefit

{ ++x;
++x; }

Spaces within braces

In mathematics, there are often no spaces at the inner side of
parentheses or braces in expressions, but spaces are used
indeed at the inner side of braces in set notation, when the
braces contain a description (not when they contain a list).

Spaces in set notation

{ x | x > 2 }

This style is adopted here: One space is written at the inner
side of braces.

Spaces at the inner side of parentheses within a block

{ ++x; }

This style is consistent with the indentation by two
positions, because only using this style, corresponding parts
of two lines have the same position.

Bad: No space after the first brace, the two statements are
misaligned

{++x;
++x; }

Good: One space after the first brace, the two statements are
properly aligned

{ ++x;
++x; }

Bad: Two spaces after the first brace, the two statements are
misaligned

{ ++x;
++x; }

There are some exceptions to this rule: No spaces are used
within empty braces "{}" and between two or more closing
braces of the same direction "}}", except, when the first one
of them is part of an empty pair "{} }" (an empty pair of
braces is treated like a single non-braces character).

Unified rules for all Brackets

For simplicity and uniformity, the rules from above apply to
all kinds of brackets, including parentheses, braces (curly
brackets), square brackets, and angle brackets.

Spaces within parentheses and square brackets

{ y = f( x )+ g() + a[ 2 ]; }

Binary operators are sorrounded by a space, but the space is
omitted, when there already is a space on the other side of a
sequence of brackets directly beside the operator: By this rule,
" )+" is written instead of " ) +".

Representation of the Syntactical Structure

A method or function definition consists of a head and a body.
The following representation shows this structure:

Good formatting according to the structure

void alpha() // head
{ beta(); } // body

The following formatting is misleading, because the line break
does not match the structural break:

Bad line break within the body

void alpha() { // head and the beginning of the body
beta(); } // the rest of the body

This formatting also would make no sense for blocks within
blocks. So it is often not used for such blocks. Therefore
even the adopters of this style can not use it uniformly.

Opening Braces Look Like "bullets"

There is a well known style to publish lists in typography
using bullets sticking out on the left, looking like this:

Common list representation with bullets in typography

o This is the first point
of this list, it is written
here just as an example.

o Here is another entry

o This is another example given
just as an example to show
an example

The braces of the beginnings of blocks stand out on the left
just the same, when the formatting being described here is
used, so they look quite naturally as beginning-of-a-block
markers, when one is used to the typographical list notation:

Left braces look like bullets to mark blocks

{ printf(); printf();
printf(); printf(); printf();
printf(); printf(); }

{ printf(); printf(); }

{ printf(); printf(); printf();
printf(); printf();
printf(); }

Neutrality

Someone wrote this C code:

while( fgets( eingabe, sizeof eingabe, stdin ))
if( sscanf( eingabe, "%d", &wert )!= 1 )
fprintf( stderr, "Please enter a number!\n" );
else
summe += wert;

It amazes me that I can add braces by my style conventions
(not changing the meaning of the code)
without the need to change the position of any character of
the given code or need to change the overall number of lines:

The code from above plus braces

while( fgets( eingabe, sizeof eingabe, stdin ))
{ if( sscanf( eingabe, "%d", &wert )!= 1 )
{ fprintf( stderr, "Please enter a number!\n" ); }
else
{ summe += wert; }}

Insofar, my bracing style might be considered non-obtrusive.

Lines per Contents

Lines containing only a single brace waste vertical space, so
less contents fits on the same screen space. Therefore, I usually
avoid them, but sometimes I do use them, when this helps to
increase readability. I also might temporarily use them when editing
a section of code. Of course, they would help programmers paid or
being judged by the lines-of-code productivity.

The Formatting of The If Statement

I want my code to express the structure of the if
statement.

What is the structure of an if statement?

According to ISO/IEC 9899:1999 (E) [it is similar in the
JLS {Java}, too]

selection-statement:
if ( expression )
statement

So, there is a head clause

if ( expression )

and a body statement

statement

Thus,

if( expression ) /* head clause */
{ exam(); ple(); } /* body statement */

The separation between head and body in the deep structure
beautifully alignes with the separation between the first
and the second line in the visible surface structure. Thus,
the surface structure exposes the deep structure in a
not-misleading way. (Which to me is the generalized meaning
of »structured programming«: expressing as much of the deep
structure as possible already in the surface structure,
which makes the code more readable.)

Moreover, why would anyone sane in his mind compose a line
of the head of a structure /and the first character of its
body/ with the rest of the body following in another line?

if( expression ) { /* head clause AND first character
of the body statement */
exam(); ple(); /* rest of body, except for */
} /* a line wasted on a brace */

As a comparision, in writing, we have headings and text body:

The Creation

In the beginning God created the heaven and the earth.

Now, why would someone write the heading /and the first word of
its body/ on a line, as in the following example?

The Creation In

the beginning God created the heaven and the earth.

I write:

if
( sscanf( input_buffer, "%d %d %d", &length, &width, &height )== 3 &&
sscanf( other_buffer, "%d %d %d", &color, &price, &weight )== 3 &&
needs_processing( color ))
{ compute_volume( length, width, height );
compute_something_else( price, weight ); }

^
'---- What I like about this is:

This is an if statement with two variable constituents:
an expression and a statement.

This is the macrostructure.

The major questions one encounters when reading are:

- What a kind of entity is this at all?

And then, having learned that it is an if statement:

- Where is its expression?

- Where is its statement?

And it are exactly the answers to these three questions
that are each marked with a character in the leftmost column!

So the type of the entity and its two constituents
clearly stand out graphically (visually). Albeit in a
manner not too obtrusive and not wasting lines.

Now we can compare this with (IIRC, this is code someone
else wrote):

if (sscanf(input_buffer, "%d %d %d", &length, &width, &height) == 3 &&
sscanf(other_buffer, "%d %d %d", &color, &price, &weight) == 3 &&
needs_processing(color)) {
compute_volume(length, width, height);
compute_something_else(price, weight);
}

Here the start and end of the statement are marked in the
leftmost column. This is also not bad, but the important
separation between the expression and the statement of the
if is »hidden« in the »center« of this character structure.
 
Ad

Advertisements

E

Eric Sosman

[...]
An indentation of just one space often is too small to be seen
clearly, because the natural width and form of characters
often varies by an amount that is not very much smaller than a
space. Therefore, the indentation should amount to at least
two positions. In order not to waste horizontal spaces, an
indentation of exactly two positions is chosen. This means,
that the left position of the next level is two larger than
the position of the directly enclosing level.
[...]

I dimly recall reading, long ago, of someone's actual attempt
to measure the readability of different indentation widths. Alas,
I can no longer find the reference. I believe, though, that the
experiments found two spaces too narrow, four spaces too wide, and
eight spaces much too wide.

Unfortunately, the remaining span includes two of the most
prominent and pervasive numbers of all, and there's no hint as to
which to use: The One True Best Indentation Width might be π or
it might be e, and I expect the religious debates on the topic
will rage endlessly. Personally, I adopt a tolerant stance: Use
either e spaces or π spaces according to the teachings of your
faith. Using anything else, though, would be heresy. :)
 
D

Daniele Futtorovic

The formatting too is part of the message I want to convey,
so to me it would not be the same message anymore.

<snippalot />

All fair and well, but one aspect that you have not covered and that to
me is of import, is the comment-out-ability. That is, because I care
about being able easily to comment-out/decomment stuff, I usually don't
mix parts of the block descriptor (flow-control, method descriptor,
etc.) and statements.

To exemplify, if I wrote...
void foo()
{ bar();
boom();
bang();
}
.... and subsequently decided that I didn't want to bar() after all, I'd
have to alter the structure. So I'll either write:
void foo()
{
bar();
boom();
bang();
}
or
void foo() {
bar();
boom();
bang();
}

While I understand, rationally, the arguments for the former, for some
eerie reason it hasn't really caught on to me, and I've mainly stuck to
the latter. But YMMV.
 
S

Stefan Ram

Daniele Futtorovic said:
... and subsequently decided that I didn't want to bar() after all,

In this case one can edit it from

void alpha()
{ beta();
gamma(); ...

to either

void alpha()
{ // beta();
gamma(); ...

or

void alpha()
{ gamma(); ...

(Place cursor in front of »b«, press »shift«,
tip »cursor down«, release shift, tip »del«.)

However, you are right, I also prefer sometimes

void alpha()
{
beta();
gamma(); ...

as this is still easier to edit. Sometimes I »unpack«
my code in this way before editing, and later »pack« it
again to

void alpha()
{ beta();
gamma(); ...

I do not argue against

void alpha()
{
beta();
gamma(); ...

at all. What I do /not/ like that much is:

void alpha() {
beta();
gamma(); ...
 
W

Wojtek

lipska the kat wrote :
Ah, my favorite style, I can't see why anyone would want or
need anything else. I've been known to reformat code with a particularly
irritating bracketing style but life is too short so generally now I try to
live with it. But really ...

void alpha() {
beta();
gamma();
}

Is a thing of beauty and a joy to behold, it's all you need :)

Hmmm, I prefer my braces on their own line. In your style I am forever
chasing my eye around the screen trying to find out if there is a
brace, whereas a brace on a separate line stands out. YMMV but IMHO it
is a faster way to read code.
 
D

Daniele Futtorovic

In this case one can edit it from

void alpha()
{ beta();
gamma(); ...

to either

void alpha()
{ // beta();
gamma(); ...

But putting those two slashes in (or removing them) is much more
cumbersome than [navigate to line] -> [ ctrl + / ].

What I do /not/ like that much is:

void alpha() {
beta();
gamma(); ...

Well understood.
 
Ad

Advertisements

J

Joerg Meier

Hmmm, I prefer my braces on their own line. In your style I am forever
chasing my eye around the screen trying to find out if there is a
brace, whereas a brace on a separate line stands out. YMMV but IMHO it
is a faster way to read code.

Personally, I moved on since the stone age and use a code formatter. So I
don't need to hunt for the opening bracket: I can tell it's there because
the code in the line under it is indented. I heartily recommend it ;)

Liebe Gruesse,
Joerg
 
G

Gene Wirchenko

lipska the kat wrote :
[snip]

Hmmm, I prefer my braces on their own line. In your style I am forever
chasing my eye around the screen trying to find out if there is a
brace, whereas a brace on a separate line stands out. YMMV but IMHO it
is a faster way to read code.

When scanning code for a section, I typically read just the left
part. With braces on their own line, this makes it much easier to
check nesting.

Sincerely,

Gene Wirchenko
 
A

Arved Sandstrom

Same here, +1. I am just not going to use different brace standards for
Java, Perl, C, C++, C# etc. And I do find the symmetric version with
brace pairs on their own lines to be more readable. It also makes sense
because quite often you need to leave some WS between the test or
whatever that creates the block, and the lead statement of the body...so
why not drop the leading brace down to accomplish that?

AHS
 
A

Arne Vajhøj

The formatting too is part of the message I want to convey,
so to me it would not be the same message anymore.

If someone is paying me to write code, he can get any format
from me that he likes. But on the Usenet I enjoy the freedom
to use the indentation style that I deem best, as explained below:

Usenet is free. Period.

But that does not change that it is impolite to ask people to
look at some code that is not formatted to make it easy for
them to read.

And even if the only reason is that they are used to another
style does not change that.

If not asking anyone for help but instead providing help,
then there is a moral aspect of what one learn people. Since
you code does not have /* do not format code like this at home */,
then someone could be mislead to think that it was OK to format
like that.

Arne
 
A

Arne Vajhøj

[...]
An indentation of just one space often is too small to be seen
clearly, because the natural width and form of characters
often varies by an amount that is not very much smaller than a
space. Therefore, the indentation should amount to at least
two positions. In order not to waste horizontal spaces, an
indentation of exactly two positions is chosen. This means,
that the left position of the next level is two larger than
the position of the directly enclosing level.
[...]

I dimly recall reading, long ago, of someone's actual attempt
to measure the readability of different indentation widths. Alas,
I can no longer find the reference. I believe, though, that the
experiments found two spaces too narrow, four spaces too wide, and
eight spaces much too wide.

Unfortunately, the remaining span includes two of the most
prominent and pervasive numbers of all, and there's no hint as to
which to use: The One True Best Indentation Width might be π or
it might be e, and I expect the religious debates on the topic
will rage endlessly. Personally, I adopt a tolerant stance: Use
either e spaces or π spaces according to the teachings of your
faith. Using anything else, though, would be heresy. :)

I sure someone has tried measuring what is optimal, but I
suspect that the difference were pretty small (for realistic
indentations).

But I am sure that it could be measured that the effect
of using the same indentation level in a file is huge and
I strongly suspect the same for using the same in a project.

Which leads to the normal conclusion:
* make a decision about indentation level and stick to it
* if there are no strong opinions about it then go with the
industry standard for that language (4 for Java)

Arne
 
Ad

Advertisements

A

Arne Vajhøj

Same here, +1. I am just not going to use different brace standards for
Java, Perl, C, C++, C# etc.

Each language has its own standards, conventions and practices. I am
very skeptical about an attempt to format different languages identical.

Arne
 
E

Eric Sosman

[...]
An indentation of just one space often is too small to be seen
clearly, because the natural width and form of characters
often varies by an amount that is not very much smaller than a
space. Therefore, the indentation should amount to at least
two positions. In order not to waste horizontal spaces, an
indentation of exactly two positions is chosen. This means,
that the left position of the next level is two larger than
the position of the directly enclosing level.
[...]

I dimly recall reading, long ago, of someone's actual attempt
to measure the readability of different indentation widths. Alas,
I can no longer find the reference. I believe, though, that the
experiments found two spaces too narrow, four spaces too wide, and
eight spaces much too wide.

Unfortunately, the remaining span includes two of the most
prominent and pervasive numbers of all, and there's no hint as to
which to use: The One True Best Indentation Width might be π or
it might be e, and I expect the religious debates on the topic
will rage endlessly. Personally, I adopt a tolerant stance: Use
either e spaces or π spaces according to the teachings of your
faith. Using anything else, though, would be heresy. :)

I sure someone has tried measuring what is optimal, but I
suspect that the difference were pretty small (for realistic
indentations).

But I am sure that it could be measured that the effect
of using the same indentation level in a file is huge and
I strongly suspect the same for using the same in a project.

Which leads to the normal conclusion:
* make a decision about indentation level and stick to it
* if there are no strong opinions about it then go with the
industry standard for that language (4 for Java)

It would be both instructive and liberating, I think, to
adopt indentation widths that are multiples of i. Instead of
pushing the indented line to the right and thereby reducing
the amount of non-white horizontal space available, a pure
imaginary indent would move the text in a direction normal to
the page or display surface: Nearer to the viewer for c*i
with c>0, or further into the background for c<0. The sign
of c could be adjusted automatically by code inspection tools,
positive when the programmer is trying to study the excruciating
details of the code and wants to deep-dive on the interiors of
conditions and loops, or negative when the focus is on the Big
Picture and petty details shouldn't get in the way.

Given the two-dimensional nature of most display surfaces,
plus a third dimension toward or away from the viewer, one might
be tempted to employ indentation standards based on quaternions.
Any "one" so tempted is urged to seek psychiatric help. NOW.
 
G

Gene Wirchenko

[snip]
Each language has its own standards, conventions and practices. I am
very skeptical about an attempt to format different languages identical.

Not identical, but I have found that I can use very similar
standards across multiple languages.

Sincerely,

Gene Wirchenko
 
A

Arne Vajhøj

[snip]
Each language has its own standards, conventions and practices. I am
very skeptical about an attempt to format different languages identical.

Not identical, but I have found that I can use very similar
standards across multiple languages.

I am sure that you *can*.

But you will end up with N-1 or N languages being
formatted "unusual".

Arne
 
J

Jim Gibson

Arne Vajhøj said:
[snip]
Each language has its own standards, conventions and practices. I am
very skeptical about an attempt to format different languages identical.

Not identical, but I have found that I can use very similar
standards across multiple languages.

I am sure that you *can*.

But you will end up with N-1 or N languages being
formatted "unusual".

To my limited knowledge Java is the only language whose originating
vendor publishes an "official" formatting standard. Usually, it is
individuals, groups, or organizations that develop formatting standards
and attempt to enforce them for some body of work.

Authors will use a consistent formatting style, and these can become
defacto standards (e.g., Kernighan and Ritchie, Stroustrup).

I, too, try to be consistent in formatting style when moving between
languages whenever possible, because it makes me more productive.

I have worked on projects with practically no standards, and others
with extensive standards, but they never seemed to be enforced.
Usually, the customer just wants the project finished, and never mind
about the format of the code.
 
Ad

Advertisements

L

Lew

Jim said:
Arne said:
I am sure that you *can* [use the same formatting style for different languages].

But you will end up with N-1 or N languages being
formatted "unusual".

To my limited knowledge Java is the only language whose originating
vendor publishes an "official" formatting standard. Usually, it is
individuals, groups, or organizations that develop formatting standards
and attempt to enforce them for some body of work.

Authors will use a consistent formatting style, and these can become
defacto standards (e.g., Kernighan and Ritchie, Stroustrup).

I, too, try to be consistent in formatting style when moving between
languages whenever possible, because it makes me more productive.

I have worked on projects with practically no standards, and others
with extensive standards, but they never seemed to be enforced.
Usually, the customer just wants the project finished, and never mind
about the format of the code.

Here other programmers are "the customer", and we're here to help with source
code, or talk about other related matters where source code is part of the discussion.

Even if the language, such as C, doesn't have an official standard but it does have a de
facto standard, standards is standards.

Whatever your customer wants is irrelevant. Here we want to talk about code.. We are
not rigid about the "official" standard, but deviate too far from the social norm and you
lose audience. Your customer is not part of this process so why mention him?

It's about clear communication *with other programmers*. You want to use a sociopathic
style like Mr. Tilde's or Stefan's, you will run into communication difficulties. Just use the
standard format, for Chrissake!

No man is an island, so ask not for whom the bell tolls. It tolls for thee.

(Sorry, Mr. Donne.)
 
A

Arne Vajhøj

Arne Vajhøj said:
[snip]

Each language has its own standards, conventions and practices. I am
very skeptical about an attempt to format different languages identical.

Not identical, but I have found that I can use very similar
standards across multiple languages.

I am sure that you *can*.

But you will end up with N-1 or N languages being
formatted "unusual".

To my limited knowledge Java is the only language whose originating
vendor publishes an "official" formatting standard. Usually, it is
individuals, groups, or organizations that develop formatting standards
and attempt to enforce them for some body of work.

Authors will use a consistent formatting style, and these can become
defacto standards (e.g., Kernighan and Ritchie, Stroustrup).

It varies.

MS has published some conventions for C#. Guido has published some
guide for python.

But C and C++ has multiple widely used standards. I have seen many
different (but somewhat compatible) conventions for Ruby and PHP.
I, too, try to be consistent in formatting style when moving between
languages whenever possible, because it makes me more productive.

That is fine if you are the only person ever to work on the code.

But if somebody else is, then they will be more productive if
it is more "standard".
I have worked on projects with practically no standards, and others
with extensive standards, but they never seemed to be enforced.

There are tools to enforce if there is a will to enforce.
Usually, the customer just wants the project finished, and never mind
about the format of the code.

That has been seen.

:)

But after 20 years with high annual maintenance cost it also happens
that they regret.

Arne
 
S

Stefan Ram

Jim Gibson said:
To my limited knowledge Java is the only language whose originating
vendor publishes an "official" formatting standard.

»By convention, method names should be a verb in
lowercase or a multi-word name that begins with a verb
in lowercase, followed by adjectives, nouns, etc.«

http://docs.oracle.com/javase/tutorial/java/javaOO/methods.html

The followers thus should write:

calculateSquareroot( calculateSquare( x )+ calculateSquare( y ))

. Now, Rob Pike has the correct guidelines for us:

»Procedure names should reflect what they do;
function names should reflect what they return.«

http://www.lysator.liu.se/c/pikestyle.html

, thus:

print( square( 2 ))

. »print« is a procedure, »square« is a function.
Life can be so simple.

Thus, one cannot reasonably follow all the Oracle
guidelines.
 
Ad

Advertisements

D

Daniele Futtorovic

»By convention, method names should be a verb in
lowercase or a multi-word name that begins with a verb
in lowercase, followed by adjectives, nouns, etc.«

http://docs.oracle.com/javase/tutorial/java/javaOO/methods.html

The followers thus should write:

calculateSquareroot( calculateSquare( x )+ calculateSquare( y ))

. Now, Rob Pike has the correct guidelines for us:

»Procedure names should reflect what they do;
function names should reflect what they return.«

http://www.lysator.liu.se/c/pikestyle.html

, thus:

print( square( 2 ))

square( x ) creates a two-dimensional square with x pixel side length,
right?
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Top