I deliberately use shift now, more and more, for two reasons:
| [reply] [Watch: Dir/Any] [d/l] |
With the "my ($x, $y, $z) = @_" style, I don't have a clean place for those comments, unless I want to break the list on the left across many lines (ick).
Why not just put the type documentation into the embeded programmer documentation above your function? To call your function correctly, others need to know what they can and can't pass to it, and what will happen if they do. In other words, the type information is a valuable part of your function interface documentation.
I embed the documentation for my function interfaces (as well as general 'programmer' documentation), within a special pod section, dedicated to the "programmerdocs" pod translator. When I need to extract the user documentation, the regular pod translator ignores the programmerdocs section. When I need to extract the programmer documentation, I have a twenty line perl script that extracts the 'programmmerdocs' section, and pipes the results of those sections to the standard pod translator.
It's a bit of an abuse of the pod translator concept, but it works, and it keeps the two kinds of embeded documentation separatate, and easy to access. If anyone has a better method for keeping distict forms of documentation separate, I'm open to suggestions. So far, abusing pod has worked for me.
I like extractable function documenation, because it allows a tester to write unit tests for all the functions without reading any of the implementation details. If the code doesn't match the documentation, the coder needs to fix one or both of his code or documentation.
--
Ytrew
| [reply] [Watch: Dir/Any] |
Why not just put the type documentation into the embeded programmer documentation above your function?
That creates a distance between the action and the documentation. That's harder to read for the maintainance programmer (the further away, the more movement in the editor needs to be done). It also makes easier for the documentation and the code to get out of sync.
To call your function correctly, others need to know what they can and can't pass to it, and what will happen if they do.
But the comments merlyn was making weren't intended for the user (then they would be in the POD) - they were there for the (maintainance) programmer. Two very different beings. With different needs. And different documentation.
When I need to extract the programmer documentation, I have a twenty line perl script that extracts the 'programmmerdocs' section, and pipes the results of those sections to the standard pod translator.
I hope I never ever have to maintain your code. Comments should be right there where the code is, and not somewhere tucked away where I need a different tool to read them.
| [reply] [Watch: Dir/Any] |
sub foo {
my $param = shift || croak 'Param must be supplied';
}
| [reply] [Watch: Dir/Any] [d/l] |