My editor has folding. I don't use it. I put the pod with the function. It's easier to maintain, and I don't find any problem doing a "find" on the function I'm interested in and hitting "next" once or twice. Or hitting the "next function" key combo. Really, it's not the issue (for most of us) that you make it out to be. Further, I strongly, strongly disagree with your statement that this makes the code harder to maintain. The code's comments (and external API) are part of the code. Separation is going to lead to disparity, which is then a bug in the code (since the docs are part of the code). To me, one of the points of intermixing POD with code is the huge convenience of colocation of code and comments making it at least plausible to keep them in sync. Which, interestingly, is also the way that Doxygen or even Javadoc. I suspect these guys know just as much about this as do the guys designing Perl when they encourage intermixing of code and documentation.

As for the existence of __END__, I'm not sure you realise that it's merely a point for the interpreter to stop and leave the file pointer in case you want to read it with the *DATA filehandle. It allows you to embed data in your source file without actually making it in your source. Many people put their POD there, but I'm not sure that's the purpose of it, merely a blessed way to use it. Personally, I think that's premature optimisation - putting it there prevents the perl parser from wasting valuable cycles looking past the POD, because it has stopped interpreting by then. But if you do things this way, then you'll never be able to use __END__ in its other manner: to provide a marker for your *DATA filehandle. If you do, then YOU will be responsible for ignoring the POD, and, personally, I'd rather that Perl's C-based interpreter skipped the POD than for me to write my own (or adapt an existing module) which can't be any faster than the native code. It's just code I don't see a need to write or maintain, just for some "convenience" (your meaning, not mine) of keeping my code easy to find.

>> My editor has folding. I don't use it. I put the pod with the function. It's easier to maintain, and I don't find any problem doing a "find" on the function I'm interested in and hitting "next" once or twice. Or hitting the "next function" key combo. Really, it's not the issue (for most of us) that you make it out to be. Further, I strongly, strongly disagree with your statement that this makes the code harder to maintain. The code's comments (and external API) are part of the code. Separation is going to lead to disparity, which is then a bug in the code (since the docs are part of the code). To me, one of the points of intermixing POD with code is the huge convenience of colocation of code and comments making it at least plausible to keep them in sync. Which, interestingly, is also the way that Doxygen or even Javadoc. I suspect these guys know just as much about this as do the guys designing Perl when they encourage intermixing of code and documentation.

As I mentioned I would likely put very abbreviated header comments - one line on what the function did, and arguments, with the function. The thing I don't like doing is putting extensive comments, not related to the implementation or calling (e.g. args and return values), at the function's head. The comments I'd separate out are the ones beyond this, which are likely useful for those learning your API, but not very interesting once someone has learned it. So the issue is how much of the "code's comments" are part of the code. Should I jam a tutorial in the notes (probably not, although SYNOPSIS shows a short how-to-use use case...should I put something like this in the function header comments)? I'm trying to distinguish between comments that are useful to people who understand the API (and thus just need a reminder), and the code for people just learning the API (which often introduces concepts). There are certainly comments that enhance readability and maintainability, no argument there. Those are the comments that would be colocated with the function. For example, comments that have to do with the implementation (which would be internal to the function). But there are certainly comments that do not help with maintenance. For example, anything aimed at a new user of the API. These tend to be fairly long, and possibly conceptual. While you may leave all of this material with the function, I find it detracts, so I want to separate it out (if this isn't helping maintenance or the basic use then it must be detracting as I have to wade through it to get to the other stuff).

As for intermixing code and documentation in other languages as well as Perl, the idea is to keep it in the same file. After this, there is a choice of where to put code and comments relative to each other. There are some comments that pertain to many functions and not just one, so I have a choice of where to put that (beginning, end, referenced from functions, etc.). Putting it at the beginning is optimized for POD production. But I dislike seeing the multipage comments as the first thing I look at, as this is guaranteed to be exactly what I don't need to look at. There is a place for all these comments, and it is not always at the top of the function (at least I don't think so).

Is this a huge issue? Probably not, but note that most people don't even put header comments on their code, mentioning that it's self-documenting. So much of existing code (CPAN not withstanding) does not have good docs. So talking about the fine details of documentation is something that I would expect to generate the occasional "huh?"

Since code is read many more times than it is written or changed, I tend to be particularly sensitive to how it looks. I suppose I adhere to what is called "literate programming", something Knuth also mentions he is fond of, which doesn't seem to have many takers. It basically means you can read code like a story. And what I find is the story gets all screwed up with the documentation that needs to exist for the new users (again, differentiating between the comments I would put at the head as already discussed).

>> As for the existence of __END__, I'm not sure you realise that it's merely a point for the interpreter to stop and leave the file pointer in case you want to read it with the *DATA filehandle. It allows you to embed data in your source file...

I did not know that...thx! And I was being a tad facetious about the whole purpose of __END__ of course.