Regarding coding style

[Steven D'Aprano]

If you're taking the time to write good comments, why not just fix the
bad names? The compiler/interpreter can never, ever catch bad comments.

Yes, but the Python compiler can only catch bad names if you do this at
the top of every module:

import semantic_analysis
import magic.crystal_ball.read_programmers_mind

Unfortunately, this comes with a *serious* performance hit, so most
people don't bother. Instead, they rely on the programmer to write good
descriptive names AND good comments, because not everything can be
documented in a name.

 

[K Viltersten]

If you can't/don't look at the source file,

The problem is that tools like Doxygen and
JavaDocs generate warnings and errors and
things if everything isn't documented
"completely". So you end up with a lot of
silly boilerplate.
/**
* Get the width of a box
*
* @param box the box
* @returns its width
*/
extern int box_get_width(box box);

Oh, yes. This is stupid. I agree with you.
If one's supposed to comment, let him
comment RIGHT. Otherwise, let it be.
Usually, when i comment my code, it's a
blessing. If not, i don't comment at all.

You are right that is it often useful to
document what to pass to a method and
what to expect back and that if this is
done well in many cases it isn't
necessary to see the implementation.
But in many other cases it's obvious, and
in other cases it's obvious if you just
look at the source which you've got.

I agree. Sometimes, there's a demand from
the customer to comment all methods. Then,
and then only, i'll go commenting all. But
i believe strongly that we think alike on
this one. When it's suitable, it should be
there. Otherwise - why bother. Right?

The lack of fascism is the big innovation.
It sounds simple but it makes a huge
difference: it's much easier to find (and
keep up to date) the real documentation if
it's not hidden in a forest of bogus
documentation.

I couldn't agree with you more on this one!
Thank you for an interesting discussion.

 

[Micah Cowan]

Right, that's a problem with the code. A comment only masks the bad
smell. 'x' should be renamed to something meaningful, obviating the
need for comments to follow it around.



I use single letter variables where their scope is very small. e.g.,
tight loops, small functions, etc. I even use them as class members
where they make sense in the domain. x, y, z for 3d vectors, r, g, b,
a for colors, etc.

This was a two-line code sample. Since you've indicated you use such
names where their scope is small, it's rather hard to say, without
more information, whether using "x" for this code generats a "smell"
or not. For that small amount of code, I'd say it doesn't.

I find that long names in short code segments actually detract from
readability. In the very first section of their book "The Practice of
Programming", Kernighan and Pike recommend using "descriptive names
for globals, short names for locals," saying "within a function, <n>
may be sufficient, <npoints> is fine, and <numberOfPoints> is
overkill."

As you point out, even for non-super-small scopes, such as class
members, it can make more sense to use single-letter names; I'd
consider red, green, blue and alpha to be unnecessary names, and it's
hard to improve on the x, y and z you gave as an example.

 

[Dan Bishop]

<rant>
What I really can't stand are the pointy-haired comment blocks
at the beginnings of C/C++ functions that do things like tell
you the name and return type of the function and list the names
and types of the parameters. Gee, thanks. I never could have
figured that out from looking at the source code itself. IMO,
comments explaining what the parameters are used for usually
indicates that the parameter names were poorly chosen.

You must work for the same company I do. I've seen a whole bunch of
comments that look like:

//---------------------------------------------------------------------------
// CXyzBase::LogMessage
//
// Write a message to the log.
//
// Args:
// strMsg = the message to log
//
void CXyzBase::LogMessage(const CString& strMsg)
{
//
}

And even worse, at the top of that file:

//---------------------------------------------------------------------------
// XyzBase.cpp
//
// This file contains the implementation of class CXyzBase.
//
// Copyright (C) 2008 Foobar Computer Consulting
//
// VERSION PROJECT# DATE DESCRIPTION
// ------- -------- -------- ------------------
// 1.00 123456 01/04/08 Original creation.
//

Eleven lines, of which the only useful information to me was the
project number, as knowing this let me look up who was behind these
comments.

 

[dave_mikesell]

/** Projects an object from 3D to 2D using
the method of Alexander The Great.
\param 3D structure to be projected
\returns 2D projection
*/
public Proj2D get2Dfrom3D(Proj3D param);

The above is, to me, very clear and
consistent. Not to mention, easily
handled with e.g. Doxygen to create a
readable documentation.

I don't see how this is dislikeable. Please
explain.

When get2Dfrom3D changes its signature but the comment is not
changed. That's where I have a problem, and it's only a matter of
time before it happens.

 

[K Viltersten]

