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:

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

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