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 Newsgroups: comp.lang.python Subject: API design before implementation (was: Lambda question) References: <20110606134215.3EYA9.180297.root@cdptpa-web25-z02> <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 Date: Tue, 07 Jun 2011 09:54:59 +1000 Message-ID: <874o42348c.fsf_-_@benfinney.id.au> 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 Steven D'Aprano 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