API design before implementation (was: Lambda question)

Path	csiph.com!x330-a1.tempe.blueboxinc.net!usenet.pasdenom.info!selfless.tophat.at!news.glorb.com!news.astraweb.com!border6.newsrouter.astraweb.com!not-for-mail
From	Ben Finney <ben+python@benfinney.id.au>
Newsgroups	comp.lang.python
Subject	API design before implementation (was: Lambda question)
References	<20110606134215.3EYA9.180297.root@cdptpa-web25-z02> <mailman.2494.1307379170.9059.python-list@python.org> <4ded5fda$0$29996$c3e8da3$5496439d@news.astraweb.com>
X-Public-Key-ID	0xAC128405
X-Public-Key-Fingerprint	517C F14B B2F3 98B0 CB35 4855 B8B2 4C06 AC12 8405
X-Public-Key-URL	http://www.benfinney.id.au/contact/bfinney-pubkey.asc
X-Post-From	Ben Finney <bignose+hates-spam@benfinney.id.au>
Date	Tue, 07 Jun 2011 09:54:59 +1000
Message-ID	<874o42348c.fsf_-_@benfinney.id.au> (permalink)
User-Agent	Gnus/5.13 (Gnus v5.13) Emacs/23.3 (gnu/linux)
Cancel-Lock	sha1:blFq0DzyKAO0xSh55lfdRLSAdDU=
MIME-Version	1.0
Content-Type	text/plain; charset=utf-8
Content-Transfer-Encoding	8bit
Lines	46
Organization	Unlimited download news at news.astraweb.com
NNTP-Posting-Host	82cd2903.news.astraweb.com
X-Trace	DXC=J4XWAZKB4CJ0UO2<>T]L;AL?0kYOcDh@JN7:H2`MmAUC^O_TDX7chUO]G;2>V^?kWCbEW9A[5UK?ENZ[SL`C\KgCSVE0XQAXKN@
Xref	x330-a1.tempe.blueboxinc.net comp.lang.python:7118

Show key headers only | View raw

Steven D'Aprano <steve+comp.lang.python@pearwood.info> writes:

> On Mon, 06 Jun 2011 12:52:31 -0400, Terry Reedy wrote:
>
> > Let me add something not said much here about designing functions: start
> > with both a clear and succinct definition *and* test cases. (I only
> > started writing tests first a year ago or so.)
>
> For any non-trivial function, I usually start by writing the
> documentation (a docstring and doctests) first. How else do you know
> what the function is supposed to do if you don't have it documented?

By trying to use it. At least, that's my approach: figure out what I
want the function to do by pretending it already exists, and write some
code that expects it to work.

Sometimes that code is a test case (in which case I'm doing test-first
development). Other times I'm not sure what I *want* the function to do
yet, so I'm also experimenting with what the interface should be (in
which case I'm doing something closer to a “spike implementation”).

All of that also stops me from writing the function until I can think of
a descriptive name for the function, and a docstring synopsis: the first
line of the docstring, a self-contained sentence saying what the
function is for. The synopsis should be exactly one short line; see PEP
257.

Once I know the function signature (parameters and return value), then I
write the docstring body.

> By writing the documentation and examples before the code, I often 
> discover that the API I first thought of was rubbish :)

Yep. That's also a big benefit of designing code by pretending it
exists, I find.

Fred Brooks tells us that we should plan from the beginning to throw one
away; because we will, anyhow. You and I seem to have ways to invest as
little as possible in the first design before throwing it away :-)

-- 
 \       “Are you pondering what I'm pondering?” “Umm, I think so, Don |
  `\          Cerebro, but, umm, why would Sophia Loren do a musical?” |
_o__)                                           —_Pinky and The Brain_ |
Ben Finney

Thread

Re: Lambda question Terry Reedy <tjreedy@udel.edu> - 2011-06-06 12:52 -0400
  Re: Lambda question Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2011-06-06 23:16 +0000
    API design before implementation (was: Lambda question) Ben Finney <ben+python@benfinney.id.au> - 2011-06-07 09:54 +1000
    Re: Lambda question harrismh777 <harrismh777@charter.net> - 2011-06-06 19:00 -0500

csiph-web