Regarding coding style

[castironpi at gmail.com]

On Mar 11, 11:31 am, Lie <Lie.1... at gmail.com> wrote:
> On Mar 10, 4:16 am, castiro... at gmail.com wrote:
>
>
>
>
>
> > On Mar 9, 4:25 am, Lie <Lie.1... at gmail.com> wrote:
>
> > > On Mar 9, 3:27 am, castiro... at 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?