Merging Conventions to Aid Readability thus Reducing Development Time
When programming in a mixed-language environment,
the naming conventions, formatting conventions, documentation conventions, and other conventions,
can be optimised for overall consistency and readability.
This may mean going against convention for one or more of the languages that’s part of the mix.
For Example…
in many classical Object Oriented and procedural languages,
routine names have an initial capital letter (PascalCase).
The convention in JavaScript is for routine names to have an initial lower case letter (camelCase),
unless the routine is a constructor (intended to be used with the new prefix).
When a constructor is invoked without the new prefix,
the constructors this will be bound to the global object,
rather than where it should be…
The functions execution context.
When invoked with the new prefix as it should be,
the function object will be created with a hidden link to the value of the functions prototype,
and the functions this value will be bound to the function object (where it should be).
Because this convention has a very important reason,
your team may decide to carry that convention across the other languages you use.
Refactor or Document Short, Hard to Read Names
I don’t know how many times I see code that uses very short names which make readability difficult.
What’s worse, is that so often there are many different names that mean the same thing sprinkled across the project/s.
Short, hard to read, pronounce, or understand names are rarely needed with the programming languages of today.
Use easily and quickly readable names where ever possible.
If you have to use short names or abbreviations, keep them consistent.
Translation tables are good for this.
You can have a commented translation table at the beginning of a file,
or at the project level if the names are wider spread.
Names should be specific to the domain your working in, rather than to the programming language.
Meaningful Loop Index Names
If your loop is more than a couple of lines long or you have nested loops,
make your loop index name something meaningful,
rather than i, j, k etc.
Additional Thoughts
- Code is read many more times than it is written.
Make sure the names you choose favour read-time over write-time convenience. - If you have names that are general or vague enough to be used for multiple purposes,
refactor your code, maybe create additional entities that have more specific names. - Don’t leave the meaning of the name to guess work.
This taxes the programmers mind unnecessarily.
There are better uses of our cycles. - Agree on and adopt a set of coding standards and guidelines.
It’s more important to have standards than to not have them because you can’t agree on the “right” way.
They will save wasted time and arguments during coding, and code reviewing.
Tags: coding standards
Binarymist 
January 12, 2013 at 17:49 |
You are talking about an environment where multiple languages are being used.
I’d like to comment on a few of your statements:
>Code is read many more times than it is written.
Actually what you mean, in my experience, is that SOME code is read many more times than it is written. This tends to be a very small proportion. If the code functions, you tend not to revisit it.
>If you have names that are general or vague enough to be used >for multiple purposes, refactor your code, maybe create additional >entities that have more specific names.
If you are writing Polymorphic functions you necessarily have to have general terms.
>Agree on and adopt a set of coding standards and guidelines.
Noble in theory, but it does not survive across languages. Words and functions mean different things in different languages. Whole concepts are different between 2GL’s , 3GL’s and 4GL’s let alone Object oriented, multi tiered, client server, compiled /interpreted/ semi compiled etc. Lisp, Cobol, Assembler, C++, PowerBuilder , T-SQL, PL/SQL and Java were all in one department of a bank I worked for..
January 12, 2013 at 20:31 |
No, actually just about all code is read many times more than it is written.
Even if it’s just skimming over it.
This has been not only my experience.
From Uncle Bob Martin’s Clean Code:
“The ratio of time spent reading (code) versus writing is well over 10 to 1 … (therefore) making it easy to read makes it easier to write.”
Steve McConnell’s Code Complete:
“Code is read far more than written. Be sure to use naming conventions that favor read-time convenience over write-time convenience.”
There are many references to code favouring read-time convenience over write-time.
On Stackoverflow the concept is unanimous:
http://stackoverflow.com/questions/3455488/code-is-read-more-than-it-is-written
Even if you don’t intend anybody else to read your code, there’s still a very good chance that somebody will have to stare at your code and figure out what it does: That person is probably going to be you, twelve months from now.
The best practice is to write it in a manner that the next person working on that project can understand your code easily.It’s better to add naming conventions in manner that even a 10th standard boy can easily understand it.There are some situations when you deliver a application and then after some months Client come back for some further modifications.And sometimes it becomes very difficult to recall all the stuff you have written some months back.That’s why this thing is said.You write your code once,but you have to read it over and over,and even if that project is passed on to another team,then too it must easily readable.
Your code is really the design of your application, so it helps when performing handovers and code reviews to make that design as simple as possible for the reader to understand. Some developers are actively against writing comments in their code, some believe that if you are writing a comment, you are having to explain a design decision which the reader should be able to understand from the structure of a well designed system, without comments.
Are certain coworkers really that ignorant or just very green? It’s no consolation, but if they argue with you on this, I am sure their code is a craptastic mess.
I don’t know of any academic writing supporting this, but it is obvious that the coder needs to constantly reread their code as they write the rest of it and as it evolves. Later, debugging and testing require a lot of reading and often insubstantial amounts of written change. And even later, other people might try to reuse it, before which they must know how it works.
On “The Old New Thing”:
http://blogs.msdn.com/b/oldnewthing/archive/2007/04/06/2036150.aspx
Re general terms:
Names should be specific to the generalisation.
Code Complete:
Names should be as specific as possible. Naming conventions distinguish among local, class, and global data. They can also distinguish among type names, named constants, enumerated types, and/or variables. Regardless of the project, some sort of naming convention should be adopted.
With a little reading, you’ll find the best programming books, authors and our best minds all seem to agree on these things.
It’s nothing new.
January 13, 2013 at 03:13 |
While I agree wholeheartedly on sensible naming, which is probably in each and every coding guideline for every language I’ve encountered in the past 15 years (with the exception of one Oracle database naming convention due to the short identifiers).
I very much disagree on the attempt to, within your department, unify codign *style* across languages. This will make for a very awkward combination of own code and framework code. And i expect that the guys that are most versed in Javascript and HTML5 and such are rarely the ones who have t stick their noses in the Biztalk orchestrations or Deep down database stuff.
My reasons:
– It’ll make the code hard to understand for new people joining fom outside.
– It’ll cause disconnects between the framework and the custom code in many places. So even though all your methods start with a non-capital letter, all the framework methods will. And I hope you’ll be using more framework than custom methods.
– Modern IDE’s will overlay the meaning using colours, icons and other means, so that the style is just one way of showing meaning. I think it shouldn’t be the predominant way any more.
– Sharing your code outside of your organisation will raise eyebrows. When you’ve decided to change these standards, what else might you have though of that was better in your organisation, than enywhere else in the world? That would be one of my first questions as a reviewer.
– A lo of tools will work against you. Resharper, Visual Studio, StyleCop, CodeRush, Code Generation tools etc (in NET Development), are all configured to use the.NET Framework Design Guidelines. When you decide to change the rules, you’ll have to do quite a bit of reconfiguration for each and every tool you add to your suite.
What you could standardise upon across teams and department, is development and deployment processes. A common notation for requirements/user stories and acceptance criteria. A common view on what done is and what quality means.
January 13, 2013 at 15:06 |
That’s why I said “your team may decide”
I assumed a level of common sense.
Be careful with expectations like “the guys that are most versed in Javascript and HTML5 and such are rarely the ones who have t stick their noses in the Biztalk orchestrations or Deep down database stuff”
I’m currently mentoring others on JavaScript and just recently been involved in BizTalk 🙂
With the tools that work against you? get rid of them or change their rule sets. That’s what most companies I’ve worked for do. Seems to make sense?
Couldn’t agree more on the “what done is” and what quality means.
That’s what I’ve attempted at addressing here https://blog.binarymist.net/2012/03/24/how-to-optimise-your-testing-effort/
January 13, 2013 at 10:27 |
As someone who is routinely called in to enhance / debug existing code, I can tell you that writing for readability is king. About 60% – 90% of my time is spent trying to figure out how (and sometimes why) the code works.
Readability is not just about variable_names vs variabeNames vs variablenames vs VariabeNales, it’s about writing so that the code can be read AND understood by someone not familiar with the project. Try going back to code you wrote two years ago – you know that code you didn’t write any comments in because it was obvious what it does, and add some meaningful functionality.
Writing in a consistent way, following a pattern makes editing your code so much easier.
Think of it this way – when some other coder has to work on your code, do you want them saying WTF!!? What was this guy smoking when he wrote this?
Or do you want them to say – Wow this is cool. I’m going to start writing like this guy.
January 13, 2013 at 23:06 |
Peter Lander from Linkedin says:
Several reactions …
1) I disagree with the idea of trying to straight-jacket all languages into a common format … excepting insofar as we are talking the accidental by-product of sensible rules re indentation etc.
2) By far the greatest impediment to clear readability is the fact that most developers have a poor command of English in the first place. Expecting programs to be clearer that the stuff that they ordinarily write is a forlorn hope indeed.
3) In these offshore outsourcing days, the problems are exacerbated.
4) In spite of these three points, we must continue to try to improve the quality of are written words.
Here is something to think about.
I have spent 40+ years urging developers to leave the code they touch not only fixed; not only enhanced; but also in better condition than when it was handed to them.
I have several times been in trouble for this advocacy. Many managers insist that one single jot or tittle more than is absolutely essential is too much expense.
Predictably, the code continuously deteriorates.
January 13, 2013 at 23:08 |
* Yeah, I guess my hope for some common sense may be a little optimistic?
* This is indeed a concern. Which is why we need to keep working on this for all of our sakes.
* Yes Indeed. Although in my experience, I’ve noticed foreign software developers I’ve worked with when receiving the same comments in reviews over and over again, do tend to improve reasonably quickly. Maybe I’ve just had the privilege of working with the better ones?
* Exactly. This is my intention.
“I have spent 40+ years urging developers to leave the code they touch not only fixed; not only enhanced; but also in better condition than when it was handed to them.”
You’re hired! Pretty much word for word from Code Complete, and Uncle Bob’s Clean Code is it? This is exactly what we are trying to install in the up and coming minds. It’s our job as professionals to take our jobs seriously enough that we push back on such managers that show a lack of experience and professionalism with such comments as you’ve described.
This post describes (as well as I could) what being a professional developer means http://elegantcode.com/2010/10/27/laborers-versus-professionals/
February 18, 2013 at 20:39 |
Love this comment from above….. “Think of it this way – when some other coder has to work on your code, do you want them saying WTF!!? What was this guy smoking when he wrote this?
Or do you want them to say – Wow this is cool. I’m going to start writing like this guy.” ….. couldn’t agree more, every now and then I stumble across someone’s clean, clever, efficient code and take their lesson on board 🙂 … balances out the WTF moments !!
March 2, 2013 at 13:01 |
[…] compiled a set of these here: JavaScript Coding Standards and Guidelines Generic Coding Standards and Guidelines C#.NET Coding Standards and […]
March 2, 2013 at 20:58 |
I was just seeking this information for a while. After six hours of continuous Googleing, at last I got it in your website. I wonder what’s the lack of Google strategy that do not rank this kind of informative web sites in top of the list. Normally the top web sites are full of garbage.