Regarding coding style

[dave_mikesell]

I've been recommended reading of:http://www.python.org/dev/peps/pep-0008/
and in there i saw two things that i
need to get elaborated.

1. When writing English, Strunk and
White apply.

If your code needs so much descriptive prose that you have to consult
Strunk and White, refactor it to be more clear. Excessive comments
are the hobgoblin of overly complex and/or sloppy code.

 

[Steven D'Aprano]

If your code needs so much descriptive prose that you have to consult
Strunk and White, refactor it to be more clear. Excessive comments are
the hobgoblin of overly complex and/or sloppy code.

Nonsense. Poor English is poor English whether you're writing short one-
line comments or three hundred page manuals.

store = make_store()
x = get_stuff(store) # Get the stuff what was brought at the store.

Not that I would consider S & W the best source for good grammar or style.

 

[dave_mikesell]

Nonsense. Poor English is poor English whether you're writing short one-
line comments or three hundred page manuals.

store = make_store()
x = get_stuff(store) # Get the stuff what was brought at the store.

Perfect example of an unnecessary comment. The variable and function
names are commentary enough.

 

[Dennis Lee Bieber]

Not in most books I've read. AFAICT, it's a (thankfully) disappearing
practice in the typesetting profession.

Unfortunately, my experience has been that proofreading is also a
disappearing practice. *

As for the double-space sentence end -- I suspect much modern
typesetting is being done with computers that don't know where sentence
ends OR the authors explicitly enter an n-space or m-space marker rather
than a plain space.




* Roger Zelazny's Amber series has been through many reprints, and even
had all 10 novels collected into one large paperback... ALL except the
original hardcover printing are missing a rather crucial sentence in the
first page of either the 4th or 5th book. Apparently no one at the
publisher has ever compared the text to the original book.
--
Wulfraed Dennis Lee Bieber KD6MOG
(e-mail address removed) (e-mail address removed)
HTTP://wlfraed.home.netcom.com/
(Bestiaria Support Staff: (e-mail address removed))
HTTP://www.bestiaria.com/

 

[Steven D'Aprano]

Perfect example of an unnecessary comment. The variable and function
names are commentary enough.

"x" is a terrible name. What does it mean? Nothing. There's only three
places x is an appropriate name:

(1) A meta-syntactic variable like foo, bar, spam, ham, parrot.

(2) Library functions, where x stands for a generic argument, usually a
number, e.g. def sin(x).

(3) Throw-away code you don't need to maintain.

The function name also doesn't explain anything. How was the stuff got?
Was it paid for, or stolen, or picked up on consignment, or what? Compare
the above line with:

x = get_stuff(store) # Steal stuff from the store.

or

x = get_stuff(store) # Pickup the stuff from the store for disposal.
# The amount paid by the store is stored in global variable "pay_received"
# and the name of the employee authorizing the pickup is stored in the
# global "authorized_by".


But even if you were right that the comment was unnecessary, you have
missed my point that even single sentences can be grammatically bogus and
the writer could learn a lot from Strunk and White or equivalent.

(Often the writer will learn bad habits, but at least they'll be
grammatically correct bad habits.)

 

[dave_mikesell]

"x" is a terrible name. What does it mean? Nothing.

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.

There's only three places x is an appropriate name:

(1) A meta-syntactic variable like foo, bar, spam, ham, parrot.

(2) Library functions, where x stands for a generic argument, usually a
number, e.g. def sin(x).

(3) Throw-away code you don't need to maintain.

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.

The function name also doesn't explain anything. How was the stuff got?
Was it paid for, or stolen, or picked up on consignment, or what? Compare
the above line with:

x = get_stuff(store) # Steal stuff from the store.

or

x = get_stuff(store) # Pickup the stuff from the store for disposal.
# The amount paid by the store is stored in global variable "pay_received"
# and the name of the employee authorizing the pickup is stored in the
# global "authorized_by".

Shouldn't get_stuff's comment be with its definition? And just
rename the function to something more meaningful, like
purchase_goods(store), or whatever.

But even if you were right that the comment was unnecessary, you have
missed my point that even single sentences can be grammatically bogus and
the writer could learn a lot from Strunk and White or equivalent.

I do agree with that 100%. It's a chore reading design and
requirements docs where I work.

My problem is with excessive comments. Comments are pathological
liars. They almost invariably fall out of date with the code.

 

[Grant Edwards]

Shouldn't get_stuff's comment be with its definition?

Probably, but better that comment shouldn't be anywhere.

get_stuff() should be

1) renamed, as you state below.

2) written such that it's obvious from reading the source code
that the amount paid is stored in the global variable
pay_received and that the name of the employee authorizing
the pickup is stored in the global authorized by.

