Beefy Boxes and Bandwidth Generously Provided by pair Networks
We don't bite newbies here... much
 
PerlMonks  

Why Create Coding Standards and Perform Code Reviews?

by eyepopslikeamosquito (Canon)
on Jul 02, 2009 at 01:27 UTC ( #776607=perlmeditation: print w/ replies, xml ) Need Help??

Since writing On Coding Standards and Code Reviews, several people have asked me:

  • Is it worth it to have a coding standard and to perform code reviews?
After all, you pay an opportunity cost in that time and energy spent on these activities might be better spent elsewhere.

I should have thought about this earlier because it would have helped focus our coding standard effort on tangible business benefits.

To remedy that oversight, I list below what I see as sound reasons for having a coding standard and for performing code reviews. I'm posting my notes here to gain some useful early feedback.

Why Have a Coding Standard?

Successful software tends to live a long time: bugs are fixed; new features are added; new platforms supported; and the software adapted to new markets. That is, successful software development is a long term activity. If you plan to be successful, you should therefore plan for your code base to be maintained by a succession of many different programmers over a period of many years. Not planning for that is planning to fail.

This is the primary reason why you want a company coding standard: to make long term code maintenance easier.

Notice that if you choose instead not to mandate a coding standard, you'll likely end up with an informal one anyway, as some strong personality in your organisation fills the vacuum by evangelizing their own set of pet coding rules.

The goals of a good coding standard are:

  • Improved code maintainability.
  • Improved code quality. In particular: testability, supportability, portability, security, efficiency, robustness, high cohesion/loose coupling.
  • 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.
  • Make it quicker and easier for a developer to move to a different project or team.
  • 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.
  • Higher company IP value.
  • The coding standard should be something developers learn from, want to follow, and want to contribute to; it should make their lives easier, not harder.
  • The coding standard should be a living document; you need a mechanism for evolving it and for dealing with the millions of lines of old code that are affected by changes to it.

The above list represents real business benefits which should help you decide what to put in your coding standard and what to leave out. My experience here is that shorter is definitely better. The longer your coding standard document, the less likely that it will be read, understood and followed.

Why Perform Code Reviews?

  • Find and fix defects early.
  • Code review often proves more cost effective than testing. (See, for example, The Case for Peer Review).
  • Good mentoring/training/learning/team building, especially for new hires.
  • Gives broader experience to team members.
  • Makes it easier for one team member to maintain another's code.
  • Improve overall quality of the code.
  • Enforce coding standards.

Of course, code reviews are not free and there is an opportunity cost in that time spent reviewing code means less time spent on other activities.

References

Comment on Why Create Coding Standards and Perform Code Reviews?
Re: Why Create Coding Standards and Perform Code Reviews?
by Your Mother (Canon) on Jul 02, 2009 at 04:43 UTC

    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... "

Re: Why Create Coding Standards and Perform Code Reviews?
by johnwashburn (Sexton) on Jul 02, 2009 at 11:32 UTC
    RE: Of course, code reviews are not free and there is an opportunity cost in that time spent reviewing code means less time spent on other activities.

    I think you need more here. Which activities could you spend time on (slinging code, taking tech support calls, doing in-field programming, working on design reviews, etc.)? Which activities are reduced by code reviews (fewer tech support calls, less in field programming, less patching, less PR spin to explain crappy performance, avoiding patch Tuesday, etc.) Which activities are slowed by code reviews and design reviews (design reviews delay the on-set of coding, programmers complain that reviewing code draws them from their core tasks, etc.)? All of these cost/save money.

    Code review only pays if you take the long view (as you do) and you show the savings in maintenance costs offsets the increase cost for initial development.

    As a QA guy I use this example from my past.
    I worked at a company with about 120 developers. I saw all five kinds of developers (see below).

    One was always dinged as being "slow". He would deliver his initial code at a rate of about 15% behind nearly all of his peers. None the less was trusted and seen as an excellent developer. During a review he was as to speed up and his response was that quality would suffer; which is how I got pulled into this as a personnel matter. (BTW using QA people and QA metrics for developer personnel reviews is STUPID. If you as a manager did not know the information below, then you should not be a manager. </rant>)

    What we in the QA department noticed and could demonstrate was that his code almost NEVER went back for re-write. We had defect records and support call records going back three to five years (depending on the module). Almost never is defined as just a bit more than 1/50th of the defect density rate of his peers. Where is peers averaged 100-105 defects per 1000 function points. He introduced 2 or 3 for the same measure of code size. His unit testing and personal code review style was off the charts phenomenal. When he said the code was done, it was done. We had implemented Fagan reviews, but he had internalize the principles nearly a decade before.

    Over beer, I asked on this and his answer was:
    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.í
    My take away was we all make mistakes. The best of us though understand this and plan for ways in which those mistakes will not leave our desk, leak much further than our peers or, at the least, never leave the company walls. Even master welders subject their welds to X-ray and other inspections because a few cold welds in the wrong place can undermine the whole steel structure. Also it is better for your welding buddy to find the cold weld, than your foreman. Better the foreman catch the cold weld than the city inspector.
    Hopefully there is someting in the above you can use.
      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.
Re: Why Create Coding Standards and Perform Code Reviews?
by gwadej (Chaplain) on Jul 02, 2009 at 13:41 UTC

    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.

    G. Wade
Re: Why Create Coding Standards and Perform Code Reviews?
by dk (Chaplain) on Jul 02, 2009 at 17:42 UTC
    I'd like to comment on one of question-answer pairs here, on "Why Perform Code Reviews? - Enforce coding standards". That's the enforcing part that I particularly dislike.

    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.

Re: Why Create Coding Standards and Perform Code Reviews?
by Burak (Chaplain) on Jul 02, 2009 at 19:55 UTC
    Code reviews (and standards) can also prevent cleverness (i.e.: actual code golfing in producton code). However, if the reviewer is not more experienced in the language, low performing or unnecessary constructs can still slip. I also think that there must a an automatic tool (like Perl::Critic) in the process. Btw, if you are implementing coding standards into the process, then it must be applied backwards on old code too IMHO. Lets say; if you forbid tabs, remove tab indentation from older code if it is still maintained. And column width is usually missed. I hate to see 500 chars on a code line (nope, word wrapping in an editor does not solve this shit).
Re: Why Create Coding Standards and Perform Code Reviews? (how not to)
by tye (Cardinal) on Jul 03, 2009 at 04:29 UTC

    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).

    - tye        

