Slash Boxes
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
More | Login | Reply
Loading... please wait.
  • I'm correcting a Perl-for-Biologists book that actually tells people to do it the wrong way because it's good practice. I see the same thing from CS majors just learning to program. It must be what they do in universities.

    I think the old biologists must be C folk, and they're passing on their bad habits. I might take a generation to get rid of all that crap.
    • It's what we did at university (The University of Melbourne, 1996-2001). Not for every comment, but for descriptions of the program at the top and above each function.

      This was through for two main reasons. One was an unawareness of syntax highlighting (many people were still using vi), but the more important reason was that the code was printed out for marking. Head tutors would compare the given output with the expected output, and then also mark on things like variable names, comments, code quality

  • Does anyone else find that POD mixed in with the code like that distracting?
    • No.

      And it keeps the docs next to what they document, reducing the risk of them getting out of sync.

      But it's just one of those debates that never end.
      • Documentation is good when it reads like prose. Code is hard enough to read without having to ignore large swathes of non-code gunk. A mixture of code and docs makes both much harder to read and write.

        If you want to be able to see docs and code at the same time, stop using Notepad and get a decent editor where you can have several windows open on the same file at different places.

        That’s my stance on this religious war.

  • what is your thought on ###### lines to separate sections of code?

    I find it ugly and distracting but have no other good logical argument against it.
    • The things which separate sections of code are called "subroutines".

      I'm more and more finding myself in the XP camp that comments mean complexity; if the code was simple and everything well named it won't need a comment. Complexity should be walled off into its own routine. That means if you find your code is complex enough to warrant a comment, or a separator, then you should consider an extract routine refactoring and a good routine name instead.
  • I wish people would use pod less because I find it personally mostly distracting to read. The markup looks too much like content. The shape isn't entirely unlike very short comments and the mandatory paragraph marks work against being able to read a chunk as a paragraph.

    I still use pod of course, I just don't like it and wish people found other ways to write docs.