I didn't become a good developer until I had to maintain my own code over the course of four years. Suddenly, I could not use the rationalization: 'if I had been the developer, then I would not have make that mistake or overlooked that possibility.’

I am in QA now (about 15 years), but I was an application and driver developer for 12 years prior to that. I still develop code. I just don't do it to put food on the table. I was/am all five of the developers below.

I have noticed there are 5 classes of developers and the quality of their work depends on how they self-defined their job.
1. I write code
2. I write code that compiles
3. I write code that compiles and works
4. I write code that compiles and works well
5. I write code that compiles and works well for a long time
The developer with 1/50 the defect density of his peers clearly wrote code that compiled and worked well for a long time.

I also told his manager that the developer was slow only because of manager's incorrect definition of done. The manager was using The programmers says so; i.e. has submitted some pastiche of code for peer review. as the measure of done. I pointed out that if done is defined as passing a peer code review with no correction noted (regardless of the need for re-review), then most of his developers have never completed their task and the guy we were discussing was done a over half the time. Suddenly, his careful, professional craftsmanship did not look so slow.

Code review helps every developer and designer become a careful, professional craftsman at developing or designing software that compiles and will work well for a long time. Code review helps every developer and designer become the careful, professional craftsman they long to be. Code review are for the long view.

Any competent carpenter can produce a china cabinet in a day, but the guy who takes 15-20% longer, makes a cabinet which will be on the Antiques Roadshow 50 years from now.

Nice, as usual. I'd add that it's not just especially beneficial for new hires. Every shop I've worked, the difference in skills between the top cats and the others was nearly exponential. Not just new hires but guys who were supposed to be experts and had been doing it for a decade or more. The Perl hacker at Amazon I learned the most from was a self-taught guy but he just knew the stuff better than all the rest of us. I think he was embarrassed he didn't have a CS degree too; all the while answering Perl and hardware questions from all the rest of us.

Code review is also a great way to set aside the opinions for the practice. It's easy to say XYZ is how we should do it because someone read a whitepaper but when someone else whips up some ABC instead and shows you how it fits in your app/code-base perfectly it's hard to keep saying, "but, but Sun says XYZ will save us from werewolves... "

Coding standards will also inevitably be sources of contention and frustration. I've found that much of this is avoided by being careful to set the right tone. This has to be done officially, as part of the coding standard.

Clearly state that the "rules" in the coding standard are suggestions. There can be situations where it is appropriate to "violate" a standard, but such cases should be exceptions, usually pretty rare exceptions (varies from "rule" to "rule"). If you can't explain and justify why you violated a rule, expect to be told to fix your violation.

A coding standard can't get better if you don't allow your programmers to discover and explore better ways of doing things. So an unchangeable coding standard leaves your code base locked in a increasingly out-dated box.

Of course, this flexibility completely blows away your "enforce rules with a tool", which I think is a horrid idea. Running code through a "tidy" step is only going to be close to reasonable for extremely simple rules (and reasonably simple languages -- ie, not Perl). Some of the stupidest coding conventions I've run into were things done as to not break some tool like a tidy step or a popular syntax highlighter or vi's % key. The results were almost as bad as the stupidest things perltidy did by itself (when people used it on their own, not because we mandated that it be used).

If the tool is good enough, the language regular enough, the rule simple enough, and the consequences of violating dire enough, then it can make sense to run the tool as part of the check-in process (note that perltidy fails all of these tests). The risk of a false-positive needs to be extremely high to burden your programmers with it constantly being run. Having the tool adjust the code being checked-in is always a bad idea, in my experience.

Enforcement tools like Perl::Critic, in order to appear extra useful, tend to come configured with a large array of tests (either from the tool distributor or the people who "adopt" it in your organization). This is the wrong way to go. Most of those rules won't pass the above tests. Even an excellent rule can become a hardship if it gets enforced by a mindless automaton (producing code splattered with comments to tell your 'linter' to "shut up!" isn't a "win" in my book).

I've implemented during-check-in enforcement rules in order to detect (accidental) violations of very simple rules with serious consequences (inclusion of "\r" in source code, which was causing horrible problems with merging in our version control system -- to the point of introducing post-merge bugs). I've implemented automated detection of more complex rules that had more severe consequences but these were run much less often (the ones that come to mind are too complex to explain here).

Even slightly complex rules are better enforced by people capable of exercising judgement (which might exclude some of your co-workers), even if those people use tools to help them.

