One of the biggest differences between POD and comments for me is that comments don't look like code while POD is not easily visually distinguished.

One of the nice things about POD is how easily and naturally you can include sample code in your POD. So I find it very likely that sample code will get included in POD. And trying to read the actually code when it is shuffled together with POD that includes sample code actually feels like a nightmare &emdash; like I'm just going along opening this innocent-looking file of Perl code and suddenly I realize that it is "finals" and I haven't studied and then everybody is laughing at me because I'm also naked, er, I mean, I suddenly realize that I can't even find the code.

Because, instead of the file containing a block of code that I can read or scan or scroll through or search through, the file contains some twisted "scavenger hunt" where I think I've found some code but it is really just text that looks like code. And when I find the code, I have a hard time concentrating on it to understand it because I'm not confident that I really did find it this time.

Because whether "code" is really code or not depends on whether one of the hundreds of '=' characters in the previous 10 pages happens to be in the first column and also whether that closest prior such '=' is followed by 'cut' or any other word.

Comments require that the fairly distinctive '#' be present on every line. POD actually requires that the ubiquitous '=' character be separated from what you are looking at by at least one blank line.

But even without embedded sample code in your interleaved POD, I find that the POD can greatly interfere with the reading of code, especially for some types of reading (especially less linear types). So please don't interleave POD and code.

Yes, I understand the theory of "keep the documentation close to the code so that when somebody changes the code they'll also change the documentation". But I don't believe it actually works that well. The documentation gets updated most when the documentation gets used. So I think you get better results by concentrating on writing useful documentation.

And it is easier to make documentation useful when you can structure the documentation usefully, not be constrained to a structure that makes sense when shuffled together with your code.

So use comments to explain things that somebody trying to read the code needs to understand. Use POD to write documentation to be used by people who are trying to make use of your code. Quite different audiences who want quite different information. And keep the POD away from the code (such as after the __END__ marker or in a separate *.pod file).