in reply to Seeking Best Practices - does your company follow a standard?

I am being clubbed to death by PEP 8.

I've just read PEP 8 and am not impressed. There's too little substance, too many platitudes and stating of the obvious with gratuitous exclamation marks. For example:

If PEP 8 is your primary concern, you don't have much to worry about. :)

A while back I wrote:

Though we have specific coding standards for each language, our general coding standards document, similar to On Coding Standards and Code Reviews, has perhaps proved the most useful. Last night, for example, I used it to club some external contractors into fixing some basic issues with their code such as "The result of every file operation or API call or external command must be checked, and unexpected results handled". Things that matter, not trivia.

Generally, Perl has come out of our coding standards effort looking very good. In particular, Perl::Tidy and Perl::Critic have proved to be excellent tools, unmatched by the other languages. For Perl, all new code must successfully pass through our tailored versions of Perl::Tidy and Perl::Critic before code review. Doing this avoids wasting time during the review arguing about trivia, such as code layout.

With a tip of the hat to kaizen, I suggest you set up a wiki page and encourage all team members to add to it during a code review, or at any time, when they find something that could improve the coding standard. That is, you need to create a vibe of inclusiveness with everyone trying to improve the quality of the shared codebase, not individuals fighting the standards police. And with a focus on real world things that matter, not trivia or dogma. The coding standard should be a living document.

To some extent, what goes into your coding standard reflects the level of your programmers. We have few Perl experts, many Perl part-timers, and some external contractors, so the sort of things that crop up here during code review (and then get added to our wiki page) may be trivial and inappropriate for an environment chock-full of Perl experts. Nonetheless, they are relevant to us because they actually happened (often repeatedly). I list below a couple of items to give you a feel for the sort of things that have cropped up here:

Replies are listed 'Best First'.
Re^2: Seeking Best Practices - does your company follow a standard?
by dineed (Scribe) on May 17, 2010 at 23:09 UTC

    Businesses definitely need to have some standards in place around coding, including guidelines (not laws) about indenting, and other questions of visual style.

    Did you actually quantify the benefit of your coding standard? At the end of the year, how much more profit did your company made because of the coding standard? How did you measure that? If productivity really went up, did you let programmers go, because you now need less of them?

    Suggestions welcome. How do you quantify something like this? Has anyone tried?

    I guess one way to try and quantify this would be to think back at how much time was spent trying to remember what your intention was for various pieces of code before you then had to go and explain that same code to junior members of your team.

    I remember several years ago, I wrote a code generating SED script, that I thought was really clever. It was virtually unreadable (all symbols, etc.) and contained zero comments. I didn't write it for production, but as a utility for my own use. It was cool and I was really proud of myself, but I would have deserved to be fired if I even thought about putting it into production like that. And if it were intended for production use, then I would not have changed a line of code, but I would have commented the heck out of it.

    Where I found a lack of standards, I've tried to discipline myself - I've used a specific exit code pattern for abends such that someone else maintaining my code in the future could easily see the pattern and add a new abend exit code as needed.

[reply]
      I guess one way to try and quantify this would be to think back at how much time was spent trying to remember what your intention was for various pieces of code before you then had to go and explain that same code to junior members of your team.
      Yes, but that falls in the category "don't use needlessly complicated algorithms". Useful, but hard to codify in a standard, and usually absent in any list of coding standard bullet points. Impossible to catch with Perl::Critic.

      My rant is against silly things as putting in a standard than you should use 3 spaces for indentation, or 4. Surely you haven't spend much time explaining code to junior members who struggled with the fact someone used 4 spaces in an indent, and not 3?

[reply]

        You are correct on all points:

        1. I believe we're speaking about judgement (common sense, or practicality) , and I don't think you can codify these things. Instead, we must rely on standards/guidelines combined with peer code reviews.

        By "peer code review", I don't mean "pressure"; rather, I'm thinking of it as idea exchange. The image I have is similar to what we see here in the monastery. Folks offer up code samples and others have a look and offer alternatives with an explanation of why they think their's is the better way to go. Very often, there are valid reasons to use the alternative. And of course, sometimes, it does come down to personal preference.

        2. No, I have not spent much time explaining the difference between 3 or 4 spaces indented, but I have spent way too much time explaining why not indenting at all is unacceptable in producton code intended to be maintained by others.

        I agree with your rant about the silly things. My point was not so much about how much one indents as it was about them just indenting, and doing so in a consistent manner.

[reply]

In Section Meditations