This does not strike me as a good reason.

Experience strongly suggests that if you use descriptive method names, collisions are rather rare, documentation is never accurate, and it is as easy to search code for private methods as it is documentation. (Besides, I'm always going to search the code in the end because I don't trust the documentation.)

Furthermore no amount of documentation can protect you if the base module's implementation changes and it now needs a new private method that might intersect what some subclass is using.

This is part of what I was referring to at Re^2: Private Methods Meditation. And there is no perfect solution to it. However after you use descriptive method names and have decent test suites, the problem virtually goes away. If you furthermore have somewhat decent designs, the issue becomes rare to the point of being an endangered species.

I'll continue my practice of not documenting private methods in POD. They are in source code, and possibly in regular comments when needed. That is good enough.

In reply to Re^5: Private Methods Meditation by tilly
in thread Private Methods Meditation by theAcolyte

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.