Post by thread:[OT]: documenting embedded software

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}>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 > >> Then you can do as our contractors do......don't document it. The ultimate >> job security ;-) >> >> Dan -- 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

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

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_OUTspeffTakeThisOuTinterlog.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

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

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}> 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 > > -- 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

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 1 1304 bytes content-type:text/plain; charset=us-ascii So, this company were not ISO accredited? ;-) ? (Embedded Mark Newland <.....apeKILLspam@spam@ESKIMO.COM>KILLspam@spam@MITVMA.MIT.EDU> image moved 24/05/2001 01:38 to file: pic07720.pcx) Please respond to pic microcontroller discussion list <PICLISTKILLspamMITVMA.MIT.EDU> Sent by: pic microcontroller discussion list <.....PICLISTKILLspam.....MITVMA.MIT.EDU> To: EraseMEPICLISTspam_OUTTakeThisOuTMITVMA.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.

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.

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.

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.