Searching \ for '[PIC]: documenting embedded software' in subject line. ()
Make payments with PayPal - it's fast, free and secure! Help us get a faster server
FAQ page: www.piclist.com/techref/microchip/devices.htm?key=pic
Search entire site for: 'documenting embedded software'.

Exact match. Not showing close matches.
PICList Thread
'[PIC]: documenting embedded software'
2001\05\23@113959 by promero

flavicon
face
part 0 44 bytes
his is a multi-part message in MIME format.
part 1 1424 bytes content-type:text/plain; charset=iso-8859-1 (decoded quoted-printable)

Hi Guys!

I don´t know how to start this thread, but i´ll give it a shot.

I have been suscribed to the piclist for about 4 months "listening"
carefully to whatever has been said (i think i use like an hour daily to
read piclist messages) and i have learned lots from you.

Lately, my boss asked me to document the embedded software of the last
project i worked in using a "template" that he designed out of
Pressman´s Software Engineering book (old edition). Although my boss is
an EE (like me) he is very software-oriented and wants me to implement
every single detail of that book to the documentation he asked for (as a
matter of fact, he is always looking for standards to implement in
everything we do: naming archives, using software, writing e-mails,
writing documents, etc).

Well, I think that creating a whole document describing everything
formally is a great tool to ease software maintainance, but learning
pseudo-code to rewrite all my software and at the same time using
cross-references between code, comments and pseudo-code and writing
everything is a task i don´t agree with.

So, finally, this is what i am asking to you:

Is there any world-spread method to do this stuff oriented to embedded
software? How do you document your firmware?
Could you give me any advice to work things out with my boss?

Thanks in advance.

Pavel Romero


part 2 422 bytes content-type:text/x-vcard; charset=us-ascii;
(decoded quoted-printable)

begin:vcard n:Romero Plaza;Pável Ernesto
tel;cell:5489528
tel;fax:6-7444829
tel;home:6-7464233
tel;work:6-7444829
x-mozilla-html:TRUE
url:http://www.insitel.com.co
org:Insitel Ltda.;Research & Development
adr:;;Calle 21 # 16 - 46 Piso 7;Armenia;Quindío;;Colombia
version:2.1
email;internet:spam_OUTpromeroTakeThisOuTspaminsitel.com.co
title:Hardware Engineer
fn:Pável Ernesto Romero Plaza
end:vcard


part 3 144 bytes
--
http://www.piclist.com hint: The list server can filter out subtopics
(like ads or off topics) for you. See http://www.piclist.com/#topics


2001\05\23@115014 by Douglas Wood

picon face
I would suggest using dataflow diagrams to document your code instead of
basically rewriting your in pseudo-code. I use OpenSELECT's Yourdon CASE
tool.

Pick up a copy of Michael J. Pont's "Software Engineering with C++ and CASE
Tools". Although it's geared toward C++, he does talk a bit about what
you're trying do: reverse-engineer your code into documentation. The book
also includes a copy of OpenSELECT (the same version that I use, actually).

Douglas Wood
Software Engineer
.....dbwoodKILLspamspam@spam@kc.rr.com

Home of the EPICIS Development System for the PIC and SX
http://epicis.piclist.com

{Original Message removed}

2001\05\23@115226 by Scott Newell

flavicon
face
>software? How do you document your firmware?

For c/c++, I use Doxygen:


http://www.doxygen.org/


newell

--
http://www.piclist.com hint: The list server can filter out subtopics
(like ads or off topics) for you. See http://www.piclist.com/#topics


2001\05\23@130158 by promero

flavicon
face
part 0 44 bytes
his is a multi-part message in MIME format.
part 1 402 bytes content-type:text/plain; charset=us-ascii (decoded 7bit)

well i happen to write 100% assembler...

Scott Newell wrote:

{Quote hidden}


part 2 422 bytes content-type:text/x-vcard; charset=us-ascii;
(decoded quoted-printable)

begin:vcard n:Romero Plaza;Pável Ernesto
tel;cell:5489528
tel;fax:6-7444829
tel;home:6-7464233
tel;work:6-7444829
x-mozilla-html:TRUE
url:http://www.insitel.com.co
org:Insitel Ltda.;Research & Development
adr:;;Calle 21 # 16 - 46 Piso 7;Armenia;Quindío;;Colombia
version:2.1
email;internet:promerospamKILLspaminsitel.com.co
title:Hardware Engineer
fn:Pável Ernesto Romero Plaza
end:vcard


