The Artima Developer Community
Sponsored Link

Weblogs Forum
What's the Most Effective Code Style Policy?

43 replies on 3 pages. Most recent reply: Jul 25, 2007 5:37 PM by Erick Reid

Welcome Guest
  Sign In

Go back to the topic listing  Back to Topic List Click to reply to this topic  Reply to this Topic Click to search messages in this forum  Search Forum Click for a threaded view of the topic  Threaded View   
Previous Topic   Next Topic
Flat View: This topic has 43 replies on 3 pages [ 1 2 3 | » ]
Bill Venners

Posts: 2248
Nickname: bv
Registered: Jan, 2002

What's the Most Effective Code Style Policy? (View in Weblogs)
Posted: Jul 13, 2007 7:15 PM
Reply to this message Reply
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.


Raoul Duke

Posts: 127
Nickname: raoulduke
Registered: Apr, 2006

Re: What's the Most Effective Code Style Policy? Posted: Jul 13, 2007 7:45 PM
Reply to this message Reply
I always dream that someone (hah! not me!) would write the tool that converts all source code into a canonical format going into revision control (so historical diffing work well), and then converts it to any and all personal styles when coming back out. So everybody can just see things how they want and we can get past this kind of trouble? It just seems to me like a problem where the humans are being forced to conform when we should be leveraging technology to allow a little more personal comfort.

Morgan Conrad

Posts: 307
Nickname: miata71
Registered: Mar, 2006

Re: What's the Most Effective Code Style Policy? Posted: Jul 13, 2007 8:04 PM
Reply to this message Reply
I think that reasonably different styles are a good thing. Because if you see code you don't understand, and it has Fred's curly bracket placement, you know who to ask what's going on.

