|Keep It Simple, Stupid|
Re^2: Documentation: POD vs Comments (proximity is not clarity)by tye (Cardinal)
|on Jul 22, 2011 at 18:31 UTC||Need Help??|
As an aside, I'd note that comments are really only useful in conjunction with the user-level documentation. Maintainers needs to know both what the code is supposed to do and how it does it.
Therefore you make the maintainer's life easy by putting POD as close as possible to the bits of code that it documents.
Much (in a great way) like (similar to) a (singular article) sentence (grouping of words expressing an idea) doesn't (fails to) make (produce) sense (coherent meaning) without (lacking) the (definite article) definition (explanation of meaning) of (preposition) words (grouping of lettings expressing a concept).
Make your reader's life easy by keeping the word definitions as close as possible to the words! It would be crazy to have a separate document that explains the basics and then to expect your copy editor to actually understand the meaning of English words before she jumps in trying to edit your sentences.
Oh, some of my definitions above rather suck. I find that often happens when I'm forced to shift tasks in the middle of composing a sentence and throw together a word definition in order to get the boilerplate in place so I can type in the next word.