With each "rule", include justification. Over time, your coding standard needs to be able to adapt. A great way to cause aggrevation is to answer "Why can't we do X?" (by which your programmer means, "why does our coding standard say not to do X?") with "That is the style we standardized on 10 years ago. I don't remember why."

If you justify each "rule", then each programmer is more likely to understand the benefit of the rule and thus to accept it (I've balked at many coding standard rules and then later had the benefit explained and stopped balking). If the justification given is weak, then that is great, because it means it is easy to get rid of or replace that rule with one that somebody has a much better justification for.

If the justification is excellent, then it guides how the rule can be adapted (including being replaced by a better rule). Often you'll also adjust the justifications.

Taking this tone means that more of your coding standard is likely to be seen as something that your programmers can learn from and can contribute to. This is why I prefer "best practices" (though that term has also become popular among people who implement dogmatic regimens so some find that term has a negative connotation).

I don't suppose you'd feel like posting your coding standard here? I'd love to pick it over :)

The trouble with coding standards is that they all too often become sticks for keeping the serfs in line in surrogate fiefdoms. One man decides that his style is the standard and everyone else must adopt it. The assumption being that cos he's the boss, he knows best.

Somethings code standards can mandate are Good Things:

• smallest scopes for local vars;
• contextually meaningful variable names;

  $i is fine for a (numeric) loop counter (preferable to $persons_array_index_counter), but not so good for a instance attribute or global variable.

  And yes; there are rare occasions when a global variable makes sense.

• proper (and consistent) indentation;

  No flattening of the structure just because one guy grew up with, and never got over, 70 column listing paper and ADM3+ terminals.

• consistent use of whitespace--horizontal as well as vertical;

  Spaces around operators vastly improve readability.

  No cramming everything together just in order to comply with an antiquated width restriction.

Conversely, I've been subjected to some horrible "standards": 2-char indentation; Hungarian notation; Camel_Case_Plus_Underscores; mandatory 24 line block comments for every function or method; and many more.

One useful piece of advice from the book "C++ Coding Standards" was to separate your Coding Standard from a Style Guide. (Rule 0: Don’t sweat the small stuff. (Or: Know what not to standardize.)) Minimizing scope of variables belongs in a coding standard, indenting belongs in a style guide.

The interesting side effect of this, is that most of the items in the coding standard are accepted by most of the developers without argument. Meanwhile people would argue for years on the curly placement from the style guide.

I've seen this approach used to good effect at a couple of positions. Even the style issues could be standardized once everyone could admit that any consistent style was better than having multiple styles in a large code base. (And, since it was just a guide and not a standard people seemed less likely to fight to the death for their "one, true indent style".)

G. Wade

separate your Coding Standard from a Style Guide.

Ditto Anonymonk.

The only problem is that you first have to agree what belongs in which!

For example. I would say that the use of consistant indentation is mandatory; the size of indent and curly placement is not.

Rule 0: Don’t sweat the small stuff.

Eek! Total divergance :)

It's strange. As an avowed anti-pedant, I probably shouldn't think this never mind say it, but I often think that the "small stuff" has more impact upon me than the "big stuff". (Bearing in mind the disparate ways we may be using the phrases.)

For example. I don't mind if code is written in a OO, procedural or functional style, or some mix of the three. I've encountered good and bad examples of all three. Though for me, the worst is badly structured (spagetti) OO code because it is so easy to pass it off as "well structured"--and believe it.

But there are some things I find intensly irritating

• a lack of horizontal whitespace;
• worse--inconsistent horizontal whitespace;
• A lack of indentation;

  <I'm not talking about whether it is 2,3,4 or 8 spaces per level, but whether indentation is used; whether every new level is indented; whether the number of spaces per level is consistant.

  If you look at thank-you letters written by small kids, the handwriting may be attrocious, the spelling aweful, and the grammar non-existant; but they all at least attempt to use paragraphs and sentences!

  But it is preferable--because you can see instantly what you're getting--to ...

• inconsistant indentation.

  I once encountered a codebase where the first level was 5; the second 4, the third 3; etc. I don't know what happened when they got level 7. Maybe they started outdenting? You know, I think I might almost prefer tha to omitting levels of indentation. See next.

  Which in turn is preferable--because it is usually unknowingly perpetrated--to ...

• institutionally sanctioned, or even mandated, inconsistant indentation;

  The single worst rule I've had applied to my coding is: "Intermediate levels of indentation will be omitted".

  I never renewed--despite the offer and convenience--for exactly that reason. Most of my gigs were from 2 to 5 years with many renewals--but that one I just could not take.

  They were not even consistant in their inconsistancy! Nobody could tell me whether it should be every second or third (or whatever) level that should be omitted; nor could I discern any pattern to when it was done.