part 3 144 bytes
--
http://www.piclist.com hint: The list server can filter out subtopics
(like ads or off topics) for you. See http://www.piclist.com/#topics


2001\05\23@130631 by D Lloyd

flavicon
face
part 1 930 bytes content-type:text/plain; charset=us-ascii
Then you can do as our contractors do......don't document it. The ultimate
job security ;-)

Dan



(Embedded     promero <.....promeroKILLspamspam.....INSITEL.COM.CO>KILLspamspam.....MITVMA.MIT.EDU>> image moved   23/05/2001 18:01
to file:
pic14197.pcx)





Please respond to pic microcontroller discussion list
     <
EraseMEPICLISTspam_OUTspamTakeThisOuTMITVMA.MIT.EDU>
Sent by:  pic microcontroller discussion list <PICLISTspamspam_OUTMITVMA.MIT.EDU>


To:   @spam@PICLISTKILLspamspamMITVMA.MIT.EDU
cc:
Subject:  Re: [PIC]: documenting embedded software

Security Level:?         Internal


well i happen to write 100% assembler...

Scott Newell wrote:

{Quote hidden}

(See attached file: promero.vcf)




part 2 165 bytes content-type:application/octet-stream; (decode)

part 3 423 bytes content-type:application/octet-stream; (decode)

part 4 144 bytes
--
http://www.piclist.com hint: The list server can filter out subtopics
(like ads or off topics) for you. See http://www.piclist.com/#topics


2001\05\23@132116 by Bob Barr

picon face
>From: D Lloyd <KILLspamdan.lloydKILLspamspamGB.ABB.COM>
>Reply-To: pic microcontroller discussion list <RemoveMEPICLISTTakeThisOuTspamMITVMA.MIT.EDU>
>To: spamBeGonePICLISTspamBeGonespamMITVMA.MIT.EDU
>Subject: Re: [PIC]: documenting embedded software
>Date: Wed, 23 May 2001 18:12:46 +0100
>
>
>Then you can do as our contractors do......don't document it. The ultimate
>job security ;-)
>
>Dan
>

I gotta ask -- why are they still your contractors?

Program documentation should be treated as part of the job, not an optional
extra.

For that matter, how did you know that they were doing the job you needed
done without design documentation?

_________________________________________________________________
Get your FREE download of MSN Explorer at http://explorer.msn.com

--
http://www.piclist.com hint: The list server can filter out subtopics
(like ads or off topics) for you. See http://www.piclist.com/#topics


2001\05\23@132128 by Olin Lathrop

face picon face
> I would suggest using dataflow diagrams to document your code instead of
> basically rewriting your in pseudo-code. I use OpenSELECT's Yourdon CASE
> tool.
>
> Pick up a copy of Michael J. Pont's "Software Engineering with C++ and
CASE
> Tools". Although it's geared toward C++, he does talk a bit about what
> you're trying do: reverse-engineer your code into documentation. The book
> also includes a copy of OpenSELECT (the same version that I use,
actually).

I just want to add that while all this separate documentation can be very
useful, the single most important documentation is in the code itself.  This
can never get separated from the code.  Every subroutine should have a clear
description of its interface, etc.  It is often hard to put good overview
documentation into the code, and a separate document can be useful for that.
However, if I got stuck maintaining the code I'd rather see a page of
overview information at the start of the main module than 10 pages in a
separate document that might have been last updated two years of ongoing
revisions ago.  (This may sound silly, but I've run into situations like
that).


********************************************************************
Olin Lathrop, embedded systems consultant in Littleton Massachusetts
(978) 742-9014, TakeThisOuTolinEraseMEspamspam_OUTembedinc.com, http://www.embedinc.com

--
http://www.piclist.com hint: The list server can filter out subtopics
(like ads or off topics) for you. See http://www.piclist.com/#topics


2001\05\23@132811 by Dale Botkin

flavicon
face
Man, you're not kidding.  I am in the process of trying to write an
interface for a box that will replace an existing one.  There is a
complete listing of the 8085 assembler from the old box, and a 2" binder
with all the C code that runs on the PC that talks to the DAQ system it's
connected to...  and not one shred of documentation in the lot.

<rant>How the hell can some people sleep nights, knowing they've
perpetrated that sort of crap?  What kind of person accepts money for
doing only half the job?  </rant>

