[racket] OFFTOPIC - Quote on Programming

No, not just giving a spec to your programmers. More importantly, give them
a design! This consists of several layers. At the toplevel a spec telling
how things will appear to the future users, or better a user documentation
(which is tricky, because at this stage you have to be aware that you must
be able to fulfill all promises made in the user docs (time considerations
included). But a spec is not sufficient. The design must include how
different aspects of the specs are distributed over libraries or modules or
however you want to call them. For each part you need an abstract
description of data and state together with the signatures of all functions
(procedures subroutines or whatever) that access or mutate data/state. At
the lowest level you describe the internal representation of the abstract
datatypes and the algorithms to be used. You also need a design of tests and
testing tools. For big projects you need to decide where and when to store
data. You need to decide which language(s) to use for the coding. You may
have to do feasibility tests while designing such as to verify that tasks
can be done within time limits imposed by the specs.

As an example without details: I once got a request from a user of an
institute that used a system advicing when and at which price to sell or buy
a certain product. His institute had a system that took a day, but the
institute needed to take its decisions within 10 minutes, because after 10
minutes the market may have changed a lot. I am talking about mid eighties.
We succeeded, but only after the user agreed to a machine dependent and
therefore almost impossibly migratable solution. In short: it is very
important to talk with your future user(s) and to understand him/her/them
and reversely.

I have had, although time has passed by, several occasions to make designs
and leave the coding to others (in some cases the most delicate parts
excepted and done by myself) When you have a big project that requires a
team of people, a detailed design is very important. Of course I have made
my mistakes, but I am proud of the cases where my approach ended well.

Jos



> -----Original Message-----
> From: users-bounces at racket-lang.org 
> [mailto:users-bounces at racket-lang.org] On Behalf Of Hendrik Boom
> Sent: jueves, 21 de marzo de 2013 18:41
> To: users at racket-lang.org
> Subject: Re: [racket] OFFTOPIC - Quote on Programming
> 
> On Thu, Mar 21, 2013 at 12:16:55PM -0400, Ray Racine wrote:
> > Ancillary story.
> > 
> > On one occasion I did do a detailed business rule design to 
> the extant of
> > constructing a full on Zed document.  In this case there 
> were 10-15K lines
> > of completely opaque RPG code dealing with pricing.  Not a 
> living soul on
> > this planet understood how pails, buckets, gobs, and dump 
> trucks full
> > shadowy data (most of which at the end of the day, didn't 
> influence a damn
> > thing) were poured into said system and then machinations 
> resulting in
> > spitting out a price from the other end.  Think your 
> digestive track here
> > and you're pretty close.
> > 
> > It took weeks to put the document together.  But ... when 
> we went to code,
> > it was the smoothest flowing constant stream effort to 
> completion of any
> > software project I've experienced.  After code completion 
> we found far more
> > bugs in the spec than we did in the code.
> 
> Exactly.  You didn't just hand off the spec to a bunch of 
> coders and get 
> a perferct system from them.  You changed the spec as a 
> result of coding 
> experience.
> 
> >  Most of the issues were failures
> > to uncover subtle corner cases (most of which were 
> themselves bugs, legacy
> > deprecated rules etc) in the RPG code.
> 
> And the RPG code was itself an initiall spec, however 
> imcomprehensible 
> and incomplete it was.
> > 
> > Summary.
> > Overall far less bugs.
> > Lesser proportion of bugs were from variance between spec and code.
> > Most bugs were in variance between spec and reality (actual 
> business rules).
> > Overall, I liked it the approach to the point where I would 
> apply it again.
> > Interestingly, I never have, though there have been a few 
> situations where
> > it would have been applicable.
> > 
> > These days, I'd throw someone out the window who wanted to 
> start coding
> > from the get go with the idea we'll sort of Agile random 
> walk the code and
> > logic to the desired end state, as I will someone who 
> advocating full on
> > upfront MBase.
> 
> I'm not advocating coding without a spec, either.  You need 
> both.  And 
> you need both to evolve as you gain further understanding of the real 
> problems.
> 
> > 
> > 
> > On Thu, Mar 21, 2013 at 11:36 AM, Richard Cleis 
> <rcleis at me.com> wrote:
> > 
> > > My experience is the same. But try to explain to a 
> program or project
> > > manager that at least four things gradually change to 
> complete a project:
> > > design, code, tests, and docs. I am no longer expecting 
> to ever work on a
> > > project where the leaders do not insist each of those is 
> a milestone
> > > completed in some exact order that was preconceived by 
> someone who never
> > > finished a good project.
> > >
> > > rac
> > >
> > > On Mar 19, 2013, at 2:29 PM, Patrick Li wrote:
> > >
> > > > My personal experience is that a good and detailed 
> design is hard to
> > > > get to *without* doing the coding.
> > > >  -Patrick
> > > >
> > > > On Tue, Mar 19, 2013 at 1:50 PM, Jos Koot 
> <jos.koot at gmail.com> wrote:
> > > >> One remark down intermixed in your email.
> > > >> Jos
> > > >>
> > > >>> -----Original Message-----
> > > >>> From: users-bounces at racket-lang.org
> > > >>> [mailto:users-bounces at racket-lang.org] On Behalf Of 
> Hendrik Boom
> > > >>> Sent: martes, 19 de marzo de 2013 15:15
> > > >>> To: users at racket-lang.org
> > > >>> Subject: Re: [racket] OFFTOPIC - Quote on Programming
> > > >>>
> > > >>> I forget where that quotation came from originally, but it
> > > >>> antedated the
> > > >>> days where internal documentation was the norm.
> > > >>>
> > > >>> On Tue, Mar 19, 2013 at 06:20:57AM +0100, Jos Koot wrote:
> > > >>>> Well, that may depend on how you define "clever code".
> > > >>> Surely it is clever
> > > >>>> to write well documented code that can easily be
> > > >>> understood, debugged,
> > > >>>> maintained and reused by yourself and by others.
> > > >>>
> > > >>> The "clever" refers to cleverness merely in producing a
> > > >>> foemalism that
> > > >>> appears to work.
> > > >>>
> > > >>>> Understanding may require
> > > >>>> knowledge of the discipline the code is written for, of
> > > >>> course. In my
> > > >>>> opinion it helps a lot first finishing the documentation
> > > >>> and the design
> > > >>>> (both user and 'inside' docs) before starting coding.
> > > >>>
> > > >>> You're talking about metacleverness -- the 
> know-yourself kind of
> > > >>> cleverness that acknowledges your own limitations and 
> take them into
> > > >>> account.
> > > >>>
> > > >>>> With good and well
> > > >>>> described design it is even possible to leave the coding to
> > > >>> another person,
> > > >>>> just like an architect designs a building and 
> constructors build it.
> > > >>>> My 2c, Jos
> > > >>>
> > > >>> I've never found it to be feasible to leave the 
> coding to another
> > > >>> person, except in cases where the remaining coding is so
> > > >>> trivial that a
> > > >>> machine could do it.
> > > >>
> > > >> I have experienced some good things leaving the coding 
> to others. I
> > > think
> > > >> that in some cases a good and detailed design makes 
> coding almost
> > > trivial.
> > > >>
> > > >>>
> > > >>> [ In which case it makes sense to use a compiler.  :-) ]
> > > >>>
> > > >>> -- hendrik
> > > >>>>
> > > >>>> From: users-bounces at racket-lang.org
> > > >>> [mailto:users-bounces at racket-lang.org]
> > > >>>> On Behalf Of Harry Spier
> > > >>>> Sent: martes, 19 de marzo de 2013 2:56
> > > >>>> To: users
> > > >>>> Subject: [racket] OFFTOPIC - Quote on Programming
> > > >>>>
> > > >>>>
> > > >>>> I found this quote on a blog and couldn't help sharing it :-)
> > > >>>>
> > > >>>>
> > > >>>> "Debugging is twice as hard as writing the code in 
> the first place.
> > > >>>> Therefore if you write the code as cleverly as 
> possible, you are by
> > > >>>> definition not smart enough to debug it." Brian Kernigan
> > > >>>>
> > > >>>
> > > >>>> ____________________
> > > >>>>  Racket Users list:
> > > >>>>  http://lists.racket-lang.org/users
> > > >>>
> > > >>> ____________________
> > > >>>  Racket Users list:
> > > >>>  http://lists.racket-lang.org/users
> > > >>
> > > >> ____________________
> > > >>  Racket Users list:
> > > >>  http://lists.racket-lang.org/users
> > > > ____________________
> > > >  Racket Users list:
> > > >  http://lists.racket-lang.org/users
> > >
> > >
> > > ____________________
> > >   Racket Users list:
> > >   http://lists.racket-lang.org/users
> > >
> 
> > ____________________
> >   Racket Users list:
> >   http://lists.racket-lang.org/users
> 
> ____________________
>   Racket Users list:
>   http://lists.racket-lang.org/users