Mailing-List: contact dev-help@httpd.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@httpd.apache.org
Received-SPF: neutral (athena.apache.org: local policy)
From: Rich Bowen <rbowen@rcbowen.com>
Mime-Version: 1.0 (Apple Message framework v1257)
Content-Type: multipart/alternative;
 boundary="Apple-Mail=_F0FDB826-D659-42B7-979C-A443A28FA546"
Subject: Re: Moving on
Date: Fri, 20 Apr 2012 09:46:44 -0400
In-Reply-To: <4F914CE2.20807@opensslfoundation.com>
To: dev@httpd.apache.org
References: <493cebfa-41e5-4eb6-9b99-078d91c5b9b0@iris>
 <4F914CE2.20807@opensslfoundation.com>
Message-Id: <B246B692-3C74-4A5D-AD70-696300BD045B@rcbowen.com>


--Apple-Mail=_F0FDB826-D659-42B7-979C-A443A28FA546
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=us-ascii


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.
>=20
> If we want to make the whole thing bland and faceless then so be it. I =
think it
> will be lessened as a result.
>=20
> If that's "sentimental" then I suppose I am.
>=20
> 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@rcbowen.com :: @rbowen
rbowen@apache.org


--Apple-Mail=_F0FDB826-D659-42B7-979C-A443A28FA546
Content-Transfer-Encoding: quoted-printable
Content-Type: text/html;
	charset=us-ascii

<html><head></head><body style=3D"word-wrap: break-word; =
-webkit-nbsp-mode: space; -webkit-line-break: after-white-space; =
"><br><div><div>On Apr 20, 2012, at 7:47 AM, Dr Stephen Henson =
wrote:</div><br class=3D"Apple-interchange-newline"><blockquote =
type=3D"cite"><span class=3D"Apple-style-span" style=3D"border-collapse: =
separate; font-family: Helvetica; font-style: normal; font-variant: =
normal; font-weight: normal; letter-spacing: normal; line-height: =
normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; =
text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; =
-webkit-border-horizontal-spacing: 0px; -webkit-border-vertical-spacing: =
0px; -webkit-text-decorations-in-effect: none; -webkit-text-size-adjust: =
auto; -webkit-text-stroke-width: 0px; font-size: medium; ">Personally I =
like humorous or thought provoking comments in source files it<br>shows =
the human side of the authors.<br><br>If we want to make the whole thing =
bland and faceless then so be it. I think it<br>will be lessened as a =
result.<br><br>If that's "sentimental" then I suppose I am.<br><br>I'd =
like to hear other peoples opinions on =
this.</span></blockquote><br></div><div><br></div><div>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.</div><div><br></div><div>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! =
;-)</div><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>Comments =
like:</div><div><br></div><div>&nbsp; &nbsp;Abandon all hope, ye who =
read this code. &nbsp;Don't believe the =
name:</div><div><br></div><div>and</div><div><br></div><div><div>&nbsp; =
&nbsp;Open-Source Software: generous&nbsp;programmers from around the =
world all&nbsp;join forces to help you shoot &nbsp;yourself in the foot =
for =
free.</div><div><br></div><div>and</div><div><br></div><div><div>&nbsp; =
&nbsp; Where's the spoons?&nbsp;Where's the spoons?&nbsp;Where's the =
bloody spoons?</div></div><div><br></div><div>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.</div><div><br></div><div>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.</div></div><br><div apple-content-edited=3D"true">
<div style=3D"word-wrap: break-word; -webkit-nbsp-mode: space; =
-webkit-line-break: after-white-space; font-family: Inconsolata; =
">--<br>Rich Bowen<br><a =
href=3D"mailto:rbowen@rcbowen.com">rbowen@rcbowen.com</a> :: =
@rbowen<br><a =
href=3D"mailto:rbowen@apache.org">rbowen@apache.org</a><br><br><br><br><br=
><br></div>
</div>
<br></body></html>=

--Apple-Mail=_F0FDB826-D659-42B7-979C-A443A28FA546--