But, it's not really fare picking on an example like that...

And just rename the function to something more meaningful,
like purchase_goods(store), or whatever.

That's true. I don't know how many times I've seen a single
sentence comment that was just plain vague and ambiguous. And
most of the time they're just plain wrong as well because the
code had been changed but nobody changed the comment (possibly
because they couldn't understand what the comment was trying to
say).

 

[castironpi]

Probably, but better that comment shouldn't be anywhere.

get_stuff() should be

 1) renamed, as you state below.

 2) written such that it's obvious from reading the source code
    that the amount paid is stored in the global variable
    pay_received and that the name of the employee authorizing
    the pickup is stored in the global authorized by.

But, it's not really fare picking on an example like that...


That's true.  I don't know how many times I've seen a single
sentence comment that was just plain vague and ambiguous. And
most of the time they're just plain wrong as well because the
code had been changed but nobody changed the comment (possibly
because they couldn't understand what the comment was trying to
say).

There are bad comments and bad variable names.

fcrg= dothingthatgoesplace( qkjwvm ). # that thing I talked about
# in last Tuesday's code for searching qkjwvm and returning its
attribute.

Does one side of this hold that there are no -good- comments?

 

[Lie]

Personally I preferred a code that has chosen good names but have
little or no comments compared to codes that makes bad names and have
twenty pages of comments to read and understand what it's about.
Personally, I think comments should be made as short and as concise as
possible and codes should try to be self-understandable if the
comments aren't accessible.

 

[Grant Edwards]

Does one side of this hold that there are no -good- comments?

I wouldn't say there are _no_ good comments, but I would say
that 90+% of the comments I've seen in my lifetime were bad.
Most of them were bad to the extent that anybody new to the
code would be best served by deleting them before trying to
understand what was going on.

I do think that a comment at the beginning of a function/module
that describes its general purpose can be a good thing. A
comment explaining a particularly opaque algorithm can be
useful as well.

<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.

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. I sometimes
wonder how/where these files were created. All of the OSes I've
ever used had a feature called a "filesystem" which kept track
of info like the names of files. It must be a bitch-and-a-half
to work on an computer that doesn't keep track of filenames and
makes the user do it.

When was the last time you thought to yourself: "Gee, I wonder
what's the the name of that file over there? I guess I'd better
open the file and look at the comment at the top to see what
the filename is?
</rant>

 

[castironpi]

I wouldn't say there are _no_ good comments, but I would say
that 90+% of the comments I've seen in my lifetime were bad.

comment explaining a particularly opaque algorithm can be
useful as well.

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,

Sometimes void*s are guaranteed to be HTHREADs.

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.  I sometimes
wonder how/where these files were created. All of the OSes I've
ever used had a feature called a "filesystem" which kept track
of info like the names of files.  It must be a bitch-and-a-half
to work on an computer that doesn't keep track of filenames and
makes the user do it.

When was the last time you thought to yourself: "Gee, I wonder
what's the the name of that file over there? I guess I'd better
open the file and look at the comment at the top to see what
the filename is?

What file did you open?

To Lie:

Personally I preferred a code that has chosen good names but have
little or no comments compared to codes that makes bad names and have

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.

Good comments are better than bad names.
Good names are better than bad comments.

And enter multi-word identifiers. <wink>

 

[K Viltersten]

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.

Coming from C++/Java camp i can't help
noticing that in most cases, when i'm
using a class written by somebody else,
i don't want to see his/her code. I only
want to know WHAT the function does (is
intended to be doing, at least).