Dale

On Wed, 23 May 2001, D Lloyd wrote:

{Quote hidden}

--
A train stops at a train station.  A bus stops at a bus station.
On my desk I have a workstation...

--
http://www.piclist.com hint: The list server can filter out subtopics
(like ads or off topics) for you. See http://www.piclist.com/#topics


2001\05\23@135312 by D Lloyd

flavicon
face
part 1 3098 bytes content-type:text/plain; charset=us-ascii
(joke)

....but we have had contractors in the past who adopted this
approach.....and as Dale points out, trying to work out the intention of a
load of assembler with no documention and large amounts of "advanced
cleverness" ('clever' code.....purely for the sake of 'clever' code) is not
much fun at all.

Needless to say, they do not do work for us anymore! Trouble is, those are
the kind of people who get things done real fast and it has been my
experience (not with this company) that this "quality" is held in great
esteem when the **** hits the fan. Hence, you get code written quickly but
with no idea what they did apart from a chunk of test results showing it
did what was expected......the day before they bugger off to pastures new.

The "worry about the documentation later" approach is an evil that occurs
and always will be, I am sure.

In a more positive vein, we used to use Select Yourdon for documenting our
code but we fell into the trap of putting too much detail in (lots of
information in the data dictionary) which means a *lot* of maintenance when
anything changes. Hence we pulled back from that and made the documentation
as abstract as possible while retaining the precise intention of the
code....that seems to have worked well.

We did look at SDL and UML but getting these things to model real time
systems has been a problem.......I looked into using Matlab to generate
code from Stateflow but it was a joke for low end systems.

I guess you should employ as much documentation detail as you feel
comfortable with without having to spend all your time maintaining it. And,
educate your manager (if you have one and they are non-technical) as to how
important this facet of writing code is.

Dan




(Embedded     Bob Barr <RemoveMEbob_barrspam_OUTspamKILLspamHOTMAIL.COM>spam_OUTspamKILLspamMITVMA.MIT.EDU>> image moved   23/05/2001 18:21
to file:
pic19097.pcx)





Please respond to pic microcontroller discussion list
     <
RemoveMEPICLISTTakeThisOuTspamspamMITVMA.MIT.EDU>
Sent by:  pic microcontroller discussion list <EraseMEPICLISTspamspamspamBeGoneMITVMA.MIT.EDU>


To:   RemoveMEPICLISTKILLspamspamMITVMA.MIT.EDU
cc:
Subject:  Re: [PIC]: documenting embedded software

Security Level:?         Internal


{Quote hidden}

I gotta ask -- why are they still your contractors?

Program documentation should be treated as part of the job, not an optional
extra.

For that matter, how did you know that they were doing the job you needed
done without design documentation?

_________________________________________________________________
Get your FREE download of MSN Explorer at http://explorer.msn.com

--
http://www.piclist.com hint: The list server can filter out subtopics
(like ads or off topics) for you. See http://www.piclist.com/#topics






part 2 165 bytes content-type:application/octet-stream; (decode)

part 3 144 bytes
--
http://www.piclist.com hint: The list server can filter out subtopics
(like ads or off topics) for you. See http://www.piclist.com/#topics


2001\05\23@143748 by Bill Westfield

face picon face
   ....but we have had contractors in the past who adopted this
   approach.....and as Dale points out, trying to work out the intention
   of a load of assembler with no documention and large amounts of
   "advanced cleverness" ('clever' code.....purely for the sake of
   'clever' code) is not much fun at all.

Sure the requirements and specifications that YOU gave to the contactors
in the first place serves as at least PARTIAL documentation, right?

What was that quote I saw recently?  Oh yeah:

   "Walking on water and developing software to specification are
   easy as long as both are frozen" - Edward V. Berard.

(not quite as applicable as I thought, but still relevant.)

BillW

--
http://www.piclist.com hint: The list server can filter out subtopics
(like ads or off topics) for you. See http://www.piclist.com/#topics


2001\05\23@150500 by Olin Lathrop

face picon face
> Then you can do as our contractors do......don't document it. The ultimate
> job security ;-)

You are obviously using the wrong contractor.


********************************************************************
Olin Lathrop, embedded systems consultant in Littleton Massachusetts
(978) 742-9014, EraseMEolinspamEraseMEembedinc.com, http://www.embedinc.com

