Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Apache: Dev

Moving on

 

 

Apache dev RSS feed   Index | Next | Previous | View Threaded


i.galic at brainsware

Apr 20, 2012, 4:25 AM

Post #1 of 15 (962 views)
Permalink
Moving on

Hi folks,

I started cleaning out mod_ssl and mod_rewrite's comments
in order for them to be accessible to mere mortals. Similarly
as we have started doing with their respective documentation.

The patches can be found here:

http://sprunge.us/VCZB
http://sprunge.us/gbNj

I will commit them unless someone objects that these sort
of comments have more value beyond the purely sentimental.

So long,

i

--
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE


shenson at opensslfoundation

Apr 20, 2012, 4:47 AM

Post #2 of 15 (949 views)
Permalink
Re: Moving on [In reply to]

On 20/04/2012 12:25, Igor Galić wrote:
> Hi folks,
>
> I started cleaning out mod_ssl and mod_rewrite's comments
> in order for them to be accessible to mere mortals. Similarly
> as we have started doing with their respective documentation.
>
> The patches can be found here:
>
> http://sprunge.us/VCZB
> http://sprunge.us/gbNj
>
> I will commit them unless someone objects that these sort
> of comments have more value beyond the purely sentimental.
>

Personally I like humorous or thought provoking comments in source files it
shows the human side of the authors.

If we want to make the whole thing bland and faceless then so be it. I think it
will be lessened as a result.

If that's "sentimental" then I suppose I am.

I'd like to hear other peoples opinions on this.

Steve.
--
Dr Stephen Henson. OpenSSL Software Foundation, Inc.
1829 Mount Ephraim Road
Adamstown, MD 21710
+1 877-673-6775
shenson [at] opensslfoundation


ruediger.pluem at vodafone

Apr 20, 2012, 4:55 AM

Post #3 of 15 (950 views)
Permalink
RE: Moving on [In reply to]

> -----Original Message-----
> From: Dr Stephen Henson [mailto:shenson [at] opensslfoundation]
> Sent: Freitag, 20. April 2012 13:48
> To: dev [at] httpd
> Subject: Re: Moving on
>
> On 20/04/2012 12:25, Igor Galić wrote:
> > Hi folks,
> >
> > I started cleaning out mod_ssl and mod_rewrite's comments
> > in order for them to be accessible to mere mortals. Similarly
> > as we have started doing with their respective documentation.
> >
> > The patches can be found here:
> >
> > http://sprunge.us/VCZB
> > http://sprunge.us/gbNj
> >
> > I will commit them unless someone objects that these sort
> > of comments have more value beyond the purely sentimental.
> >
>
> Personally I like humorous or thought provoking comments in source
> files it
> shows the human side of the authors.
>
> If we want to make the whole thing bland and faceless then so be it. I
> think it
> will be lessened as a result.
>
> If that's "sentimental" then I suppose I am.
>
> I'd like to hear other peoples opinions on this.

+1

Regards

Rüdiger


trawick at gmail

Apr 20, 2012, 4:57 AM

Post #4 of 15 (947 views)
Permalink
Re: Moving on [In reply to]

On Fri, Apr 20, 2012 at 7:47 AM, Dr Stephen Henson
<shenson [at] opensslfoundation> wrote:
> On 20/04/2012 12:25, Igor Galić wrote:
>> Hi folks,
>>
>> I started cleaning out mod_ssl and mod_rewrite's comments
>> in order for them to be accessible to mere mortals. Similarly
>> as we have started doing with their respective documentation.
>>
>> The patches can be found here:
>>
>>    http://sprunge.us/VCZB
>>    http://sprunge.us/gbNj
>>
>> I will commit them unless someone objects that these sort
>> of comments have more value beyond the purely sentimental.
>>
>
> Personally I like humorous or thought provoking comments in source files it
> shows the human side of the authors.
>
> If we want to make the whole thing bland and faceless then so be it. I think it
> will be lessened as a result.
>
> If that's "sentimental" then I suppose I am.
>
> I'd like to hear other peoples opinions on this.

Ralf's style isn't my style, but I suggest we keep his banner for
sentimental reasons and also the contribution lines.

>
> Steve.
> --
> Dr Stephen Henson. OpenSSL Software Foundation, Inc.
> 1829 Mount Ephraim Road
> Adamstown, MD 21710
> +1 877-673-6775
> shenson [at] opensslfoundation



--
Born in Roswell... married an alien...


rbowen at rcbowen

Apr 20, 2012, 6:46 AM

Post #5 of 15 (941 views)
Permalink
Re: Moving on [In reply to]

On Apr 20, 2012, at 7:47 AM, Dr Stephen Henson wrote:

> Personally I like humorous or thought provoking comments in source files it
> shows the human side of the authors.
>
> If we want to make the whole thing bland and faceless then so be it. I think it
> will be lessened as a result.
>
> If that's "sentimental" then I suppose I am.
>
> I'd like to hear other peoples opinions on this.


