Docstrings considered too complicated

[alex23]

But as I said: a) I am (we are) not in a position to impose this (We
don't work with the code, we just run the software).

I personally believe that the end users have _every_ right to impose
quality requirements on code used within their business...although I
may not bring this up in front of them at meetings

 

[Andreas Waldenburger]

I personally believe that the end users have _every_ right to impose
quality requirements on code used within their business...although I
may not bring this up in front of them at meetings

Huh? That's like demanding a certain type of truck or vehicle
maintenance plan from a trucking company. Sure, you *could* do it, but
that effectively only limits your options. I think there should be a
clear separation of concerns here.

/W

 

[MRAB]

Guys, you sound like people arguing about old school TV show / series
like star treck
- "He was wearing a blue suit !"
- "Check episode number 29, he appeared with a pink one!"

I'm glad I'm too young to had to code in assembler, or to bear the
vision of those unlikely space suits from the 70's ;-)

Ah, yes, Star Trek (the original series).

If they transported down to a planet and there was a man in a red shirt
who you'd never seen before, he'd be the one to die!

BTW, the first programming I did was in hexadecimal (C4xx was "LDI xx").

 

[Lie Ryan]

Huh? That's like demanding a certain type of truck or vehicle
maintenance plan from a trucking company. Sure, you *could* do it, but
that effectively only limits your options. I think there should be a
clear separation of concerns here.

If my truck contains food items that spoils quickly, I would want to
make sure that the trucking company takes good care of their
refrigeration system and that the truck have as little chance as
possible for breakdown due to poor maintenance.

 

[Andreas Waldenburger]

If my truck contains food items that spoils quickly, I would want to
make sure that the trucking company takes good care of their
refrigeration system and that the truck have as little chance as
possible for breakdown due to poor maintenance.

My point was that it should not be any of your concern *how* they do
it, only *that* they do it.

Back in the software world: Those guys write code that works. It does
what it's supposed to do. Why should we care where they put their
comments?

 

[Robert Kern]

Back in the software world: Those guys write code that works. It does
what it's supposed to do. Why should we care where they put their
comments?

Software usually needs to be maintained and extended over the course of its
lifetime. The original team that wrote it may not be available in the future.

Furthermore, docstrings are not comments. They become part of the function
object and can be introspected at runtime. This is a very important tool when
working with code at the interactive prompt and for the collection of API
documentation. Comments are less useful than docstrings; the OP's complaint was
that his programmers were putting the function documentation in other places
than docstrings, rendering them less useful than they could have been.

--
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
that is made terrible by our own mad attempt to interpret it as though it had
an underlying truth."
-- Umberto Eco

 

[Jean-Michel Pichavant]

My point was that it should not be any of your concern *how* they do
it, only *that* they do it.

Back in the software world: Those guys write code that works. It does
what it's supposed to do. Why should we care where they put their
comments?

If you've bought the code and want to maintain it, you'd better make
sure it's possible.
By the way, the ISO 9001 standard ask for your out sourced processing to
be compliant with your QA objectives, so if you care about your code,
then you should care for the code you buy.

JM

 

[Andreas Waldenburger]

Software usually needs to be maintained and extended over the course
of its lifetime. The original team that wrote it may not be available
in the future.

Furthermore, docstrings are not comments. They become part of the
function object and can be introspected at runtime. This is a very
important tool when working with code at the interactive prompt and
for the collection of API documentation. Comments are less useful
than docstrings; the OP's complaint was that his programmers were
putting the function documentation in other places than docstrings,
rendering them less useful than they could have been.

No, the OP complained about those guys being idiots. I should know,
because I posted it.

/W

 

[Andreas Waldenburger]

Andreas Waldenburger wrote:
[snip]

Back in the software world: Those guys write code that works. It
does what it's supposed to do. Why should we care where they put
their comments?

If you've bought the code and want to maintain it, you'd better make
sure it's possible.

Fair enough, but we don't want to maintain it.

By the way, the ISO 9001 standard ask for your out sourced processing
to be compliant with your QA objectives, so if you care about your
code, then you should care for the code you buy.

We did not buy code. If it were written in C or such, we would never
get to see it.

It's not our concern.

/W

 

[Mark Lawrence]

Andreas Waldenburger wrote:
[snip]

Back in the software world: Those guys write code that works. It
does what it's supposed to do. Why should we care where they put
their comments?

If you've bought the code and want to maintain it, you'd better make
sure it's possible.

Fair enough, but we don't want to maintain it.

By the way, the ISO 9001 standard ask for your out sourced processing
to be compliant with your QA objectives, so if you care about your
code, then you should care for the code you buy.

We did not buy code. If it were written in C or such, we would never
get to see it.

It's not our concern.

/W

From your original post.

<quote>
a company that works with my company writes a lot of of their code in
Python (lucky jerks). I've seen their code and it basically looks like
this:
</quote>

So what is the relationship between your company and this other company?
When it gets down to pounds, shillings and pence (gosh, I'm old! it
sure as hell could make a tremendous difference in the long term, given
that usually maintainance costs are astronomical when compared to
initial development costs.

Regards.

Mark Lawrence.

 

[Roy Smith]

Ah, yes, Star Trek (the original series).

If they transported down to a planet and there was a man in a red shirt
who you'd never seen before, he'd be the one to die!

Of course. Everybody knows there's an endless supply of red shirts.

 

[Andreas Waldenburger]

[snip]
We did not buy code. If it were written in C or such, we would never
get to see it.

It's not our concern.

/W

From your original post.

<quote>
a company that works with my company writes a lot of of their code in
Python (lucky jerks). I've seen their code and it basically looks like
this:
</quote>

So what is the relationship between your company and this other
company?

They write a piece of software that we run as a component in a software
ecosystem that we (and others) have developed.

When it gets down to pounds, shillings and pence (gosh, I'm
old! it sure as hell could make a tremendous difference in the long
term, given that usually maintainance costs are astronomical when
compared to initial development costs.

I totally agree, but as long as their software works, why should we
care how their code looks? It's totally their responsibility. Why
should we nanny every partner we have?

Don't get me wrong; our whole system is more fragile than I find
comfortable. But I guess getting 10ish different parties around the
globe to work in complete unison is quite a feat, and I'm surprised it
even works as it is. But it does, and I'm glad we don't have to
micromanage other people's code.


/W

 

[Andreas Waldenburger]

Then I don't see what that problem is.

There is none. I was griping about how stupid they are. That is a
personal problem I have with their *code* (not software), and I thought
I'd just share my superiority complex with everyone.

I had hoped that everyone just read it, went like "Oh geez.", smiled it
off with a hint of lesson learned and got back to whatever it was they
were doing. Alas, I was wrong ... and I'm sorry.

/W

 

[Jean-Michel Pichavant]

There is none. I was griping about how stupid they are. That is a
personal problem I have with their *code* (not software), and I thought
I'd just share my superiority complex with everyone.

I had hoped that everyone just read it, went like "Oh geez.", smiled it
off with a hint of lesson learned and got back to whatever it was they
were doing. Alas, I was wrong ... and I'm sorry.

/W

There's something wrong saying that stupid people write working code
that totally satisfies your needs. Don't you agree ? ;-)

JM

 

[Andreas Waldenburger]

There's something wrong saying that stupid people write working code
that totally satisfies your needs. Don't you agree ? ;-)

No, in fact I don't.

It works. They are supposed to make it work. And that's what they do.
Whether or not they put their docstrings in the place they should does
not change that their code works.

Sorry, you guys drained all the funny out of me.

/W

 

[Andreas Waldenburger]

It's rather odd that you think of “require general quality standards,
independently measurable and testable†to be “micromanagingâ€.

I should know better than to argue these things, but I don't. Hmph.

We demand testable quality standards, but not of their code. We demand
it of their software. We say *what* we want, they decide *how* they'll
do it. Noncompliance will be fined, by a contractually agreed
amount. Everything beyond that is micromanaging and detracts workforce
from the stuff *we* have to do.

We are in exactly the same kind of bond with a company that buys our
system (and support). I have yet to see any one of them demand to see
how we write our code. Why should they care? (Rhetorical question, I
refuse to discuss this any further.)

I guess that when even the *customers* will resist implementing such
quality expectations, it's little surprise that the vendors continue
to push out such shoddy work on their customers.

When I'm building bicycles I can go to the trouble of going by what
method of galvanization my tires are produced. Or I save myself the
trouble and just take the best offer and hold them responsible when
they don't deliver on their promise. Both possible, both work, and both
appropriate in certain situations.

You can keep discussing if you want, I've said more than I was hoping
to.

/W

 

[Albert van der Horst]

You could think of it as a not bad use of the design principle "Clear The
Simple Stuff Out Of The Way First". Destinations are commonly a lot simpler
than sources -- just as in Python assignment statements. So you can tell
more or less at a glance what's going to be changed, then get into the deep
analysis to find what it's going to be changed to.

The real background is that a very long time ago at Intel
the first guy that wrote an assembler, got it "wrong", i.e.
violated the conventions established already at the time.

No nothing clever, nothing conscious, just reinventing the wheel
badly.

Next time you tell me that the MSDOS "file" system was well thought
out

Mel.

Groetjes Albert

 

[Aahz]

Sorry, you guys drained all the funny out of me.

Don't let a few nitpickers do that! I thought it was funny; after that,
just remember that every Usenet thread drifts away from *your* point.
--
Aahz ([email protected]) <*> http://www.pythoncraft.com/

"Many customs in this life persist because they ease friction and promote
productivity as a result of universal agreement, and whether they are
precisely the optimal choices is much less important." --Henry Spencer

 

[Grant Edwards]

No nothing clever, nothing conscious, just reinventing the wheel
badly.

Next time you tell me that the MSDOS "file" system was well thought
out

Just a mediocre copy of the CP/M filesystem, which was in turn
copied from DEC's RSTS or RSX.

 

[Steven D'Aprano]

No, in fact I don't.

It works. They are supposed to make it work. And that's what they do.
Whether or not they put their docstrings in the place they should does
not change that their code works.

Sorry, you guys drained all the funny out of me.

Most of the customers I've worked for have insisted we follow best
practices. Sometimes they even invent their own best practices that
nobody has even heard of, and that's fun (not). You're the first one I've
ever met that bitches publicly that your contractors don't follow best
practice, but objects strenuously to the idea that you are right to care
about that they don't.

Wow. Just... wow.

P.S. next time you want some not-quite-best-practice Python code written,
send me an email off-list. I'll be more than happy to do not-quite-best-
practice work for you.

*wink*