Regarding coding style

[castironpi]

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?

 

[castironpi]

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

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]

rockingred schreef:

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

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]

rockingred schreef:







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- Hide quoted text -

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

 

[sjdevnull]

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.

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]

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

 

[castironpi]

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]

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.

 

[sjdevnull]

Unfortunately, no free VC system existed for the language in which I
was programming

Explain? VC isn't language-specific.

 

[Marc 'BlackJack' Rintsch]

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.

 

[Tim Lesher]

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

Regards,
Ryan Ginstrom

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.