Formatting for humans or for tools?

[Alf P. Steinbach]

At the last meeting of Oslo C++ Users Group it was maintained (as I understood
it) that code like ...

SomeType someName; // Knurre.
SomeOtherType someOtherName; // Voff.
AThirdType aThirdName; // That was a good catchy melody.
Fifthum huhWhatsThat; // But you're too young to remember.
NoHeresTheReal5th ohYeah; // Probably.

.... is bad, because most any refactoring tool tool will destroy the nice line-up
when you change those type names, and that it's therefore much better &
preferred to have no line-up, like ...

SomeType someName; // Knurre.
SomeOtherType someOtherName; // Voff.
AThirdType aThirdName; // That was a good catchy melody.
Fifthum huhWhatsThat; // But you're too young to remember.
NoHeresTheReal5th ohYeah; // Probably.

It seemed that everybody agreed.

Comments?


Cheers,

- Alf
(blog at <url: http://alfps.wordpress.com>)

 

[Victor Bazarov]

What nice line-up? I use a proportional font.

Where? In your code editor?

V

 

[Öö Tiib]

At the last meeting of Oslo C++ Users Group it was maintained (as I understood
it) that code like ...

    SomeType              someName;        // Knurre.
    SomeOtherType         someOtherName;   // Voff.
    AThirdType            aThirdName;      // That was a good catchy melody.
    Fifthum               huhWhatsThat;    // But you're too young to remember.
    NoHeresTheReal5th     ohYeah;          // Probably.

... is bad, because most any refactoring tool tool will destroy the nice line-up
when you change those type names, and that it's therefore much better &
preferred to have no line-up, like ...

There are refactoring tools and there are code beautifier tools and i
am almost sure that some code beautifying tools can revert the damage
done by some clumsy refactoring tool. I am not sure why you decided
that this nice line-up has to go because of tools.

    SomeType someName; // Knurre.
    SomeOtherType someOtherName; // Voff.
    AThirdType aThirdName; // That was a good catchy melody.
    Fifthum huhWhatsThat; // But you're too young to remember.
    NoHeresTheReal5th ohYeah; // Probably.

It seemed that everybody agreed.

Comments?

It is still true that some data i keep formating as table, but usually
these are not declarations.
With declarations I prefer:
/// Knurre.
SomeType someName;
/// Voff.
SomeOtherType someOtherName;
/// That was a good catchy melody.
AThirdType aThirdName;
/// But you're too young to remember.
Fifthum huhWhatsThat;
/// Probably.
NoHeresTheReal5th ohYeah;

I read narrow declaration row ~3 times quicker. Also most editors
syntax highlight and most monitors have enough vertical space, so i do
not see point to separate types, names and comments with tabulation,
they are separated by colors. Three '///' are to indicate to editor
that this "Knurre." is information that i want to see among instant
information about that particular "someName" when i meet it elsewhere.

 

[DeMarcus]

At the last meeting of Oslo C++ Users Group it was maintained (as I
understood it) that code like ...

SomeType someName; // Knurre.
SomeOtherType someOtherName; // Voff.
AThirdType aThirdName; // That was a good catchy melody.
Fifthum huhWhatsThat; // But you're too young to
remember.
NoHeresTheReal5th ohYeah; // Probably.

... is bad, because most any refactoring tool tool will destroy the nice
line-up when you change those type names, and that it's therefore much
better & preferred to have no line-up, like ...

SomeType someName; // Knurre.
SomeOtherType someOtherName; // Voff.
AThirdType aThirdName; // That was a good catchy melody.
Fifthum huhWhatsThat; // But you're too young to remember.
NoHeresTheReal5th ohYeah; // Probably.

It seemed that everybody agreed.

Comments?

I used to go for the first one, especially for functions in header
files, but I gave up since it was too difficult to be consistent. E.g.

class SomeClass
{
public:

void doSomething();
int doSomethingElse();
std::map<std::string, MySpecialClass> destroyIndentation();
};

It would be awkward to change to

class SomeClass
{
public:

void doSomething();
int doSomethingElse();
std::map<std::string, MySpecialClass> destroyIndentation();
};

Not to mention when all wicked arguments come into play. Basically, I've
given up, and now I'm just trying to make it nice looking at the spot
without using any stringent formatting convention.

 

[Öö Tiib]

I used to go for the first one, especially for functions in header
files, but I gave up since it was too difficult to be consistent. E.g.

class SomeClass
{
public:

    void   doSomething();
    int    doSomethingElse();
    std::map<std::string, MySpecialClass> destroyIndentation();

};

It would be awkward to change to

class SomeClass
{
public:

    void                                  doSomething();
    int                                   doSomethingElse();
    std::map<std::string, MySpecialClass> destroyIndentation();

};

Not to mention when all wicked arguments come into play. Basically, I've
given up, and now I'm just trying to make it nice looking at the spot
without using any stringent formatting convention.

This is anyway written usually so:

class SomeClass
{
public:
typedef std::map<std::string, MySpecialClass> SpecialAtName;
public:
void doSomething();
int doSomethingElse();
SpecialAtName destroyIndentation();

};

 

[DeMarcus]

This is anyway written usually so:

class SomeClass
{
public:
typedef std::map<std::string, MySpecialClass> SpecialAtName;
public:
void doSomething();
int doSomethingElse();
SpecialAtName destroyIndentation();

};

Hm, thanks for that tip!

It's interesting; the more I learn about C++, the more I realize I just
know a small portion.

 

[Victor Bazarov]

Most right-on URL I found quick googling:
http://en.wikipedia.org/wiki/Refactoring_Browser#Refactoring_Class_Browsers

It was a sarcastic rhetoric. I've not seen any "refactoring tools" used
extensively (or at all) in any of the shops I worked in. All the
refactoring is done manually, so the formatting is usually restored as
the refactoring is taking place...

Yes, I think Thunderbird started Really Messing Up quoting in version 3.x.

Not only that. They definitely got many other things wrong. Oh well...

I think something like TBQuoteFix is needed (like old OEQuoteFix for
Microsoft's Outlook Express).

Usenet is dying. The tools are dying with it.

V

 

[Victor Bazarov]

[..]

It's interesting; the more I learn about C++, the more I realize I just
know a small portion.

And the portion will continue to be small since C++ is expanding If
you keep learning at the same rate as C++ is expanding, that is <BG>

V

 

[James Kanze]

At the last meeting of Oslo C++ Users Group it was maintained
(as I understood it) that code like ...

SomeType someName; // Knurre.
SomeOtherType someOtherName; // Voff.
AThirdType aThirdName; // That was a good catchy melody.
Fifthum huhWhatsThat; // But you're too young to remember.
NoHeresTheReal5th ohYeah; // Probably.

... is bad, because most any refactoring tool tool will
destroy the nice line-up when you change those type names, and
that it's therefore much better & preferred to have no
line-up, like ...

I'm tempted to say "bullshit". I've been doing extensive
refactoring lately, with my preferred tool (vim), and just the
reverse is true; it creates such formatting when it wasn't there
to begin with. (Of course, I've extended it somewhat with my
own tools.)

In the end, to hell with the tools. The only question is: which
do you find easier to read and understand?

SomeType someName; // Knurre.
SomeOtherType someOtherName; // Voff.
AThirdType aThirdName; // That was a good catchy melody.
Fifthum huhWhatsThat; // But you're too young to remember.
NoHeresTheReal5th ohYeah; // Probably.

It seemed that everybody agreed.

There mustn't have been any experienced programmers there, then.

Comments?

Write the code so that it's easy to read. Even if it gets
screwed up by some tool later, you've at least had a period of
time where it was easy to read.

 

[James Kanze]

messagenews:[email protected]...

What nice line-up? I use a proportional font.

Masochist.

Regretfully, none of the tools I know handle proportional fonts
correctly without additional markup. And the C++ compiler
doesn't like additional markup. There's been some experiments
in this direction (the "literate programming" croud), but to
date, I've not seen anything which was really satisfactory for
handling real layout (as opposed to the classical ASCII
formatting based on fixed width fonts) in program sources.

 

[James Kanze]

There are refactoring tools and there are code beautifier
tools and i am almost sure that some code beautifying tools
can revert the damage done by some clumsy refactoring tool. I
am not sure why you decided that this nice line-up has to go
because of tools.

It is still true that some data i keep formating as table, but
usually these are not declarations.

I format most of my code. In different ways.

With declarations I prefer:
/// Knurre.
SomeType someName;
/// Voff.
SomeOtherType someOtherName;
/// That was a good catchy melody.
AThirdType aThirdName;
/// But you're too young to remember.
Fifthum huhWhatsThat;
/// Probably.
NoHeresTheReal5th ohYeah;

I read narrow declaration row ~3 times quicker.

How do you recognize what is being declared? (These are simple
examples. In practice, you often have more complicated type
specifications.) And how do you distinguish between a
definition and an expression statement.

Also most editors syntax highlight

To a point. In order to syntax highlight well, they have to
know which symbols define types, and which don't. Which is
impossible without reading and parsing all of the header files.
Some of which may not have been written yet.

and most monitors have enough vertical space, so i do not see
point to separate types, names and comments with tabulation,
they are separated by colors.

Comments, yes, but not types and other names. And I know of no
editor which will, for example, display a declaration in a
different color than an expression statement.

 

[Öö Tiib]

I format most of my code.  In different ways.

Yes me too, but usually not as a table when it is not a data.

How do you recognize what is being declared?  (These are simple
examples.  In practice, you often have more complicated type
specifications.)  And how do you distinguish between a
definition and an expression statement.

I first typedef too complex types. As for parsing it is hard but not
too hard? Lets say:

Moo * foo;

If Moo is type then it is declaration, if both are variables it is
expression using operator*, if Moo is unknown then it is a bug?

To a point.  In order to syntax highlight well, they have to
know which symbols define types, and which don't.  Which is
impossible without reading and parsing all of the header files.
Some of which may not have been written yet.

Yes ... hmm ... but what holds the code editors back? Preprocessors
are open source. Parsers are open source. Desktops have tremendous
processing power (can render 3D scenes real-time). Several third party
Visual Studio plugins can keep types and variables and macros slightly
differently colored. It simply underlines red the names that are
possibly from headers that are not written (or included) yet ...
almost as soon as i type them.

Comments, yes, but not types and other names.  And I know of no
editor which will, for example, display a declaration in a
different color than an expression statement.

Most IDEs do it with other languages like java. Ability to parse C++
well is somewhat more expensive (because without preprocessing it is
impossible to parse it correctly and even with preprocessing it is a
bit more complex than LALR(1) task) so editors need a special plugin.

One day you get fresh standard out and make it impossible to parse it
again for a while ... but then editors learn to use some from 500
cores of video cards and things become livable again.

 

[Alf P. Steinbach]

* James Kanze:

* Leigh Johnston:

Masochist.

Regretfully, none of the tools I know handle proportional fonts
correctly without additional markup. And the C++ compiler
doesn't like additional markup. There's been some experiments
in this direction (the "literate programming" croud), but to
date, I've not seen anything which was really satisfactory for
handling real layout (as opposed to the classical ASCII
formatting based on fixed width fonts) in program sources.

It's possible that Bjarne has a practical answer. Some, ten?, years ago he
switched to proportionally spaced font in all his examples. I don't know how he
does it, perhaps by magic: sadly, I forgot to ask when he brought up the idea (I
think that was in connection with the FAQ for [no.it.programmering.c++]).


Cheers,

- Alf

CC: Bjarne, perhaps he'll enlighten us?

 

[Alf P. Steinbach]

* James Kanze:

* Leigh Johnston:

Masochist.

Regretfully, none of the tools I know handle proportional fonts
correctly without additional markup. And the C++ compiler
doesn't like additional markup. There's been some experiments
in this direction (the "literate programming" croud), but to
date, I've not seen anything which was really satisfactory for
handling real layout (as opposed to the classical ASCII
formatting based on fixed width fonts) in program sources.

It's possible that Bjarne has a practical answer. Some, ten?, years ago
he switched to proportionally spaced font in all his examples. I don't
know how he does it, perhaps by magic: sadly, I forgot to ask when he
brought up the idea (I think that was in connection with the FAQ for
[no.it.programmering.c++]).

Mystery partially demystified, Bjarne replies:


<quote author="Bjarne">
Sorry, I don't have tools for programming that uses a proportional font. I wish
I had and that vendors supported it well. I think it is significantly more
readable that those 1950s style typewrite fonts.

What I did for TC++PL was simply to run my programs through a small program that
changed the font and fixed up the operators (which tend to be awful for nice
readable proportional fonts).
</quote>


Cheers,

- Alf

 

[Jorgen Grahn]

At the last meeting of Oslo C++ Users Group it was maintained (as I understood
it) that code like ...

SomeType someName; // Knurre.
SomeOtherType someOtherName; // Voff.
AThirdType aThirdName; // That was a good catchy melody.
Fifthum huhWhatsThat; // But you're too young to remember.
NoHeresTheReal5th ohYeah; // Probably.

... is bad, because most any refactoring tool tool will destroy the nice line-up
when you change those type names, and that it's therefore much better &
preferred to have no line-up, like ...

SomeType someName; // Knurre.
SomeOtherType someOtherName; // Voff.
AThirdType aThirdName; // That was a good catchy melody.
Fifthum huhWhatsThat; // But you're too young to remember.
NoHeresTheReal5th ohYeah; // Probably.

It seemed that everybody agreed.

Comments?

I agree with the fine people in Oslo, but I admit your second example
is hard to read. I'd group them using blank lines, use more lowercase,
and probably not need comments for most of them:

SomeType somename;
SomeType someothername;
AThirdType athirdname;

Fifthum huhwhatsthat; // But you're too young to remember.
NoHeresTheReal5th ohyeah;

Let the text editor apply color to that, and the readability problem
is IMHO gone.

/Jorgen

 

[Jorgen Grahn]

[..]

It's interesting; the more I learn about C++, the more I realize I just
know a small portion.

And the portion will continue to be small since C++ is expanding If
you keep learning at the same rate as C++ is expanding, that is <BG>

Isn't that an exaggeration? The last big change was in the 1990s, and
the TR1 and C++0x stuff doesn't seem to really change the way you
program (at least not unless you're heavily into template
meta-programming).

Compare that to the Microsoft universe, where you're told to use a
whole new set of tools, languages and APIs every few years. (Or at
least it seems like that to a Unix guy like me, who mostly uses APIs
dating back to the 1970s and 1980s).

/Jorgen

 

[Jorgen Grahn]

On 13.05.2010 03:30, * Alf P. Steinbach: ....

It's possible that Bjarne has a practical answer. Some, ten?, years ago
he switched to proportionally spaced font in all his examples. I don't
know how he does it, perhaps by magic: sadly, I forgot to ask when he
brought up the idea (I think that was in connection with the FAQ for
[no.it.programmering.c++]).

Mystery partially demystified, Bjarne replies:


<quote author="Bjarne">
Sorry, I don't have tools for programming that uses a proportional font. I wish
I had and that vendors supported it well. I think it is significantly more
readable that those 1950s style typewrite fonts.

What I did for TC++PL was simply to run my programs through a small program that
changed the font and fixed up the operators (which tend to be awful for nice
readable proportional fonts).
</quote>

The following small Perl program implements the TC++PL style (but
lacks support for comments and string constants so far, and outputs
troff source, which I suppose few people use.)

I wish this style was more common on the web. The fashionable thing
on Wikipedia etc seems to be to just throw lots of colors and
boldfacing at the code.

(For editing I stick to a good, fixed-width font.)

#!/usr/bin/perl -w
use strict;

# start and end macros
#
my ($startmac, $endmac) = ('.vS', '.vE');

# sym - used for all the code except
# txt - variables, keywords, strings; all alphanumerics except
# com - comment text
#
my ($sym, $txt, $com) = ('CR', 'BI', 'I');

my $ingrind = 0;

while(<>) {

if(/^\.vS\b/) {
print;
print ".nf\n";
print ".ft $sym\n";
$ingrind = 1;
next;
}

if(/^$endmac/) {
print ".ft\n"; # wrong...
print ".fi\n";
print;
$ingrind = 0;
next;
}

print and next unless $ingrind;

s/(\w+)/\\f[$txt]$1\\fP/g;
# s/\\/\\e/g;

print;
}

/Jorgen

 

[Jorgen Grahn]

I'm tempted to say "bullshit". I've been doing extensive
refactoring lately, with my preferred tool (vim), and just the

Yes; Alf mentioned refactoring tools, but it's enough to talk about
programmers with text editors.

reverse is true; it creates such formatting when it wasn't there
to begin with. (Of course, I've extended it somewhat with my
own tools.)

Tools are a constant dilemma. I find myself doing fancy things which
my editor (Emacs) supports, and disliking things it *doesn't* support.
So I line up function arguments

draw_rectangle(100, N,
width, height,
blue);

while the vim users typically don't, and I use filled paragraphs and
bullet lists in my longer comment blocks.

But as far as I know, Emacs doesn't support the table above ... so
I don't to that.

In the end, to hell with the tools. The only question is: which
do you find easier to read and understand?

No, there is one more question. Ease of reading isn't enough; it also
has to be easy to modify.

More than once I have wanted to add a 'const' or two in such a nicely
tabular list ... but decided not to, because I would have to reformat
the whole table, and maybe split it into two tables: one narrow and
one wide.

You could argue that I should use a better editor, but I have
coworkers using everything from Eclipse, Emacs and vim to that ancient
OpenLook text editor ...

Write the code so that it's easy to read. Even if it gets
screwed up by some tool later, you've at least had a period of
time where it was easy to read.

I think anyone who uses such a tool on the code is also responsible
for cleaning up afterwards. You can not get away with writing
unreadable code by saying "it wasn't me, it was my tool".

/Jorgen

 

[James Kanze]

* James Kanze:

* Leigh Johnston:
* Alf P. Steinbach:
At the last meeting of Oslo C++ Users Group it was
maintained (as I understood it) that code like ...
SomeType someName; // Knurre.
SomeOtherType someOtherName; // Voff.
AThirdType aThirdName; // That was a good catchy melody.
Fifthum huhWhatsThat; // But you're too young to remember.
NoHeresTheReal5th ohYeah; // Probably.
... is bad, because most any refactoring tool tool will
destroy the nice line-up when you change those type names,
and that it's therefore much better& preferred to have no
line-up, like ...
What nice line-up? I use a proportional font.
Masochist.
Regretfully, none of the tools I know handle proportional fonts
correctly without additional markup. And the C++ compiler
doesn't like additional markup. There's been some experiments
in this direction (the "literate programming" croud), but to
date, I've not seen anything which was really satisfactory for
handling real layout (as opposed to the classical ASCII
formatting based on fixed width fonts) in program sources.

It's possible that Bjarne has a practical answer. Some, ten?, years ago
he switched to proportionally spaced font in all his examples. I don't
know how he does it, perhaps by magic: sadly, I forgot to ask when he
brought up the idea (I think that was in connection with the FAQ for
[no.it.programmering.c++]).

Mystery partially demystified, Bjarne replies:

<quote author="Bjarne">
Sorry, I don't have tools for programming that uses
a proportional font. I wish I had and that vendors supported
it well. I think it is significantly more readable that those
1950s style typewrite fonts.

What I did for TC++PL was simply to run my programs through
a small program that changed the font and fixed up the
operators (which tend to be awful for nice readable
proportional fonts).
</quote>

I was about to suggest that he might do something of that sort.
Preparing code for a book is somewhat different from developing
it in an editor. This was always my sticking point with
Knuth's literate programming as well. The output in printed
form is beautiful, but the code you have to edit during
development is buried down in loads of TeX markup. Which is
a shame, because the basic premise (that the code is first for
human readers) is the right one.

(WRT the choice of fonts---there are some pretty bad ones out
there for code, and the code examples in Barton and Nackman,
while not fixed width, were really bad. On the other hand,
I use Lucida typewriter in my editor, and even though it's fixed
width, it's not that bad. IMHO, of course---this is something
that is really a question of personal preferences.)

 

[James Kanze]

On 13 mai, 01:17, James Kanze <[email protected]> wrote:

[...]

I first typedef too complex types. As for parsing it is hard
but not too hard? Lets say:

Moo * foo;

If Moo is type then it is declaration, if both are variables
it is expression using operator*, if Moo is unknown then it is
a bug?

Practically, you may be right. My personal coding convention
has types starting with upper case, and other symbols with
lower. A line which begins with an upper case letter is
a declaration, one which begins with a lower case letter is an
expression. Except, of course, if it begins with a keyword like
static, but the editor should highlight those differently.

There's still the problem of finding exactly what is being
declared in a complex declaration: I'd write something like:
Toto (* func)(...);
for a pointer to a function, for example. But in practice, such
declarations are rare. Not only because of typedef's.

Yes ... hmm ... but what holds the code editors back?
Preprocessors are open source. Parsers are open source.
Desktops have tremendous processing power (can render 3D
scenes real-time).

None of which helps if you haven't written the header yet.
Parsing incomplete code is a couple of orders of magnitude more
difficult than parsing complete code. Still, as you say, the
power is there today.