DAVES Coding Standards Manifesto
By David C. Walley
First placed in the public domain 2012 Jun 20, in the hopes that you will help improve it.
There is a lot of talking to be done first – to turn radical into obvious and sensible.
Thinking is critical, comfort is illusion.
Developers of the world unite in not uniting. It makes no sense to thoughtlessly repeat the same style of work when we know we will repeat the same bugs. We can do more than fix today’s bug, we can fix our style so the bug has no tomorrow.
To err is human, to repeat is robotic. So, are we programmed or are we programmers?
Let us be unafraid to contemplate and discuss our human failings. Let us start by examining what we now accept without thinking. Let us evolve a better way, every day.
Let us talk, think and learn.
DAVES (the acronym’s similarity to my name is purely accidental, I swear) coding meta-standard for programming languages, and an approach to the profession and craft of technology development. The starting point is a blank canvas with no automatic acceptance of existing standards. This is not a rejection of industry standards, but it encourages re-evaluation of all practices on an on-going basis.
The largely unwritten rationales behind the broadly accepted coding styles need to be re-examined with an eye to improving code quality. Supporters of DAVES believe many common practices are the result of tradition and the comfort of following footsteps. We do not reject common practice and tradition as a rule, rather, we advocate fair and open examination of ideas old and new.
Supporters of DAVES believe rationales for a new style must include readability, expandability, fixability, quality, efficiency, logic, and in particular, systematic eradication of bugs of all kinds.
We ask for a fair hearing before judgment.
We believe in being open with our biases, as they are inevitable, but we are open to persuasion by logic and counter-examples. This author admits to a bias against aspiring to be average.
Having started on this path some time ago, to start the discussion I present the style axioms I have come to believe:
There is value to having a standard, but it does not have to be the same as our competitors’. It is helpful to know, at a glance, which details of code are from an outside source, and what is ours and subject to change by us. If an organization shares an easily learned distinctive style, insiders can take pride in the quality they understand at a glance, even if competitors are baffled.
Evolution demands alternatives.
If you disagree with the above axiom, then we will disagree about everything that follows, so let’s part as friends now. If you agree that trying different coding standards is needed for progress, then let’s talk further.
As much as possible, a style should be adaptable to different languages. Style can guide those unfamiliar with a language to understand it quickly. Languages will continue to come and go according to the demands of technological change. Coding style should evolve according to the demands of the human brain – which is both plastic and hard-wired.
A style should take advantage of the human visual cortex, to see patterns at a glance, and most importantly to see when those patterns diverge. Looking closely should show local patterns, looking broadly should illuminate broad patterns. Good code that looks good is the goal, bad code that looks bad is okay because at least we can recognize it, but bad code that looks good is a freaking disaster.
The word ‘comment’ evokes an image of a petty, off-hand statement. Code should be ‘explained’. A style should encourage explanation, and get out of the way when not required. Pity the maintenance programmer, they might have to read your comments. Almost always, they are NOT interested in how or why code works, they want to know why it does not. That changes everything, including the basic assumptions of the “Clean Code” school.
Developers should be proud to sign all of their work, and welcome open-minded scrutiny. Copyright, source control systems and reviews are all indispensable, but we also need pride-of-craft, and that means signing. Historical examples, such as the signing of paintings, indicate that quality improves when work is signed.
If you disagree with any of the other axioms, that is okay, because we welcome distinctive styles, we welcome different ideas, and we welcome discussion. This author holds to all of the axioms, until shown better, and we use them in all of the explanations, proposals and examples that follow.
David C. Walley