Saul Luizaga <sau### [at] netscapenet> wrote:
> Darren New wrote:
> > Saul Luizaga wrote:
> >> Haskell I presume?...
> >
> > More specifically, every open source project I've ever been hired to
> > look into that was intentionally designed to be extended or embedded by
> > the end user. None of them (besides Tcl) has ever had any documentation
> > on how you're supposed to use the libraries. Applications, sure.
> > Something that only programmers see? Why the hell would we need any
> > *prose* for that?
> >
> I see. Is there a council or .org that regulates open source projects
> structure that this kind of projects can base their work on? Or at least
> it should be, somewhere they can reference and get their projects in a
> more formal and understandable form.
>
> If not, I think someone would think about it.

Yeah, everyone is waiting for that rather than just digging into the code and
getting the hands dirty. :)

Post a reply to this message

Warp <war### [at] tagpovrayorg> wrote:
> Darren New <dne### [at] sanrrcom> wrote:
> > 50,000 files, 370 meg of code, "developer" web pages like "here's how we
> > capitalize our identifiers and where to put spaces", and "here's how we plan
> > to modify the way we do unit tests", and not a single "this is what the fuck
> > each of the 14 top level directories hold, let alone the other 1500 directories.
>
>   Judging from thedailywtf.com, proprietary code isn't always much better
> either.

5+ Insightful

Post a reply to this message

Saul Luizaga wrote:
> I see. Is there a council or .org that regulates open source projects 

I think it's more that open source authors are writing code for themselves. 
They don't need to document it, because they know what it does. The next 
person coming along can't document it because they *don't* know what it 
does. By the time that next person understands well enough to document it, 
*they* don't need to document it. All of which slows down the adoption of 
that particular piece of open source.

I've come to learn that if your project has a wiki, it probably means "we 
have no documentation, and we're hoping the users will supply it."  A few 
notable exceptions, sure, but not many.

Actually, I think that's a good question for the next person I interview for 
a commercial position: "Have you added functionality to any open source 
project?" Yes.  "Show me the documentation you wrote for programmers who 
come after you."  Ooops.   No wonder software is so unreliable.

It's not like programmers don't know how to document stuff. They just don't 
feel the need to, because it's no benefit to *them*, since they're giving 
the code away for free and don't really care whether someone else can use it.

-- 
   Darren New, San Diego CA, USA (PST)
   There's no CD like OCD, there's no CD I knoooow!

Post a reply to this message

Warp wrote:
>   Judging from thedailywtf.com, proprietary code isn't always much better
> either.

Quite true, but for different reasons. :-)

-- 
   Darren New, San Diego CA, USA (PST)
   There's no CD like OCD, there's no CD I knoooow!

Post a reply to this message

Darren New <dne### [at] sanrrcom> wrote:
> Actually, I think that's a good question for the next person I interview for
> a commercial position: "Have you added functionality to any open source
> project?" Yes.  "Show me the documentation you wrote for programmers who
> come after you."  Ooops.   No wonder software is so unreliable.

That's a good one. Even if it can't serve as a pass/fail criterion (you better
not expect any applicants passing this one ;)) it may kick even the
best-prepared know-all smartass into defensive mode :P

(*Rushes off to hastily throw together a rudimentary doc about POV radiosity and
subsurface scattering...*)

Post a reply to this message

"clipka" <nomail@nomail> wrote:
> Darren New <dne### [at] sanrrcom> wrote:
> > Actually, I think that's a good question for the next person I interview for
> > a commercial position: "Have you added functionality to any open source
> > project?" Yes.  "Show me the documentation you wrote for programmers who
> > come after you."  Ooops.   No wonder software is so unreliable.
>
> That's a good one. Even if it can't serve as a pass/fail criterion (you better
> not expect any applicants passing this one ;)) it may kick even the
> best-prepared know-all smartass into defensive mode :P
>
> (*Rushes off to hastily throw together a rudimentary doc about POV radiosity and
> subsurface scattering...*)

LOL

Post a reply to this message

clipka wrote:
> (you better not expect any applicants passing this one ;))

*I* would pass it!  :-)   Seriously, it boggles me that there are people 
smart enough to do a week's worth of coding without ever having to write 
anything down.

It's not that hard to do. You just spend 20 minutes writing down what you're 
planning to do as you plan it. A one-page "this is how the code is laid out" 
document does wonders.

What would you rather interface to: A protocol specified by an RFC, or a 
protocol specified by a big chunk of C code?

-- 
   Darren New, San Diego CA, USA (PST)
   There's no CD like OCD, there's no CD I knoooow!

Post a reply to this message

Darren New <dne### [at] sanrrcom> wrote:
> *I* would pass it!  :-)   Seriously, it boggles me that there are people
> smart enough to do a week's worth of coding without ever having to write
> anything down.

Well, when not coding for cash, I typically just happily hack away in some kind
of "autopilot" mode, interspersing a few comments (typically to other people's
code I didn't fully understand at first glance ;)), until I run into something
seriously complicated - usually involving a non-trivial interface between two
modules or such, with a chance of generating deadlocks, race conditions,
unhandled errors, and/or poorly defined responsibilities.

At that point, I first take a pee, then a *deep* breath, then hack up about a
page's worth of comments into the source code file (or a separate file
occasionally) about how I want the things to interface, find that there are
loopholes, replace half of the smash with a better approach or more precise
description, and iterate over and over again until I have a clear, airtight
contract for the interface to stick to. Which may take a few hours, or
occasionally days.

*Then* I continue coding.

> It's not that hard to do. You just spend 20 minutes writing down what you're
> planning to do as you plan it. A one-page "this is how the code is laid out"
> document does wonders.

I'm not really good at 20-minutes-docs: As soon as I start documenting, I just
can't keep myself from drilling down into all the details...

> What would you rather interface to: A protocol specified by an RFC, or a
> protocol specified by a big chunk of C code?

Why, the RFC of course.

Note however that the task of interfacing to a protocol is somewhat different
from doing maintenance work on an existing piece of software.

Post a reply to this message

clipka wrote:
> Note however that the task of interfacing to a protocol is somewhat different
> from doing maintenance work on an existing piece of software.

Depends on the kind of maintenance. I'd say using a complicated library, or 
porting it to a new environment, is much closer to interfacing to a protocol 
than it is to maintaining the library.

Sure, fixing someone else's code, or adding functionality? You're going to 
need to read the code. Documentation that tells you what code you don't need 
to read would be great.

Figuring out what goes in the configuration files based by reading the 
configuration file parser? Sucktastic.

-- 
   Darren New, San Diego CA, USA (PST)
   There's no CD like OCD, there's no CD I knoooow!

Post a reply to this message

Darren New wrote:
> What would you rather interface to: A protocol specified by an RFC, or a
> protocol specified by a big chunk of C code?

What if nobody intended the protocol to be used by any other software in the
first place? (making it technically hard to fork the software)

Post a reply to this message