Perl Code Quality

Micz has asked for the wisdom of the Perl Monks concerning the following question:

Replies are listed 'Best First'.
Re: Perl Code Quality by kvale (Monsignor) on Sep 24, 2004 at 22:24 UTC
Right off the bat, the code should also come with a decent set of tests that can be used to check functionality. Tests are useful for verifying that the system works as specified, but are also useful for future development. Having to write tests generally motivates developers to create a clean API for their modules. And a comprehensive test suite gives more confidence, that when one does make changes, the original functionality doesn't break. If the test suite is written in the context of a test-driven development process (i.e., tests first, then code), even better. Update: corrected a grammar mistake. -Mark	[reply]
Re^2: Perl Code Quality by biosysadmin (Deacon) on Sep 25, 2004 at 03:21 UTC
I like this idea quite a bit, but one interesting question is who should write them? You could ask the software company to write tests for you as well if you're busy, but I think it would be a very interesting if you wrote them yourself. That way you have a very simple, quantifiable way of determining that they are fulfilling the terms of their contract. On the other hand, if you're busy enough to contract out programming work, you may too busy to write tests. Writing your own tests involves might involve you in the development process more than you (and possibly the software company) want. Now my question: How can I assure that the system written is well-done? I am assuming it should be OO, with clean documentation and sensible classes, a documented and thought-out database structure as well as abstraction where possible. These are things I can observe. What else could/should I check for? You can do a lot by explicitly defining the object structure and APIs that you want. If you don't want to be this involved in the design, you could just look at the code as it is returned to you and give the development team feedback. AFAIK there is no automated way of determining code "quality," so I think you'll have to just describe your desire for good, modular code and see how well the company can do with it. I'm assuming that you've already picked your software company of choice, if not you should definitely attempt to shop around and get code samples from a variety of places.	[reply]
Re^2: Perl Code Quality by Micz (Beadle) on Sep 26, 2004 at 18:13 UTC
Thanks for the suggestion. Could you give me a pointer towards resources regarding unit testing in Perl? I am currently thinking of having one company write the code and a freelancer write the tests. This might lead to some conflict (pointing fingers), but it should provide me with quite good results.	[reply]
Re: Perl Code Quality by FoxtrotUniform (Prior) on Sep 24, 2004 at 22:28 UTC
Why assume that it should be OO? The world is not object oriented. In your place, I'd do a short code review as a "quality check", to try to get a feel for how easy the code is to understand. I'd look for clean interfaces, short functions, and good identifiers. I'd ask myself: "If I had to fix a show-stopping bug, how long would it take for me to get familiar with this piece of code?" `-- F o x t r o t U n i f o r m Found a typo in this node? /msg me % man 3 strfry`	[reply]
Re: Perl Code Quality by samtregar (Abbot) on Sep 24, 2004 at 22:47 UTC
I see two possibilities here. One, you learn enough about good software engineering and good Perl coding that you can evaluate the code yourself. Or, two, you hire someone you trust to do it for you. I suggest you investigate the second option if you don't have a lot of time for the first. Look for someone well-known in the Perl community who can do a code-review at several points in the project (not just at the end when it's too late to fix anything). Someone with training experience who can help your team learn from their errors would be preferable. -sam	[reply]
Re: Perl Code Quality by perrin (Chancellor) on Sep 24, 2004 at 22:57 UTC
I'd suggest you read Peter Scott's book Perl Medic. It contains good advice about what qualifies as maintainable Perl code and what the current best practices are.	[reply]
Re: Perl Code Quality by saberworks (Curate) on Sep 25, 2004 at 01:27 UTC
This is one of the most frustrating topics simply because you can't take anyone's word on it, you have to check yourself or find someone you really trust and have them check it. I took a new job in December and talking to the lead programmer (who I replaced), he told me that the code was very clean and well written, nice standards, etc. When I got there, the code was just insane. Every variable in the entire program is stored in a huge, arbitrarily nested hash that's passed into and out of every function. I think some of the most important things are: Make sure there aren't a lot of anonymous functions that are hard to reuse. Look for clearly defined function libraries with small functions that take arguments related to the calculations the function will make and returns a value that's related to the functions name. If it's a web-based project, make sure the HTML and perl code isn't mingled much, if at all. Make sure any part of code that is potentially confusing to someone who isn't necessarily a perl guru is documented. A decent gauge of a good perl programmer is one who uses a lot of CPAN modules for core functionality. The program, if large, should be split into appropriately named modules or classes (which should both be stored in simple reusable .pm files). Anything the programmer does to make the code more readable and more resuable is A Good Thing and is a testament to the coder. Of course, if there is a huge time crunch, some of the things mentioned above won't be done or won't be done correctly. However, a good programmer always shows effort to make sure code is elegant and reusable.	[reply]
Re^2: Perl Code Quality by ihb (Deacon) on Sep 26, 2004 at 19:51 UTC
Make sure there aren't a lot of anonymous functions that are hard to reuse. I use a lot of anonymous functions, and that doesn't make it hard to reuse them. On the contrary, I do it to easier reuse code. I use it as an local abstraction technique, and we agree on that abstraction is good, while I at the same time don't want to pollute the global namespace for a function that would only be confusing there since it only has value where it is. In the future, if that piece of code has value outside the lexical scope it's defined in, it's easy to move it out. Sometimes these functions are closures, sometimes they're not. Using anonymous functions is a good sign for me, if done right. I see it as the programmer appreciates abstractions and tight scoping. `ihb` Read argumentation in its context!	[reply] [d/l]
Re^3: Perl Code Quality by FoxtrotUniform (Prior) on Sep 26, 2004 at 23:30 UTC
Make sure there aren't a lot of anonymous functions that are hard to reuse. I use a lot of anonymous functions, and that doesn't make it hard to reuse them. On the contrary, I do it to easier reuse code. I use it as an local abstraction technique, and we agree on that abstraction is good, while I at the same time don't want to pollute the global namespace for a function that would only be confusing there since it only has value where it is. In the future, if that piece of code has value outside the lexical scope it's defined in, it's easy to move it out. Sometimes these functions are closures, sometimes they're not. Edit: I'm not arguing with ihb, I'm adding to the above argument. See also Is it possible to create a sub exclusive to a sub?. Further, function generators often allow a level of abstraction that "ordinary" programming techniques don't: the ability to build code from data, not just operate on data. Look at Specializing Functions with Currying for a simple example of how higher-order functions can promote reuse and remove redundant code. I agree with ihb that anonymous functions (well, let's say "lots of coderefs") are a good sign, not a bad one. I'm sure there are exceptions, but functional abstraction isn't the kind of thing I can easily imagine a mediocre programmer doing. `-- F o x t r o t U n i f o r m Found a typo in this node? /msg me % man 3 strfry`	[reply]
Re: Perl Code Quality by cosimo (Hermit) on Sep 25, 2004 at 08:14 UTC
I found out in my experience, that if you are going to use lots of CPAN modules, you'd better encapsulate their functionality in your classes, at least for the most critical. In this way, when some CPAN class changes the way it works over time, you are not going to be hurt for that, and you can always adapt (and improve) your code base.	[reply]
Re^2: Perl Code Quality by steves (Curate) on Sep 25, 2004 at 12:49 UTC
Maybe it depends on the CPAN modules used, but I was just remarking to someone last week how, with over 300 installed CPAN packages, I can only remember finding one backward compatibility issue in 5 years. We do wrap some, but only if we're extending functionality. Still not a bad idea though. I would agree that the world is not all OO. We have mostly OO code but there are a fair number of procedural modules. I think the point a lot of people miss is that, regardless of the coding paradigm used, the most important thing is packaging -- things should always be relegated to packages, properly factored out, in a directory structure that allows for additions and changes over time. A friend of mine refers to the base directory layout and packaging scheme one sets up as the pegboard of the programmer's workshop: a place to hang everything and everything in its place. It seems that a lot of programmers are not very comfortable working by building packages, unit testing those, and building small scripts that use them. For whatever reason, I always find that the average programmer gravitates towards long scripts. I think a lot of people just can't see the pieces as they present themselves. For that reason I'd try to hire at least one senior person who has done a lot of package building. Typically people who have had to build APIs for others to use are a good choice, whether it be in the open source world (like CPAN) or for a company that sells software. The experience of having to define interfaces is not as common as it seems sometimes.	[reply]
Re: Perl Code Quality by diotalevi (Canon) on Sep 24, 2004 at 23:26 UTC
Piggy back on the US military and use IEEE Std 830-1998.	[reply]
Re^2: Perl Code Quality by Anonymous Monk on Sep 27, 2004 at 10:20 UTC
http://search.cpan.org/src/SOFTDIA/Docs-US_DOD-STD2167A-0.06	[reply]
Re: Perl Code Quality by sfink (Deacon) on Sep 25, 2004 at 17:48 UTC
In my opinion, your self-declared "little bit of Perl knowledge" is likely to be a lot dangerous for this purpose. When judging code, as with anything, the first thing that anyone does is read through it for surprises -- namely, things being done in unfamiliar ways. With Perl, there are many good and many bad ways of doing something. So unless you are very experienced in large-system Perl (a very different beast from small-script Perl!), you're likely to either overestimate or underestimate the hazards of ways of doing things that are unfamiliar to you. I'm not knocking your Perl ability. It's just that anyone who has used Perl for a while is likely to have experimented with different ways of doing things. Some of those ways will seem great for a while, and will only gradually reveal their weaknesses. Without having gone through a good deal of that process yourself, you just aren't equipped to differentiate between "solid and robust" and "fatally flawed". My suggestion would be to find a very good, experienced Perl programmer to quickly eyeball the code a few times during the development, and make his -- or her -- feedback a gating factor in the contract. (Perhaps indirectly -- you should have no difficulty in understanding his objections once he explains them to you.) Perl is a bit unusual in this respect. There are many ways of doing things, which makes it hard sometimes to differentiate genius from impending doom. At the same time, it expands the space of possibilities in such a way that it is actually much easier for an experienced practitioner to quickly tell how good code is. I find that doing Perl code reviews is much, much faster and easier than doing C, C++, or Java code reviews -- you can sniff out the overall quality and style in about 30 seconds, and robust Perl is so idiomatic that finding the troublesome bits is far easier. And although there are many valid ways of doing things, one code base should use one consistently. Fortunately, the different techniques tend to look different enough that it is easy to judge consistency.	[reply]
Re: Perl Code Quality by pdcawley (Hermit) on Sep 26, 2004 at 21:25 UTC
How does it read? Pick a module, remove all its commentary. Read the code, possibly aloud. Can you follow it? Do the method names make sense? Is the layout consistent? Good code expresses the programmer's intent in clear, readable code that doesn't depend on comments. Comments, where they exist should only have to explain the why of the code. The code itself should tell you how. Is there a fully automated test suite? The lack of one doesn't necessarily mean the system is crap, but it's not a good sign. Try and implement a new feature (or ask another programmer to do so). How hard was it? Can it be done? Can it be tested? Will the software engineering company stand behind their code? Will they give you a warranty (unlikely) it (or offer a reasonably priced support contract).	[reply]
Re: Perl Code Quality by brycen (Monk) on Sep 26, 2004 at 17:23 UTC
I don't think you can sucessfully legislate code quality with a set of rules (especially not "must be OO", or "must be well documented"). Rules like that lead to OO solutions to non-OO problems, and documentation not worth the bits it is printed on. Instead ask for code samples from the small company up front. And as YOUR code arrives, look at it. If you have time, perhaps you can write some of the source code comments or test cases, based only on the code you receive. A second set of eyes is often the best path to clarity. The original author of the code is often too intimate with it to understand what the subsequent maintainers might find confusing. I've maintained a lot of code. Far too often what the original author documented was already obvious to me based on the code. Usually I needed higher level hints -- like what the overall purpose of a code section is for. Or a description of the reason for a methodology or algorithm.	[reply]
Re^2: Perl Code Quality by DrHyde (Prior) on Sep 27, 2004 at 09:25 UTC
Surely documentation that is "not worth the bits it is printed on" doesn't count as good documentation! Far too often what the original author documented was already obvious to me based on the code. Sounds like the difference between comments and documentation. Documentation tells you what the software does - the API, perhaps a high-level description of the algorithm. Documentation exists to help people who want to use your code (including other programmers) as well as maintainers. Comments are about how it does the job, and help explain much lower level stuff, eg "treat \ character as special", "these constants copied from MySQL headers", and are only for maintainers. Even so, they shouldn't say things like "add one to $i".	[reply]