I don't want to look at the source code
(in some cases i can't even see the code
because it's compiled). I only care that
when i execute

SomeType obj = SomeType();
obj.aggregate();

the object gets aggregated. How it's done
will be up to the author. I'm just a user
of the product.

Now, i'm getting the signal that it's
done in a different way in Python. Please
elaborate. I'm very new to snakeology.

 

[castironpi]

I wouldn't say there are _no_ good comments, but I would say
that 90+% of the comments I've seen in my lifetime were bad.

comment explaining a particularly opaque algorithm can be
useful as well.

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,

Sometimes void*s are guaranteed to be HTHREADs.

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.  I sometimes
wonder how/where these files were created. All of the OSes I've
ever used had a feature called a "filesystem" which kept track
of info like the names of files.  It must be a bitch-and-a-half
to work on an computer that doesn't keep track of filenames and
makes the user do it.

When was the last time you thought to yourself: "Gee, I wonder
what's the the name of that file over there? I guess I'd better
open the file and look at the comment at the top to see what
the filename is?

What file did you open?

To Lie:

Personally I preferred a code that has chosen good names but have
little or no comments compared to codes that makes bad names and have

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.

Good comments are better than bad names.
Good names are better than bad comments.

And enter multi-word identifiers. <wink>

 

[dave_mikesell]

<hilarious rant snipped>

LOL. Thanks for the laughs. I share your frustration.

 

[dave_mikesell]

Good comments are better than bad names.
Good names are better than bad comments.

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.

 

[Grant Edwards]

Coming from C++/Java camp i can't help noticing that in most
cases, when i'm using a class written by somebody else, i
don't want to see his/her code. I only want to know WHAT the
function does (is intended to be doing, at least).

If you can't/don't look at the source file, then comments
aren't going to help (except in the case of something like
docstrings in Python).

I don't want to look at the source code (in some cases i can't
even see the code because it's compiled). I only care that
when i execute

SomeType obj = SomeType();
obj.aggregate();

the object gets aggregated. How it's done will be up to the
author. I'm just a user of the product.

If you don't look at the source file, then I guess the question
of whether comments are good, bad, or indifferent is irrelevent
to you.

Now, i'm getting the signal that it's done in a different way
in Python.

I'm not sure how you concluded that from this thread.

I very rarely look at the source files for the standard
library. I usually just look at the library reference document.
The only times I look at the source code are the rare occasion
that the function doesn't seem to be working correctly or when
I can't understand what the reference docs are saying. The
cases where I suspect the former generally turn out to be the
latter.

Comments in source code are for people maintaining the code,
not for people using a standard library API (again, except for
docstrings).

 

[K Viltersten]

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

then comments aren't going to help (except
in the case of something like docstrings in
Python).

I strongly disagree. Now, perhaps we're
talking about different things, here?
Usually, in the header file (C++), there
won't be any source code, except for
method declarations. 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);

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. Perhaps the above IS what you
ment by "docstrings"? For Java, one has the
JavaDocs, a great tool, provided one will
comment each method and variable used.

in a different way in Python.

I'm not sure how you concluded that from this thread.

The below, more or less.

"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."

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.

 

[Ben C]

I strongly disagree. Now, perhaps we're
talking about different things, here?
Usually, in the header file (C++), there
won't be any source code, except for
method declarations. 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);

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. Perhaps the above IS what you
ment by "docstrings"? For Java, one has the
JavaDocs, a great tool, provided one will
comment each method and variable used.

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.

I see this kind of nonsense a lot:

/**
* Get the width of a box
*
* @param box the box
* @returns its width
*/
extern int box_get_width(box box);

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.

What's needed is just a bit of common sense and pragmatism: APIs need
more documentation if the source of the implementation isn't being
released with them, and some APIs just need more documentation than
others anyway.

Python docstrings, like most things in Python, demonstrate this kind of
common sense: you write what you want in them and as far as I can tell
nothing complains if you don't write them at all.

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.

 

[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.

 

[Steven D'Aprano]

Coming from C++/Java camp i can't help noticing that in most cases, when
i'm using a class written by somebody else, i don't want to see his/her
code. I only want to know WHAT the function does (is intended to be
doing, at least).

I don't want to look at the source code (in some cases i can't even see
the code because it's compiled). I only care that when i execute

SomeType obj = SomeType();
obj.aggregate();

the object gets aggregated. How it's done will be up to the author. I'm
just a user of the product.

Now, i'm getting the signal that it's done in a different way in Python.
Please elaborate. I'm very new to snakeology.

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


rather than:

See source code for details.



*wink*