> ASCII art code is a very bad idea for two reasons: > > 1) Some developers like to use proportional fonts, and to > them, the code will be hard to read (which is exactly how > the code appears in the forum, by the way). > I hadn't thought about that.
> 2) The slightest refactoring will mess everything up, > forcing the user to do manual editing of the refactoring. > Which is exactly what refactoring is supposed to avoid. > And I hadn't thought about that either. Thanks. I was thinking that it would be difficult to get other programmers to adhere to the style, but we do auto-refactoring a lot, and those tools also wouldn't adhere.
I have been watching the discussion and considering this issue. I think it is good to have a code standard for a project that has multiple people working on it. I liked the suggestion of several people here that the standard come from the group itself. I think that would help buy-in. I also really liked that Sun had published a code style guide for Java, because instead of fighting over what our code style standard would be, we could just point to that document. (But deciding to use that document was really a group decision.)
We found, however, that there were style differences that arose that were not covered by that document. In that case several here have suggested that we just not worry about it, as these things really are minutia. I agree they are minutia, but I've been thinking it would be good to have a policy on such things--just don't worry too much when people make minor infractions. If you find a file in which someone made a minor (or major) deviation from the style standard, just fix it, test it, and check that in before making any other changes to it. Several people pointed out here the problem with intermingling formatting changes with real changes--it is harder to find the real changes in diffs later. So a rule should be to check in any formatting changes before making real changes to the file.
I also have been coming to the conclusion that it is helpful if there's a tool that can reformat code to the standard rather than having people do it by hand. Once you get the bugs out of that reformatter tool, it will be more reliable than hand-reformatting. One problem I have heard about, which I don't think anyone mentioned here, is that when you have people just reformatting code that isn't heavily covered by unit tests, that act can introduce bugs. After the reformatting, the code may be prettier, but it also may be broken. Such reformatting tools exist for Java, but it implies that the standard we decide upon needs to be algorithmic. In other words, it isn't good enough that the standard be written down in a document, but that it be captured in a reformatter tool in code.
The best policy is to make sure that your team is made up of people who can agree to a similar set of rules. Sometimes that similar set of rules is "The best policy is No Policy", and sometimes that similar set of rules is a strict set of style guidelines.
So agree to agree, or agree to disagree.
But it sucks when you have style Nazis and style hippies on the same team. Then you end up arguing about nonsense instead of getting work done.
> I have been watching the discussion and considering this > issue. I think it is good to have a code standard for a > project that has multiple people working on it.
I think there is pretty much universal agreement here. Even a bad style guide is better than no guide at all, in my opinion.
The Sun style guide is a good start but a lot of companies and projects just use it as a foundation and then list exceptions to these rules, which can range from significant semantic differences (e.g. "all fields must begin with m_" or "all interfaces must start with 'I'") to fairly minor ones ("opening braces always go on their own line").
There is very little point in discussing which one is better, but it is important to capture "a" decision in a document that all developers need to refer to when they're coding.
Another rule that works well in my experience is: "In doubt, make your code look like the code that surrounds it".
> > I have been watching the discussion and considering > this > > issue. I think it is good to have a code standard for a > > project that has multiple people working on it. > > I think there is pretty much universal agreement here.
How can you say that, when this whole topic is about this question? If there were "universal agreement", this topic wouldn't have 30+ responses.
> Even a bad style guide is better than no guide at all, in > n my opinion.
> > > I have been watching the discussion and considering > > this > > > issue. I think it is good to have a code standard for > a > > > project that has multiple people working on it. > > > > I think there is pretty much universal agreement here. > > How can you say that, when this whole topic is about this > question? If there were "universal agreement", this topic > wouldn't have 30+ responses. > > > > Even a bad style guide is better than no guide at all, > in > > n my opinion. > > Hmm, how bad can I make one? :-)
Oh boy, this can be fun! Imagine this is for C++ or Java.
1. All variable names must be no more than two letters long. 2. All variable names must contain at least two vowels. 3. Newlines are not allowed in code. Since it is a freeform language newlines just take up extra space that can be wasteful of disk space. Not to mention it slows down compilation. 4. ALWAYS ALWAYS ALWAYS use pre-increment unless post-increment is specifically called for. 5. function names should be all caps 6. variable names should be all caps 7. the letters 'Q' and 'Z' cannot be used in function names. Phones work just fine without them. So can we.
> > The goal should be for any programmer to feel equally > at > > home in any part of the code base, which means that > code > > written by one programmer should be impossible to > > distinguish from code written by another programmer. > > Several comments have said similar - that different code > styles hinder collective code ownership. I just find this > hard to believe. > > The fact that some unfamiliar 3rd party open source > library is used often hinders, a different take on "what > is OO" often hinders, a poor design choice (like using a > Bubble Sort, like using every pattern in the book to show > off that you just read it) often hinders, but relative to > those the placement of spaces in a line is just, well, > trivial. If your programmers are seriously confused by > bracket placement, they aren't very good programmers.
Actually, the situation where I have had this experience most profoundly (FreeBSD) is mostly the opposite: The people are very, very good programmers working in cooperation, so the problems you mention do not occur (much).
People aren't seriously confused by bracket placement; it's just an annoyance, one thing to adapt to. Sort of like if I staartd 2 change hov ai rite inglish, u kan rid it it is just slouver and harder to pick up the high-level stuff as you're wasting mental energy on extra low-level cognitive processing.
Standardizing that, and having people learn that style so it sits deeply, frees up that cognitive capacity for working at a higher level. It is far from the only issue, yet it makes it easier to work on the other issues, and is low-hanging fruit.
Also, the thing that is most important is that code in the same "area" (usually, same file or subproject) follow the same style, so you can set up a cognitive context for it. It's just even more effective if you can do this for the entire project, and it is easier for people to do modifications in a way that keep the style consistent in one area if that area has the same style they are used to.
That's my experience, with my cognitive style and the different projects I've worked with. And it is also my experience that having a strict style is in some ways more important when you work with good programmers than bad, as the bad programmers will make other mistakes that are more significant - but fixing the low hanging fruit of the style will make it easier to fix the other problems.
From the above discussions, it appears that "Java Coding Standards" and "Bracket Placement" are wholly interchangeable terms.
Once you've eliminated (or preferably permitted) the bracket variations is there anything of importance left that is not covered by the Sun guidelines and conventions?
> Once you've eliminated (or preferably permitted) the > bracket variations is there anything of importance left > that is not covered by the Sun guidelines and conventions?
TAB characters versus spaces. While that is covered by the guidelines (as is bracket placement) there is considerable disagreement.
The reason coding standards so often seem like micromanaging is because they are. The most effective way to get people to achieve a goal is to explain the problem and the goal, and unless they are incompetent they can figure out how to meet it (if they are that dense, some suggestions help).
For a coding standard, explaining what the problems are is probably much more important than mandating a single solution. For example, if the problem is different placement of braces in a file, say that the goal is style should be consistent within a file - match whatever's there. For the question of where to break lines, say that the goal is that the next line should present as much information at the beginning to indicate its relationship to the previous line as possible, so:
a = b + c + d + e;
...might best be split before an operator rather than before a variable:
a = b + c + d + e;
For columns, decide whether the priority for code appearance is easier reading or easier editing (I'd go for editing). And so on.
If a coding standard wants to define a solution to every variation of every item it covers, it's going to start looking like a language definition itself (BNF and all). But programmers are problem solvers - if you just want someone to type in a program without thinking you'd hire typists. If you're going to bother hiring people who solve problems for a living, let them solve problems. Following a list of conditions and actions are what computers are for, not people.
> > Once you've eliminated (or preferably permitted) the > > bracket variations is there anything of importance left > > that is not covered by the Sun guidelines and > conventions? > > TAB characters versus spaces. While that is covered by the > guidelines (as is bracket placement) there is considerable > disagreement.
One thing I liked about Python's use of indentation to set off blocks was that it completely eliminated the debate about where to put the open curly brace. My friend Matt Gerrans and I were talking about how this was a good thing many years back, and then spent the next half hour arguing about how many spaces to indent in Python programs. Seems how to indent could also have been dictated by the Python language, but interestingly Guido found a useful way to apply this variation. In his first blog post after joining Google, he wrote:
And did I mention that I get to spend 50% of my time on Python? No strings attached. Of course I get to spend the other 50% on Python too, but that's in a corporate setting. Fortunately it's easy to separate the two. If it uses two-space indents, it's corporate code; if it uses four-space indents, it's open source. (If it uses tabs, I didn't write it! :-)
I'm in a big minority, but I like to mix styles. A couple of examples: (Java, but applicable to other languages - I added this a lot of palces for clarity)
Long vs. shorter variable names. I tend to use short names. A File would be file, a Foo would be a foo, (or maybe inFoo, outFoo) etc. Unless there is something tricky going on. For example, if a class has a List of Orders that might be getting modified by another thread, and I want to look at it
List<Order> avoidConcurrentModificationException = new ArrayList<Order>(this.orders); for (Order order : avoidConcurrentModificationException)...
Somebody else reading the program has their eyes drawn to the unusually long name, and hopefully realizes that this is the important or tricky part of the routine.
Similar with "trivial" getters and setters. I used to write them on one line. The idea is to emphasize that they (for the most part) aren't worth looking at. Especially if they are private and only there because Hibernate needs them.
The reader's eye can skim over this boilerplate code, and will be drawn to the real code that has normal bracket placement and useful Javadocs.
IMO, having pages of normal styled trivial accessors, each with some meaningless Javadoc required by a style checker, so they add up to 10 lines or so each, detracts from real understanding of the code by distracting the reader from the "meat".
i'm a great fan of coding standards but am nonetheless cautious of overimplementation. still, things that seem silly like extra spaces and blank lines really ought to be given proper definition and sun's standard is a great base on which to build.
have a strict standard permits the creation of effective value-adds like code generation utilities. if all code follows strict rules, codegen utils can be created quickly, knowing that certain preconditions will be in place. even one-off whizbang codegen utils can bring exponential efficiencies and one key to that pile of gold is not having to spend a lot of time on the generator. a code standard goes a long way to enabling the ability to create such utils.
i worked for an outstanding practitioner who had at one time been on the c++ standards committee and who was/is a big believer in a very strict code standard, enforced through code reviews. at times these reviews and resulting marks felt nit-picking, but the advantages were more than worth it.
developers will grouse at having to bend their style to match a code standard, but really, the true impact such (likely minor) adaptations will have on productivity really should be negligible at first and non-existent within a very short period of time.
>> it took me extra time to line up everything into the columns
bad stuff. columns are prettier but a pain to maintain in the face of refactorings, renaming and other house cleaning. if important, soup up a formatter to columnize things on checkin.
Flat View: This topic has 43 replies
on 3 pages
[
«
|
123
]
Previous Topic
