Damien Katz

Reading horrible comments makes reading code harder. I normally will remove all comments from a source document with stream libraries that I have. And if the programmer doesnt write 1000 line functions and uses a standard coding convention, reading code should be pretty straightforward. I think writing code is not hard either, it is easy to throw stuff together. Writing applications that people want to use is the difficult challenge.

If we learn that one, we will be living in Bill Gate's world.

I agree bad comments are far worse than no comments at all. I remember once looking at some code and I couldn't make heads or tails what it was supposed to do. I asked the guy who wrote it originally, and he said he copy and pasted most of the code, but didn't change the comments from before. I wanted to kill him, but I was also happy I wasn't going crazy.

It really does depend both on the coding style and the language. And the benefits of one can easioly outweight the other.

I learnt formula language in Notes by reading the formulas in the standard Notes templates. But then, formula language isn't too difficult, and tends to lend itself only to short snippets. The code itself, combined with the online help available, make it pretty easy to become productive in Formula language. I've seen some formulas which are taxing to break down, but those are usually ones stretching the engine...

LotusScript I also learnt by looking at the code in the Notes standard templates. But I recently revisited one of these to look at something for a project I was working on, and the code was almost impenetrable. I'm talking, specifically, about the code for the contacts synchronisation in the iNotes/DWA template. It has lots of short-named variables (like "i", and "x") which therefore make little sense. It puts EVERYTHING into its own function/sub, so it's difficult to follow the flow of the "program". Comments are sparse. Frankly, even following it in a debugger was difficult - the sheer number of procedures being called made it a taxing experience.

Following it on paper in my mind would have been very difficult. Yet I've done that with many other LotusScript programs - even larger ones.

(Although I did eventually understand it enough to realise that the code wasn't going to do what I wanted, but I felt like I'd wasted too much time discovering that by the time I got there!)

It depends a lot on the language being used. Most people I know think C is a lot easier to read than C++ and James Gosling has said readability was a driving force behind the design of Java. For a really unreadable language look at regular expressions. http://www.regexlib.com/DisplayPatterns.aspx

Reading bad code is hard and writing bad code is easy.

Reading good code is easy and writing good code is hard.

That I think explains it all.

Wasn't there a book completely about how to read code? I think it was specifically for debugging code but I can't seem to find it now on amazon. But reading code is definitely harder than writing it, bad or good. Especially if it is someone else's code. When you write code you have all the organization and logic in your brain. You can keep it all there and generally get right back into it after short breaks. When you read code, even your own, it may take serious time to understand the inner workings of the code. And if people use f'd up logic or comments, it makes it worse. Especially if your brain thinks one way and this code is written another. So many times you are tempted to write code because reading it is difficult. But often times there are subtleties in the original code that make rewriting it a bad idea, even if it is bad code. I think Joel on Software goes into this in one of his articles.

I expect that you have a lot of experience reading bad/good code. This makes it easier and allows you to develop that scanning ability that is necessary to get any real work done.

Take the daily WTF, sometimes the code examples on there I don't even go into because I know that reading them is going to be hard because they are WTFs. Whenever I do read them I immediately go into this rewriting mode that wants to clean up the code and make the logic clearer.

Where are the classics? In literature, there seems to be an agreed upon set of classic writers/novels/works and this ‘code’ is available for all to see, copy, use, etc. etc. There’s no equivalent in our world. No one has ever given me a bit of code to look at and said “See this! This! Ah, it is the standard to which we should all aspire! Write it this way!”

Even for those of us who are just looking to be Stephen King and not Shakespeare, we are in a bit of a bind. I’m willing to bet King reads as much, if not more, than he writes. The two are tightly intertwined. The equivalent for coders I suppose would be to USE as many applications as you write applications. But while using applications may allow the developer to create more useable software, the code underneath could very well be unreadable garbage.

The success of our work depends on the cover, the UI. The goal is not to write code that’s easy to read, it’s to write great applications that are easy to use (and work!). There’s no incentive to write code that’s easy to read. This is why you don’t see well written code, it gets written once, it works, you move on. If you are writing a novel, you would spend an enormous amount of resources rewriting, editing, letting others examine and edit, etc., etc. Try to get that line item into the development budget... and until that happens, I guess we’ll just have to keep waiting for the classics to be written.

Ironically, I often find Formula Language code hard to read, I forgot about that somehow. I think it's because it's so easy to condense code into one complex expression. One thing that was on my personal to-do list at Iris was to make a formula formatter, so it would indent the code in a consistent manner. I never did get to it though.

I guess most of my development work lately has been lower level backend code, where the needs for stability and maintainability are higher. Hence code that's harder to write, but easier to read.

Each programmer will write in their own style. It starts with them thinking differently when solving the same problem. So the difficulty may be in reconstructing the thinking from someone elses code. Its a detective activity, it deconstructs the code to constructs thoughts. When you write code you start with the thought and then translate it into code.

And of course there are many ways to solve the same problem, even many elegant ways. So if you find it hard to read bad code even good code may be expressing the same solution in different ways.
Training and conditioning would help to see through the code to the solution sooner.

Then you may add the complication of different people thinking in terms of the different idiom in their language of choice and you can imagine how some concepts not to mention code might be hard to see and understand.

I would love to see an anthology of software classics. I read about this idea here http://java.sun.com/features/2002/11/gabriel_qa.html

David Bohlin wrote:
"Reading bad code is hard and writing bad code is easy.

Reading good code is easy and writing good code is hard.

That I think explains it all."

Amen, brother. Amen.