/** Projects an object from 3D to 2D using

When get2Dfrom3D changes its signature but
the comment is not changed. That's where I
have a problem, and it's only a matter of
time before it happens.

I think we've arrived at the spot where i'll
claim that a _always_ update my comments,
and you'll question that i can (in the long
run). Let's agree on that!

 

[sjdevnull]

I'm also a bit baffled by people who put a comment at the top of every
file that tells you what the filename is.

[snip rant]

You've never printed out a source file on pieces of dead tree to read on
the train on the way home, or in bed or the bath?

Yes, some editors will print a header or footer showing the file name,
but not all will, or are configured to do so.

The only times I can recall printing source were in college classes
where I was required to hand in a hardcopy with the assignment and
code samples for job interviews. In the real world the code base
tends to be too huge to contemplate printing, especially when I'd then
be stuck without sane ways to navigate around (tags, search, oobr,
etc). For instance, our project right now is around 350,000 lines of
python and about 300,000 of DTML/mako templates. I expect the
availability of laptops since I really started working as a programmer
in the mid-1990s biases me a bit compared to earlier times.

Even in the early 1990s the moral equivalent of enscript (I think it
was a2ps) worked just fine for printing with filenames, line/page
numbers, and other niceties no matter what editor you used. It seems
more reasonable to mandate using a sane print tool for the odd case
where someone wants to print things out than to mandate cluttering up
every file with the filename in a comment.

 

[Steven D'Aprano]

I'm also a bit baffled by people who put a comment at the top of
every file that tells you what the filename is.

[snip rant]

You've never printed out a source file on pieces of dead tree to read
on the train on the way home, or in bed or the bath?

Yes, some editors will print a header or footer showing the file name,
but not all will, or are configured to do so.

The only times I can recall printing source were in college classes
where I was required to hand in a hardcopy with the assignment and code
samples for job interviews. In the real world the code base tends to be
too huge to contemplate printing...

You've never (say) printed out the source code to one of the modules in
the Python standard library to read and study?

If your code base is so huge that you can't print out any meaningful
piece, then you desperately need more encapsulation.

Even in the early 1990s the moral equivalent of enscript (I think it was
a2ps) worked just fine for printing with filenames, line/page numbers,
and other niceties no matter what editor you used. It seems more
reasonable to mandate using a sane print tool for the odd case where
someone wants to print things out than to mandate cluttering up every
file with the filename in a comment.

Sure, but really, adding ONE LINE to the start of a file is hardly
"cluttering up" anything. Especially if it is in the doc string, like
this:

"""widgets.py: create, manage and destroy widgets.

blah blah blah blah..."""

 

[Grant Edwards]

I strongly disagree. Now, perhaps we're
talking about different things, here?
Usually, in the header file (C++),

Header files are source code.

there won't be any source code, except for method
declarations.

Declarations are source code.

A common example:

/** Projects an object from 3D to 2D using
the method of Alexander The Great.
\param 3D structure to be projected
\returns 2D projection
*/
public Proj2D get2Dfrom3D(Proj3D param);

That's source code.

The above is, to me, very clear and
consistent. Not to mention, easily
handled with e.g. Doxygen to create a
readable documentation.

I've no problem with that.

I don't see how this is dislikeable. Please
explain. Perhaps the above IS what you
ment by "docstrings"?
http://en.wikipedia.org/wiki/Docstring
http://epydoc.sourceforge.net/docstrings.html

For Java, one has the JavaDocs, a great tool, provided one
will comment each method and variable used.


The below, more or less.


Please note that i DO NOT argue against one
way or another. I simply expressed surprise
since i've been tought otherwise earlier
and, maybe, there's a larger picture than
what i've seen this far. As stated before,
snakeology is a very new area to me. Yet.

Duplicating information in a comment that is plainly obvious 5
lines below it in the actual source code is a waste of time
when the code is written. A week later, the comment will be
out of sync with the code and anybody paying attention to the
comment will be mislead. I exaggerate (slightly), but in my
experience anytime information is duplicated in multiple places
it doesn't take very long at all before it's out-of-sync and
incorrect in all places except one.

 

[Grant Edwards]

I think we've arrived at the spot where i'll
claim that a _always_ update my comments,

Perhaps you do. AFAICT, nobody else does.

 

[Grant Edwards]

I'm also a bit baffled by people who put a comment at the top of every
file that tells you what the filename is.

[snip rant]

You've never printed out a source file on pieces of dead tree
to read on the train on the way home, or in bed or the bath?

Not in the last 20 years or so.

Yes, some editors will print a header or footer showing the
file name, but not all will, or are configured to do so.

If I want the filename printed at the top of the first page (or
at the top of every page) I'll use a tool that does that.

 

[Grant Edwards]

Even in the early 1990s the moral equivalent of enscript (I think it
was a2ps)

I still use a2ps occasionally, but rarely for printing out
source code. I occasionally print out hex dumps that I need to
markup to figure out what's going on.

worked just fine for printing with filenames, line/page
numbers,

It still does.

and other niceties no matter what editor you used. It seems
more reasonable to mandate using a sane print tool for the odd
case where someone wants to print things out than to mandate
cluttering up every file with the filename in a comment.

And guess what? After a while, files get renamed and nobody
remembers to change the comments.

If people really want a filename in the top of the file, they
should at least use something like a CVS or SVN variable so
that it's generated automagically and can't be wrong.

 

[Grant Edwards]

You've never (say) printed out the source code to one of the
modules in the Python standard library to read and study?

Nope. Can't say that I have. I can't really recall printing
out a source file in the past 10-15 years.

