|Keep It Simple, Stupid|
Re^6: Documenting Methods/Subsby adrianh (Chancellor)
|on Jan 17, 2003 at 17:41 UTC||Need Help??|
I totally agree with the assertion that well factored code needs little in the need of code documentation. However the fact that perl lacks the ability to talk succinctly about type means that some things are less obvious than they are in other languages unless you add explicit assertions.
Consider the example of specifying a logger:
The Logger object is not used by new(). It may not be used anywhere near the constructor code - especially if in a subclass. Without the assertion it's not obvious what kind of thing the logger should be.
If I passed something that wasn't a Logger the problem wouldn't show up until it was used - potentially quite a distance from the incorrect call to new() making debugging harder.
Writing a test that concisely states "this has to be a logger object in all subclasses" is pretty much impossible.
Writing a comment has the usual problem of getting out of sync with the code, and doesn't solve the debugging issues.
Having an assertion (using validate or something like Carp::Assert::More seems a better solution.