http://qs1969.pair.com?node_id=209555

I am preparing to give a local talk on the topic of Style Guides for large projects. By "large" I mean number of developers, (perhaps >10), as well as code-size. By "style guides" I mean recommended coding practices, not the bigger topic of project management, which I think has been very well discussed in nodes such as this one and books like Code Complete and The Mythical Man-Month.

I've started doing a literature review. Perl being perl, there are at least as many opinions on style as there are perl programmers; starting from perlstyle and Tom C.'s Perl Style guide, and many nodes here, but I have seen little about style guides for large projects, and less on writing a style guide for large projects of one's own.

I have seen many nodes here that recommend using OO perl for projects with many developers. Others here have said that OO perl is a bad design choice for large projects because of OO's relaxed nature; some have recommended not using perl on big projects because developers with no discipline will dirty the code for all. I don't agree with these naysayers. I would like to know if anybody has put all the "good advice" in one place as regards large projects and perl.

I'd also like to look at more large projects themselves, for ideas; I would hope they have all created style guides of their own.

Here's what I've found. Can you add any big projects I should be looking at?

Probably the largest, most complex perl project I know of is Ensembl, an open-source bioinformatics database and genome analysis tool which has been instrumental to the Human Genome Sequencing Project and other projects. They have excellent design and style notes online, and a team of 40 active developers. This is the sort of thing I'm looking for.

I've tried looking into a few projects on Sourceforge. I hit paydirt with Slashcode, whose Slash Style Guide seems like a good document. I looked at POE, but I couldn't find a coding style guide. Can anybody suggest other large projects I should look at, or perhaps style guides you've seen that talk about issues for large projects?

___ -DA $_='daniel@coder.com 519-575-3733 /Prescient Code Solutions/ coder.c +om ';s/-/ /g;s/([.@])/ $1/g;@y=(42*1476312054+7*3,14120504e4,-42*330261-3 +3, 42*5436+3,42*2886+10,42*434987+5);s/(.)/ord(uc($1))/ge;for(@x=split/32 +/; @y; map{print chr} split /(..)/, shift(@x) + shift(@y)) {perlmonk.da.r +u}