My comment on this is that humorous comments can be good, and they can be intimidating and confusing - particularly for people who don't get the joke, and in particular for those whose first language is not English or other related languages or whose culture is not conducive to humor in a technical context. People who are in the know, and get the jokes, don't see this as a problem because, well, they get the joke.

I'm reminded of the Python documentation, where every other thing is a monty python joke. All well and good if you get the joke, but if you don't, it's just baffling. This separation often occurs between those of us from either the US, or western european nations, and people from the rest of the world (i.e., most of humanity.) and serves, in part, to perpetuate an under-representation from those cultures. (Not sure what's up with those Sri Lankans! ;-)

Humor in the code, and in the documentation, does indeed provide a human side, and inside jokes are something that binds together communities. However, it can also be the thing that makes people reluctant to change existing code, because it's so clearly "owned" by one particular person.

This is something of a soap-box for me, so I suppose I'm not speaking just about mod_ssl, but documentation/comments in general.

Comments like:

Abandon all hope, ye who read this code. Don't believe the name:

and

Open-Source Software: generous programmers from around the world all join forces to help you shoot yourself in the foot for free.

and

Where's the spoons? Where's the spoons? Where's the bloody spoons?

for example, contribute nothing to the code, and serve to confuse, intimidate, and generally discourage people who want to contribute to the effort, and aren't inside the joke yet. It may be that they should just get over it and that I'm being overly sensitive, but, well, you asked for other opinions. That's mine.

This simply one small example, in one project, where I see this problem. It's not an enormous problem, and I'm sure that most folks don't even think it's a problem. But it's something that I've been thinking about for a few years.

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache


tevans.uk at googlemail

Apr 20, 2012, 6:58 AM

Post #6 of 15 (942 views)
Permalink
Re: Moving on [In reply to]

On Fri, Apr 20, 2012 at 2:46 PM, Rich Bowen <rbowen [at] rcbowen> wrote:
> …
> and
>
>     Where's the spoons? Where's the spoons? Where's the bloody spoons?
>

But with no mention of swimming pools full of puppies or Lord
Palmerston? Of course no one gets it...

Tom

(I have, of course, just demonstrated both the good and bad of
humorous comments.)


shenson at opensslfoundation

Apr 20, 2012, 7:15 AM

Post #7 of 15 (941 views)
Permalink
Re: Moving on [In reply to]

On 20/04/2012 14:58, Tom Evans wrote:
> On Fri, Apr 20, 2012 at 2:46 PM, Rich Bowen <rbowen [at] rcbowen> wrote:
>> …
>> and
>>
>> Where's the spoons? Where's the spoons? Where's the bloody spoons?
>>
>
> But with no mention of swimming pools full of puppies or Lord
> Palmerston? Of course no one gets it...
>
>

I was either that, bicycles or asking if someone had passed their driving test.

Steve.
--
Dr Stephen Henson. OpenSSL Software Foundation, Inc.
1829 Mount Ephraim Road
Adamstown, MD 21710
+1 877-673-6775
shenson [at] opensslfoundation


rbowen at rcbowen

Apr 20, 2012, 7:34 AM

Post #8 of 15 (941 views)
Permalink
Re: Moving on [In reply to]

On Apr 20, 2012, at 10:15 AM, Dr Stephen Henson wrote:

>> But with no mention of swimming pools full of puppies or Lord
>> Palmerston? Of course no one gets it...
>>
>>
>
> I was either that, bicycles or asking if someone had passed their driving test.


Thank you, both of you, for further illustrating my point. Now, ask yourself whether your mutual chuckle was worth making most of the rest of us feel like we were outside some shared joke.

For myself, I'm not sure I care. I'm somewhat used to being a foreigner in a culture of shared jokes, and one learns to ignore it. But some people find it very alienating, and this is a loss to all of us.

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache


tevans.uk at googlemail

Apr 20, 2012, 7:39 AM

Post #9 of 15 (943 views)
Permalink
Re: Moving on [In reply to]

On Fri, Apr 20, 2012 at 3:34 PM, Rich Bowen <rbowen [at] rcbowen> wrote:
> Thank you, both of you, for further illustrating my point. Now, ask yourself
> whether your mutual chuckle was worth making most of the rest of us feel
> like we were outside some shared joke.
>

That was kind of my point, hence why I pointed it out..

Cheers

Tom


mi+thun at aldan

Apr 20, 2012, 8:14 AM

Post #10 of 15 (940 views)
Permalink
Re: Moving on [In reply to]

On 20.04.2012 09:46, Rich Bowen wrote:
> My comment on this is that humorous comments can be good, and they can be
> intimidating and confusing - particularly for people who don't get the joke,
> and in particular for those whose first language is not English or other
> related languages or whose culture is not conducive to humor in a technical
> context. People who are in the know, and get the jokes, don't see this as a
> problem because, well, they get the joke.
In my opinion, this is a good argument to discourage such style from appearing
in new comments. But it does not seem enough to rephrase the existing ones.
Clarifications can be added, but the older comments should persist for as long
as they remain technically correct.

