in reply to Re^3: Documentation: POD vs Comments (proximity is not clarity)
in thread Documentation: POD vs Comments
No. The difference is that you don't appear to look for the structure in code and so think of it as a bunch of unrelated definitions and so you don't appreciate how jarring it can be to have the structure of code (or documentation) so badly broken up.
Your example above is like "boxing chess" or the Yazoo album Upstairs at Eric's: interleaving stripes of quite opposed types. And it wouldn't really matter if you had special colors assigned to help distinguish the stripes. (Except that "boxing chess" and an album are things that you almost always experience quite linearly so the transitions between stripes are quite few and even predictable.)
The stripes still mean that you can't scan the documentation without having constant interruption of the non-documentation stripes breaking up your visual and mental parsing. Your eyes move a bit up or down on the page and your brain has to jump between "parse this Perl code" and "parse this documentation in POD format".
Parsing of Perl code is all about punctuation. Parsing of POD is greatly about whitespace. Shifting gears between those modes is disruptive.
Why that isn't a problem for sample code included in POD helps to illustrate why mixing real code and POD is a problem. Sample code is visually distinct in the context of POD. It is indented. It also is always quite short. If your sample code gets very long, then it really disrupts the structure and flow of the documentation.
More importantly, it is also nested inside of the POD as a separate paragraph (or several paragraphs). And the primary structure of POD is separate paragraphs.
Nested structures of different types is not a problem. I see a visual field structured around physical objects. One of those physical objects is a screen. Inside of that screen are a bunch of "windows". Inside one of those windows are a bunch of panels. Inside one of those panels is a bunch of POD. Inside that POD is a paragraph that is Perl code. Inside that Perl code is a regex. That all is easy to deal with.
Including real code with POD is quite different. The real code doesn't have to be indented so you lose the visual distinction.
More significantly, the real code isn't nested inside of the POD, it is just adjacent to it. The line between the two isn't defined by the outermost structure of POD nor by the outermost structure of code. So when you are scanning the POD at the outermost layer of its structure, you can very easily cross into real code without having noticed the line you crossed. Same for scanning real code.
If you can stand the distraction (to me) of a whole rainbow of colors, then you can make it easy to tell that you crossed the line between POD (which is probably one color) and real code (which is probably tons of colors). But that doesn't fix the problem of adjacent rather than nested dissimilar outer structures.
The color scheme doesn't form an outer structure (at least it wouldn't to me). A 'sub' or other "block" doesn't get assigned a single color. So the outer structure of real code is much broader than the finer structure of the syntax highlighting. So now we've gone to three different types of structure jumbled together.
With some mental gymnastics, you can make this mishmash work by defining just "pink" (the example color for POD) vs. "not pink" as the outermost structure. Within "pink", the next layer of structure is the paragraphs of POD. Withing "not pink", the next layer of structures is the outer structure of code (likely an eclectic layer slightly wider than the "block" layer). After you go a few layers deeper into that "code" structure, then you get to the layer that matches the color scheme (minus "pink").
I can understand how some people would be just fine with that rather fractured mental model and it would work well for them -- at least during those few source code tasks that they actually do from within their syntax highlighting editor and where the editor can know how to highlight the syntax.
And, if you are reading linearly (and not scanning), then the shifts between stripes are likely quite gentle. And if you suck at grokking code structure in a more "all at once" manner, then even when you scan or jump around, you have to parse the code nearly linearly so you notice the jar from the stripes much less.
But if you are parsing code or POD more holistically, then the competing outermost structures being mashed together in stripes can be maddeningly disruptive. It really feels very much like having the outer structure of "sentence" horribly broken up by shuffling definitions between each word (as I did just above).
It is like looking at a room and seeing a couch next to a block of text that isn't part of any physical object next to a table next to... stripes of physical reality and stripes of "computer images" side by side with no sensible border between them... and trying to plan the physical layout for the party with the guest list "helpfully" made adjacent to reality in a way that gives your mind no sensible outer structure to apply (except it is worse because POD and code aren't even close to as visually distinctive as "reality" vs. "text").
And it doesn't really matter that much that the text on the slices of computer screen that have impossibly shuffled themselves (between the slices of reality) is green while there isn't a single green physical object in the room. It still makes it jarring and difficult to figure out if the couch would look better over there.
- tye
|
|---|
| Replies are listed 'Best First'. | |
|---|---|
|
Re^5: Documentation: POD vs Comments (nesting)
by Anonymous Monk on Jul 23, 2011 at 09:00 UTC |