For you Linux programmers out there?

[Chris Miller]

On 9/5/07, Knapp <magick.crow at gmail.com> wrote:
> >D. Michael McIntyre: I keep trying to say something here without
> running on, and two hours later, I
> >don't have anything simple to say on this topic.  If I'm going to write an
> >essay about the vagaries of documenting Linux projects, I may as well do it
> r>ight, and publish it on a blog or something.  Or better yet, figure out some
> >way to get someone to pay me to publish it.  :D
> >The jist of it, though, is that it's a crappy and nearly impossible job.
>
> >Criss Miller: It's really difficult to properly document code.  Some
> bits leave you
> >wondering how on earth someone could not understand the code that you
> >just wrote, and those often are the parts that need documenting the
> >most.  Coders have a notorious lack on an internal barometer to tell
> >them when to doc and when not to doc.  It's not something that saying
> >something can fix.
>
>
> Anyone that write code can write docs (but maybe not in English).
> Maybe not good ones but they can do it. If they put the time in to do

Let me explain "The Zone" to you then.  "The Zone" is a programming
phenomena which occurs when you can literally see entire directories
of code in your head, all at once.  It's a kind of nirvana that you
search for, mainly because code from this state is only very rarely
buggy or slow.  I hypothesize that it's a result of the subconscious
brain depositing a finished product into the consciousness of the
individual.  Aside from my crude explanations, let me make my point.

When in the zone, it's like stopping an oil tanker at sea.  From the
time the skipper calls all stop and the engine room locks the screws,
it take about six miles or more for that boat to come to a full and
complete dead-in-the-water stop.  Same thing for a programmer in the
zone.  I have come out of the zone realizing I haven't eaten a meal
and it's time for the next meal.

Unfortunately, docs aren't part of the zone.  Thus why the best and
most useful parts of applications have zero docs.

> it, it will help. Once they have done that it makes it much easier for
> the next poor soul to come along and make it better writing.

Yes, I agree there.

> I see no reason that programmer can not do this. Yes, we all hate it
> but don't we all hate lots of things we do everyday? And would the
> world not be much better, if we all spent half our programming time
> doing docs?

Most of my time is spent reading docs to best use existing APIs.  Not
so much with APIs I'm familiar with, but for me to get really comfy
with an API it takes about 7,000 lines of real jewel code to get to
that level of comprehension.  If you cut that code time in half again,
I'd never get anything done!

> I think there are 2 types of docs being talked about here. One is the
> documentation of code and the other is the book that goes with the
> program. I was talking about the book in the first place but talking
> about documenting code is also very important.

Oh................

<quotable>That was stoopid of me</quotable>

My meter stick of program design is: if it needs a book, YOU DIDN'T DO IT RIGHT!

> So that brings me to a question. Have you ever gone back to your code
> 3 years later that was done in some language that you have for gotten
> and tried to figure out what you were doing in the undocumented
> obvious code sections? I think that every line or at least every loop

No, my memory isn't actually that bad for stuff I've written.  I spend
most of that nostalgia time going "man, I was a complete and total
n00b three years ago, this could be done better..."

> and function should have documentation. Old code is a bear to
> understand! Now what about that poor person who comes after you and
> just learned that old no longer used language after you retire?
>
> Nether type of doc is fun (at least to me) but both types are a total
> must do; if we are to make anything that others will ever use or
> update.

My general stance is that if you can't figure out what SourceScope
does, then I really can't help you at all.  I agree, however, larger
programs (think GIMP in size) need to be documented.  But the entire
UNIX philosophy is to build large systems using small blocks.  Hence
manpages and all the command line functionality.  Much of Linux is
command-line centric, and booting itself is a command-line activity.
You could technically type in the commands necessary to boot after you
had a working tty.  It'd take for-freaking-ever, but it's possible.

Beats the heck out of Windows and it's dynamically linked libraries
with archives of undocumented functions you need to call.  I should
share a Vista story, but I'll do it in another thread.