Docstrings considered too complicated

[Steven D'Aprano]

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.

You specify the Functional Requirements but not the Design Requirements.
Fair enough.

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

It is true that most people don't care how code is written. But they
*should* care, because how it is written directly impacts the quality of
the code. Saying "I don't care how it is written" is precisely the same
as saying "I don't care how reliable, secure or efficient the code is".

Of course people do this. People also inhale carcinogenic chemicals, vote
bad laws into place, drive too fast, ingest noxious chemicals, and spend
hours on Usenet debating the number of angels that can dance on the head
of a pin.

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.

Many years ago, I assisted a professional building architect design a
software system for specifying the requirements of major architectural
works such as bridges and high-rise buildings. They specify *everything*,
right down to the type of sand used in the concrete and the grade of
steel used for the frame. When using the wrong type of sand could mean
that the bridge collapses in 35 years, you soon learn that, yes, you damn
well better care.

 

[Gregory Ewing]

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

Hey, a SC/MP! That was my first programming language,
too. What sort of machine was it in?

 

[Gregory Ewing]

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

It was actually an improvement over CP/M's file
system. CP/M didn't have hierarchical directories
or timestamps and recorded file sizes in 128-byte
blocks rather than bytes.

 

[Gregory Ewing]

Just as customers should demand both that a building be built to do its
job well, *and* that its architectural plans meet measurable, testable
industry standards of quality for independent re-use at some
indeterminate later date.

A problem is that it's very hard to come up with
*measurable* standards of code quality.

There's no equivalent in the software world of
specifying a grade of steel or type of sand.
The things that really matter are all subjective.

 

[Steven D'Aprano]

A problem is that it's very hard to come up with *measurable* standards
of code quality.

There's no equivalent in the software world of specifying a grade of
steel or type of sand. The things that really matter are all subjective.

True, but one can look at "best practice", or even "standard practice".
For Python coders, using docstrings is standard practice if not best
practice. Using strings as comments is not.

Or one can simply use *reason*: what justification is there for putting
comments in strings at the top of the function? The only one I can see is
if you are writing for an embedded device, you may want to remove doc
strings to save memory -- and even that is implementation dependent.

What justification is there for putting docstrings in functions? Code
becomes self-documenting, you can run Python tools that extract and run
doctests, standard tools in the standard library work, other coders will
immediately understand what you have done, and (unlike the behaviour of
string-comments) the behaviour of docstrings is guaranteed by the
language.

Unless you are writing for an embedded devise, there is NO objective
reason for putting comments in strings above the function, and MANY
objective reasons for putting them into docstrings. Okay, this isn't
quite the same as measuring the strength of concrete under compression,
but it's not a subjective choice like "tea or coffee?".

 

[BlueBird]

Hi all,

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:

"""Function that does stuff"""
def doStuff():
    while not wise(up):
        yield scorn

Now my question is this: How do I kill these people without the
authorities thinking they didn't deserve it?

If they are generating their doc with doxygen, I think it's the right
choice. See:

http://www.stack.nl/~dimitri/doxygen/docblocks.html#pythonblocks

Oops, after a second look, doxygen needs comments before the function,
not doc strings.

Philippe

 

[Lie Ryan]

Or one can simply use *reason*: what justification is there for putting
comments in strings at the top of the function? The only one I can see is
if you are writing for an embedded device, you may want to remove doc
strings to save memory -- and even that is implementation dependent.

Python already have a well-defined mechanism to remove docstrings with
the -O flag; there is really no other reason but plain ignorance and
inflexibility to think in other language than
<insert-your-first-language-here>.

 

[MRAB]

Hey, a SC/MP! That was my first programming language,
too. What sort of machine was it in?

Mk14 from Science of Cambridge, a kit with hex keypad and 7-segment
display, which I had to solder together, and also make my own power
supply. I had the extra RAM and the I/O chip, so that's 256B (including
the memory used by the monitor) + 256B additional RAM + 128B more in the
I/O chip.

 

[Grant Edwards]

It was actually an improvement over CP/M's file
system. CP/M didn't have hierarchical directories

Neither did the original MS-DOS filesystem.

or timestamps and recorded file sizes in 128-byte blocks
rather than bytes.

I thought that was true of the original MS-DOS filesystem as
well, but I wouldn't bet money on it.

 

[Grant Edwards]

Neither did the original MS-DOS filesystem.


I thought that was true of the original MS-DOS filesystem as
well, but I wouldn't bet money on it.

I definitely remember that old MS-DOS programs would treat
Ctrl-Z as an EOF marker when it was read from a text file and
would terminate a text file with a Ctrl-Z when writing one.

I don't know if that was because the underlying filesystem was
still did everything in blocks or if it was because those
MS-DOS programs were direct ports of CP/M programs. I would
have sworn that the orignal MS-DOS file API was FCB based and
worked almost exactly like CP/M. IIRC, the "byte stream" API
showed up (in the OS) sever versions later. The byte stream
API was implemented by many compiler vendor's C libraries on
top of the block-oriented FCB API.

 

[Steven D'Aprano]

I definitely remember that old MS-DOS programs would treat Ctrl-Z as an
EOF marker when it was read from a text file and would terminate a text
file with a Ctrl-Z when writing one.

I believe that Windows (at least up to Windows XP) still supports using
ctrl-Z as EOF when reading text files.

 

[D'Arcy J.M. Cain]

Gregory Ewing wrote:
Mk14 from Science of Cambridge, a kit with hex keypad and 7-segment
display, which I had to solder together, and also make my own power
supply. I had the extra RAM and the I/O chip, so that's 256B (including
the memory used by the monitor) + 256B additional RAM + 128B more in the
I/O chip.

In case some of you youngsters think that there is a typo in the above,
no, he means a total of 640 bytes. In today's terms that would be
approx 0.0000006GB.

Makes me want to go down to the basement and fire up the Altair.

 

[Alf P. Steinbach]

* Steven D'Aprano:

I believe that Windows (at least up to Windows XP) still supports using
ctrl-Z as EOF when reading text files.

It does, at least when the Ctrl Z is the sole contents of a "line".

And it's a pain. :-(

As a practical matter, when entering text in a console window the F6 key
generates Ctrl Z.


Cheers,

- Alf

 

[David Robinow]

I definitely remember that old MS-DOS programs would treat
Ctrl-Z as an EOF marker when it was read from a text file and
would terminate a text file with a Ctrl-Z when writing one.

Actually cmd.exe (at least on Windows XP) still treats Ctrl-Z as an EOF marker.

 

[D'Arcy J.M. Cain]

Neither did the original MS-DOS filesystem.

I think that it always had a hierarchical file system although I am not
sure about 86-DOS or QDOS on which is was based.

I thought that was true of the original MS-DOS filesystem as
well, but I wouldn't bet money on it.

And that is why text files in MS-DOS and CP/M before it end with ^Z.
They needed a way to tell where the end of the information was. Why
they used ^Z (SUB - Substitute) instead of ^C (ETX - End of TeXt) or
even ^D (EOT - End Of Transmission) is anyone's guess.

 

[Grant Edwards]

I think that it always had a hierarchical file system

The hierarchical file system wasn't introduced until MS-DOS 2.0.
Versions prior to that were flat filesystem just like CP/M.

From http://en.wikipedia.org/wiki/File_Allocation_Table

At the time FAT12 was introduced, DOS did not support hierarchical
directories, and the maximum number of files was typically limited
to a few dozen. Hierarchical directories were introduced in MS-DOS
version 2.0.

 

[mk]

Makes me want to go down to the basement and fire up the Altair.

Please don't, or else I fire up that univ Yugoslavian copy of VAX with
Pascal compiler (where I wrote my first program) and I will start my
first program of ping-pong.

It was a few hundred lines but took 5 minutes to compile; "VAX" was
theoretically multitasking, but when more than 3 people were trying to
do smth on it simultaneously, it was basically seizing up.

Regards,
mk

 

[MRAB]

I think that it always had a hierarchical file system although I am not
sure about 86-DOS or QDOS on which is was based.

[snip]

MS-DOS had a hierarchical file system from version 2.0.

 

[MRAB]

In case some of you youngsters think that there is a typo in the above,
no, he means a total of 640 bytes. In today's terms that would be
approx 0.0000006GB.

Makes me want to go down to the basement and fire up the Altair.

There was partial address decoding, so the blocks appeared at several
different places in the address space, the blocks weren't contiguous
(normal RAM at 0xFxx, extra at 0xBxx), and the external address bus was
12 bits.

Not only that, I discovered that one of the bits in the extra RAM
was faulty - stuck at 0 (or was it 1)?

But I was still able to play Nim and Duck Shoot (after keying it in)!

 

[Steve Holden]

Please don't, or else I fire up that univ Yugoslavian copy of VAX with
Pascal compiler (where I wrote my first program) and I will start my
first program of ping-pong.

It was a few hundred lines but took 5 minutes to compile; "VAX" was
theoretically multitasking, but when more than 3 people were trying to
do smth on it simultaneously, it was basically seizing up.

Regards,
mk

Puts me in mind of Mario Wolczko's early attempts to implement SmallTalk
on a VAX 11/750. The only bitmapped display we had available was a Three
Rivers PERQ, connected by a 9600bps serial line. We left it running at
seven o'clock one evening, and by nine am the next day it had brought up
about two thirds of the initial VM loader screen ...

You tell these young kids, and they just don't believe you!

regards
Steve