Replies are listed 'Best First'.
Re: Perl Style Guides for Large Projects
by andreychek (Parson) on Oct 31, 2002 at 22:51 UTC
    I find the P5EE Style Guide to be an excellent resource. Oddly, it can no longer be found on the P5EE website, but you can find the P5EE Style Guide in Google's cache.

    Hope that helps
    -Eric

    --
    Lucy: "What happens if you practice the piano for 20 years and then end up not being rich and famous?"
    Schroeder: "The joy is in the playing."

      From a brief perusal of the Slash style guide I see that chunks of the P5EE guide are borrowed directly from it (e.g., sections on parentheses, braces, functions vs methods), so at least there's already some consensus among your sources. I seem to recall the P5EE guide having a whole section on object-orientation though, conspicuously absent in the notes available now. I have found that to be very helpful before; hopefully it will reappear at some point. But I have some suggestions for managing development in a large OO project:

      • Adopt a standard terminology for describing things not enforced by perl itself, i.e.: public/private/protected variables and methods; static vs instance methods; container classes like arrays of user-defined objects. I've found it helpful to borrow terms from Java/C++ to describe how a method is supposed to operate. POD can contain anything, so public static void foobar(String str) is perfectly legit, even if perl and pod2html don't have a clue as to the meaning.

      • Define a standard model of exception handling. Personally I like the C++/Java style of try/catch/finally as opposed to eval/die, and so I lean toward using modules like Error or Exception, but what matters is that everyone can count on code choking in the same way.

      • Decide upon a standard form of constructor. On my project, much to my frustration, I've found in a number of cases that modules previously written (yes, some were mine) were not written to support full inheritance with respect to initialization of state. While inheritance of methods is very easy to attain, it takes more careful planning to ensure that child classes will be able to utilize the superclass's initialization code. Whether you want to follow Java's model where each constructor's first act is to call super() all the way up to java.lang.Object or to try an approach like separating instantiation from initialization (my favored method nowadays), what matters is that you avoid the situation where a programmer wanting to subclass an existing module needs to read the code for the proposed superclass. And to do this requires a standard format for constructors. (See inheritance: constructors)

      • Create a module for argument checking that all programmers can use when validating data coming into a method. This keeps a major source of redundant code in one place, and ensures that you know something about the safety of your code across the whole project. It also means that you can simply turn off argument checking if you want to for speed.

      Good luck, fever

        Create a module for argument checking that all programmers can use when validating data coming into a method. This keeps a major source of redundant code in one place, and ensures that you know something about the safety of your code across the whole project. It also means that you can simply turn off argument checking if you want to for speed.

        I, the omnipresent Anonymous Monk, wholeheartedly second this advice. It saves a lot of work and results in far simpler, more flexible software. It took me far too long to start doing this myself. Good stuff.

      Thanks for the reference to p5ee. I've emailed their list to find out what their current status is; it looks like they've gone through some changes in focus recently. But it still looks useful for my talk. For what it is worth, I found the style guide within their code download and it is in their CVS tree. But they really should fix that link. :-)

      Update: The URL to their style guide is fixed.

      ___ -DA $_='daniel@coder.com 519-575-3733 /Prescient Code Solutions/ coder.c +om ';s/-/ /g;s/([.@])/ $1/g;@y=(42*1476312054+7*3,14120504e4,-42*330261-3 +3, 42*5436+3,42*2886+10,42*434987+5);s/(.)/ord(uc($1))/ge;for(@x=split/32 +/; @y; map{print chr} split /(..)/, shift(@x) + shift(@y)) {perlmonk.da.r +u}
Re: Perl Style Guides for Large Projects
by dws (Chancellor) on Nov 01, 2002 at 04:25 UTC
    I've worked on several mid-sized projects (including one 80KLOC Perl application suite) that used fairly minimal style guidelines, and a couple of projects that used coding standards.

    What I've found works best is a combination of light-weight guidelines coupled with "educational" code reviews. Reviewing work by senior team members demonstrates what "good" is to junior team members. Reviewing work by junior team members is an opportunity for gentle correction. Even in the absence of standards or guidelines, senior people can usually form a concencus about where the boundaries around "good" are, and the rest of the team can learn by example.

    This approach might not scale to a situation where all of the coders are peers, without an acknowledged senior/junior distinction.

      This approach might not scale to a situation where all of the coders are peers, without an acknowledged senior/junior distinction.

      I've found it still works well for groups of peers as long as there is collective code ownership.

      I'm not sure if this is just because CCO is just a sensible idea, or if the... individuals... who cannot take constructive criticism can't stand to work in an environment with CCO :-)

Re: Perl Style Guides for Large Projects
by adrianh (Chancellor) on Nov 01, 2002 at 11:15 UTC

    Although testing is mentioned briefly in the guides you link to I cannot emphasise enough how essential good test suites are for large projects.

    Good unit, functional and acceptance tests will save you from much hassle during the development process.

    I'd also recommend that you base them on the existing perl modules (Test::Harness, Test::Builder, Test::More, etc.) rather than rolling your own.

      Also, in order for your tests to be worth beans, write them before you write the code they test. If tests are written after the code, knowledge of the code's functioning will tend to taint the tests, making them much less useful. When you code your tests in advance, you can be sure they're right.
      --

      Love justice; desire mercy.

        In a perfect world so it would be, however test written after the fact can be invaluable and are better than no tests at all. They come into their own every time you change a single character in your code. It never ceases to amaze me how often seemingly benign changes can have unforseen side effects. It is alway reassuring to be able to make a change, run the tests and KNOW that you have not broken anything by accident.

        cheers

        tachyon

        s&&rsenoyhcatreve&&&s&n.+t&"$'$`$\"$\&"&ee&&y&srve&&d&&print

