kasia in a nutshell

When I posted this entry I never expected it to turn into a long discussion. It was really more of a rant born out of frustration when trying to read someone's code. I don't have much to add other than what is posted in the previous entry, but I thought Burt's (who is a former co-worker, a good friend and an excellent programmer anyone would wish to have on their project) comment deserves to be in an entry all on its own. He explains much better than I why this is even an issue. For context, read the previous entry and all the comments first.

Golly.

This is not a religious war - this is clearly a difference of opinion between people who have different ideas of what clarity is.

There's several key aspects of clear programming that some of the people here are missing:

1. Methods should NOT be 10 miles long. If you need a long variable because you don't reference it until 50 lines later or you don't know what type 'rval' is because the method declaration is 5 pages back in your editor, the problem is with your method, *not* with the choice of name. And in fact, something like rval *is* very clear. After looking at 50 methods all where rval is returned, it becomes pretty damn clear that when you set 'rval', you're setting what is returned. If some uniquely named thing is returned from every method, there is an order of magnitude more effort identifying what is returned.

2. Formatting *is* important. As Mats mentioned, the human brain is great at pattern recognition. If this causes you a bit more effort when you modify code, too bad. Code is read MANY more times than it is edited - Paul, are you suggesting that we should the tradeoff of legibility vs. ease of writing should be made in favor of ease of writing? Shame on you!

I'd say that formatting is even more relevant than the length of the variable name. The clear organization of her example was more important than the length of the variable names - but the shorter length of the variable names enables such clear organization more than variable names such as preparedStatement, jdbcDatabaseConnection, queryResultSet and objLongAss. In addition, your brain's time to process will be proportional to the length of the name, as will the effort to match the pattern. Which is quicker? Finding 'rval' in ( ps, rval, conn, rs ) or finding 'customerObject' in ( customerQuery, customerObject, connection, customerQueryResults )? Furthermore, there is an inherent loss of clarity when you have to break a single statement into multiple lines because you are doing something like

PreparedStatement selectCustomerPreparedStatement = c customerDatabaseConnection.prepareStatement(selectCustomerSQLString); ResultSet selectedCustomersResultSet = selectCustomerPreparedStatement.executeQuery();

3. The aptly-named Aristotle there was 100% spot on. If I'm writing a loop, give me an actual reason to use a giant variable name as a loop index. Since the loop should fit on the screen, i.e. be no more than 5-10 lines, it should be pretty damn clear that i is the loop index - I really don't need something like intLoopIndex to tell me that. If you're finding yourself scrolling back and forth to check variable names and types, you've gone past the point where it's time to refactor a chunk of code into another function/method.

5. Don't knock the C programmers. There's a lot to be said for typing efficiency, and there's a reason why many unix commands are 2 characters or so. Frankly, I am less concerned about there being a slightly longer learning curve for people than I am about treating senior developers as fools, and I am greatly concerned about the effect of 'point-and-click' programming on the capabilities of developers.

6. WHAT THE HELL HAPPENED TO COMMENTING YOUR CODE?! Yes, the code should be clear. But it is your responsibility as a developer to write clear comments! The clearest variable name in the world will still not tell you WHY something was done. I (fruitlessly in many cases) look to the comments for purpose, not to the variable names.

Anyways, I agree with Kasia 100% on this, though I fear it's a losing battle given the vast preponderance of 'helpful' IDEs these day - observe pbw's comments about the editor 'fixing' the code formatting. Great, just what I need, yet another tool that thinks it's smarter than I am.