The fact that the level of knowledge of the audience is uncertain does not obviate the need to address the audience at a certain level.

But that's the problem. At what level?

It's certainly a knotty problem all right, and like most such difficult problems there's one all encompassing solution: make a guess.

You can't just wish the problem away because you'd like the world to be a simpler place.

The idea that everytime any Perl programmer uses a hash slice, he should annotate that usage with # hash slice, still feels faintly ludicrous to me.

And who says that you should? My guess would be that the first usage in a module is probably where it's needed.

Or to quote some of those I found on the net ...

None of which strike me as "ludricous": they're just jokes. Small human touches that give you some sense of the way the programmer was thinking about the code. Even if you don't think that a hash slice is particularly fancy, it can be useful to know that the original programmer did.

(I suggest that the central difficulty here is that you're trying to find some way to make code into some sort of pure mathematical construct, and my own opinion is that it definitely isn't.)

Would you argue against explanatory subroutine and variable names because a really good programmer doesn't need those hints?

Absolutely not, but the sting in the tail of the question is not the reason. It's because they do not create a maintenance problem. Nothing is duplicated; no couplings are created; they can't lie; they are tested.

Sorry, but this is just wrong. As code evolves, the function of a routine can easily drift away from what you would assume from the name of the routine. If you don't refactor the names of your routines when that happens, you can easily end up with a misleading name. (Note: you can help cover these problems with appropriate comments.)

---

---

• Are you posting in the right place? Check out Where do I post X? to know for sure.
• Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:

  <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>

• Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
• Want more info? How to link or How to display code and escape characters are good places to start.