• Boiler-plate (especially block) comments.

  These are no substitute for clearly formatted code; or meaningful function, class and method names; nor meaningful parameter names.

• Otherwise excessive commenting.

  I'm not just talking about the usual 'no one-per-line comments'; but also generally "does this comment tell me anything that the code doesn't"? If not, it is redundant. Or Worse.

  I've recently been doing some Java coding and dug out a book I bought when I decided to learn it 10 or 12 years ago. As an example of it's type it is not all bad, but here is a randomly selected sample from the CD:

  <Reveal this spoiler or all in this thread>

  This is a little unfair as this is a teaching book example, but of the 71 comment lines in those 208 lines, there are exactly two comments that are (maybe) useful.

  ...
          // See if we found the relative token
          if( nIndex == -1 )
  ...
          // Could not find the requested token
          return -1;
  ...
  [download]

  And even those would be redundant if he defined -1 as INDEX_NOT_FOUND or similar.

  Or (maybe) better yet, since he is going to use that to instigate throwing an exception:

          // Search for the relative token
          int nIndex = findToken( strSearchString );
  
          // See if we found the relative token
          if( nIndex == -1 )
          {
              NoSuchElementException e = 
                  new NoSuchElementException
                  ( 
                      "HTMLParser.getToken() Error: " +
                      strSearchString + 
                      " does not exist in the Token list"
                  );
                  
              throw e;
          }
  [download]

  Why not just throw the exception at source? See what I mean about OO structure being deceptive :)

  Like good pasta is much more than boiling it and throwing a sauce on it; good OO is about so much more than just grouping code and data. And Java's easy and mandatory OO just leads to boil-in-the-bag spagetti.

• Redundantly verbose variable/function/method names;

  From above:

  • String strSearchString: Can anyone say st-stu-stutter!

    That 15 character variable name contains 6 useful characters.

    And what does String Search tell you about it? Is this the thing we are searching? Or the thing we searching for? An action request we are receiving? Or a place we are going to to look?

  • (This is not the authors fault!).

        public String getToken( int nIndex ) throws ArrayIndexOutOfBoundsE
    +xception
        {
    ...
                ArrayIndexOutOfBoundsException e = 
                    new ArrayIndexOutOfBoundsException
                    ( 
    ...
                    );
                    
                throw e;
    ...
    [download]

    Why isn't that?

    public String getToken( int nIndex ) 
       throws ArrayIndexOutOfBoundsException e
    {
        ...
        throw e( ... );
        ..
    }
    [download]

    Because the usability of the language; considerations like Huffman; and common sense; all played second fiddle to the CS correctness and elegance BNF grammar.

    It could have been worse:

                ArrayIndexOutOfBoundsException 
                    m_AiOoBExIndexException = 
                        new ArrayIndexOutOfBoundsException = ...
    [download]

    Reminds me a little of some stuff I was reading the other day about "His Excellency President for Life, Field Marshal Al Hadji Doctor Idi Amin, VC, DSO, MC, Lord of All the Beasts of the Earth and Fishes of the Sea, and Conqueror of the British Empire in Africa in General and Uganda in Particular.".

    Unlike some other African despots who are just in for the wealth and power and narcisism it gives them, he truly believed that his actions were good for both the Ugandan and African peoples. He often took it upon himself to speak for, and act on behalf of, the peoples of the entire continent.

    Which brings us neatly back on to the subject of oligarchs imposing their world visions :)

• Excessive vertical whitespace.

  Try reading a double-spaced manuscript to understand why books are not typeset this way.

any consistent style

Bravo! That my watchword for both categories, but especially style: consistancy. Whichever way you opt to do it, do it everwhere the same.

better than having multiple styles in a large code base.

However we'll have to agree to differ on that. Nobody reads an entire large codebase from beginning to end, they dive in to small pools for a while, occasionally.

Consistancy within individual source files makes reading them easier; and across closely related sets of file is nice to have as they will often be used concurrently. But 4-space indentation and cuddled elses across the entire codebase, is entirely unimportant. I won't save time nor money; nor make the code run more correctly or efficiently. It won't even look good on paper because no one will ever see it (all) on paper.

And when it comes to maintaining someone elses code within the codebase, sticking with their indentation & curly placement is a good idea--for consistancy--but don't expect me to omit all horizontal whitespace; add one-per-line or block comments; or make up new, stupidly long variable names.