--
http://www.piclist.com hint: The list server can filter out subtopics
(like ads or off topics) for you. See http://www.piclist.com/#topics


2001\05\23@152527 by Bob Ammerman

picon face
I am currently looking at 200 pages of pascal that need to translated to
"C/C++". The only parts with comments or documentation are the parts I did
18 years ago.

Bob Ammerman
RAm Systems
(contract development of high performance, high function, low-level
software)

{Original Message removed}

2001\05\23@182629 by Olin Lathrop

face picon face
> I am currently looking at 200 pages of pascal that need to translated to
> "C/C++". The only parts with comments or documentation are the parts I did
> 18 years ago.

What kind of Pascal is it?  I have a source to source translator that, among
other things, can convert Pascal to C.


********************************************************************
Olin Lathrop, embedded systems consultant in Littleton Massachusetts
(978) 742-9014, @spam@olin@spam@spamspam_OUTembedinc.com, http://www.embedinc.com

--
http://www.piclist.com hint: The list server can filter out subtopics
(like ads or off topics) for you. See http://www.piclist.com/#topics


2001\05\23@185348 by klpauba

picon face
Dale Botkin wrote:

> <rant>How the hell can some people sleep nights, knowing they've
> perpetrated that sort of crap?  What kind of person accepts money for
> doing only half the job?  </rant>

Perhaps it is due to the customer not wanting to _pay_ for the documentation.

--
http://www.piclist.com hint: The list server can filter out subtopics
(like ads or off topics) for you. See http://www.piclist.com/#topics


2001\05\23@190020 by Andy Kelley N1YEW

picon face
try p2c i fyou have linux =)

andy
----- Original Message -----
From: Olin Lathrop <spamBeGoneolin_piclistspamKILLspamEMBEDINC.COM>
To: <.....PICLISTspam_OUTspamMITVMA.MIT.EDU>
Sent: Wednesday, May 23, 2001 9:14 PM
Subject: Re: [PIC]: documenting embedded software


> > I am currently looking at 200 pages of pascal that need to translated to
> > "C/C++". The only parts with comments or documentation are the parts I
did
> > 18 years ago.
>
> What kind of Pascal is it?  I have a source to source translator that,
among
{Quote hidden}

--
http://www.piclist.com hint: The list server can filter out subtopics
(like ads or off topics) for you. See http://www.piclist.com/#topics


2001\05\23@211307 by Bob Ammerman

picon face
Data General SP/Pascal, which is pretty standard with a few extensions.

And yeah, it would probably be worth feeding thru a source-to-source
translator at least as a start.

What can you tell me about the one you have?

Bob Ammerman
RAm Systems
(contract development of high performance, high function, low-level
software)





{Original Message removed}

2001\05\24@005258 by Dale Botkin

flavicon
face
On Wed, 23 May 2001, Kevin L. Pauba wrote:

> Dale Botkin wrote:
>
> > <rant>How the hell can some people sleep nights, knowing they've
> > perpetrated that sort of crap?  What kind of person accepts money for
> > doing only half the job?  </rant>
>
> Perhaps it is due to the customer not wanting to _pay_ for the documentation.

Could be.  In this case, though, I think it's more the customer not
knowing any better.  They don't know they got taken until much later, when
someone else has to clean up after the first guy.  When I make a deal with
someone to do a job, I figure in the time to AT LEAST comment the code.  I
can't even finish it without some comments as I go along, I have no idea
how someone could write several thousand lines of C without ANY comments.

If I hire someone to replace my roof, I expect them to do a proper job of
it -- even if I don't know enough about roofing to tell if it's up to
building code standards, it's part of the deal that it has to be so.

Dale
--
A train stops at a train station.  A bus stops at a bus station.
On my desk I have a workstation...

--
http://www.piclist.com hint: The PICList is archived three different
ways.  See http://www.piclist.com/#archives for details.


2001\05\24@030829 by Lee Jones

flavicon
face
>> <rant>How the hell can some people sleep nights, knowing
>> they've perpetrated that sort of crap?  What kind of person
>> accepts money for doing only half the job?  </rant>

How about accepting money for the job _as contracted_.
You may not agree with what the customer wants, but if
you can't change their mind, your only option is to walk
away from the job.  And they may think that their written
specification is complete and all the documentation that
the project needs.

