Kudzu’s Coding Conventions
My Experience, My Standard
My conventions come from nearly 40 years (as of 2018) of coding in dozens of languages. Currently I primarily use C#, Delphi, TypeScript and x86/x64 assembly.
Goals
My standard is guided by the following goals:
- Unobtrusive – Cost of compliance must be low. Coders should be able to focus on coding rather than bureaucratic rules for which they nor anyone can demonstrate any benefit.
- Flexible – Heavy on guidance, with only minimal hard fast rules.
- Language Neutral – If you are coding in more than one language, make your standards are as cross language as possible with language specific rules only when necessary.
- Evolutionary – Tools and languages evolve and often obsolete coding standard rules. Regularly review and revise.
The High Cost of Compliance
Coding standards are established within most software projects. In most cases that I have seen coding standards are overly restrictive and include rules that have no real value and in worse cases are a hindrance to coding rather than a benefit.
When coding standards become like the US tax code (~8 million words), they become either impossible to comply with, or compliance costs become so high that the code suffers.
WWSD?
WWSD? What would Spock do? Code like Spock, not Jesus.
Choice of coding language often becomes religious, so it is no surprise it extends to coding standards. This is wrong and coding standards should be logical rather than religious canon. Few coding standards have ever been thought about deeply, if at all. If a rule or guideline cannot be justified with a tangible technical benefit, it should be disposed of.
Be Flexible and Trusting
Obtrusive standards are not only bothersome and counterproductive, but make developers feel like they are being treated like idiots. If your team has junior developers, focus on training them and growing their knowledge rather than blind obedience to rules.
If you have developers “in it for the money only” and who are not up to par, get rid of them. A team is often better off short a developer than to have a developer dragging down the team with bad code checkins that require more developers to undo and back out their changes. If you can’t get rid of them, marginalize their role or seek to have them transferred.
It can be difficult to explain to management, but a case can often be made. I once successfully explained to management that I had to assign 2 senior developers to “follow” a single junior developer. Thus 3 developers were involved in doing basically nothing productive. Letting go of that one developer reduced physical head count by 1, but increased our virtual head count by 2 by allowing us to regain the 2 more senior developers for productive work.
Be a Polyglot
If you are coding in more than one language, make your standards are as cross language as possible with language specific rules only when necessary. The whole world doesn’t speak only English, and likely you won’t only code in a single coding language your whole career.
Meet the Flintstones
Coders often love to introspect written code and refactor it to improve it. So why are coding standards treated like some kind of commandments delivered thousands of years ago on stone tablets? Most coding standards I have seen fall into one of these categories:
- We have always done it this way – We have no idea why we do it this way. But we keep doing it, because its our standard.
- Joe/Jane wrote it – At some point it was decided we needed a standard, so one was written. But the person who wrote it was motivated like a legislator who was more motivated to simply produce a lot of legislation (volume) to appear successful rather than produce something useful.
- We adopted some standard we found on the internet – Many standards published on the internet, even by the big boys like Microsoft and Sun are horrible in many key areas and suffer from the problems outlined in this article. Many are written by C++ developers with little regard for the target language they are writing the standard for. Things that make sense in C++ do not always make sense in C#, Java, Delphi, or other languages.
Our languages and tools evolve, and so should our coding standards. Many things written into coding standards become obsolete or negligibly useful as our tools and languages evolve, yet obsoleted rules are almost never removed from coding standards and accumulate into a bureaucracy of rules.
Coding rules should be regularly reviewed and revised with input from every involved developer rather than by a single person.
Sins of Our Fathers
First, lets dispense with the religious nonsense. Many readers will react strongly, even virtually violently to some things I will discuss in this section. That more often than not is a sign of religious adherence, rather than logical reaction.
If you have such a reaction, please honestly ask yourself this.
Why do I follow this practice?
Can you elaborate a single beneficial technical reason let alone a justifiable one? In nearly every case an honest person will boil it down to:
I learned this way, I’ve always done it this way, but I’ve never honestly thought about it.
Old habits die hard. And some have lived well beyond their lifespan. It is time to let go.
Hungarian No No
Fortunately, Hungarian notation is one rule that actually has largely been abandoned but is still in use today in some places. 25 years ago Hungarian notation did make sense in many cases because of the state of languages and tools. But even then, it made sense only for UI controls or at least classes. ie butnOK or btnOK for an OK button. Such was very common in pre .NET Visual Basic and very helpful at the time.
Tools and languages have evolved to better solve the problems since then and Hungarian notation provides little benefit today and is outweighed by the compliance costs.
In extreme cases some shops still use Hungarian notation for simple types like iIndex for integer, fIndex for float, sIndex for string, etc. This is a horrible practice and should be avoided. This practice also leads to duplicated names, that is iFoo and sFoo being used in the same scope which leads to necessary confusion.
Case Sensitivity
Never ever code for case sensitivity, even if the language supports it. See Case Sensitivity is an Anti-Pattern.
Coding in the Desert
here We are at another “i Can’t believe I have to debate this $**t.” despite Even Microsoft and .NET adopting Pascal Casing, others Are still holding to camelCasing As a feature.
camelCasing (or is it CamelCasing since its the first word in the sentence?) is much more common than foo Foo (can we just call it fufu?) and is the predominant continued practice in many languages today. Fortunately its problems are far less than fufu, but none the less it has detrimental effects especially when combined with the prevailing case sensitivity of languages today. The bigger problem though is that it really has no beneficial effects and simply used for the same reason as fufu: “We’ve always done it this way.”
How We Got Here
fufu and camelCase are essentially the same problem, or at least camelCasing seems to be caused by fufu. Wikipedia says the actual origin is unknown, but it seems logical and obvious to assume how it came about.
Coders had a variable named foo. Variable names no longer had to be short and programs became far bigger, so more distinctive names were needed. fooforfred was too difficult to read.
foo-for-fred was also tried, but most languages did not allow – to be used in identifiers. Next foo_for_fred was tried, but many languages did not support _, and _ requires a shift key so it was what I call shifty. That is, it required a lot of use of the shift key and was inconvenient to type.
It could have been adjusted normally to FooForFred, but that “offended the senses” of coders who had no programmed into their brains that variables must start with a lower case letter. So instead of doing things right, they did what was easy and we got fooForFred.
The Actual Standard
This is as living document and I will update it over time. Initially I will focus on adding the most important rules first, and adding guidelines later. For now at least I have covered some of the bigger convention problems so that I don’t have to regurgitate the history to each and every new coder that joins one of our open source projects.
The Rules
If a language is case sensitive, abide by it but do not use it as a feature.
Pascal Casing
Obviously by this this point it should be clear. Use Pascal Casing.
Identifier Naming
Hungarian notation is not used, however prefixes are used to identify important aspects of certain identifiers, usually scope.
Even to this list, there are exceptions. But they should be rare, and exactly that – exceptions.
g is for Global
In some languages like most .NET languages, there are no global variables. In those that support globals, they are usually necessary in some cases. They should however be minimized and static members of static classes preferred. However when the are used, they should be prefixed with g.
|
1
|
gLoaded = false;
|
This article is currently under edit and the rest may appear to be a cluttered mess until completed.
_ is for Member
shift {, why _
_ from m from f, f and l are tall skinny
a is for Argument
a / r / o
x is for Local
x from l
this. req in ts
The Guidelines
Code Formatting
personal, rarely technical. be free.. use formatters
} hanging
Taken from Kudzu Coding Conventions.