The Artima Developer Community
Sponsored Link

Angle Brackets and Curly Braces
What's the Most Effective Code Style Policy?
by Bill Venners
July 13, 2007
Summary
To what extent should a project or company have a coding style policy, and how and to what extent do you think it should be enforced?

Advertisement

We have been gradually expanding the number of programmers who work on software at Artima, and not unexpectedly, the more programmers we've brought in to work on the code the more personal coding styles we have encountered. This has led me to struggle with just what style policy to adopt for our project, and the extent and manner of enforcement of that policy.

The first person besides me to work on the code was Frank Sommers. Frank and I discussed this issue early on, and our original notion was that we should indeed adopt a style standard. Given that Sun had defined recommended code conventions for Java, which was our main implementation language, we decided to just adopt the those recommended conventions as our style standard. We tried to follow that style in our hand-written code, and set up the format code feature of our IDE to match the standard, occasionally using the IDE to reformat code that had gone astray.

Frank and I had a few minor differences in style that had to do with blank lines and spaces used in ways on which the Java code conventions seemed to be silent. The Java code convention document does talk about blank lines and spaces, and lists some ways in which spaces should be used, but doesn't say you can't use them in other ways. For example, I would always leave a blank space after a //, as in:

// This is a comment
Frank would not:
//This is a comment
Or, I would never leave a blank line before a closing curly brace, whereas Frank sometimes would. These differences I saw as minutia, and although I really like consistency in code and design, I felt uncomfortable bringing such little things up. There are far more important things to worry about.

A more recent addition to our programming team, George, when I brought up the Java code convention, indicated that he really believed in standards and would be happy to follow suit. Besides following the standard, though, it turned out that George takes a lot of care in trying to make the code readable. One new style that started showing up in his code was a lot more lining up similar things into columns. For example, here are some variable declarations in this style. George inserted enough spaces to line up the variable names into a column:

        Zine                     zine;
        boolean                  multipleEditors;
        List<ItemLink>           articleSummaries;
        String                   topofpagead;
        long                     userID;
        String                   userName;
        boolean                  userSignedIn;
        String                   doneURL;
        List<Link>               links;
        String                   currentURL;
        String                   skyscraperAd;
        Set<ZineSection>         sections;
        ColorStyle               colorStyle;
        String                   sponsoredLinks;
        String                   rectangleAd;
        String                   leaderboardAd;
        String                   zineName;
        String                   editor;
        String                   advisoryBoard;

What I had always done was insert a single space between a variable type and name, as in:

        Zine zine;
        boolean multipleEditors;
        List<ItemLink> articleSummaries;
        String topofpagead;
        long userID;
        String userName;
        boolean userSignedIn;
        String doneURL;
        List<Link> links;
        String currentURL;
        String skyscraperAd;
        Set<ZineSection> sections;
        ColorStyle colorStyle;
        String sponsoredLinks;
        String rectangleAd;
        String leaderboardAd;
        String zineName;
        String editor;
        String advisoryBoard;

The Java code convention seems to be silent on this kind of use of blanks as well, and when I looked at George's code, I felt it was more readable. I liked it. But later when I went to modify code formatted in this way, I noticed it took me extra time to line up everything into the columns. I took the time to do that, but I started thinking about how difficult it might be, as we bring in more people, to get others on the project to do so. What we might end up with, then, is source files in which some things were lined up in columns, and others were not. I figured that would be worse than no columns at all, and I also imagined we wouldn't be able to configure the IDE to automatically reformat code into nice columns. Thus as soon as we reached for the automatic format fixer tool, the variable space that forms lined up columns would be replaced with one space. Thus, should we simply decree that there should be just one space?

Finally, we have begun working with another programmer who has demonstrated his preference for putting the curly brace on the next line, rather than at the end of the current line. Many words have been spilled about curly brace placement, and I am uninterested in debating the relative merits of the different approaches. Rather, I am struggling to figuring out just what policy to adopt.

To me it feels a bit dictatorial to decree even curly brace placement. By themselves I think people might be more productive if they are able to write code the way they most prefer. The trouble with such style freedom arises when multiple people work on the same code. Total freedom in that situation I think would mean that much of the time people would be working in code that is styled differently than their preferred style, which might hinder productivity—especially if there are ten different styles, sometimes in the same source file. But to what level of detail do you go with the standard? And how do you enforce it?

My goal is maximizing programmer productivity. That means programmers can read the code and enjoy working in it. (I'm guessing happy programmers will often be more productive than unhappy ones.) Would you recommend having a style standard? If so, what level of granularity would you recommend for that standard, and how would you manage the enforcement of it? What I'd like to hear is what policies you have observed have been most effective in projects you've worked on in the past—projects in which several people have worked together on the same code. Please post your recommendations in this forum topic.

Talk Back!

Have an opinion? Readers have already posted 43 comments about this weblog entry. Why not add yours?

RSS Feed

If you'd like to be notified whenever Bill Venners adds a new entry to his weblog, subscribe to his RSS feed.

About the Blogger

Bill Venners is president of Artima, Inc., publisher of Artima Developer (www.artima.com). He is author of the book, Inside the Java Virtual Machine, a programmer-oriented survey of the Java platform's architecture and internals. His popular columns in JavaWorld magazine covered Java internals, object-oriented design, and Jini. Active in the Jini Community since its inception, Bill led the Jini Community's ServiceUI project, whose ServiceUI API became the de facto standard way to associate user interfaces to Jini services. Bill is also the lead developer and designer of ScalaTest, an open source testing tool for Scala and Java developers, and coauthor with Martin Odersky and Lex Spoon of the book, Programming in Scala.

This weblog entry is Copyright © 2007 Bill Venners. All rights reserved.

Sponsored Links



Google
  Web Artima.com   

Copyright © 1996-2019 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use