> Perhaps it is due to the customer not wanting to _pay_ for
> the documentation.

> Could be.

I've had customers who hired me on time & materials who would
not pay time charges for documentation.  If I wanted to do it,
they would happily accept it -- they just wouldn't pay for it.

> I can't even finish it without some comments as I go along,
> I have no idea how someone could write several thousand lines
> of C without ANY comments.

I always document code internally as to what it's trying to
accomplish.  I learned to do that the first time I had to go
back and rework code that I had written when I was young,
foolish, and _knew_ the code was obvious.  Details are in
the code itself.  But if you can preserve the "why", then
later when you revisit the code, you may be able to see a
whole new approach.

(I too am going to steal the #include "docs.h" idea; such a
neat way to tie in the overview and philosophy statement. )


> If I hire someone to replace my roof, I expect them to do a
> proper job of it -- even if I don't know enough about roofing
> to tell if it's up to building code standards, it's part of
> the deal that it has to be so.

But the roofer isn't doing the documentation.  It (building
code standards) was done by a different body and paid for
out of a different fund (usually government taxation).

And if the roofer has to "document" his work, it's usually
in the form of a building permit with the local governing
body (city, county, etc).  And the cost of that permit is
usually a seperately billed item from the roofing contract.

                                               Lee

--
http://www.piclist.com hint: The PICList is archived three different
ways.  See http://www.piclist.com/#archives for details.


2001\05\24@103928 by Dale Botkin

flavicon
face
I understand what you're saying, and I also would not spend the time to
write up a separate document for software if I were not being paid to do
so.  But to write code with no comments is simply wrong.  Comments are as
much a requirement of what you do as is syntax.  Yes, I know the code will
compile without them...  but if you write code devoid of any comments,
you're not doing your job, whatever that job is.  I cannot imagine a job
in which there is so little time or money that I can't at least stick a
lin or two per function in to gove some sort of vague idea as to what's
taking place or why the function exists.

Continuing the roofing analogy, comments in source code aren't like the
building permit, they're more like the tar paper (underlayment, whatever
the hell it's called).


On Thu, 24 May 2001, Lee Jones wrote:

{Quote hidden}

--
A train stops at a train station.  A bus stops at a bus station.
On my desk I have a workstation...

--
http://www.piclist.com hint: The PICList is archived three different
ways.  See http://www.piclist.com/#archives for details.


2001\05\24@104618 by Olin Lathrop

face picon face
part 1 1724 bytes content-type:text/plain; (decoded 7bit)

> Data General SP/Pascal, which is pretty standard with a few extensions.
>
> And yeah, it would probably be worth feeding thru a source-to-source
> translator at least as a start.
>
> What can you tell me about the one you have?

It started out being Apollo Domain Pascal, but I've added a number of my own
extensions over the years.  I have no idea how that relates to DG Pascal,
but probably not too different.

I still use this Pascal for creating general host code.  I've added a bunch
of portability features which insulate me from machine dependencies better
than C does.  The translator uses a configuration file to define the target
environment, which includes things like the natively available integer
sizes, the size of the integer that can hold a machine address, etc.  Most
of my host source code is in Pascal.  My build system runs it thru the
translator for the particular target machine, compiles the resulting C, then
throws out the C file and keeps the binary.  The translator is therefore not
optimized for creating C that is intended to be further worked on by humans.
It does things like flatten out include files, strip comments (doesn't
matter if the original source didn't have any), and occasionally substitute
constants when it's not sure what the C compiler might do.  On the other
hand, it's really quite clever about renaming symbols to suite the output
language, especially in changing Pascal variant records to C structs/unions.

I've attached a Pascal example file and the resulting C for the MSVC
compiler.  This isn't meant to be useful code, just an example.  I haven't
run the code, but it does translate and compile without errors.


part 2 2228 bytes content-type:application/octet-stream; (decode)

part 3 2153 bytes content-type:application/octet-stream; (decode)

part 4 330 bytes

********************************************************************
Olin Lathrop, embedded systems consultant in Littleton Massachusetts
(978) 742-9014, TakeThisOuTolinKILLspamspamspamembedinc.com, http://www.embedinc.com

--
http://www.piclist.com hint: The PICList is archived three different
ways.  See http://www.piclist.com/#archives for details.


2001\05\24@111940 by Jeff DeMaagd

flavicon
face
----- Original Message -----
From: Lee Jones <.....leespamRemoveMEFRUMBLE.CLAREMONT.EDU>


> > Perhaps it is due to the customer not wanting to _pay_ for
> > the documentation.
>
> > Could be.
>
> I've had customers who hired me on time & materials who would
> not pay time charges for documentation.  If I wanted to do it,
> they would happily accept it -- they just wouldn't pay for it.

I have a real problem with that.  IMO these customers have significant
misunderstandings of what it takes to do a proper job and keep the code
maintainable.  What's going to happen when the thing breaks and no one can
figure out what it does because it's undocumented?  Redo the entire project?
I think it's pretty arrogant to ask a professional to cut corners,
particularly when the customer doesn't understand the future costs
associated with cutting those corners when (not if) something goes wrong.

Jeff
http://demaagd.com/

--
http://www.piclist.com hint: The PICList is archived three different
ways.  See http://www.piclist.com/#archives for details.


2001\05\24@113438 by Alan B. Pearce

face picon face
> I've had customers who hired me on time & materials who would
> not pay time charges for documentation.  If I wanted to do it,
> they would happily accept it -- they just wouldn't pay for it.

Is not the wrong order? Surely the correct thing to do is document what you
are going to do then do it :) This way the customer sees it as part of the
job being done, not something done at the end - yeah I appreciate there are
details that need tiding up later, but that can be done while they test can
it not?

