Programmer Musings

Coding Style: Terse vs Verbose

One coding style issues that causes many arguments is the distinction between the Terse/Elegant/Succinct style and the Verbose/Legible/Debuggable style. As usual, each side explains that their style is the only rational choice and that the other approach is obviously wrong. First, let's look at the two styles to see what they say. In order to avoid showing too much bias towards either style, I'm going to refer to both using accurate but slightly derogatory terms: Terse and Verbose.

Terse Tim

Let's take Tim, a hypothetical programmer of the Terse style, and see how he explains the style.

PM: Tim, why do you advocate the terse style of coding?

Tim: Because it is obviously correct. Good code style is uses the minimum syntax necessary to get the point across. Anything else is unnecessary and gets in the way of working with the code.

PM: One thing people complain about in terse code is short variable names. Why not use longer names?

Tim: Names should be no longer than necessary. Some incorrect styles require that all names of subroutines and variables and such be long. The longer the better. This is ludicrous.

A short name is just as clear in context. If you don't understand the code well enough to understand the context, a longer name on one variable is not going to fix it.

Longer names get in the way of troubleshooting code. Code that has too many long names ends up with most of them being similar: source_user_name_for_copy and source_user_name_for_compare. What a crock!

PM: Couldn't you just use comments to clarify the differences?

Tim: Oh, yeah. Like that will help. Most comments are wrong. The ones that aren't out and out wrong are usually out of date. The more comments in the code, the more likely that most of them are misleading. I'd prefer no comments to misleading comments.

In the few cases where the comments are actually correct, they probably just repeat what the code says. So they are redundant.

Since you can't trust the comments, you have to read the code to see what it does. The code can't lie. The computer actually compiles and executes the code. There are no such checks on the comments.

PM: Doesn't this make the code harder to understand for new people?

Tim: Obviously, someone who has never seen the code before will need to learn the system before being proficient. But, that's true no matter how you write the code.

The problem with writing code to the least common denominator is that your advanced programmers can't use their knowledge and skills to advance the code and the team. Everyone is forced to work as if all of the other developers are clueless.

PM: What is your position on advanced language features?

Tim: Many advanced features are great! You can do a lot more with less code. What's not to like?

PM: What about people who say the advanced features are too hard to understand?

Tim: If it's in the language, it should be available for use. More advanced features usually reduce lines of code. Less code is easier to maintain. If you haven't learned the more advanced features, maybe you should avoid advanced code until you've learned more.

PM: Aren't more advanced features harder to debug?

Tim: Actually, the more advanced features often leave less need for debugging. Several studies have reported that the number of bugs per line of code is relatively consistent across the industry, independent of language. Higher level languages are more productive, partially because they require fewer lines for a given piece of functionality. That translates to fewer bugs per feature.

If we are using higher level constructs in a system, that allows us to write more functionality with fewer lines, which translates directly to fewer bugs.

PM: How do you feel about optional syntax?

Tim: If it's optional, leave it out. I don't see how adding extra code junk helps anyone. People who get used to adding optional syntax just in case often end up adding useless code that just slows the system down.

For example, if a variable contains a string, there is no need to interpolate that variable before using it as a string. In most cases, that creates a new copy of the string unnecessarily.

Since extra syntax, at best, has no effect on how the program works, and, at worst, can cause a performance penalty, why would anyone use it?

Verbose Vinnie

Let's talk with another hypothetical programmer, Vinnie, for an explanation of the Verbose style of programming.

PM: Vinnie, why do you advocate a verbose style of coding?

Vinnie: It's all about readability, understanding, and debugging. If you are coming to the code with a less-than-perfect understanding, more detail is better. This applies whether you are new to the codebase or just haven't looked at this particular piece of code in a few months. A little more explicit information helps you orient yourself to the code and begin working sooner.

Consistently using a more explicit style makes all of the code easier to understand for those who will maintain it.

PM: Doesn't that constrain your advanced programmers to dumbing down their code to the level of a beginner?

