Searching \ for '[OT]: 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/index.htm?key=documenting+embedded
Search entire site for: 'documenting embedded software'.

Exact match. Not showing close matches.
PICList Thread
'[OT]: documenting embedded software'
2001\05\23@154214 by Barry Gershenfeld

picon face
Yep, unfortunately, it doesn't seem to be limited to the
contractors.  I'm in this situation right now, there's hardly
a scrap of documentation anywhere.  I don't even have names
on the modules to know who it was that didn't put in comments!
Well, that's easy, it's everybody.  Meanwhile I don't appear
to be making any "progress" because all I do all day is write
documentation. :-)

My latest trick is this:

#include docs.h

docs.h is nothing but comments and it talks about the architecture
of the whole project.  You can't "lose" it, either--the project
won't compile without it.  Anybody smart enough to figure out
they can delete the reference is probably smart enough to know
why they shouldn't.

Come to think of it, there _is_ a PIC in this thing.

Oh, I don't know how many "inches thick" the source code is.  I
don't kill trees.  TextPad is a wonderful thing.

Barry

(Retagged from [PIC])

{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@155634 by Kev

picon face
Trees are a renewable resource.  It is in your best interest to treat them
as a such, just as you would any other "crop".  This encourages people to
replant & regrow.

> Oh, I don't know how many "inches thick" the source code is.  I
> don't kill trees.  TextPad is a wonderful thing.
>
> Barry

--
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@160558 by Barry Gershenfeld

picon face
I was being funny.  The real problem is that I can't
yell "find 'I2CByte(' at a stack of paper.  That's
why I prefer the computer.

My attempts at generating schedules (using MS Project, no
less) is what kills trees :)

Barry


At 03:56 PM 5/23/01 -0400, you wrote:
>Trees are a renewable resource.  It is in your best interest to treat them
>as a such, just as you would any other "crop".  This encourages people to
>replant & regrow.
>
>> Oh, I don't know how many "inches thick" the source code is.  I
>> don't kill trees.  TextPad is a wonderful thing.

--
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@180603 by Spehro Pefhany

picon face
At 03:56 PM 5/23/01 -0400, you wrote:
>Trees are a renewable resource.  It is in your best interest to treat them
>as a such, just as you would any other "crop".  This encourages people to
>replant & regrow.

You might be surprised how picky the big US/Cdn. consumers of forest products
are to assure that they are really buying renewable resources.

It's mostly a bureaucratic auditing/ISO certification process in Ontario,
but in some other places they have had to actually change their practices.
The likes of Home Despot etc. don't want any possibility of consumers
boycotting their products. Just as the giant D*ney corporation checks
fire escapes and such like in their China sweatshops.

Best regards,


=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Spehro Pefhany --"it's the network..."            "The Journey is the reward"
spam_OUTspeffTakeThisOuTspaminterlog.com             Info for manufacturers: http://www.trexon.com
Embedded software/hardware/analog  Info for designers:  http://www.speff.com
Contributions invited->The AVR-gcc FAQ is at: http://www.bluecollarlinux.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@181855 by Dale Botkin

flavicon
face
On Wed, 23 May 2001, Barry Gershenfeld wrote:

> My latest trick is this:
>
> #include docs.h
>
> docs.h is nothing but comments and it talks about the architecture
> of the whole project.  You can't "lose" it, either--the project
> won't compile without it.  Anybody smart enough to figure out
> they can delete the reference is probably smart enough to know
> why they shouldn't.

Fantastic idea.  Consider it stolen.  8-)

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 list server can filter out subtopics
(like ads or off topics) for you. See http://www.piclist.com/#topics


2001\05\23@184614 by Dale Botkin

flavicon
face
Yes...  I much prefer electronic copies because they're searchable.  This
time I have only paper copies, aand it sucks.

On Wed, 23 May 2001, Barry Gershenfeld 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@204041 by Mark Newland

flavicon
face
I work as a contractor on the hardware side of things.  I have had several jobs
where there was not only no proper docs on the software (I.E. So what does the
program do?  Reply: I don't know!!!) but no proper documentation on the hardware
either.  Following is a actual conversation at one of my previous jobs:

    Me: So where is the schematics for this product?
    Boss:  There isn't any.  It's kind of like this product over here but
different!
    Me: So where is the schematic for this other product?
    Boss: We don't have that either but it's like this schematic here but
different!
    Me: Is there anything that tells what these differences are?
    Boss: NO!!!

--
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\24@031922 by D Lloyd

flavicon
face
part 1 1304 bytes content-type:text/plain; charset=us-ascii
So, this company were not ISO accredited? ;-) ?




(Embedded     Mark Newland <.....apeKILLspamspam@spam@ESKIMO.COM>KILLspamspam@spam@MITVMA.MIT.EDU>
image moved   24/05/2001 01:38
to file:
pic07720.pcx)





Please respond to pic microcontroller discussion list
     <PICLISTspamKILLspamMITVMA.MIT.EDU>