--
http://www.piclist.com hint: The PICList is archived three different
ways.  See http://www.piclist.com/#archives for details.


2001\05\24@125605 by Doug Joel

picon face
Aren't we talking of two different things here?

The customer is saying they don't want to pay for a book.

It doesn't take any longer to comment the code as you design
it,  at least to the level where someone with some
experience can figure it out.  It may be you in a years time
trying to figure out why you did what you did...

--
http://www.piclist.com hint: The PICList is archived three different
ways.  See http://www.piclist.com/#archives for details.


2001\05\24@144919 by Peter L. Peres

picon face
> <rant>How the hell can some people sleep nights, knowing they've
> perpetrated that sort of crap?  What kind of person accepts money for
> doing only half the job?  </rant>

Rant, rant, but:

1) You are doing what he did for less money probably.
2) He is doing the same thing now for someone else probably.
3) He will still be irreplaceable because he will not part with the info,
and you will not be, because you do part with it, for *zero* cost.

Just my opinion,

Peter

PS: Of course I prefer *with*. When it is reasonable to do it that way.
Don't you get some sort of contractual specification wrt. what exactly you
deliver ? I.e. don't you charge differently for a turnkey product ready
for multiplication, with 5 or 10 working prototypes, and for a 'study'
product with university-quality documentation which explains everything
from the physical principles to the calculus sheet - that can form the
base of a whole series of products plus in house training (by them without
your knowing) - essentially at $0 ?

--
http://www.piclist.com hint: The PICList is archived three different
ways.  See http://www.piclist.com/#archives for details.


2001\05\24@144924 by Peter L. Peres

picon face
> I am currently looking at 200 pages of pascal that need to translated to
> "C/C++". The only parts with comments or documentation are the parts I
> did 18 years ago.

There is a program called p2c (GNU). Try it.

Peter

--
http://www.piclist.com hint: The PICList is archived three different
ways.  See http://www.piclist.com/#archives for details.


2001\05\24@180916 by Dale Botkin

flavicon
face
On Thu, 24 May 2001, Peter L. Peres wrote:

> > <rant>How the hell can some people sleep nights, knowing they've
> > perpetrated that sort of crap?  What kind of person accepts money for
> > doing only half the job?  </rant>
>
> Rant, rant, but:
>
> 1) You are doing what he did for less money probably.
> 2) He is doing the same thing now for someone else probably.
> 3) He will still be irreplaceable because he will not part with the info,
> and you will not be, because you do part with it, for *zero* cost.

Irreplaceable?  I dunno, I can hire incompetent and/or undisciplined
engineers (software, hardware, network, civil or mechanical) anywhere,
cheap.  I never said he's ever going to be without work, I just observed
that he's doing a lousy job.  I stick by that.

> PS: Of course I prefer *with*. When it is reasonable to do it that way.
> Don't you get some sort of contractual specification wrt. what exactly you
> deliver ? I.e. don't you charge differently for a turnkey product ready
> for multiplication, with 5 or 10 working prototypes, and for a 'study'
> product with university-quality documentation which explains everything
> from the physical principles to the calculus sheet - that can form the
> base of a whole series of products plus in house training (by them without
> your knowing) - essentially at $0 ?