Vinnie: The advanced programmers are the ones with the knowledge we want to capture. When the experts encode their knowledge in comments and good naming, more junior programmers can contribute without having the whole system in their heads already.

Sometimes expert programmers want to write more advanced, cooler code. But, that is not where the business value lies. On any given system, there are only a few experts and the rest of team is intermediate or junior. The verbose style accommodates most of the programming staff to make the best use of the team, as a whole.

PM: What about the use of terser, more powerful language constructs? Shouldn't we use the power of the language when possible?

Vinnie: Given two constructs that will do the same job, we should consistently use the clearer, easier-to-understand construct. This makes the code easier to understand for the whole team and any new members. If some of the code uses a clearer construct and other code uses a high-power, cryptic construct, people will have a harder time understanding the code as a whole.

Consistency is much more important than the desire to show off obscure coding practices.

PM: What is your position on optional syntax?

Vinnie: There is no reason to remove optional syntax. Leaving off the optional syntax obviously generates some ambiguity. Did the programmer mean to leave it off? Was the programmer really aware of the implications of leaving it out?

For example, leaving out the parentheses in a mathematical equation can cause loads of grief. Did the original programmer understand the precedence rules correctly? (If he didn't, there could be a bug.) Will everyone that maintains the code understand? Someone coming back later and clarifying by putting in the parentheses could break the code if they misunderstand the precedence.

Using the explicit syntax, even if it is optional, keeps everyone on the same page. No need to guess about the intent of the code.

In addition, more explicit styles often simplify debugging.

PM: How is that?

Except in simple cases like optional parentheses, optional syntax usually removes lines of code. Think of C's block if versus the statement if. The only thing the statement if gives us is the ability to drop the curly braces in the case that the if only applies to a single statement. The block if can do a single statement in the block just as well.

But the block gives us more opportunity for debugging. We can easily add a print statement to the block to see what is going on. Some debuggers may not allow you as many options for breakpoints if the statement is all on one line. Obviously, the difficulty debugging is much more of a downside than the saving of 2 characters when you are writing the code.

Arguments Against Each Style

Now that we've explained the high points of each style, we should really consider the complaints that people make against each of the styles.

Arguments Against the Terse Style

The main argument against the terse style is that it fails if all of your developers are not at similar levels of skill and comfort with the code. Often managers will argue with this style because they are not as familiar with the code as their programmers and they can easily see how the terseness hurts their ability to read the code.

People also say that this style can cause the learning curve for a new developer to be longer. They need to learn the idioms of this group and become comfortable with the level of code that the team is writing.

As for the higher-level, denser constructs, a less experienced programmer will definitely need to learn how these constructs work. Until they do, code using those constructs is going to be hard to understand.

Arguments Against the Verbose Style

Code is read much more than it is written. The more verbose style requires more reading to understand what the programmer wants to say. Extraneous code junk slows the reader down without necessarily making the code any clearer. In short, verbose does not equal readable.

Verbose code is a liability for the experienced programmer on your team. She will need to wade through all of this extra, explicit text explaining things she already knows every time she reads the code, during the whole time she works on it. While this may make code easier to understand for the new programmer, the experienced programmer is penalized each time she touches the code.

In general, your experienced programmers are more productive than your junior programmers. A decrease in the productivity of your experienced programmers probably cost you more than any gains you get from making the junior programmer a few percent more effective.

Verbose advocates often argue for the same style throughout the code. By having everything the same style throughout, there is no indication in the code of when things are getting more complex and that you might need to take care.

Including extra, optional syntax for the sake of clarity might help an inexperienced programmer who is new to the language. It just gets in the way of the more experienced developer. It's more to read and mentally parse, without necessarily making things clearer.

Conclusion?

So, which is the correct style?

This post is already way too long. In the next installment, I'll talk about some trade-offs and myths regarding these two styles.

Posted by GWade at July 17, 2013 11:15 PM. Email comments