Re: Commenting style?
Francis Glassborow wrote:
In article <45b72d23$0$49207$14726298@news.sunsite.dk>, Angel Tsankov
<fn42551@fmi.uni-sofia.bg> writes
And what about:
int z; // Comment.
int y; // Another comment.
std::vector<double> x_intersections; // Yet another comment.
IMHO, madness. Allowing the longest typename control the position of the
names being declared (and do you propose to do the same for function
declarations? Or perhaps we should make sure all the assignment
operators are vertically aligned? :-)
The rules for code layout should be about readability. People will
disagree about the details. In ordinary text I have been taught to try
to avoid vertical alignment, particularly where the words are similar as
that inhibits easy reading by trapping the eye into skipping lines.
But code isn't ordinary text, and there are many cases where
using two dimensions can add to understandability. The most
obvious is initialization lists; given something like:
struct MapInit
{
char const* key ;
int value ;
} ;
MapInit const initTable[] =
{
{ "one" , 1 },
{ "two" , 2 },
{ "three", 3 },
} ;
I cant' imagine not aligning. It's very much like a table in a
book or article (which would also be aligned). Because in C and
C++, declarations and expression statements are so
indistinguishable, I've also adopted the policy of using a
special formatting for declarations: what is being declared is
always indented 20 spaces. It's arbitrary, but it does mean
that a declaration doesn't look like just another expression,
and draws attention to what is being declared. Other than that,
I do use a lot of vertical alignment, when I want to draw
attention to parallels in the code: if I'm assigning a sequence
of values, for example, I'll align the = signs, so that the
reader will immediately see the code for what it is: a sequence
of the same operations. Code is, on the whole, a lot less
verbose than normal text, and anything I can do to add semantic
content for the reader, I do.
--
James Kanze (GABI Software) email:james.kanze@gmail.com
Conseils en informatique orient?e objet/
Beratung in objektorientierter Datenverarbeitung
9 place S?mard, 78210 St.-Cyr-l'?cole, France, +33 (0)1 30 23 00 34
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.moderated. First time posters: Do this! ]