 |
|
|
|
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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.
It's hard to believe that wikipedia is more informative about what the open
source project does than the wiki for the open source project itself.
--
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
I understand you have a hate/love relationship. :)
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Haskell I presume?...
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Saul Luizaga wrote:
> Haskell I presume?...
No. Virtually every open source project I've ever been hired to look into
the guts of. :-?
--
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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?
--
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] san rrcom> wrote in message
news:49d699b2$1@news.povray.org...
| 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.
|
| It's hard to believe that wikipedia is more informative about what the
open
| source project does than the wiki for the open source project itself.
|
So, contribute to the open source projects.
You like to see the kind of documentation you want, write it.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
pan wrote:
> So, contribute to the open source projects.
Well, duh! Why else would I be trying to find documentation on how the
source code is organized and where to find various classes and interfaces?
> You like to see the kind of documentation you want, write it.
That attitude is exactly the *cause* of the problem. By the time I have
learned enough to be able to write that documentation, it's no longer a
benefit to me to write the documentation. That's *exactly* the way in which
this sort of open source fails.
However, it's pretty trivial to write that sort of documentation if you're
the original author of the code, and takes far less time than actually
writing the code or deciding what it should do or how it should be organized.
--
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:
> 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.
Cheers.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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.
--
- Warp
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Warp wrote:
> Judging from thedailywtf.com, proprietary code isn't always much better
> either.
Especially CAD software - excluding the huge sellers like AutoCAD.
They're actually quite powerful programs, but the documentation is
incredibly poor, and often incorrect. I remember the docs of a certain
EM simulation software giving an example of how to calculate something
that made no sense physically. And the _proper_ way to calculate it was
not in the docs.
--
It's not hard to meet expenses, they're everywhere.
/\ /\ /\ /
/ \/ \ u e e n / \/ a w a z
>>>>>>mue### [at] nawazorg<<<<<<
anl
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
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
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Nicolas Alvarez wrote:
> 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)
Let's exclude from discussion open source software the author doesn't want
you to look at, hmm? :-)
--
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:
> Warp wrote:
>> Judging from thedailywtf.com, proprietary code isn't always much better
>> either.
>
> Quite true, but for different reasons. :-)
See Step 1:
http://blog.objectmentor.com/articles/2008/03/05/clues-for-reading-new-code
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
On 4/4/2009 5:42 PM, clipka wrote:
> At that point, I first take a pee, then a *deep* breath,
I totally understand, peeing always makes me breathe hard, too! :)
--
...Chambers
www.pacificwebguy.com
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Chambers wrote:
> On 4/4/2009 5:42 PM, clipka wrote:
>> At that point, I first take a pee, then a *deep* breath,
>
> I totally understand, peeing always makes me breathe hard, too! :)
Me too, except after asparagus.
--
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
|
|
| |
| |
|
|
|
|
| |
