You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@httpd.apache.org by Jim Jagielski <ji...@jaguNET.com> on 1998/03/30 03:44:08 UTC
Re: cvs commit: apache-1.3/src/modules/standard mod_expires.c mod_include.c mod_log_config.c mod_rewrite.c mod_usertrack.c
Dean Gaudet wrote:
>
> This is ridiculous. Apache is 72k lines of code. If we can't keep our
> own symbols from colliding with each other then we've got serious problems.
> We need only one prefix.
I think the whole idea was some sort of logical use of prefixes to
better define the API and which functions are public, private, whatever.
I think that makes sense... It's real easy for 72k lines of code
to become a mess that no one can read or understand.
--
===========================================================================
Jim Jagielski ||| jim@jaguNET.com ||| http://www.jaguNET.com/
"That's no ordinary rabbit... that's the most foul,
cruel and bad-tempered rodent you ever laid eyes on"
Re: cvs commit: apache-1.3/src/modules/standard mod_expires.c
mod_include.c mod_log_config.c mod_rewrite.c mod_usertrack.c
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
Paul Sutton wrote:
>
> Well, debugging is pretty important if you ask me, and people doing
> debugging want things to be both easy to understand and easy to use.
Yes, it's important - but you don't base your nomenclature on what's
easy on the debugger's fingers, you base it on what's most easily
understandable/usable to the customers that are going to be using it.
I doubt that the vocal ones of us on this list could be considered
a majority of that category. <g>
So maybe the thing to do is to *keep* the hide.h thing around, and just
educate UpdateHide appropriately. Then the people doing debugging
in controlled circumstances can just turn the HIDE rule off and
save their fingers - but it's on when we build for distribution.
#ken P-)}
Ken Coar <http://Web.Golux.Com/coar/>
Apache Group member <http://www.apache.org/>
"Apache Server for Dummies" <http://WWW.Dummies.Com/
Re: cvs commit: apache-1.3/src/modules/standard mod_expires.c mod_include.c mod_log_config.c mod_rewrite.c mod_usertrack.c
Posted by Paul Sutton <pa...@c2.net>.
On Sun, 29 Mar 1998, Rodent of Unusual Size wrote:
> Dean Gaudet wrote:
> > Documentation is documentation, it shouldn't be enforced as part of the
> > symbols. You'll notice that I put a bunch of documentation into the
> > header file where I defined (the now-named) ap_vformatter. That is how we
> > should document our API. Every function which is part of the API should
> > be documented like that, and NOTED as being part of the API (or part of
> > whatever sub-part of whatever interface you want to talk about).
>
> Sole documentation of the API in the source? Rubbish. And only
> in the routines that are part of the API? Worse rubbish. As you
> say, documentation is documentation. And it ain't source.
Lets not get too confrontational about this. But for what it's worth, I'm
with Dean on this. We should document API functions fully in the source
code. It hasn't been done in the past, and that is why getting any sort of
external documentation has been so difficult -- people have to figure out
how things are supposed to work from the source. Look at module authors --
they have to read the source anyway to figure things out. If there were
comments all over, it would be unbelievably easier to write modules. By
definition module authors will be able to read source code, so this is
perfectly reasonable. Sure in the end we'd like to have the API documented
outside the source, but once it is fully documented within the source it
is a relatively easy job to extract that information into nicely formatted
documentation. I don't like to see such negative comments addressed at
people who are actually documenting their changes to the API in the
source.
> > But to make us type "apapi_" or "appri_" or whatever is a complete waste
> > of screen width, and typing time.
>
> I'm sorry, but what crap (IMO). Debugging is *not* the normal mode
> of operation for everyone. Between making it easy to understand
> and making it easy to type.. well, the correct choice is clear to me.
Well, debugging is pretty important if you ask me, and people doing
debugging want things to be both easy to understand and easy to use.
Paul
Re: cvs commit: apache-1.3/src/modules/standard mod_expires.c
mod_include.c mod_log_config.c mod_rewrite.c mod_usertrack.c
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
Dean Gaudet wrote:
>
> I use debuggers not only to find known bugs but as a sort of "walk through
> the code on steroids". When I write anything non-trivial, I fire it up
> under a debugger first and breakpoint and step through it reviewing the
> logic step by step. I find when I don't do this and it appears to work
> first try I become a little too elated and stop testing ;)
Hmm, I've done that last myself. <g> And the first sentence as well,
though probably not as much as you. I just don't think it's the norm.
#ken P-)}
Ken Coar <http://Web.Golux.Com/coar/>
Apache Group member <http://www.apache.org/>
"Apache Server for Dummies" <http://WWW.Dummies.Com/
Re: cvs commit: apache-1.3/src/modules/standard mod_expires.c mod_include.c mod_log_config.c mod_rewrite.c mod_usertrack.c
Posted by Rasmus Lerdorf <ra...@lerdorf.on.ca>.
> > Someone trying to learn how Apache works doesn't do it by sitting in
> > front of a debugger.
>
> To be honest, and I'm not just being pedantic, I *did* learn apache this
> way. I use this technique frequently when I have few clues to go on with
> a new program. I walk into a program from main, and I step into every
> function until I get tired of what they do or I understand what they do...
> eventually I get somewhere useful. Or I'll let it fly and run along until
> I do something externally (like make a tcp connection to port 8080) and
> then ^C the debugger and see where it's at, which is probably more
> interesting.
That's also how I figured out the Apache API. I literally spent days in
gdb httpd -X first figuring the various phases of the module header, then
looking at request_rec for different types of requests, and then finally
single-stepping mod_include. One of the off-shoots from this was mod_info
which I wrote simultaneously in another window. It was a summary of what
I learned about Apache module handling.
I don't see how else anybody would grok the .conf file handling code or a
lot of the other startup stuff. It's not documented anywhere.
-Rasmus
Re: cvs commit: apache-1.3/src/modules/standard mod_expires.c mod_include.c mod_log_config.c mod_rewrite.c mod_usertrack.c
Posted by Dean Gaudet <dg...@arctic.org>.
On Mon, 30 Mar 1998, Rodent of Unusual Size wrote:
> Someone trying to learn how Apache works doesn't do it by sitting in
> front of a debugger.
To be honest, and I'm not just being pedantic, I *did* learn apache this
way. I use this technique frequently when I have few clues to go on with
a new program. I walk into a program from main, and I step into every
function until I get tired of what they do or I understand what they do...
eventually I get somewhere useful. Or I'll let it fly and run along until
I do something externally (like make a tcp connection to port 8080) and
then ^C the debugger and see where it's at, which is probably more
interesting.
So I found -X when I stepped past the line which said "if (!one_process)
detach();" and the debugger suddenly had nothing to debug... so I then had
something to grep for in the source code, one_process, and that got me to
-X.
It is a backdoor way to do things... but when presented with a huge amount
of new data it seems like a good way to filter the data.
I use debuggers not only to find known bugs but as a sort of "walk through
the code on steroids". When I write anything non-trivial, I fire it up
under a debugger first and breakpoint and step through it reviewing the
logic step by step. I find when I don't do this and it appears to work
first try I become a little too elated and stop testing ;)
Dean
Re: cvs commit: apache-1.3/src/modules/standard mod_expires.c
mod_include.c mod_log_config.c mod_rewrite.c mod_usertrack.c
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
Dean Gaudet wrote:
>
> On Sun, 29 Mar 1998, Rodent of Unusual Size wrote:
>
> > Sole documentation of the API in the source? Rubbish. And only
> > in the routines that are part of the API? Worse rubbish. As you
> > say, documentation is documentation. And it ain't source.
>
> Would you folks stop putting words in my mouth?! I didn't say that the
> SOLE documentation of the API would be in the source. I just said that
> there better be documentation in the source, and the best place for it is
> in the .h file that defines the interface. I find that easier to keep up
> to date than man pages, or html files.
Ah. Then I apologise; I misuderstood. I didn't mean to put words on
your keyboard.
> I'm sorry. But if you're not using a debugger now and then then I really
> can't understand how you call yourself a developer.
Sure I use a debugger - but I suffer with the extra typing for the
sake of the principle.
> The debugger is a VERY normal mode of
> development. There is no gain in understanding from your extra letters in
> the symbol names, there is only a loss of screen width and typing time.
Someone trying to learn how Apache works doesn't do it by sitting in
front of a debugger. It wouldn't know what to do, and missing the
so-obvious-to-us -X would cack it proper. It learns how Apache
works by reading the code, and whatever documentation is available.
*Then* it might get into debugging sessions.
It'll take some heavy-duty effort to convince me that open-source code
should be written, and interfaces named, for ease of debugging by
experts (in both the code and debugging). But I could be convinced.. maybe.
> Of course I've wasted so much effort debating with you folks that any gain
> in typing time by using ap_ is lost.
You're not the only one involved. Look at it this way: the people who debate
with you expend the effort, too. They must think it's worth it; isn't
their opinion worth anything? Maybe they think of it as being spent rather
than wasted. I know I do; I learn something from this project every day,
often because I take a vocal stand and someone debates my position with
me. I've no corner on being right - but nor do I have a monopoly on being
wrong. Give and take..
#ken P-)}
Ken Coar <http://Web.Golux.Com/coar/>
Apache Group member <http://www.apache.org/>
"Apache Server for Dummies" <http://WWW.Dummies.Com/
Re: cvs commit: apache-1.3/src/modules/standard mod_expires.c mod_include.c mod_log_config.c mod_rewrite.c mod_usertrack.c
Posted by Dean Gaudet <dg...@arctic.org>.
On Sun, 29 Mar 1998, Rodent of Unusual Size wrote:
> Sole documentation of the API in the source? Rubbish. And only
> in the routines that are part of the API? Worse rubbish. As you
> say, documentation is documentation. And it ain't source.
Would you folks stop putting words in my mouth?! I didn't say that the
SOLE documentation of the API would be in the source. I just said that
there better be documentation in the source, and the best place for it is
in the .h file that defines the interface. I find that easier to keep up
to date than man pages, or html files.
> > But to make us type "apapi_" or "appri_" or whatever is a complete waste
> > of screen width, and typing time.
>
> I'm sorry, but what crap (IMO). Debugging is *not* the normal mode
> of operation for everyone. Between making it easy to understand
> and making it easy to type.. well, the correct choice is clear to me.
I'm sorry. But if you're not using a debugger now and then then I really
can't understand how you call yourself a developer. Either you never test
your code completely or you write perfect code. Nobody writes perfect
code. Yes that is an insult. The debugger is a VERY normal mode of
development. There is no gain in understanding from your extra letters in
the symbol names, there is only a loss of screen width and typing time.
Of course I've wasted so much effort debating with you folks that any gain
in typing time by using ap_ is lost.
Dean
Re: cvs commit: apache-1.3/src/modules/standard mod_expires.c mod_include.c mod_log_config.c mod_rewrite.c mod_usertrack.c
Posted by Rasmus Lerdorf <ra...@lerdorf.on.ca>.
> > But to make us type "apapi_" or "appri_" or whatever is a complete waste
> > of screen width, and typing time.
>
> I'm sorry, but what crap (IMO). Debugging is *not* the normal mode
> of operation for everyone. Between making it easy to understand
> and making it easy to type.. well, the correct choice is clear to me.
Personally I don't really care what the functions are called, but it does
worry me that I saw a patch go by which looked like it was indicating that
a bunch of functions I use in my PHP module are deemed private. Like
appri_block_alarms(). How the heck is this a private function? Do I not
need to block alarms while calling register_cleanup()? I also have all
sorts of critical sections in my module where I do not want an alarm to go
off. I just did a quick count. I call this function no less than in 18
separate places in mod_php3.
-Rasmus
Re: cvs commit: apache-1.3/src/modules/standard mod_expires.c
mod_include.c mod_log_config.c mod_rewrite.c mod_usertrack.c
Posted by Rodent of Unusual Size <Ke...@Golux.Com>.
Dean Gaudet wrote:
>
> But naming something like that is a lot like microsoft's hungarian
> notation, which is supposedly useful for something that I'm not clear on.
> "char *pByte"? Wow that's such a useful name! So much more useful than
> "char *str".
Wow, that's so relevant to the discussion. <g>
> Documentation is documentation, it shouldn't be enforced as part of the
> symbols. You'll notice that I put a bunch of documentation into the
> header file where I defined (the now-named) ap_vformatter. That is how we
> should document our API. Every function which is part of the API should
> be documented like that, and NOTED as being part of the API (or part of
> whatever sub-part of whatever interface you want to talk about).
Sole documentation of the API in the source? Rubbish. And only
in the routines that are part of the API? Worse rubbish. As you
say, documentation is documentation. And it ain't source.
> But to make us type "apapi_" or "appri_" or whatever is a complete waste
> of screen width, and typing time.
I'm sorry, but what crap (IMO). Debugging is *not* the normal mode
of operation for everyone. Between making it easy to understand
and making it easy to type.. well, the correct choice is clear to me.
#ken P-)}
Ken Coar <http://Web.Golux.Com/coar/>
Apache Group member <http://www.apache.org/>
"Apache Server for Dummies" <http://WWW.Dummies.Com/
Re: cvs commit: apache-1.3/src/modules/standard mod_expires.c mod_include.c mod_log_config.c mod_rewrite.c mod_usertrack.c
Posted by Paul Sutton <pa...@c2.net>.
On Sun, 29 Mar 1998, Dean Gaudet wrote:
> But naming something like that is a lot like microsoft's hungarian
> notation, which is supposedly useful for something that I'm not clear on.
> "char *pByte"? Wow that's such a useful name! So much more useful than
> "char *str".
Microsoft say it is better, so it must be. Look at all the people that use
it. They can't all be wrong? Even Apache uses it in some of the
windows-only code.
But I've never what benefit it gives you. Besides looking ugly.
Paul
Re: cvs commit: apache-1.3/src/modules/standard mod_expires.c mod_include.c mod_log_config.c mod_rewrite.c mod_usertrack.c
Posted by Dean Gaudet <dg...@arctic.org>.
But naming something like that is a lot like microsoft's hungarian
notation, which is supposedly useful for something that I'm not clear on.
"char *pByte"? Wow that's such a useful name! So much more useful than
"char *str".
Documentation is documentation, it shouldn't be enforced as part of the
symbols. You'll notice that I put a bunch of documentation into the
header file where I defined (the now-named) ap_vformatter. That is how we
should document our API. Every function which is part of the API should
be documented like that, and NOTED as being part of the API (or part of
whatever sub-part of whatever interface you want to talk about).
If it's not part of the API but exported anyhow then say that where the
function is documented. Folks ignoring the documentation get exactly what
they deserve: no forward compatibility.
But to make us type "apapi_" or "appri_" or whatever is a complete waste
of screen width, and typing time.
Dean
On Sun, 29 Mar 1998, Jim Jagielski wrote:
> Dean Gaudet wrote:
> >
> > This is ridiculous. Apache is 72k lines of code. If we can't keep our
> > own symbols from colliding with each other then we've got serious problems.
> > We need only one prefix.
>
> I think the whole idea was some sort of logical use of prefixes to
> better define the API and which functions are public, private, whatever.
> I think that makes sense... It's real easy for 72k lines of code
> to become a mess that no one can read or understand.
>
>
> --
> ===========================================================================
> Jim Jagielski ||| jim@jaguNET.com ||| http://www.jaguNET.com/
> "That's no ordinary rabbit... that's the most foul,
> cruel and bad-tempered rodent you ever laid eyes on"
>