If your code base is so huge that you can't print out any
meaningful piece, then you desperately need more
encapsulation.

Sure, but really, adding ONE LINE to the start of a file is
hardly "cluttering up" anything. Especially if it is in the
doc string, like this:

"""widgets.py: create, manage and destroy widgets.

blah blah blah blah..."""

The bad part is that it's redundant information. That means
that eventually, it's going to be wrong.

 

[Grant Edwards]

I think even Grant would agree that when you call "help(make_widget)",
you should see something like:

make_widget(styleID, material) -> widget or
raise ValueError on failure

styleID: numeric ID or string name of the widget style
material: WidgetMaterial instance or None to use default

I think docstrings are a great idea. What's needed is a way to
document the signature that can't get out-of-sync with what the
fucntion really expects.

 

[Grant Edwards]

You must work for the same company I do. I've seen a whole bunch of
comments that look like:

//---------------------------------------------------------------------------
// CXyzBase::LogMessage
//
// Write a message to the log.
//
// Args:
// strMsg = the message to log
//
void CXyzBase::LogMessage(const CString& strMsg)
{
//
}

And even worse, at the top of that file:

//---------------------------------------------------------------------------
// XyzBase.cpp
//
// This file contains the implementation of class CXyzBase.
//
// Copyright (C) 2008 Foobar Computer Consulting
//
// VERSION PROJECT# DATE DESCRIPTION
// ------- -------- -------- ------------------
// 1.00 123456 01/04/08 Original creation.
//

Eleven lines, of which the only useful information to me was the
project number, as knowing this let me look up who was behind these
comments.

I'm currently consulting part-time for a company that's very
fond of that sort of thing. And it's it's not like they're
working on some DoD contract that explicitly requires such
time-wastage -- it's something they torture themselves with of
their own volition.

[I honestly didn't expect my rant to spark such a long thread.]

 

[Steven D'Aprano]

The bad part is that it's redundant information. That means that
eventually, it's going to be wrong.

I withdraw my defense of including the file name.

After looking at both the Python standard library and my own scripts/
modules, I can see that it is a lot rarer than I thought it was, and even
when I do it, it is almost always in help strings for quick and dirty
scripts.

 

[Ryan Ginstrom]

On Behalf Of Grant Edwards

I think docstrings are a great idea. What's needed is a way
to document the signature that can't get out-of-sync with
what the fucntion really expects.

Like doctests? (I know, smart-ass response)

Regards,
Ryan Ginstrom

 

[sjdevnull]

On Sat, 08 Mar 2008 19:31:47 +0000, Grant Edwards wrote:
I'm also a bit baffled by people who put a comment at the top of
every file that tells you what the filename is.
[snip rant]
You've never printed out a source file on pieces of dead tree to read
on the train on the way home, or in bed or the bath?
Yes, some editors will print a header or footer showing the file name,
but not all will, or are configured to do so.

The only times I can recall printing source were in college classes
where I was required to hand in a hardcopy with the assignment and code
samples for job interviews. In the real world the code base tends to be
too huge to contemplate printing...

You've never (say) printed out the source code to one of the modules in
the Python standard library to read and study?

Nope. It's a lot easier to read on the computer, with searching,
proper syntax highlighting, tags, etc and access to all the other
information I might want while reading the code, and the ability to
drift to other modules that might be imported/mentioned, find examples
using them, etc.

If your code base is so huge that you can't print out any meaningful
piece, then you desperately need more encapsulation.

Yeah, most of the code is encapsulated into smaller parts. The
problem is figuring out what meaningful piece(s) I might want. How
often do you really find yourself knowing ahead of time exactly what
you want to read? Even in code reviews it's common to look at other
files in the system, version control history, the issue/spec tracker,
or even wander off into Python documentation, algorithm papers, or
whatever. It just doesn't seem worth playing a guessing game about
exactly what code/versioning/docs/etc I might want to have on hand
when the net result even if I guess right will be a worse reading
experience without searching, tags, bookmarks, etc.

Sure, but really, adding ONE LINE to the start of a file is hardly
"cluttering up" anything.

It's not terrible, no, just vaguely pointless and a bit fragile in the
face of change.

 

[Lie]

To Lie:


Personally I don't.  Show me a good one.  Until you do, it's not that
I won't like it, it's that I can't.  You know, in linguistics, there's
what's called 'code switching', which is switching between two
languages you know midstream.  People can understand 'hear' a language
but not speak it.  If you speak it, <leaves open>.  If comments aren't
the 'short version', then patience is the problem.  There's not one
word for lots and lots of things.  Examples on backorder.

But I much prefer it that the code has good names AND concise
comments, not too short and not too long that it becomes obscure. If
the code is complex, that it's hard to explain in a few sentences, it
might be a good idea to refactor it.

If I have to choose between bad names + twenty pages of documentation
and good names + a paragraph of short documentation, I chose the
latter.

 

[castironpi]

Yes, but the Python compiler can only catch bad names if you do this at
the top of every module:

import semantic_analysis
import magic.crystal_ball.read_programmers_mind

dir( magic )!
dir( magic.crystal_ball )?