Regarding coding style
K Viltersten
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.
Where can i download it? Am i actually
expected to read the whole book? How
many people actually do aply it?
2. You should use two spaces after a
sentence-ending period.
For heavens sake, why? I've always been
obstructed by the double blanks but
tolerated them. Now, that i read that
it actually is a recommendation, i need
to ask about the purpose.
Thanks for the input in advance.
--
Regards
Konrad Viltersten
--------------------------------
sleep - a substitute for coffee for the poor
ambition - lack of sense to be lazy
Simon Brunning
>
> 1. When writing English, Strunk and
> White apply.
I apply Fowler, PEP 8 be damned. ;-)
--
Cheers,
Simon B.
si...@brunningonline.net
http://www.brunningonline.net/simon/blog/
Richard Brodie
"K Viltersten" <tm...@viltersten.com> wrote in message
news:63d80bF...@mid.individual.net...
> 1. When writing English, Strunk and White apply.
Do they? I've never seen them ;)
> 2. You should use two spaces after a sentence-ending period.
>
> For heavens sake, why?
Most people find it easier to type two spaces than one and a half.
D'Arcy J.M. Cain
"K Viltersten" <tm...@viltersten.com> wrote:
> 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.
>
> Where can i download it? Am i actually
> expected to read the whole book? How
> many people actually do aply it?
"The Elements of Style" by William Strunk Jr. and E.B. White. The
original, revised edition was published in 1935. The third edition is
copyright 1979 and published by MacMillan Publishing Co., Inc., NY,
NY. There may be a later version with an ISBN but this one doesn't
have one.
It's a very small book, 4-1/2" by 7", 81 pages. If you are writing
English it is worth browsing from time to time.
> 2. You should use two spaces after a
> sentence-ending period.
>
> For heavens sake, why? I've always been
> obstructed by the double blanks but
> tolerated them. Now, that i read that
> it actually is a recommendation, i need
> to ask about the purpose.
Like many things of this nature, the purpose is to follow the rules of
correct English usage.
--
D'Arcy J.M. Cain <da...@druid.net> | Democracy is three wolves
http://www.druid.net/darcy/ | and a sheep voting on
+1 416 425 1212 (DoD#0082) (eNTP) | what's for dinner.
D'Arcy J.M. Cain
"Simon Brunning" <si...@brunningonline.net> wrote:
> On Fri, Mar 7, 2008 at 4:31 PM, K Viltersten <tm...@viltersten.com> wrote:
> >
> > White apply.
>
Fowler's is good too but much more comprehensive. Strunk and White is
a pamphlet compared to Fowler's tome.
Jeff Schwab
> 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.
>
> Where can i download it? Am i actually
> expected to read the whole book?
It's a short book, and worth your time. Searching does turn up free
downloads, but I recommend the illustrated version (of which I own a copy).
http://www.libraryshop.org/elofstilbywi.html
> How many people actually do aply it?
The problem is how many people don't.
> 2. You should use two spaces after a sentence-ending period.
>
> For heavens sake, why? I've always been obstructed by the double blanks
> but tolerated them. Now, that i read that
> it actually is a recommendation, i need to ask about the purpose.
(a) It makes the ends of sentences more visually obvious.
(b) It makes text easier to parse reliably from scripts.
(c) Some text-editors can navigate such sentences out of the box,
whereas others cannot. (I recall this limitation with Emacs'
text-editing major mode, though it may have been fixed since then; I
switched to Vim about five years ago.)
Jon Ribbens
>> 2. You should use two spaces after a sentence-ending period.
>>
>> For heavens sake, why? I've always been obstructed by the double
>> blanks but tolerated them. Now, that i read that it actually is a
>> recommendation, i need to ask about the purpose.
>
> Like many things of this nature, the purpose is to follow the rules of
> correct English usage.
Well, no, it's to follow a particular person's choice out of the many
and various competing rules of "correct English usage". Personally,
I dislike double spaces after sentences, but it is not wrong to put
them there any more than it is wrong not to put them there.
Consistency is far more important (hence the rule, I presume).
K Viltersten
>> sentence-ending period.
>>
>> For heavens sake, why? I've always been
>> obstructed by the double blanks but
>> tolerated them. Now, that i read that
>> it actually is a recommendation, i need
>> to ask about the purpose.
>
> (a) It makes the ends of sentences more visually obvious.
> (b) It makes text easier to parse reliably from scripts.
> (c) Some text-editors can navigate such sentences out of
> the box, whereas others cannot.
Got it. Thanks. :)
Grant Edwards
> Personally, I dislike double spaces after sentences, but it is
> not wrong to put them there any more than it is wrong not to
> put them there.
You're lucky my high school typing teacher didn't hear you say
that...
--
Grant Edwards grante Yow! I joined scientology
at at a garage sale!!
visi.com
K Viltersten
>> sentences, but it is not wrong to put them
>> there any more than it is wrong not to put
>> them there.
>
> You're lucky my high school typing teacher
> didn't hear you say that...
I'm unclear if your teacher was a double or
single spacer. It's only implied that he
felt strongly one way.
D'Arcy J.M. Cain
Jon Ribbens <jon+u...@unequivocal.co.uk> wrote:
> Well, no, it's to follow a particular person's choice out of the many
> and various competing rules of "correct English usage". Personally,
> I dislike double spaces after sentences, but it is not wrong to put
> them there any more than it is wrong not to put them there.
> Consistency is far more important (hence the rule, I presume).
Warning: Opinion follows possibly influenced by insufficient research.
I have read the arguments about single or double spacing and find that
they can be distilled down to the following:
You should use double space for monospaced fonts and single for
proportional. I reject this argument for two reasons. One is
consistency. It is entirely possible for the same document to be
rendered in multiple ways and you may not be aware of them ahead of
time. The second is that it seems to me that programs that use
proportional fonts should be able to make any space between sentences
render properly by their own rules so the number of spaces should be
irrelevant. I am not swayed by arguments that they don't handle this
properly yet.
The arguments for one over the other fall into these basic ones. Use
double spaces to make the document easier to read, especially by people
who read a lot and tend to skim to absorb as much information as
possible. Use single space because it makes the document display
nicer. This suggests to me that the schism is probably between two
different types of people, text/information oriented and
display/presentation oriented. I don't see any way to appeal to both.
Grant Edwards
>>> Personally, I dislike double spaces after sentences, but it is
>>> not wrong to put them there any more than it is wrong not to
>>> put them there.
>>
>> You're lucky my high school typing teacher didn't hear you say
>> that...
>
> I'm unclear if your teacher was a double or single spacer.
Double.
> It's only implied that he felt strongly one way.
She, actually. Leaving out one of the two spaces after the end
of a sentence was no less an error than leaving out the period
or forgetting to capitalize the first word of the next
sentence.
AFAIK, that's the way pretty much everybody was taught to type
back then (1977).
If you're using a word-processor or typesetting system that's
worth its weight in bits, it won't matter how many spaces you
type -- the paragraph layout algorithm will handle it.
--
Grant Edwards grante Yow! I'm having fun
at HITCHHIKING to CINCINNATI
visi.com or FAR ROCKAWAY!!
Jeroen Ruigrok van der Werven
>The arguments for one over the other fall into these basic ones. Use
>double spaces to make the document easier to read, especially by people
>who read a lot and tend to skim to absorb as much information as
>possible. Use single space because it makes the document display
>nicer. This suggests to me that the schism is probably between two
>different types of people, text/information oriented and
>display/presentation oriented. I don't see any way to appeal to both.
The double space came from the era of typewriters and monospace printers.
Technology nowadays with all kinds of rendering engines and font
specifications basically make the entire point of 'two spaces after a
period' a moot point.
In all my professional technical writing and documentation work I completely
gave up on two spaces after a period. It's archaic.
--
Jeroen Ruigrok van der Werven <asmodai(-at-)in-nomine.org> / asmodai
イェルーン ラウフロック ヴァン デル ウェルヴェン
http://www.in-nomine.org/ | http://www.rangaku.org/
When you are right, you cannot be too radical; When you are wrong, you
cannot be too conservative.
Steven D'Aprano
>> 2. You should use two spaces after a
>> sentence-ending period.
>>
>> For heavens sake, why? I've always been obstructed by the double blanks
>> but
>> tolerated them. Now, that i read that it actually is a recommendation,
>> i need to ask about the purpose.
>
> Like many things of this nature, the purpose is to follow the rules of
> correct English usage.
Except English grammar does not and never has specified using two spaces
after a period. The (bad) habit of doing so was introduced by typists, in
the old days of manual typewriters, in the belief (completely bogus, in
my opinion) that a larger gap between sentences would make them more
readable. I believe that the larger gap is a distraction, one of the
reasons that typewriter text is generally harder to read than properly
typeset text.
I believe it is one of those things that everybody (for some value of
"everybody") does because that's what they were taught to do, and they
were taught to do it because that's what their teachers were taught, and
so on all the way back to some nutter who just decided that *he* was
going to use two spaces after a period because the Great and Mighty
Pumpkin told him to.
Professional typesetters, using proportional fonts, don't use double-
spaces because it throws off word spacing and line justification and just
plain looks ugly. I suppose that since coders typically use non-
proportional fonts, we can at least justify the use of two spaces with a
claim that it aids readability for "typewriter fonts" -- if you believe
such a thing, which I do not.
--
Steven
Grant Edwards
> Professional typesetters, using proportional fonts, don't use double-
> spaces because it throws off word spacing and line justification and just
> plain looks ugly.
They do, however, put more space between sentences than they do
between words within a sentence. It is that practice which the
"two spaces after a period" rule in typewriting is attempting
to emulate.
> I suppose that since coders typically use non- proportional
> fonts, we can at least justify the use of two spaces with a
> claim that it aids readability for "typewriter fonts" -- if
> you believe such a thing, which I do not.
My thumb has been putting two spaces after a period for 30
years, so the chances that it's going to change are rather
slim. :)
--
Grant Edwards grante Yow! A shapely CATHOLIC
at SCHOOLGIRL is FIDGETING
visi.com inside my costume..
Aahz
Grant Edwards <gra...@visi.com> wrote:
>
>My thumb has been putting two spaces after a period for 30
>years, so the chances that it's going to change are rather
>slim. :)
+1 QOTW
--
Aahz (aa...@pythoncraft.com) <*> http://www.pythoncraft.com/
"All problems in computer science can be solved by another level of
indirection." --Butler Lampson
Roberto Bonvallet
cybersource.com.au> wrote:
> I believe it is one of those things that everybody (for some value of
> "everybody") does because that's what they were taught to do
Actually I was never taught to, and I never learnt about it anywhere.
I started
to do it spontaneously in order to tell apart end-of-sentence periods
from abbreviation
periods. Anyway, I don't think it's something people should be forced
to do.
--
Roberto Bonvallet
casti...@gmail.com
> at SCHOOLGIRL is FIDGETING
> visi.com inside my costume..
So, what gets you plonked around h... *plonk*?
Micah Cowan
> 2. You should use two spaces after a sentence-ending period.
>
> For heavens sake, why? I've always been obstructed by the double
> blanks but tolerated them. Now, that i read that
> it actually is a recommendation, i need to ask about the purpose.
AFAICT from modern publications (which nevertheless get many other
things wrong, such as how f and i are handled when they appear in
sequence), this practice has mostly been eschewed, thankfully.
In "The Elements of Typographical Style", by Robert Bringhurst, has
this to say (section 2.1.4 of version 3.0):
In the nineteenth century, which was a dark and inflationary age in
typography and type design, many compositors were encouraged to
stuff extra space between sentences. Generations of
twentieth-century typists were then taught to do the same, by
hitting the spacebar twice after every period. Your typing as well
as your typesetting will benefit from unlearning this quaint
Victorian habit. As a general rule, no more than a single space is
required after a period, colon or any other mark of
punctuation. Larger spaces (e.g., en spaces) are _themselves_
punctuation.
He goes on to note that this does not apply to setting languages such
as classical Latin or Greek, or other circumstances in which sentences
begin with lowercase letters, where the extra space is actually
helpful.
The Elements of Typographical Style (much like Strunk & White) is not
gospel, but is written by a highly experienced typesetter, and is
chock full of very sound advice.
Personally, I find double-spacing to be an abomination. However, there
are some practical issues to note. One is that some editors (notably
vi) only recognize a period as ending a sentence if they are followed
by two spaces. This may be the default for Emacs as well (I don't do
much "moving by sentence" in Emacs). For this reason, the GNU Coding
Guidelines recommend ensuring that all periods in comments and in
plaintext documentation have periods.
Knuth's typesetting program, Τεχ, in its default "plain" format (and
in the popular Laτεχ format as well), will add extra space at the ends
of sentences automatically (I always disable this functionality when I
write for either of those; I believe the command is "\frenchspacing").
--
Micah J. Cowan
Programmer, musician, typesetting enthusiast, gamer...
http://micah.cowan.name/
Micah Cowan
> On 2008-03-07, Steven D'Aprano <st...@REMOVE-THIS-cybersource.com.au> wrote:
>
>> Professional typesetters, using proportional fonts, don't use double-
>> spaces because it throws off word spacing and line justification and just
>> plain looks ugly.
>
> They do, however, put more space between sentences than they do
> between words within a sentence. It is that practice which the
> "two spaces after a period" rule in typewriting is attempting
> to emulate.
Not in most books I've read. AFAICT, it's a (thankfully) disappearing
practice in the typesetting profession.
dave_m...@fastmail.fm
> 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
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.
--
Steven
dave_m...@fastmail.fm
cybersource.com.au> wrote:
> On Fri, 07 Mar 2008 20:04:47 -0800, dave_mikesell wrote:
> > On Mar 7, 10:31 am, "K Viltersten" <t...@viltersten.com> wrote:
> >> I've been recommended reading
> >> 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.
>
> 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.
Steven D'Aprano
>> 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.
"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.)
--
Steven
dave_m...@fastmail.fm
cybersource.com.au> wrote:
> On Fri, 07 Mar 2008 20:57:32 -0800, dave_mikesell wrote:
> >> 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.
>
> "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
>> 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?
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.
>> 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.
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).
--
Grant Edwards grante Yow! I was giving HAIR
at CUTS to th' SAUCER PEOPLE
visi.com ... I'm CLEAN!!
casti...@gmail.com
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
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>
--
Grant Edwards grante Yow! .. does your DRESSING
at ROOM have enough ASPARAGUS?
visi.com
casti...@gmail.com
> On 2008-03-08, castiro...@gmail.com <castiro...@gmail.com> wrote:
>
> > 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.
Limit your comments, in other words. <em>LIM-IT</em>.
> comment explaining a particularly opaque algorithm can be
> useful as well.
But can't the name do that? <wink>
> 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
> 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.
casti...@gmail.com
> On 2008-03-08, castiro...@gmail.com <castiro...@gmail.com> wrote:
>
> > 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.
Limit your comments, in other words. <em>LIM-IT</em>.
> comment explaining a particularly opaque algorithm can be
> useful as well.
But can't the name do that? <wink>
> 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?
dave_m...@fastmail.fm
<hilarious rant snipped>
LOL. Thanks for the laughs. I share your frustration.
dave_m...@fastmail.fm
> 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
>> 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).
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).
--
Grant Edwards grante Yow! YOU PICKED KARL
at MALDEN'S NOSE!!
visi.com
K Viltersten
> 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.
>> 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.
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
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
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*
--
Steven
Steven D'Aprano
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.
--
Steven
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.
Micah Cowan
> On Mar 8, 2:38 am, Steven D'Aprano <st...@REMOVE-THIS-
> cybersource.com.au> wrote:
>> On Fri, 07 Mar 2008 20:57:32 -0800, dave_mikesell wrote:
>> >> 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.
>>
>> "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.
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.
K Viltersten
> * 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.
dave_m...@fastmail.fm
> /** 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
>> 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.
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! :)
sjde...@yahoo.com
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
> On Mar 8, 7:34 pm, Steven D'Aprano <st...@REMOVE-THIS-
> cybersource.com.au> wrote:
>> 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?
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..."""
--
Steven
Grant Edwards
>> 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++),
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.
>
>>> 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.
>
> 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. ;)
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 grante Yow! I'm using my X-RAY
at VISION to obtain a rare
visi.com glimpse of the INNER
WORKINGS of this POTATO!!
Grant Edwards
>>> /** 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.
>
> 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 grante Yow! One FISHWICH coming
at up!!
visi.com
Grant Edwards
> 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?
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 grante Yow! If I am elected no
at one will ever have to do
visi.com their laundry again!
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 grante Yow! I want DUSTIN
at HOFFMAN!! ... I want
visi.com LIBRACE!! YOW!!
Grant Edwards
>> 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. 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.
>> 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..."""
The bad part is that it's redundant information. That means
that eventually, it's going to be wrong.
--
Grant Edwards grante Yow! I'm young... I'm
at HEALTHY... I can HIKE
visi.com THRU CAPT GROGAN'S LUMBAR
REGIONS!
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.
--
Grant Edwards grante Yow! I'm wearing PAMPERS!!
at
visi.com
Grant Edwards
:)
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.]
--
Grant Edwards grante Yow! I will invent "TIDY
at BOWL"...
visi.com
Steven D'Aprano
>> 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.
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.
--
Steven
Ryan Ginstrom
> 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
sjde...@yahoo.com
cybersource.com.au> wrote:
> On Sat, 08 Mar 2008 20:45:25 -0800, sjdevn...@yahoo.com wrote:
> > On Mar 8, 7:34 pm, Steven D'Aprano <st...@REMOVE-THIS-
> > cybersource.com.au> wrote:
> >> 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.
> > 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.
It's not terrible, no, just vaguely pointless and a bit fragile in the
face of change.
Lie
> 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.
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.
casti...@gmail.com
cybersource.com.au> wrote:
> On Sat, 08 Mar 2008 13:40:56 -0800, dave_mikesell wrote:
> > On Mar 8, 2:27 pm, castiro...@gmail.com wrote:
>
> >> 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.
>
> 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 )?
casti...@gmail.com
> On Mar 9, 3:27 am, castiro...@gmail.com wrote:
>
> > 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
>
> comments, not too short and not too long that it becomes obscure.
What do you mean? If 'obscure' is the right word, then it's
subjective (from metrics import obscurity?), which means that 10% of
the people disagree with you, or 90% do. The end-all be-all, there is
no such thing. I don't think it's obscure; I do. Is it?
casti...@gmail.com
> > >> 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.
>
> > 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 )?
Someone should try annotating code with a dictionary lookup on
identifiers. Anyone bored on Fridays? No one should try printing out
the definitions in real-time as the code is executing.
rockingred
> // 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.
Actually, "editorial" comments that tell you who last changed a
program, when and why can be useful. I worked in a company with a
number of programmers on staff. Having comments that told us Joe
worked on a program yesterday that isn't working today could often
solve half the battle. Especially if Joe also added a comment near
the lines he had changed. Likewise including the "Project#" would
help us track all the programs that had to be changed for a specific
project. This allowed us to move all related items into the Live
system once the testing phase had been completed (we just searched for
everything with the same Project# in it). Yes, on rare occasions we
would have an entire page of "Editorial" comments to ignore at the
beginning of our program listing, but it was easy enough to skip that
page. I will grant you that probably after 10 changes the first
change isn't as important anymore (unless you want to backtrack and
find out who started the Project in the first place and what it's
original purpose was).
Roel Schroeven
That is certainly useful, but IMO that's what version control systems
are for.
--
The saddest aspect of life right now is that science gathers knowledge
faster than society gathers wisdom.
-- Isaac Asimov
Roel Schroeven
rockingred
wrote:
>
> - Show quoted text -
Unfortunatly, in many of the companies I worked for, version control
software was not implemented. In some cases, where it was, it
actually inserted the comments into the header of the program as
described. In others, the software was so limited as to make it
useless.
sjde...@yahoo.com
Fix that. That's usually something that's fairly easy to get done as
a programmer (I've had to do it at 2 of the last 4 places I worked).
Just go explain all the problems that can happen by not having VC and
all the benefits it brings to your managers, and that there's a good
free VC system that will work for everyone, and it'll likely become a
mandate pretty quickly.
It's almost certainly worth fixing that problem rather than mucking
around with half-solutions.
Lie
No, there is a point where everyone would say obscure. Such as a
simple two integer addition function that have thirty pages of
documentation and that have names like:
def dosomereallyfunkythings(argumentoneissomethingadded,
argumentbisaddinga):
""" blah blah blah blah
...
30 or so pages later...
...
Ok, that is the end of it, it's a complex function actually
"""
return argumentoneissomethingadded + argumentbisaddinga
(remember you don't have access to source code, so you have to
decipher the documentation for what the function is about)
I prefer to see something like this:
def add(a, b):
return a + b
Even without documentation I'd know immediately what it does from the
name (add)
casti...@gmail.com
> On Mar 10, 4:16 am, castiro...@gmail.com wrote:
>
>
>
>
>
> > On Mar 9, 4:25 am, Lie <Lie.1...@gmail.com> wrote:
>
> > > On Mar 9, 3:27 am, castiro...@gmail.com wrote:
>
> > > > 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
>
> > > 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.
>
> > What do you mean? If 'obscure' is the right word, then it's
> > subjective (from metrics import obscurity?), which means that 10% of
> > the people disagree with you, or 90% do. The end-all be-all, there is
> > no such thing. I don't think it's obscure; I do. Is it?
>
> No, there is a point where everyone would say obscure.
But not on all code. Comments can obscure code, and code can too.
Here's a snip from the docs:
# p2cwrite ---stdin---> p2cread
# c2pread <--stdout--- c2pwrite
# errread <--stderr--- errwrite
Is c2pread more or less obscure than c2pr or chi2parread? If there's
an objective metric of the degree of something's obscurity (obscured-
ity), then that has an answer. Is it a scalar, or if not, is there
abs( answer )? Does that comment obscure the later code? Are 'in'
and 'out' more or less obscure than those?
(p2cread, p2cwrite,
c2pread, c2pwrite,
errread, errwrite) = self._get_handles(stdin, stdout, stderr)
Information design can get (*subjective) breathtaking, but if you see
a potential improvement, you should always be able to make it.
Tell me what you think of this simile: Sometimes Steve Chessmaster
reads board positions, sometimes prose. Some of the prose is less
obscure, -to- -him-, than board states. To someone with a different
speciality, as in bishops vs. knights, endgame vs. openings, certain
forks, the states are less obscure than the corresponding prose. To
my fmr. A.I. professor, "The minimax A*," and "The beaten path A*" are
plenty clear. He can say what they do. Can you?
> (remember you don't have access to source code, so you have to
> decipher the documentation for what the function is about)
But you're still calling it?
> I prefer to see something like this:
> def add(a, b):
> return a + b
> Even without documentation I'd know immediately what it does from the
> name (add).
What if the word is generic? Do you know if it has a return value?
rockingred
wrote:
> Fix that. That's usually something that's fairly easy to get done as
> a programmer (I've had to do it at 2 of the last 4 places I worked).
> Just go explain all the problems that can happen by not having VC and
> all the benefits it brings to your managers, and that there's a good
> free VC system that will work for everyone, and it'll likely become a
> mandate pretty quickly.
>
> It's almost certainly worth fixing that problem rather than mucking
> around with half-solutions.
Unfortunately, no free VC system existed for the language in which I
was programming, and our budget (managers) wouldn't permit the
purchase of one easily. These people insisted that every change that
affected more than 1 user go through a committee that met once a
week. The amount of verbiage required just to submit a proposal to
the committee (whom you never got to see in person), was ridiculous in
the extreme.
sjde...@yahoo.com
> On Mar 10, 11:30 am, "sjdevn...@yahoo.com" <sjdevn...@yahoo.com>
> wrote:
>
> > Fix that. That's usually something that's fairly easy to get done as
> > a programmer (I've had to do it at 2 of the last 4 places I worked).
> > Just go explain all the problems that can happen by not having VC and
> > all the benefits it brings to your managers, and that there's a good
> > free VC system that will work for everyone, and it'll likely become a
> > mandate pretty quickly.
>
> > It's almost certainly worth fixing that problem rather than mucking
> > around with half-solutions.
>
> Unfortunately, no free VC system existed for the language in which I
> was programming
Explain? VC isn't language-specific.
Marc 'BlackJack' Rintsch
> On Mar 17, 12:15 pm, rockingred <willsteve2...@yahoo.ca> wrote:
>> On Mar 10, 11:30 am, "sjdevn...@yahoo.com" <sjdevn...@yahoo.com>
>>
>> Unfortunately, no free VC system existed for the language in which I
>> was programming
>
> Explain? VC isn't language-specific.
It is. It depends usually on the fact that there are individual files.
Preferably text files if you want automagic merging of different changes.
Now think of languages that are tightly coupled with their IDE storing
only binary "tokenized" files instead of plain text or even one big binary
file that contains all sources and resources of the project.
Ciao,
Marc 'BlackJack' Rintsch
Ben Finney
> [A general VCS] depends usually on the fact that there are
> individual files. Preferably text files if you want automagic
> merging of different changes.
Yes.
> Now think of languages that are tightly coupled with their IDE
> storing only binary "tokenized" files instead of plain text or even
> one big binary file that contains all sources and resources of the
> project.
Those issues have nothing to do with the language, and everything to
do with the language implementation.
Moreover, a brain-dead monstrosity as you describe would result in far
greater problems than merely the lack of decent version control
support. I think it's safe to leave such implementations to rot,
rather than stretching tools to acommodate them.
--
\ “That's all very good in practice, but how does it work in |
`\ *theory*?” —anonymous |
_o__) |
Ben Finney
Tim Lesher
Not a smart-ass response at all--a _smart_ response.
Doctests are one of the few mechanisms I've ever seen that even
attempt to make this happen.
--
Tim Lesher
tle...@gmail.com