Sure, IDEs and CVS can do this, but that's extra time and work and it's usually modal (at least in Eclipse, where anything you do is modal. :-(

Vincent O'Sullivan

Posts: 724
Nickname: vincent
Registered: Nov, 2002

Re: What's the Most Effective Code Style Policy? Posted: Jul 13, 2007 8:33 PM
Reply to this message Reply
You said it yourself:

> There are far more important things to worry about.

Good code will be readable. Bad code will be shaken out in your code reviews.

Things like bracket placement and blank lines should never be an issue because, these days, no one should be writing methods of more than a dozen lines; and in small methods the distractions of style differences are minimised.

You give an example where the declarations of nineteen variables are aligned. In such circumstances, the question is not which style is best but why are nineteen variables being declared in one go.

Visus Zhao

Posts: 1
Nickname: visus
Registered: Jul, 2007

Re: What's the Most Effective Code Style Policy? Posted: Jul 13, 2007 9:10 PM
Reply to this message Reply
I been dreaming about this kind of tool too! I'd like that it be able to show a souce code in a personalized formatted VIEW mode, not changing the real format of a code file. Then you can view any code in your style and enjoy it!
I think someone could improve java perspective in Eclipse to achieve this.
> I always dream that someone (hah! not me!) would write the
> tool that converts all source code into a canonical format
> going into revision control (so historical diffing work
> well), and then converts it to any and all personal styles
> when coming back out. So everybody can just see things how
> they want and we can get past this kind of trouble? It
> just seems to me like a problem where the humans are being
> forced to conform when we should be leveraging technology
> to allow a little more personal comfort.

Bill Venners

Posts: 2248
Nickname: bv
Registered: Jan, 2002

Re: What's the Most Effective Code Style Policy? Posted: Jul 13, 2007 9:26 PM
Reply to this message Reply
> You give an example where the declarations of nineteen
> variables are aligned. In such circumstances, the
> question is not which style is best but why are nineteen
> variables being declared in one go.
>
Well the question of this blog is also not which style is best, but which style policy is most effective.

But to address your question, the code I showed was taken from a controller. In our controllers the climax of an HTTP GET request processing method is instantiating a view object, which takes data needed by the template in rendering the response page as constructor parameters. What he was doing was declaring variables in which to stuff data that then gets passed to the constructor a la:


ZineHomeView view = new ZineHomeView(
locale, // non-null Locale
userSignedIn, // boolean
userName, // String
doneURL, // non-null String
userID, // long
leaderboardAd, // non-null String
zineName, // String
zine.getBannerImageURL(), // non-null String
zineName, // non-null String
multipleEditors, // boolean
articleSummaries, // non-null List<ItemLink>
links, // non-null List<Link>
currentURL, // non-null String
skyscraperAd, // String
rectangleAd, // String
sections, // Set<ZineSection>
colorStyle, // non-null ColorStyle
sponsoredLinks, // non-null String
zine
);

Chee Seng Chua

Posts: 62
Nickname: quai83
Registered: Nov, 2006

How about tab or spaces intent? Posted: Jul 13, 2007 9:35 PM
Reply to this message Reply
Hi all,

I wonder if the tab or spaces intent war has over? Recently I am setting coding style standard for the new project. It turns out into problem when Eclipse beginner users and Netbeans users are working on the same code base, as the default for Eclipse is tab intent while default for Netbeans is spaces intent. I personally prefer tab intent than spaces intent, and is happy to see that source codes downloaded from Spring Framework, BIRT and Flex is using tab intent. Anyway, this is my first time working on coding style standard, if I use tab intent, is there some things that I have missed out which are going to cause problem in the future?

robert young

Posts: 361
Nickname: funbunny
Registered: Sep, 2003

Re: What's the Most Effective Code Style Policy? Posted: Jul 13, 2007 9:38 PM
Reply to this message Reply
The best policy is (almost) No Policy: use a formatter (jacobe is what I use) on check in. Establish the format for the repository. Folks can use whatever style they want locally. The Almost: NO TABS.

My editor, SlickEdit, will line up blocks a la what you discussed with a couple of key strokes. People who use IDEs, Eclipse in particular, don't know what a Good Editor Can Do.

W. Edwards Deming opined that Bad Quality would drive out Good Quality. Kind of a corollary to Gresham's Law. He was not happy about his conclusion.

Tim LS

Posts: 37
Nickname: parchandri
Registered: Jul, 2005

Re: What's the Most Effective Code Style Policy? Posted: Jul 13, 2007 11:39 PM
Reply to this message Reply
So its a parameter object being constructed in one go?
That looks like an example of when it would be nice to have keyword arguments. I wonder though, whether it would be easier to get those parameters via queries, rather than storing them as members.

Vincent Oostindiƫ

Posts: 5
Nickname: voostind
Registered: Dec, 2003

Re: What's the Most Effective Code Style Policy? Posted: Jul 14, 2007 2:41 AM
Reply to this message Reply
I think coding style is very important. I'm all for collective ownership of code. If each developer is allowed to use his/hers personal style, then collective ownership never happens. Nobody feels responsible for some piece of code because 'it's clear it was written by someone else, so it's not my problem'. I've experienced that it really helps collective ownership when you enforce a strict coding style.

If you don't want collective ownership, than a coding style policy isn't that important I think.

As for how granular it should be, that's simple: make it as granular as needed, without spending too much time on it. Start with a basic policy everyone agrees on, and as soon as an issue arises, resolve it by adding a new rule.

To get a coding style adopted by the whole team, make it a thing of the team. For the initial set of coding style rules, sit down with the whole team for an hour or so, give them a proposal and discuss it. If there are issues (and there always are) just vote on it. That resolves the curly braces issue once and for all. An hour is really all you need.

Anybody can get used to any kind of coding style, so that's not really an issue. If someone tells you he cannot, he just has a really big ego, and he either has to overcome that, or he has to stop working in a team; he'll not be fit for it then.

Zijad Kurtanovic

Posts: 1
Nickname: zkey
Registered: Apr, 2006

Re: What's the Most Effective Code Style Policy? Posted: Jul 14, 2007 10:29 AM
Reply to this message Reply
> Thus, should we simply decree
> that there should be just one space?

Yes. I guess it would be a painful and time-consuming work to change the code-style manually and it's not worth do to it; I don't see a big improvement with that style using columns.

> But to what
> level of detail do you go with the standard? And how do
> you enforce it?

I think that the effectiveness of an good coding style can be measured with the developers possibility of interpreting code without the help of tools like IDE's.
That means, it should be easy for the developer to get on-the-fly all the essencial properties about - for example - a variable or method from the code he is reviewing/writing like is-static/is-member/is-const/etc. For example the following code-fragment follows the coding-convention I'm using:

<pre>
void doSomething(int param)
{
int myVar;
bool success;

... // a great bunch of code

// comment of an one-liner
myVar += 1;

//
// this is a comment of an block of code
if (success)
{
// we *directly* see that this var is a member
// of the class containing this method, because
// the coding-convention tells that all member-vars
// start with the prefix "m_"
m_Changed = true;
}
else
{
// m_OFFSET is a member AND it's const
// g_EXTRA is a global-var AND it's const
myVar += m_OFFSET + g_EXTRA;
}
}
</pre>

My opinion is that strictly following an coding-convention, that covers at least the most essential rules, enhance developer's productivity a lot, and I really think that any developer is able to become comfortable with it very quickly.

An interesting fact is, that it's few (mili)seconds faster to get the information about an object in code on-the-fly (from the naming) then to wait for the IDE - and really depend on it - to get these informations or to wait for the compiler to tell you that you made a mistake because e.g. you tried to change a const-var :) In the long term you will save a lot of time.

Of course, nowadays almost nobody is coding without an good IDE, so I think that in general using an welldefined coding-convention with an powerful IDE equipped with modern features is the way to go to enhance programmer's productivity.

Steven E. Newton

Posts: 137
Nickname: cm
Registered: Apr, 2003

Re: What's the Most Effective Code Style Policy? Posted: Jul 14, 2007 12:01 PM
Reply to this message Reply
I've come to believe that having a coding style is important, but enforcement is not:

http://www.cmdev.com/buzz/index.cgi/2007/01/31#CodingStyle

If programmers on my team can't adhere a style without having to have their wrists slapped by some tool or enforcement police, it's likely there are more serious issues lurking that will bite the team far worse than misplaced curly braces or indentation errors.

Bill Venners

Posts: 2248
Nickname: bv
Registered: Jan, 2002

Re: What's the Most Effective Code Style Policy? Posted: Jul 14, 2007 12:37 PM
Reply to this message Reply
> The best policy is (almost) No Policy: use a formatter
> (jacobe is what I use) on check in. Establish the format
> for the repository. Folks can use whatever style they
> want locally. The Almost: NO TABS.
>
Well, there the policy would be that you use a formatter on check in. So that's not no policy. Frank Sommers tried that at one point. I think he configured IntelliJ to reformat the code automatically on check in, and at some point it messed up some of our files enough they wouldn't compile. It may have been the JSPs, but as a result of that experience we decided that wasn't such a good idea. We have never had problems with IntelliJ's reformat tool when I used it by hand, so we trust it when used that way. But given that software *can* have bugs in it, even code reformatting software, I am nervous in general about the idea that programmers would run transformations on code then check them in without testing to make sure the code still works after the transformation. (We're working to replace all of our JSPs, after which I expect we wouldn't see a problem using the policy you suggest. But it still makes me a bit nervous.)

The other thing is that in such a world, the programmer would only get to "use whatever style they want locally" when they are creating a brand new file, right? Because when they go to an existing file, it would be in the repository standard format.

> W. Edwards Deming opined that Bad Quality would drive out
> Good Quality. Kind of a corollary to Gresham's Law. He
> was not happy about his conclusion.
>
Where did he do that opining?

Bill Venners

Posts: 2248
Nickname: bv
Registered: Jan, 2002

Re: What's the Most Effective Code Style Policy? Posted: Jul 14, 2007 12:55 PM
Reply to this message Reply
> I've come to believe that having a coding style is
> important, but enforcement is not:
>
> http://www.cmdev.com/buzz/index.cgi/2007/01/31#CodingStyle
>
> If programmers on my team can't adhere a style without
> having to have their wrists slapped by some tool or
> enforcement police, it's likely there are more serious
> issues lurking that will bite the team far worse than
> misplaced curly braces or indentation errors.
>
Thanks for pointing to that. In your blog you mention something Frank and I were talking about yesterday, which is the difficulty of seeing real code changes via version control diffs if you've got a bunch of format changes in there. We were thinking that maybe part of our policy should be that if you need or want to make formatting changes to a file as well as real changes, do the reformatting first, test, and check that in, then do the real changes, test, and check that in separately.

I also had forgotten Frank had posted about this issue in January. We're obviously struggling with it now. What we were trying to get help with then (i.e., by trying to draw on the wisdom of the community) was whether or not a style checker should be integrated into the build. The message came back that it should not, and that's what we did. In using it more I realized there were too many "false positives" or exceptions to the rules checked by the tool to allow the style checker tool to break the build if it wasn't 100% happy. Of course, perhaps we just needed to more carefully configure the style checker.

George was suggesting yesterday that he thought that code should be reviewed by someone else before being checked into the trunk (which is what we do now), and that part of the reviewer's job is to look at the formatting. That seems like it might be the time to run the style check tool.

Bill Venners

Posts: 2248
Nickname: bv
Registered: Jan, 2002

Re: What's the Most Effective Code Style Policy? Posted: Jul 14, 2007 1:00 PM
Reply to this message Reply
> So its a parameter object being constructed in one go?
> That looks like an example of when it would be nice to
> have keyword arguments.
>
It's not really a parameter object a la Martin Fowler's Refactoring book, because it as interesting behavior. If you call its render method it will spit out the web page (or whatever it is) using the data that was passed to its constructor. We put that data into an object first primarily so our controller tests can just check the data not the string of characters produced by render.

I wonder though, whether it would
> be easier to get those parameters via queries, rather than
> storing them as members.
>
What do you mean by "get those parameters via queries?"

Flat View: This topic has 43 replies on 3 pages [ 1  2  3 | » ]
Topic: What's the Most Effective Code Style Policy? Previous Topic   Next Topic Topic: Pardon My French, But This Code Is C.R.A.P.


Sponsored Links



Google
  Web Artima.com   

Copyright © 1996-2014 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use - Advertise with Us