I'll hug your elses if you do; use the full, unadulterated name a variable's mother gave it; and emphasise the silences between my (lowercase) words if that's the local custom. I'll adapt to the local customs for the duration, but do not expect me to adopt your ways, including your bad habits, wholesale.

When I visit a Japanese business man at his home or workplace, I'll nod my head on greeting, but when he visits me, I'll offer my handshake. And don't expect me to spend 5 minutes silently admiring his damn business card, just cos he has more money than sense. And just to ensure that this isn't seen as anti-Japanese--I could have picked any national cultural quirks--I won't accept, or give, kisses to a Frenchman I've never met either. Even just on the cheek.

Enough! I don't have time for this :) I've got to get back to that dratted Java :(

---

Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.

"Science is about questioning the status quo. Questioning authority".

In the absence of evidence, opinion is indistinguishable from prejudice.

RIP PCW

I love the recomendation to separate the style guide from the coding standard.

Well done.

The only points I can think of to add are relatively trivial.

Like the code base and the experience of the developers, coding standards should/will evolve over time. As new best practices emerge, the coding standard should take these into account. (I once worked at a shop with a well-defined coding standard that advocated best practices from 15 years earlier. Unfortunately, the world had changed in that time.)

Depending on the review type, there is a benefit of code reviews that many people miss: increasing the company's Bus Number. I worked at one place that used tool-assisted code reviews. We had multiple people on every review.

This helped spread knowledge about individual modules and their usage. As a side effect, several modules that were only known by one person became partially understood by many. Although some developers won't like this (the old job security argument), most people seem to understand the benefits.

I'm becoming increasingly convinced that good coding and good writing have a lot in common. Structure, clarity of names, use of comments all work together to tell a story on two levels: one to the machine that will compile it and one to the person reading or maintaining it.

If you write a paper for a scientific journal, magazine or a university course there are clear guidelines for formatting, footnote and citation style, length of abstract, and so forth. All of these are meant to speed up the reading and review process. None of these pretend to try to make the article into a better article.

I think we ask too much of coding standards. We want to them to create good code. They can't. Only clear thinking about the code and how to explain it to other readers down the line can. Comments, variable names, structure are all tools that can work together in this effort. Sometimes they are interchangable. Sometimes they are not. Trying to come up with fixed rules about how they should be used actually impedes the writing process rather than helping it.

When I started out leading teams I used to get very fussy about how people coded. I've grown up since then and have moved more to a minimal set of standards focused entirely on readability and error detection. I try to focus on those that make it easier to skim code and leave the quality of code issues to other parts of the team process (e.g. code reviews). These are some of the standards that have worked for me and my teams (YMMV):

• Standard organization. If one file places public methods at the top and another at the bottom it is hard to skim through a large number of files. It really helps to know where to look for things in a file.
• Standard abbreviations. We have a list of standard abbreviations for words that commonly show up as part of variable names. Long descriptive names are a pain, but if everyone makes up their own abbreviations, code becomes illegible and variable names cease to be self-documenting. For the list to be useful it has to be short. For less common abbreviations the rule of thumb is (a) choose one (b) be consistent (c) for any abbreviation that isn't obvious from context, add a note somewhere at the top of your file listing the abbreviations you use and what they mean.
• Standard indenting. Standard indenting makes code so much easier to read. It really doesn't matter how much you indent as long as you do it consistently so that you can reasonably expect that adjacent lines of code at the same indentation level will be executed in sequence.
• Consistency. Whatever style you choose, be consistent. People can read a file more quickly if they can assume a single consistent style through the file.
• An alpha "sigal". When the content of a scalar variable is not blindingly obvious (e.g. while ($line = <DATA>), we put a one or two letter content type indicator at the beginning of variable name, e.g. $aUserNames. This is not standard Perl style, but I have found it very helpful none the less. The goal isn't to exhaustively type variables. Rather, this is mainly to distinguish quickly between scalars holding strings, numbers, arrays, code references, regular expressions, hashes, and things that are intentionally multi-typed. There are usually several ways to represent "foo" - it may have a name, an id, a hash storing fields by name, or a record containing several fields in a particular order. By giving it a one or two letter prefix to indicate which of these you mean, you can set up a lot of expectations about how the variable should be used. This makes it easier to skim the code. It also focuses one's attention during careful reviews. We use "s" for string, so if one sees "$sFoo == $sBar" one knows to look more closely for a possible error - either a misnamed variable or a misused operator.

Anything else is up for discussion. Over time I've come to believe that things like cuddling vs. not-cuddling don't have a huge impact on readability, so long as one approach or the other is used consistently within a code sample. We can learn to read code either way and probably should. The items listed above seem to matter more because they reduce the time spent searching up and down a file to figure out what someone meant.

Best, beth

I'm becoming increasingly convinced that good coding and good writing have a lot in common.

Not only is this generally true, I think its veracity is proportional to a language's expressiveness. Perl being what it is, this might be more true for Perl than any other language. It's either a weakness or a strength, like many other parts of Perl, depending on who is on the console.

Now, I'm all in favour of writing good code. But once people are talking about coding standards, they almost all first focus on layout nits. Like whether you may omit parens when calling a function. Whether you should put spaces before a bracket/curly/paren, after it, or none at all. Whether you should write $$aref[1][2], $aref->[1][2] or $aref->[1]->[2]. Where to put opening and closing braces of a block. Whether you should use "foo" or 'foo' for a string that doesn't use interpolation. Do you shift from @_ or not? Or other visual things, like whether every module should start with 'use strict'.

They seldomly focus on the real issues - or if they do, they aren't willing to put it up front in the coding standard because it's so hard to enforce. 'use strict' isn't important. Using properly scoped lexical variables is. And if $WORK prouds itself it's only hiring "top" programmers, it shouldn't matter programmer A always uses parens when calling a function, and B only when needed.

As for the particular points:

Improved code maintainability.

Improved code quality. In particular: testability, supportability, portability, security, efficiency, robustness.

Improved development speed. Your developers don't need to make all decisions starting from first principles.

Better teamwork. Don't waste time with needless debates. Spend your creative energy on things that matter.

Better performance under pressure. Under stress, people fall back on what they've been trained to do.

Fewer bugs. Good standards should minimize common coding mistakes.

Shallower learning curve and useful training for new hires -- if your standard mandates proven, well-known idioms and style from the programming mainstream.

Again, I'm not saying company coding standards aren't good. Sometimes, they are. But it's not clear-cut, and one should be well aware of both the benefits and the drawbacks.

I don't understand your argument though. What have first principles to do with coding, or coding standards?

Someone like Damian Conway has derived each of his 256 best practices in PBP "from first principles". In the interests of development speed, I don't want each member of my team to similarly repeat his research and analysis.

Regarding development speed, the places where a good coding standard has the potential to help is in areas (often "cross-cutting concerns") that are common to many projects and many teams. For example:

• Should I use File::Slurp from CPAN or write my own ... or add one to our library code to be shared with other teams?
• When parsing XML, should I use XML::Simple or XML::LibXML or something else? ... or just use a regex? ;-)
• In my Perl module, should I use '1.23' version numbers or '1.2.3'?
• Should I use C++ Boost shared pointer or write my own "from first principles"? (Update: or wait for ANSI C++ committee std::shared_ptr ;-)
• Ditto for C++ Boost regex (Update: or wait for std::regex - see also Re: Regex match for Any number of words? by davido).
• Error handling.
• Logging.
• Tracing.
• Debugging.
• Memory management.
• Concurrency and locking.
• Thread-safety and reentrancy.
• Exception-safety.
• Portability. I need a cross-platform mutex. How well do C++ templates work on HP-UX? I need file locking or threading that works on both Unix and Windows.
• Libraries. For C++, should I use Boost or something else ... or write my own?
• Documentation. Should I document my C++ code with doxygen or something else? For Perl, POD or Perl comments? BTW, see PBP 7.2: "Create standard POD templates for modules and applications".
• Naming.
• Internationalization and Localization.
• C++ Unit testing/Mocking. Should I use CppUnit or CxxTest or Catch or Boost or GoogleTest/GoogleMock ... or write my own?
• Code review checklists.
• Build and release engineering. e.g. revision control, makefiles, ...
• How do I make a customer patch?

Note: More bullet points were added long after the original reply

In the interests of development speed, I don't want each member of my team to similarly repeat his research and analysis.

I'd expect of my team members to have encountered such situations many times in the past, and have done the research and analysis long before being hired. For junior programmers, I expect them to do the research once they encounter a situation for the first time, and remember them. It's called experience.

Now, there maybe situations that require different solutions for different projects. But you cannot both follow a company wide coding standard, and use a different solution each time.

Color me anarchist, but when some, well, as you warily put "strong personality" manager hammers down how I shall code, "enforcing the teamwork" if I may, then a good half from the joy that comes from programming is gone. Well at least in my case.

I understand that my experiences do not disproof the validity of your points. But emotional responses aren't really provable, and mine currently are such that when I hear "coding standard" I flinch.