[taeric]

Of course, this is a wonderful example of how a literate style works. Despite the small variables names, the code is easy to understand because of the accompanying text. My (admittedly biased) leaning is that it is easier to understand than a similar snippet with "good variable names" without the accompanying explanation.

That is, if you aren't willing to read this article, then I have my doubts that you would have worked through any free standing code.

[phillmv]

Yeah, but you should still have meaningful variable names.

Let's be honest here, very few people practice a good literate style.

[taeric]

Hmm... I definitely do not want to just toss out meaningful variable names. I'm torn, though, as I feel that if we had better practices in place to promote literate styles in general, we'd be in a better place. (That is, I think the return from literate styling is higher than the return from meaningful variable names.)

It really just comes down to adding a narrative to what you're doing. I think the README convention that github has helped push out there is doing more to get people using each other's codes than any amount of variable naming.

[phillmv]

>I think the README convention that github has helped push out there is doing more to get people using each other's codes than any amount of variable naming.

Well… the README file is an ancient convention that probably stretches all the way back to the 70s.

IMHO, no, not at all. Github is helping people cos it lowered the cost of publishing code by 1) making it easy and 2) putting code at the forefront of the project.

In my ideal world, we would all use something like Docco - http://jashkenas.github.com/docco/ - but in my day to day I count myself lucky if I find the barest amount of class documentation, let alone a literate style.

So: people will do what is easy. Everyone should start by having meaningful variable names.

[taeric]

Yes, apologies, I meant to word that in a better way. I knew github did not invent the readme, it just seems they are sparking a revival of it. In that I mean you don't just get a bloody jar file (or whatever) and have to go looking for ways to use it. Take a look at any good shared project out there and there is just a text file outlining how to get going with it.

I think this is possibly my being jaded with Java's documentation conventions. It can be great for index level documentation, but is absolutely terrible at showing use cases and why things were done the way they are.