Re: Why Create Coding Standards and Perform Code Reviews?
by JavaFan (Canon) on Jul 03, 2009 at 13:36 UTC
    In a couple of $WORKPLACES, people have been discussing introducing coding standards, and enforcing them. Each time, I've been successful in changing their minds.

    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.
    Perhaps, but that strongly depends on the standard. It also doesn't mean code that doesn't adhere to some standard isn't maintainable. But what's more important is the trade-off. Unless the standard is your own standard so you don't have to think about it, following the standard takes an effort. I'd code much more slowly if I had to follow everything PBP says - just because it sometimes wildly differs from my style. So the business pays a price: it takes longer to write new code. Now, if your code lives for many years, and needs regular maintainance, ease of maintainance is important. But if code has a short half-life cycle, faster delivery of code at the expense of creating "techical debt" is better for the business.
    Improved code quality. In particular: testability, supportability, portability, security, efficiency, robustness.
    That requires a very good coding standard. I'd be interested to see a Perl coding standard that improves code in half of the mentioned topics.
    Improved development speed. Your developers don't need to make all decisions starting from first principles.
    That I strongly disagrees with. Almost any rule a programmer has to follow decreases coding time, it doesn't increase it. (If it did, it wouldn't have to be in the standard.) I don't understand your argument though. What have first principles to do with coding, or coding standards?
    Better teamwork. Don't waste time with needless debates. Spend your creative energy on things that matter.
    I've wasted time on many (needless) debates about coding standards, including the time I spend writing this message. I've never had a co-working coming up to me asking why I put (or didn't put) a space somewhere, or why I omitted an arrow. Nor do I ask my co-workers about details. Now, I might ask a co-worker why they used a cubic algorithm instead of a quadratic, or why they opted for Module X instead of Module Y, but I doubt such things could be covered by a coding standard.
    Better performance under pressure. Under stress, people fall back on what they've been trained to do.
    But what people have been trained to do is most likely not the rules laid down in standard of their current $EMPLOYER. If I have a dead line loming, I'm much more likely to finish before the deadline if I don't have to check my code with the rules in the coding standard - its rules won't be better or worse than my rules, but they are different.
    Fewer bugs. Good standards should minimize common coding mistakes.
    Doubtful. I'm not going to make less bugs because I'm following someone elses rules. Now, I will make less bugs if I am following my rules, but it's unlikely my rules will match $WORK rules (again, not that one rule is better than the other - many coding standard rules have just one purpose: uniformity). If I have to do work to make live easier for someone, than that's not free. It takes me time, and I'll make mistakes I wouldn't have made otherwise.
    Shallower learning curve and useful training for new hires -- if your standard mandates proven, well-known idioms and style from the programming mainstream.
    More rules means there's more to learn.

    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. For example:

      • Should I use C++ boost shared pointer or write my own "from first principles"?
      • 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 write my own?
      • Documentation. Should I document my C++ code with doxygen or something else? PBP 7.2: "Create standard POD templates for modules and applications".
      • Naming.
      • Internationalization and Localization.
      • Which of these three similar CPAN modules should I use?
      • Unit testing. Should I use CppUnit or CxxTest or write my own unit test framework?
      • Code review checklists.
      • Build and release engineering. e.g. revision control, makefiles, ...
      • How do I make a customer patch?

        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.

Re: Why Create Coding Standards and Perform Code Reviews?
by BrowserUk (Pope) on Jul 03, 2009 at 15:15 UTC

    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.


    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.

      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
        I love the recomendation to separate the style guide from the coding standard.
        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:

          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; ...

          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; }

          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; ...

            Why isn't that?

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

            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 = ...

            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.
Re: Why Create Coding Standards and Perform Code Reviews?
by ELISHEVA (Prior) on Jul 04, 2009 at 20:46 UTC

    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.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlmeditation [id://776607]
Approved by ikegami
Front-paged by Arunbear
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others having an uproarious good time at the Monastery: (2)
As of 2014-09-22 05:57 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    How do you remember the number of days in each month?











    Results (182 votes), past polls