separate your Coding Standard from a Style Guide.
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: Dont 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
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 =
"HTMLParser.getToken() Error: " +
" does not exist in the Token list"
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;
- 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
ArrayIndexOutOfBoundsException 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:
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.
Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
Read Where should I post X? if you're not absolutely sure you're posting in the right place.
Please read these before you post! —
Posts may use any of the Perl Monks Approved HTML tags:
You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
- a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
Link using PerlMonks shortcuts! What shortcuts can I use for linking?
See Writeup Formatting Tips and other pages linked from there for more info.
| & || & |
| < || < |
| > || > |
| [ || [ |
| ] || ] ||