Chambers wrote:
> Point taken.  I got in the bad habit of using my headers as my 
> documentation, and coding my implementations to match them, rather than 
> keeping the documentation separate :)

That's a perfectly reasonable way to do it in a language that requires 
headers to start with.  A language with javadoc-like features? Nah.

The cool thing about Eiffel is you can not only produce a document that's 
the equivalent of a .H or javadoc (doxygen, etc) file, but also a "flat" 
version that includes all the documentation from the parent classes that you 
didn't override. So if you want the docs for "hashtable implemented using 
arrays of streams" documentation, you don't need to grope through three or 
more superclasses just to understand what that one class does.

> Of course, being Visual Studio, the Class explorer offers similar 
> functionality, but it's not in the same form I'm used to from looking at 
> header files.  Ah, well, I'll adjust eventually.

Yep. And Smalltalk is even more different, since you can open browsers on 
things like "all classes that implement a method called X". Smalltalk being 
one of those "duck-typing" languages.

Speaking of which, what is "duck typing" that isn't just "dynamic typing"?
WTF does that even mean?

> Yes, it is rare.  But good, so keep it up :)

I remember once way back, having written docs for the library, I was sitting 
there coding it up. (The project was a rewrite from BASIC to C, so I had a 
real good idea what the library needed to do.) I had a stack of 
documentation, and I was implementing each function.  The "best" programmer 
in the company comes up and asks what I'm doing, and I tell him. He points 
to the inch-thick print-out, asks what it is, and I tell him it's the docs. 
He says, sounding baffled, "How can you write the docs before the program?" 
I ask him "How can you know when you're done programming without writing the 
docs first?"

Ah, fun times. The first time I ever completely stopped taking a job seriously.

-- 
   Darren New, San Diego CA, USA (PST)
   "We'd like you to back-port all the changes in 2.0
    back to version 1.0."
   "We've done that already. We call it 2.0."

Post a reply to this message