I charge by the hour, or by the project -- depending on how interesting
and how time consuming the project is.  Any contractural agreement always
includes code *with comments* plus any separate documentation they're
willign to pay for, whether that is design docs, diagrams, user manuals,
whatever.

No one has ever asked me for strictly a "study" project (remember, I do
this for fun as a sideline. I don't actively seek out business.)  If I
were asked I'd probably want royalties or a pretty hefty up-front payment.

Dale
--
A train stops at a train station.  A bus stops at a bus station.
On my desk I have a workstation...

--
http://www.piclist.com hint: The PICList is archived three different
ways.  See http://www.piclist.com/#archives for details.


2001\05\24@210703 by Olin Lathrop

face picon face
> I have a real problem with that.  IMO these customers have significant
> misunderstandings of what it takes to do a proper job and keep the code
> maintainable.  What's going to happen when the thing breaks and no one can
> figure out what it does because it's undocumented?  Redo the entire
project?
> I think it's pretty arrogant to ask a professional to cut corners,
> particularly when the customer doesn't understand the future costs
> associated with cutting those corners when (not if) something goes wrong.

I pretty much agree with you.  I've never had a customer that told me not to
document something.  If they had, it would have been my responsibility to at
least make sure they understand all the implications of that.  I might also
decide that I don't want any part of that job.

Most of the customers are not sophisticated enough to insist on particular
documentation.  I document what I think makes sense, and most of the time
they don't read it.  But I know how it will save their butt two years later
when someone else might pick up the project.  The funny thing is that when
the documentation is done right, the customer will never really notice and
therefore appreciate it.  That's just part of the job.  Bad documentation,
however, will eventually be noticed.  Unfortunately that often happens too
late for there to be serious reprocussions to the perpetrator.

I consider most of the documentation I create to be an integral part of the
overall job.  Good code comments don't take time, they save time.


********************************************************************
Olin Lathrop, embedded systems consultant in Littleton Massachusetts
(978) 742-9014, RemoveMEolinspamspamBeGoneembedinc.com, http://www.embedinc.com

--
http://www.piclist.com hint: The PICList is archived three different
ways.  See http://www.piclist.com/#archives for details.


2001\05\24@210715 by Olin Lathrop

face picon face
> I've had customers who hired me on time & materials who would
> not pay time charges for documentation.  If I wanted to do it,
> they would happily accept it -- they just wouldn't pay for it.

I'm surprised this even came up as an issue.  If a customer ever asked me to
save time by not doing documentation like comments, for example, I would
explain that comments save time.  If they insisted, then they would be a
customer definitely not worth having.  Customers with that type of nickle
and dime mentatlity are invariably much more trouble than they are worth.


********************************************************************
Olin Lathrop, embedded systems consultant in Littleton Massachusetts
(978) 742-9014, spamBeGoneolin@spam@spamspam_OUTembedinc.com, http://www.embedinc.com

--
http://www.piclist.com hint: The PICList is archived three different
ways.  See http://www.piclist.com/#archives for details.


2001\05\24@210720 by Olin Lathrop

face picon face
> Rant, rant, but:
>
> 1) You are doing what he did for less money probably.
> 2) He is doing the same thing now for someone else probably.
> 3) He will still be irreplaceable because he will not part with the info,
> and you will not be, because you do part with it, for *zero* cost.

Fine, let them get someone's brother in law Vinny in a garage to bang out
code with no comments.  Eventually it will get so bad and they'll be so
screwed that they'll pay me anything to fix it (usually means re-create from
scratch the right way).  Go ahead.  Make my day.  I've been there before.


********************************************************************
Olin Lathrop, embedded systems consultant in Littleton Massachusetts
(978) 742-9014, TakeThisOuTolinspamspamembedinc.com, http://www.embedinc.com

--
http://www.piclist.com hint: The PICList is archived three different
ways.  See http://www.piclist.com/#archives for details.


2001\05\25@022709 by Dale Botkin

flavicon
face
On Thu, 24 May 2001, Olin Lathrop wrote:

> I pretty much agree with you.  I've never had a customer that told me not to
> document something.  If they had, it would have been my responsibility to at
> least make sure they understand all the implications of that.  I might also
> decide that I don't want any part of that job.

