Perl code - sometimes UGLY...

...or at least the way many people write it

Someone once stated that, "code should be more than write only," it should be READABLE. The author went on to suggest that style, like that outlined in the Chicago manual of style identifies document attributes to make material more easily absorbed by the reader.

(BTW if you know of the ref for that statement, please throw a ref...thx.)

Imagine no chapters, paragraphs, side bars, different size fonts, images (gee images in pod - no way huh!), one continuous monologue. Yeah Amazon, Borders, BarnesNoble would be less desirable by their stock holders!

Humans ! spend more time reading code than does the perl executable - so lets write for the most time consuming reader.

I am so tired of reading code in which my eyes, brain, and everything else has to parse the text to determine whether or not I'm looking at comments, code, pod, data, blah, blah, blah.

POD a curse (and a blessing). Pod helps compared with *roff, sgml, *tex, and all the others in being able to quickly generate accompanying documentation for a program or library. It makes it easy to have a single file contain both the code and the documentation. Compiled languages don't have this feature (hacks not included) nor do the early scripting languages.

However the ease of pod seems to be excuse to write textual elements in a file, interleaving code and documentation, in a willy nilly fashion. That is in a manner that is not quickly apparent to a human reader.

An astute reader may ask, "But why should I want to read the code - it has Pod?" That is often why I turn to the code, the Pod is a bolt-on, maybe just to pass some test, and is insufficient - at least for my poor brain.

Yep the curse of Pod, a module writer thinks, "Well if I don't get everything in the Pod, the user can always just read the code. Well for compiled languages, that was not the case, hence the docs had better be good. But now with scripted languages, gee you can always just read the code so embedded docs are simply gravy, right?

Oh and gee, what about images ! See my perlmonk writeup pod and images

If you're taking the time to read this diatribe and you have ref's to nice looking, easily readable perl code, please throw a reference.

Update

Well as you might suppose I had a bad day, reading other people's code, because of poor documentation.

Its just so frustrating...

So I apologize if I offended anyone. Perl really is a nice language, I've used it for years, which makes it even more painful when it is butchered.

Comment on Perl code - sometimes UGLY...

Replies are listed 'Best First'.
Re: Perl code SUCKS by atcroft (Abbot) on Apr 28, 2009 at 23:30 UTC
Why not run it through perltidy?	[reply]
Re: Perl code - sometimes UGLY... by perrin (Chancellor) on Apr 29, 2009 at 05:23 UTC
I tend to agree about interleaved POD being hard to read. I much prefer it in one chunk at the end of the file.	[reply]
Re^2: Perl code - sometimes UGLY... by pemungkah (Priest) on Apr 30, 2009 at 19:17 UTC
I think it depends on the code in question. The debugger docs are interspersed, and they make it somewhat possible to understand what in heaven's name is going on. If they'd all been in a lump at the end they'd be almost useless.	[reply]
Re^3: Perl code - sometimes UGLY... by perrin (Chancellor) on Apr 30, 2009 at 19:46 UTC
Nope, it doesn't depend on the code. Interleaved POD is always wrong. Phew, glad I got that off my chest!	[reply]
Re^4: Perl code - sometimes UGLY... by pemungkah (Priest) on May 01, 2009 at 22:56 UTC
Re^3: Perl code - sometimes UGLY... by DStaal (Chaplain) on Apr 30, 2009 at 20:10 UTC
Just wanted to put in that I agree with you. My system is that programs are documented at the end, and libraries are interleaved. The difference being to me that programs are designed to be used and understood by non-programmers, so the docs often have little or nothing to do with any specific code. Libraries on the other hand are designed to be used by programmers, and each function should be documented on what it does (or, at least, what it is documented to do...) anyway, so the interleaved docs can often serve both purposes: Telling users how to use functions/methods, and telling maintainers what those functions/methods are intended to do. Otherwise I'd have to write both a comment and documentation, and they'd have to both be maintained in parallel. Interleaving them I only have two things to maintain: the docs and the code.	[reply]
Re: Perl code SUCKS by codeacrobat (Chaplain) on Apr 28, 2009 at 20:19 UTC
Why waste a lot of time with useless technical documentation when the code is self explaining. If you like images in your documentation then use formatting hints and pod2html. `=for html <img src="thebigpicture.gif"/> =cut` [download] If POD obfuscates your view on source code then use a decent IDE http://www.epic-ide.org/ which can fold pod comments. `print+qq(\L@{[ref\&@]}@{['@'x7^'!#2/"!4']});`	[reply] [d/l] [select]
Re: Perl code SUCKS by JavaFan (Canon) on Apr 28, 2009 at 20:05 UTC
Imagine no chapters, paragraphs, side bars, different size fonts, images That never stopped Shakespeare producing one of the highest regarded pieces of English literature. Oh, and Shakespeare didn't even spell consistently.	[reply]
Re^2: Perl code SUCKS by DStaal (Chaplain) on Apr 30, 2009 at 20:12 UTC
Yes, but he was Shakespeare. He could get away with it. Good process doesn't produce talent, but even talent is helped by good process.	[reply]
Re^3: Purl, pirl, pearl, perle, p-p-p-p- by Your Mother (Archbishop) on Apr 30, 2009 at 21:17 UTC
I completely agree with your first point. The second sort of collides against it because only the talent can determine the processes helpful to the talented and process is a Lowest Common Denominator game. For some reason today that almost strikes me as sad enough to make me cry. Oh, well, more caffeine and sugar should fix that; for an hour.	[reply]
Re^4: Purl, pirl, pearl, perle, p-p-p-p- by DStaal (Chaplain) on Apr 30, 2009 at 23:07 UTC
Re: Perl code SUCKS by sasdrtx (Friar) on Apr 28, 2009 at 19:27 UTC
Get a decent editor that color-codes program source. TextPad, and UltraEdit are a couple of examples. sas	[reply]
Re^2: Perl code SUCKS by otto (Beadle) on Apr 28, 2009 at 19:47 UTC
Get a decent editor that color-codes program source Too true. But when I'm on the go, reading a printout, yes I do that, it does not help.	[reply]
Re^3: Perl code SUCKS by Anonymous Monk on Apr 29, 2009 at 14:12 UTC
Solutions: Get the editor to print its syntax colouring (or dump colouring to html) and print in colour Get a highlighter and do it manually. Added bonus: it'll be done just the way you want it and you'll know up to where you've read.	[reply]
Re^3: Perl code SUCKS by codeacrobat (Chaplain) on Apr 30, 2009 at 22:09 UTC
Ok, dump Perl and try Lisp ;-) `print+qq(\L@{[ref\&@]}@{['@'x7^'!#2/"!4']});`	[reply] [d/l]