Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl: the Markov chain saw
 
PerlMonks  

Re^2: Why Create Coding Standards and Perform Code Reviews?

by gwadej (Chaplain)
on Jul 03, 2009 at 18:00 UTC ( [id://777101]=note: print w/replies, xml ) Need Help??


in reply to Re: Why Create Coding Standards and Perform Code Reviews?
in thread Why Create Coding Standards and Perform Code Reviews?

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

Replies are listed 'Best First'.
Re^3: Why Create Coding Standards and Perform Code Reviews?
by BrowserUk (Patriarch) on Jul 04, 2009 at 03:23 UTC
    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.

      Wow... I didn't mean to hit a nerve.<grin/>

      Despite what it appears from your response. I'm in almost total agreement with you. Much of what you appear to disagree with is from my paraphrasing and abbreviating the book. If you get a chance, I highly recommend it.

      Most of the coding standards in the book are what most of us describe as good coding practice with a short blurb about why. It then refers you multiple texts for the full discussions about why you need to follow these standards.

      As you've described, they talk about consistent formatting (in the item 0) but don't mandate what that formatting is.(The particular style is "unimportant".) If I remember correctly, they may also have mentioned the "style per file" is more important than "style for all code" and to avoid wasting time with reformatting for the sake of reformatting. Or, that may be in one of the books they referenced.

      G. Wade
Re^3: Why Create Coding Standards and Perform Code Reviews?
by Anonymous Monk on Jul 03, 2009 at 18:49 UTC
    I love the recomendation to separate the style guide from the coding standard.

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://777101]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others pondering the Monastery: (4)
As of 2024-03-29 11:17 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found