Yours,

-mi


draht at suse

Apr 20, 2012, 8:27 AM

Post #11 of 15 (940 views)
Permalink
RE: Moving on [In reply to]

> > Personally I like humorous or thought provoking comments in source
> > files it
> > shows the human side of the authors.
> >
> > If we want to make the whole thing bland and faceless then so be it. I
> > think it
> > will be lessened as a result.
> >
> > If that's "sentimental" then I suppose I am.
> >
> > I'd like to hear other peoples opinions on this.
>
> +1
> Regards
> Rdiger

+1
(if this counts, in comparison to major contributors on the list)

There was a piece of software some years ago where in one of the larger
.c files someone complained about the manipulative and back-stabbing
qualities of his step mother. Very entertaining, and certainly absolutely
no harm.
The code itself was cleanest in the .c file about the step mother. Guess
special hygiene was applied.


Roman.


covener at gmail

Apr 20, 2012, 9:04 AM

Post #12 of 15 (942 views)
Permalink
Re: Moving on [In reply to]

> In my opinion, this is a good argument to discourage such style from
> appearing in new comments. But it does not seem enough to rephrase the
> existing ones. Clarifications can be added, but the older comments should
> persist for as long as they remain technically correct.

+1, unless they're a distraction in the guts of something I'm not so
keen on ripping this stuff out after so long.


wrowe at rowe-clan

Apr 20, 2012, 12:33 PM

Post #13 of 15 (940 views)
Permalink
Re: Moving on [In reply to]

On 4/20/2012 6:25 AM, Igor Galić wrote:
> Hi folks,
>
> I started cleaning out mod_ssl and mod_rewrite's comments
> in order for them to be accessible to mere mortals. Similarly
> as we have started doing with their respective documentation.
>
> The patches can be found here:
>
> http://sprunge.us/VCZB
> http://sprunge.us/gbNj
>
> I will commit them unless someone objects that these sort
> of comments have more value beyond the purely sentimental.

I'm happy with such changes on trunk. They are fun, but the module
has changed radically since it was written, RSE should no longer be
assigned the majority of the blame ;-P

He should be assigned attribution under ABOUT_APACHE (oh my that's grown
into an entire novel). It only needs to be placed in NOTICE if subject
to an advertising clause (the donation predates AL 2.0).

Please ***do not backport***. It's worse than whitespace changes, because
at least whitespace changes can be skipped with command line options.


i.galic at brainsware

Apr 20, 2012, 12:47 PM

Post #14 of 15 (941 views)
Permalink
Re: Moving on [In reply to]

----- Original Message -----
> On 4/20/2012 6:25 AM, Igor Galić wrote:
> > Hi folks,
> >
> > I started cleaning out mod_ssl and mod_rewrite's comments
> > in order for them to be accessible to mere mortals. Similarly
> > as we have started doing with their respective documentation.
> >
> > The patches can be found here:
> >
> > http://sprunge.us/VCZB
> > http://sprunge.us/gbNj
> >
> > I will commit them unless someone objects that these sort
> > of comments have more value beyond the purely sentimental.
>
> I'm happy with such changes on trunk. They are fun, but the module
> has changed radically since it was written, RSE should no longer be
> assigned the majority of the blame ;-P
>
> He should be assigned attribution under ABOUT_APACHE (oh my that's
> grown
> into an entire novel). It only needs to be placed in NOTICE if
> subject
> to an advertising clause (the donation predates AL 2.0).
>
> Please ***do not backport***. It's worse than whitespace changes,
> because
> at least whitespace changes can be skipped with command line options.

Bill,

I did absolutely not intend to back-port this.
Given the majority of the feedback I've received, I'm not going to
commit it on trunk either.
Instead I will be moving on. Leaving it to braver committers to fix
that what isn't broken.

i

--
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE


kyanha at kyanha

Apr 20, 2012, 5:55 PM

Post #15 of 15 (943 views)
Permalink
Re: Moving on [In reply to]

On Fri, Apr 20, 2012 at 7:34 AM, Rich Bowen <rbowen [at] rcbowen> wrote:
> Thank you, both of you, for further illustrating my point. Now, ask yourself
> whether your mutual chuckle was worth making most of the rest of us feel
> like we were outside some shared joke.
>
> For myself, I'm not sure I care. I'm somewhat used to being a foreigner in a
> culture of shared jokes, and one learns to ignore it. But some people find
> it very alienating, and this is a loss to all of us.

I have no strong feelings one way or the other.

But is it httpd's job to make up for deficiencies in its users' socialization? If so, how far will it go to do so?

(In-jokes are one of the Shared Experiences that lead to camaraderie, both for being within them and for being outside of them. If it is alienating, perhaps an explanation that they are in-jokes and they are not to be taken seriously, and also by the way if the reader doesn't know the reference she could look up specific keywords? I find that alienation is much more easily overcome than blandness.)

-Kyle H
Attachments: Verify This Message with Penango.p7s (3.93 KB)

Apache dev RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.