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
[email protected] :: @rbowen
[email protected]