Re: Perl Style Guides for Large Projects
by ignatz (Vicar) on Nov 01, 2002 at 05:19 UTC
Re: Perl Style Guides for Large Projects
by joe++ (Friar) on Nov 01, 2002 at 16:57 UTC
    If you're going the OO way (and I think you should, together with XP's unit-testing approach), then perltootc has some nifty conventions for using Class data vs. Object data, "Eponymous Hashes" and "Translucent Attributes".

    You'll even even find a good excuse for manipulating the Symbol Table in some cases... something to be very suspicious about normally.

    Just my $0.02

    --
    Cheers, Joe

Re: Perl Style Guides for Large Projects
by talexb (Chancellor) on Nov 01, 2002 at 15:08 UTC

    Let me throw in a plug for Extreme Programming by Kent Beck (ISBN 0-201-61641-6). I had heard of this far-out technique but had never practised it until starting a full-time job a month ago. It's a weird way to work, but it's unbelievably effective.

    --t. alex
    but my friends call me T.
Re: Perl Style Guides for Large Projects
by da (Friar) on Nov 01, 2002 at 20:32 UTC
    These are great suggestions, thanks. ++'s all 'round.

    And for another perspective, I leave you with a quote from TheDamian: "Programming is a Dark Art, and it will always be. The programmer is fighting against the two most destructive forces in the universe: entropy and human stupidity. They're not things you can always overcome with a "methodology" or on a schedule."

    ___ -DA $_='daniel@coder.com 519-575-3733 /Prescient Code Solutions/ coder.c +om ';s/-/ /g;s/([.@])/ $1/g;@y=(42*1476312054+7*3,14120504e4,-42*330261-3 +3, 42*5436+3,42*2886+10,42*434987+5);s/(.)/ord(uc($1))/ge;for(@x=split/32 +/; @y; map{print chr} split /(..)/, shift(@x) + shift(@y)) {perlmonk.da.r +u}
Re: Perl Style Guides for Large Projects
by Anonymous Monk on Nov 04, 2002 at 15:49 UTC
    I don't have any references to any formal specifications, but here's what I've gleaned from my experience working on some large Perl projects:

    1. Always always always "use strict".

    2. Use the "-w" flag during development (if not production) to catch any odd behavior.

    3. When using OO, don't consolidate multiple modules into one file. Each module should have its own file, named after the module itself, in a respective directory. What this means is that the module Foo::Bar::Baz should be in the directory Foo/Bar, and have a filename of Baz.pm.

    4. Also when using OO, you might want to not corrupt the main Perl lib tree. Typically (under a Unix-ish system), you would want to keep your program in an /opt directory, such as /opt/foo. I would suggest creating an /opt/foo/lib to keep your Perl modules in. You can then, in each script which uses these modules, add the following lines:

    BEGIN { require '/opt/foo/.perlpath' if -e '/opt/foo/.perlpath'; }
    /opt/foo/.perlpath would then contain:

    use libs qw(/opt/foo/lib);
    This will allow you to port your application from host to host, without having to recompile perl to see your modules, and without having to polute the common perl library directories, which your application's respective user id does not own.

    5. You should definitely settle on OO structure, such as only allowing access to data through getter and setter methods, as well as how you will address private and public methods (private is usually denoted as having a "_" in front of the method name, such as "_findStuff").

    6. I would also recommend coming up with common utilities, used throughout the code so that you don't have developers writing the same thing twice or, worse yet, copying and pasting code. Look at CPAN for logging modules and other common modules which will be used by developers.

    7. Standardize on your logging! This is the only thing that will save you in a production environment to help diagnose a problem.

    8. Remember that, although there is more than one way to do it, this should not necessarily be the case on a large-scale Perl project. Readability and maintanability should come before artistic freedom.

    Good luck!

    clifford-perlmonks@330software.com