The other day I talked to a collegue about some technical details and doing this I took notes directly in code. When we finished this collegue asked me not to delete these comments. A little peculiar in itself (who would have done such a thing?) in this particular case the comment had a double meaning: The code being some more or less complex mapping of numeric ranges would not have been comprehensible without comments. And in my opinion incomprehensible code is worse than bad code. Bad code can be fixed after all.
About the same time I stumbled over an article that pointed to “Proof reading is more important than composition“. The authors opinion about readability is something to applaud. All the more irritating how wrong his conclusions are (just my opinion of course!). He deprecates coding conventions as being of adverse effect for readability. Having worked on software in teams of up to 80 developers and of different age (in terms of versions and maintenance impact) I am accustomed to read and evolve existing code as well as write code that has to be understood by other developers after I have moved on. And of one thing I am certain: Coding conventions are a necessary requirement for readability. Of course they are not sufficient, but do away with them and readability will follow shortly. All it needs is the next developer working on the code and using his personal coding style. This has to happen only once, no way to put the chicken back in the egg.
While the author of this article started with a right assumption and quickly got it wrong, the author of the article that pointed to it did the opposite: He started with a wrong assumption (“few people actually … are going to come back and read that code” — if the code matters, people will come back) but he quickly gets it right. I especially like his distinction between programmers and developers:
- Programmers write code to solve problems
- Developers write code that can be read by other people and to solve problems
I recommend reading that post because the author makes some good points getting there and even better ones based on that statement.
That’s all for now folks,
AJ.NET
AJ's blog 
Correction: I deprecated coding conventions as a focal point for readability.
Give a person a fish or teach them how to fish? A coding convention document by itself is the equivalent of giving your developers fishes. They learn to comment every method, but not write meaningful comments.
Teach them how to improve overall readability, learn why and where it matters, and they’ll write relevant comments in relevant places.
Will a coding convention exist? You bet: it leads to maintainable code. But not only will developers follow it, they’ll collaborate to create something that’s much more consistent and readable than if all they had was a document that said “write a comment on each method”.
It’s the difference between following the book, and participating in writing it.
Comment by assaf — January 7, 2007 @ 12:18 am
I should have expected some kind of comment 🙂
If you say “coding conventions are not an end in itself but a means to readability” and “use your brain when applying coding conventions” I’m with you. In fact after reading your comment I think we are on the same side. It’s just that I don’t read your post that way, actually there you said “Forget about coding convention, just write the code.”
Also I would rewrite your metaphor to: Coding conventions is like giving a person a net. But it needs teaching and experience to use that net to catch a fish. The fact that one might strangle himself with a net does not lead to the conclusion “forget about the net, just get the fish out anyway you want”.
Anyway, I think we both share the same intention, yet argue about the way to get there. Let’s settle this as different points of view as long as other people get the idea.
AJ.NET
Comment by ajdotnet — January 8, 2007 @ 8:40 am
Thanks for the links AJ.NET, I would like to just jump in and qualify my “wrong” assumption.
“few people actually … are going to come back and read that code”
That statement is based on my experience at my current day job. I can see why you’ve read it as an incorrect assumption – it’s my bad for not being more clear. It is not intended to imply that code is write-and-forget and it isn’t re-read by anyone. I actually meant “where I work; code is write-and-forget and it isn’t re-read. This act of not revisiting code and understanding it is bad.”
Apologies for correcting my own posting on yours. 🙂
Comment by Tom — January 8, 2007 @ 7:05 pm
Never mind 😉
Actually while your statement may be overly pessimistic, mine may be overly optimistic (kind of wishful thinking). Just this morning I had to discuss a code review that had the two major issues I almost allways encounter. Readability is one of them. (The other one is robustness.)
Anyway, I keep trying and it’s good to know that I’m not the only one.
AJ.NET
Comment by ajdotnet — January 8, 2007 @ 9:40 pm
I really did mean “forget about coding conventions, just write the code”. It’s a leap of faith. Try writing code without paying attention to coding conventions, but fixing it for readability every time you have to go through it.
(I don’t know about you, but I have just enough bugs and fixes that I end up reading the same piece of code several times over)
When I do that I end up with very readable code. Does it look consistent? You bet. Because I hesitate when it’s inconsistent, or poorly documented, or too complex, or too terse. And after fixing the same thing over and over, it’s imprinted in my brain how to write it well the first time.
So it converges towards a coding convention very quickly, but it ends up more readable than if all I did was memorize and follow a coding convention document. Sometimes the best way to get something is to let go.
Comment by assaf — January 8, 2007 @ 9:53 pm
See, here we disagree.
This might work if your are the only one working on that code. You are accustomed to your own coding style and evolving it should be relatively easy. Given the fact that it is usually the most complex or error prone code that is looked over mostly, you will also have the bennefit that by incrementally improving it you will spend this work very efficiently where it’s needed mostly.
But what if there are other developers during development and especially during maintenance? No coding convention to begin with? How should the next guy understand your code if he confuses classes with parameters? Incrementally improving code? What if the next guy just did that and applied his personal style, in the process wrecking your half polished code? Can you imagine code ping pong, e.g. you constantly adding underscores to fields, your neighbour constantly removing them?
No way. Any none-trivial project needs a means to herd the cattle, otherwise it would be doomed.
Just my 0,02€ (albeit learned the hard way).
AJ.NET
Comment by ajdotnet — January 9, 2007 @ 8:56 am
Excuse me for jumping in here, but this is again the difference between developing and programming.
Assaf is correct, as long as his stance is “this *programming* convention works for me”. The incremental updates and fixing works for him. On his projects with his code, when it’s him who has to go back through it and fix or enhance it.
However, AJ.NET (and myself) are correct, as long as our stance is “we all must conform to *development* standards”. When you work in a team with a size greater than 1 you have to make sacrifices for the benefit of that team. That might mean using CamelCase or it might mean Using_Underscores. It might mean putting your braces on the line that they open, or maybe on the next line in column 0.
But whatever the standard is, everyone has to stick to it. If all the code looks the same your brain trains itself to read it more quickly. If just one person doesn’t conform that training is wrecked.
What’s the hassle with just hitting Ctrl-Alt-F (in Eclipse) before checking your stuff in?
Comment by Tom — January 9, 2007 @ 2:57 pm
This works out pretty well for me with several groups of people, across several projects, with different conventions. (Funny how some languages are CamelCase and others are under_score). The reason is, we’re not motivated to put our own unique stamp on the code: we’re motivated to make it maintaintable.
When you have that sort of motivation, you’re not “making sacrifices”, or being herded. You want to create code that’s readable, and it’s surprisingly very easy to do. And it goes beyond the One True Use of the underscore, into explorations of better ways to comment, write test case, organize build systems.
Caring about maintainance at its very core implies caring about what other people will be doing.
But it wont work if you have to deal with developers who want to do their own thing, who think their personal style is more important than the future of the software. If you are in a situation that demands sacrifices and requires herding, then my advise is clearly wrong.
Comment by assaf — January 9, 2007 @ 7:26 pm
Apropos coding conventions:
http://thedailywtf.com/Articles/Little_Black_Book.aspx
Comment by assaf — January 10, 2007 @ 10:06 am
Why is it that style can’t be abstracted out from semantics in source files? Why can’t IDEs consume and produce text files with some kind of embedded source DOM instead of the source itself? Why can’t the IDE take such a source DOM and display it *according to the developer’s preferences*. Why can’t the compiler take the source DOM and turn it into code? etc. This whole debate then becomes a non-issue. Just throwing it out there coz it’s been bothering me for a while.
Comment by Kent Boogaart — February 13, 2007 @ 4:05 am
What you are dreaming about may be “intentional programming” http://en.wikipedia.org/wiki/Intentional_Programming , something Charles Simonyi, the “inventor” of Ungarian Notation worked on – quite a coincidence, isn’t it? However an apple is still an apple and you have to name it accordingly, no matter how you present that name. If somebody used that term for an apple shaped piece of meat, your pie would disqualify as dessert.
Comment by ajdotnet — February 13, 2007 @ 8:09 am
Not quite what I was thinking of, but thanks for pointing that out – I hadn’t heard of IP before. Here’s my idea in a nutshell. Suppose you write:
//does something
int i = DoSomething(foo, bar);
The IDE would store this source something like (using XML as an example, but might be a binary format like IP):
does something
foo
bar
The IDE would be able to use such a format to display the code however the dev likes. Perhaps:
// does something
Int32 i = DoSomething ( foo, bar );
Note the extra spacing and “Int32” instead of “int” – very much a .NETty example. Obviously this is a simple example and you would still need conventions for naming, but conventions for whitespace, brace positioning etc. would be unnecessary.
Comment by Kent Boogaart — February 14, 2007 @ 12:47 am
But conventions for whitespace, brace positioning etc. already are (nearly) unnecessary. With all those code beautifiers, either as addons (e.g. ReSharper) or build in (VS as well as Eclipse) the days in which we had to agree on tab size are fortunatelly gone. Usually this “reformating” is even sytax aware, e.g. it allows you to shorten namespace qualified names and reorganizes usings/imports.
Comment by ajdotnet — February 14, 2007 @ 7:56 am
I disagree because those programmer’s conventions are then persisted to the source file, making diffing problematic.
Comment by Kent Boogaart — February 15, 2007 @ 12:37 am