Sent by:  pic microcontroller discussion list <.....PICLISTKILLspamspam.....MITVMA.MIT.EDU>


To:   EraseMEPICLISTspam_OUTspamTakeThisOuTMITVMA.MIT.EDU
cc:
Subject:  Re: [OT]: documenting embedded software

Security Level:?         Internal


I work as a contractor on the hardware side of things.  I have had several
jobs
where there was not only no proper docs on the software (I.E. So what does
the
program do?  Reply: I don't know!!!) but no proper documentation on the
hardware
either.  Following is a actual conversation at one of my previous jobs:

    Me: So where is the schematics for this product?
    Boss:  There isn't any.  It's kind of like this product over here but
different!
    Me: So where is the schematic for this other product?
    Boss: We don't have that either but it's like this schematic here but
different!
    Me: Is there anything that tells what these differences are?
    Boss: NO!!!

--
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 131 bytes
--
http://www.piclist.com hint: The PICList is archived three different
ways.  See http://www.piclist.com/#archives for details.


2001\05\24@151333 by michael brown

flavicon
face
Since the original post was about implementing standards for documentation,
here is my 2¢.  Way back when, when I was in the military my group didn't
have much to do in the way of programming.  So my (our) supervisor decided
that we needed to bring all the systems documentation up to the "standards".
It didn't take long to figure out that you could write documentation that
was completely and precisely according to "standards", BUT(<---really big
BUT) was totally useless.  If you strictly adhered to the "standards"  the
resultant documentation failed to include anything that was actually
important.  If you tried to include the important aspects of a system, it
would be rejected because it didn't adhere to the "standards".

<pertaining to the current thread>

Don't get me wrong, comments within the code are as important as the actual
code itself (IMHO).  But, trying to "inflict" standards upon documentation
techniques often results in "less than desirable results".  It takes far
less time to comment the code than to actually write it.  My experience also
indicates (no surprise here) that when a programmer says, "I'll come back
and document it later" that this is as likely as him (or her) winning the
lottery and then sharing  the winnings.  On many occasions I have ended up
re-writing code (especially "clever" code) because without comments it was
indecipherable.  Except, of course, in the case of COBOL "the self
documenting language" (extreme sarcasm intended).  Anyone caught writing
uncommented code should be beaten about the head and shoulders until common
sense sets in.  ;o)  Finally, as with many things in life, the Law of
Reciprocity applies.  What goes around comes around.  When you think that
some string of code doesn't need comments, it will often be you who has to
try and figure it out later.  Tell me which item takes longer; writing some
comments, or beating your head against the proverbial wall for a while and
then, finally, rewriting the code.

This concludes my sermon for today.  Take care everyone and TTYL.

Michael Brown
Instant Net Solutions
http://www.KillerPCs.net

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


2001\05\24@181103 by Dale Botkin

flavicon
face
On Thu, 24 May 2001, michael brown wrote:

8< snippage..
> Finally, as with many things in life, the Law of
> Reciprocity applies.  What goes around comes around.

Or my own favorite:

Time wounds all heels.

I think I made that up, but I've been using it for so long I've forgotten.

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@183029 by Bill Westfield

face picon face
There are a couple issues here.

1) Separate documentation (manuals) vs internal documentation (ie comments)
2) "Standards" vs good practices.
3) what to do with undocumented, uncommented code that you inherit.

I think most people agree that actual coding for largish projects should
be done AFTER you have described what the code is going to do
("Functional specificatio" here) and how it is going to do it (design
specification.)  These specifications are valuable, and can include flow
charts, pseudocode, and other pre-coding aids to understanding what goes
on.  In a consulting environment, one would hope that the first spec
(what it should do) would be provided by the customer, and the second
would be provided by the engineer (and perhaps reviewed by the
customer.)  Having standard formats for this sort of thing is a not a
bad idea, as long as most of what you do fits those formats.  There is a
tendancy for functions to expand and designs to change somewhat as the
project continues, without modifying the spec documents (this is bad -
try to avoid it.)

There is, IMO, no excuse for not commenting your code, or for stripping
comments from your code before providing it to the customer :-( Whether
the comments are sufficient for the "next generation" contractors to
"get a clue" is dependent on a lot of different things.  There are some
complications here as well (what about your well-worn library and macro
code that is NOT part of what the customer gets exclusive rights to?)
One hopes that one does a good enough job that the "next contractor"
will be you, right?

There's another level of documentation, usually prepared when code will be
sold as "intellectual property", or when you're explicitly "handing off" a
project to someone you know is going to extensive additional work on it.
"Porting guides", "Suggested improvements", detailed explanations of all
the tricky bits you had to do to get the !@&#^@ ethernet controller to
behave, stuff like that.  I can't see that this would be "free" to a
customer, because it IS something that goes beyond the design and code
that you were supposed to make...  (IMO, this stuff is pretty hard to
write well, but anything is better than nothing...)

BillW

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


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