And I wouldn't blame you.  You surely don't want your name associated with
a bungled project when someone else (or even you) needs to try to decipher
a few years from now what you've done, but has to start from scratch due
to lack of comments or docs.

{Quote hidden}

Amen.  I will be the first to admit I probably don't comment as much as
you do, but I at least document what is going on and why so it's not a
guessing game when I look at the code after a week.

Dale
--
A train stops at a train station.  A bus stops at a bus station.
On my desk I have a workstation...

--
http://www.piclist.com#nomail Going offline? Don't AutoReply us!
email listservEraseMEspammitvma.mit.edu with SET PICList DIGEST in the body


2001\05\25@052205 by Peter L. Peres

picon face
Dale Botkin wrote:
> I figure in the time to AT LEAST comment the code.  I can't even
> finish it without some comments as I go along, I have no idea how
> someone could write several thousand lines of C without ANY comments.

Perhaps they carefully removed them when they were done using a little
script ?

> If I hire someone to replace my roof, I expect them to do a proper job
> of it -- even if I don't know enough about roofing to tell if it's up
> to building code standards, it's part of the deal that it has to be
> so.

Do you expect them to tolerate you around, watching every move they make,
asking about the materials, procedures, and tools used, and have you take
little notes on it in their view ? When they are done, will you be glad
with a signed statement that they made it compliant to standards, or do
you want a ISO9000 q.c. crew all over your roof for 3 days drilling probe
holes all over the place and a sheaf of paper tall enough to use as a car
jack ? (For the price of another roof).

As a matter of fact, pick any trade, not just roofing, and tell me if it
works that way. Or even more scientific things. Like building and
architecture. Not to mention medicine. Cooking in a restaurant ? Anodizing
some parts ? Any more examples ?

Peter

--
http://www.piclist.com#nomail Going offline? Don't AutoReply us!
email RemoveMElistservEraseMEspamspam_OUTmitvma.mit.edu with SET PICList DIGEST in the body


2001\05\25@084536 by Dale Botkin

flavicon
face
On Fri, 25 May 2001, Peter L. Peres wrote:

> Dale Botkin wrote:
> > I figure in the time to AT LEAST comment the code.  I can't even
> > finish it without some comments as I go along, I have no idea how
> > someone could write several thousand lines of C without ANY comments.
>
> Perhaps they carefully removed them when they were done using a little
> script ?

We call that sabotage.  The comments are part of the source.

{Quote hidden}

Certainly not.  But I do expect that the next time it rains the house
stays dry,and if I go up to replace a shingle later on I expect to find
them nailed in place, not stuck down with adhesive or duct tape.  I
shouldn't have to watch their every move to ensure that they do the job to
spec.

> As a matter of fact, pick any trade, not just roofing, and tell me if it
> works that way. Or even more scientific things. Like building and
> architecture. Not to mention medicine. Cooking in a restaurant ? Anodizing
> some parts ? Any more examples ?

Substandard is substandard, and if it's not done right it's done wrong.
It's as simple as that.  I'm not quite as dedicated to the art as Olin,
but code without any sort of comments at all is unfinished work.

Dale
--
A train stops at a train station.  A bus stops at a bus station.
On my desk I have a workstation...

--
http://www.piclist.com#nomail Going offline? Don't AutoReply us!
email @spam@listservRemoveMEspamEraseMEmitvma.mit.edu with SET PICList DIGEST in the body


2001\05\26@051916 by Peter L. Peres

picon face
> It's as simple as that.  I'm not quite as dedicated to the art as Olin,
> but code without any sort of comments at all is unfinished work.

You do not seriously believe that the people who wrote your thousands of
lines of code did not comment it at all I hope ? Maybe their idea of
'finished' implied no comments at the price they were paid. Maybe it was
the pointy headed leader's idea. Or the pointy headed lawyer's ?

Peter

PS: There is a certain piece of open source software (I forget which file)
that contains a single line of comment. It goes like:

// This is a comment. I love comments.

Then it goes on for ~500 lines of C etc without a single explanation or
comment ;-)

--
http://www.piclist.com hint: To leave the PICList
EraseMEpiclist-unsubscribe-requestspam@spam@mitvma.mit.edu


More... (looser matching)
- Last day of these posts
- In 2001 , 2002 only
- Today
- New search...