Coding Convention
Coding ConventionYou have a team working on a project that will extend over a moderately long period of time. Over the course of the project, people will come and go. You desire to have as much specialization on the team as necessary, but also as much general capability as possible.
The project needs to go as fast as possible, which means you want to implement only what you really need, not what you might need. New functionality will be built as the need for it emerges, by whatever pair needs it.
Teams will be looking at many other classes as they craft simple enhancements to make the system do what is needed. They will create or find duplicate code that should be moved elsewhere in the system. They will read many classes, and edit many. Over time, few classes will be able to be said to have an author.
Therefore, strive to use the same coding conventions in every regard. Name your classes similarly, your variables, your methods. Comment the same way, format your code the same way. By doing this, you ensure rapid appreciation of whatever class needs changing, and as they evolve, your classes will not degenerate into a HorseByCommittee appearance. -- RonJeffries
Projects benefit from having strong Coding Conventions/Standards because...
Here's where all this came from ...
AlistairCockburn asked: "How come all the rigor on the CodingConventions? That really surprised me. What causes you to put so much weight on the idea that everyone should write identically? Usually programmers tell me the indentation style etc makes so little difference."
Happens I was thinking about that on the way to work this morning (I have no life).
On ChryslerComprehensiveCompensation, we do not practice code ownership. When you need a class to do something, you and your partner make it do something. We use ContinuousIntegrationRelentlessTesting to help make this work. (see FunctionalTesting for a short description.)
Everyone codes to the same conventions, so that no matter what code you read (and even if you do practice ownership you will be reading code), it looks familiar. We need every bit of help we can get in understanding the system. Making it all look alike is a key aspect of that.
We strive to name classes and methods the same way for the same reason: when you're looking for something you wrote, you can usually find it because you know how you name things. If everyone worked like you do, you could find their stuff too. To the extent that we all work alike, we can find our way around better.
My thought this morning was along another line. When a team member won't agree to use the team's conventions, I would expect to have other behaviors from that individual which were even more destructive to the trust relationship that supports the ability to go fast. In a number of places in the C3 rules I suggest that people who won't play by the rules shouldn't be on the team. There's a "Do It My Way" discussion on my site as well.
In my memory, more project damage has been done by cowboys and other dysfunctional personalities than by most other causes (and HeroicProgramming is dysfunctional IMO). Doing things the team's way is very important. If folks won't ... I'd rather do without them.
-- RonJeffries
Inconsistent style also encourages "Format/Comment to Understand" which can be dangerous. It's quite easy to break code when you were 'just formatting' it. In a team environment unnecessary formatting also causes a lot of unnecessary work during a code merge.
The specific style usually doesn't make much difference (although people will sometimes fight to the death over a particular nuance of their style!) but having a consistent style definitely helps.
-- BrianSyme
For things like indentation, a pretty printer can help. the notion that everyone has to indent their code the same way is an anachronism, at least in the Lisp world (where they are very used to treating code as data). -- DaveHarris
Perhaps it's just what you're used to. I find that most decent programmers have at least a self-consistent style, and I've read enough code in enough different styles that I don't usually find that a serious impediment to understanding code. (Of course I've encountered inconsistent or dysfunctional code as well, but rarely would that have been materially helped by style alone).
A common style can be handy, of course, but can be impractical if not everyone is using the same development environment, editors, etc. In such cases a rule of following the existing style when editing a piece of code works well enough, though it requires self-restraint.
The technology solution (Lisp, etc.) sounds good, but I haven't personally seen it work. To avoid churning the revision control system you'd need to store a neutral form (e.g. list structure vs. text), but that can tend to lose information such as comments.
This is related to CodeOwnership. If you have a strong form of ownership, where only the owner edits, there's no real issue. If you have completely communal ownership, where everyone edits everything, that favors a consensus style. In between, where I suspect most development occurs, there's a gray area. Given that C3 seems to emphasize the communal approach, a standard style sounds appropriate in that context.
It's true that if an established team insists on a rigid set of rules, a newcomer who objects to following those rules probably won't work well in that team. -- JimPerry
I'd like to offer some answers to AlistairCockburn original question "How come all the rigor on the CodingConventions?":
Sorry, Thomas, I apologize for how poorly I must have made my point. By having a team that works the same way in everything from design through style through testing, you get a team that goes smoothly and quickly. We don't have discussions about what the style should be: we adopted one from Kent's book. We work together to have common values about everything, even about inheritance, because it lets us go faster and be more productive. We have no bean counters or managers involved in setting our process. We do have professionals working together to be a close, highly functional TEAM. -- RonJeffries
I agree that those are possible reasons for many coding conventions, but I also believe that there are tangible benefits for everyone in a shop agreeing to the same one. In my area, we have a meta-coding convention. Each developer adopts their own style, but if you modify another developer's code in must be in the original style. Over time, we've migrated so that the variations are few. I guess that is a positive form of GroupThink. But, I do think that it is interesting to see how adopting that meta-coding convention helped us out. It immediately rendered all pointless discussion about coding conventions off-limits. And, it helped us all become proficient code readers. Multidialect readers. Some people I encounter get so locked into a particular set of conventions in a shop that they are thrown when they see code in another style. Not severely, but you can see that they are not immediately grokking it and they need to assimilate the style.
As for me, I'll adopt whatever conventions a group has.When in Rome...
All in all, I agree with the XP practice, given its conditions: no code ownership and you are going fast. -- MichaelFeathers
I would suggest that whenever a developer, however clever, is faced with code formatted other than how s/he is used to it, s/he will go slower and be more likely to misunderstand or make mistakes. Surely s/he won't perform better in an unfamiliar format. Therefore ... use the same format. -- RonJeffries
True the first time for a given developer for a given new formatting convention, less so the second time for that same convention and increasingly less so over time given increasing exposure to various conventions. Perhaps this is not the case in XP-land, but in the broader world the ability to adapt to different formatting conventions (not to mention other stylistic variations, different languages, etc.) is a positive asset for a developer. -- JimPerry
Seems clear to me that no one can ever be better reading randomly formatted code than they are using the format with which they are most familiar. Consistency will always dominate any other strategy. Or am I missing something?
I think consistency is not generally an option; in real life one encounters many different styles. Objectively one is not really much better than another, as a rule. Therefore I find it worthwhile to transcend personal preferences and adapt to others' styles when appropriate. My experience is that especially given experience doing that, switching between styles is a relatively trivial part of programming (again, few half-decent programmers use what I'd call randomly formatted styles; occasionally you find something more off-the-wall than usual, but a range of experience better prepares you for coping even then). That being so, I don't find it worthwhile insisting on a particular style within a project, assuming those involved have rational styles they use consistently.
The risk of consistency is that MichaelFeathers raised of getting so attached to a single style that one is less willing or able to deal with variation. Also, of course, some variation is a prerequisite for evolution. Exposure to multiple styles can reveal little tricks that can improve one's own. To reiterate, that's not to say y'all on C3 shouldn't have a common style. -- JimPerry
This clash between what is best for an individual and what is best for organizations which utilize individuals is explored more thoroughly on SpecializationIsForInsects. At times the goals of an organization and the goals of an individual coincide. At other times, they don't. Given that many organizations, such as projects, are shorter lived than individuals, individuals must be able to adapt, or they die with their host organization because they are unable to learn anything else. I think that this dichotomy of individual versus organization goals often glossed over. -- MichaelFeathers.
Horrible Example, not even a little bit exaggerated.
Developers are working on class Person, with instance variables identityProfile and employeeProfile. The identityProfile records name and address information, the employeeProfile records the Person's employment information, such as where he works and how much he is paid.
Person developers have a need for export access to the Person's last name, first name, middle initial, department, location, and pay rate. They plan to implement methods lastName, firstName, middleInitial, department, location, and payRate.
They look at the identity profile information. The class name turns out to be ProfilePersonalInformation?, with instance variables and accessors lpszNameLast, lpszNameFirst, lpszMiddleInitial.
They look at the employee profile information. The class name turns out to be EmploymentData?, with instance variables and accessors dept, locn, and pyrt.
Would it be better if everyone named their classes, variables, and methods the same way? Duh. -- RonJeffries
It would be better if everyone spoke fluent Esperanto, practiced altruism, and enjoyed Brussels sprouts. (Well, maybe not, but that's not going to happen either).
In a team environment, global naming (as of classes and their methods) is going to be a collaborative activity, more so than details of code formatting. Even if nobody ever edits anyone else's code, there must be agreement on what classes exist and what their methods are; given that, there will tend not to be gross divergence in naming conventions for such common things, for what that's worth. (If the identity profile class stores a concatenated full name, it matters very little if it's called fullName or lpsz_nameInFull, or even fn, assuming I want the last name).
On the other hand, if the basic functionality is there, the time it takes me to look up the spelling of the particular method I need is insignificant. I've already looked up the interface definition of the class I'm using (to verify that it provides a get-last-name method at all), and I'm only using it in one place, so it doesn't seem a big issue how to spell it. (I have to do such looking up on my own code as well).
And again, naming is inherently more important in communication than other CodingConventions issues like how many spaces to put where, whether to insert line breaks here or there, etc. -- JimPerry
One of the advantages of new and/or minority languages is that there is greater chance of consistency between communities. For example, when there was only one good book on C, all C programmers tended to adopt the same style. Ditto a decade or so later, with Eiffel. And again with Java - Sun made a deliberate effort to encourage good, consistent style.
As communities grow larger, divergence becomes harder to avoid. Also when cultures overlap - people coming to Java from C++ tend to stick with their old naming conventions. People using Java for Windows code tend to want to use Windows naming conventions. These are problems of success. -- DaveHarris
It seems to me that when you start to try and manage people's coding styles, you are just looking for something to manage. I just wish that everyone I worked with would use Source Safe correctly. I would think that the concept of PickYourBattles would apply. -- NoahClements
This is only true if coding style doesn't matter. In XP, since you spend so much time looking at code someone else typed, it matters a great deal that everyone formats their code the same way. The conventions for naming and method size are more important than where you put returns and tabs, but knowing exactly where the white space will be when you look at a method reduces friction considerably. -- KentBeck
I can agree that it is very nice (and even useful) for everyone on a team to use the same naming conventions, etc. How do you get a team together that will actually do all the things that ExtremeProgramming talks about? It seems that it would take an absence of ego that doesn't exist in my neck of the woods. I wasn't joking about the VersionControl thing.
We all know that CodingConventions are not a new concept (and they probably exist in most of the places that I have worked), but we also know that in most cases, there is not enough control to make it work. That's what got me; the concepts in ExtremeProgramming reflect an extraordinary amount of control (self-imposed?).
Am I correct in thinking that you have to have Olympic caliber programmers to make it work? -- NoahClements
It might be good to talk about DeveloperMaturity. -- MichaelFeathers
Noah asks: "Am I correct in thinking that you have to have Olympic caliber programmers to make it work?"
XP is a very light-weight discipline, and as such it's important that its practices be followed fairly carefully. It does take discipline. That said, I've never had big problems in getting team members (in XP or elsewhere) to follow reasonable practices. Sometimes you have to sit down with an individual and explain why X is important. More rarely you have to sit down with them again and explain why they can't be on the project any more.
The team must be willing to do the practices. Since they know that "TheyreJustRules", that's pretty easy to accomplish. They must continue to do them, and that takes both discipline and some cross-checking. In putting out the fires it's easy to forget to do what you know you must. There needs to be a team conscience, designated or collective.
I'll take a crack at the "Olympic caliber" question. XP can be done just fine with less-than-stellar programmers. Ward has noticed that PairProgramming prevents one developer's weakness from having too great an effect on the system.
I have found it easier to teach XP to ordinary, blue-collar programmers, because they aren't so in love with the way they have done things in the past.
Noah, it sounds like you have trouble getting your team to sing from the same page. My first strategy in that kind of situation is making the effect of their misalignment as visible as possible. If a person can see that they are causing problems and they don't change, you are better off without them. -- KentBeck
Brooks (in MythicalManMonth) suggested using a (human) code librarian who vets all submitted code and rejects that which does not follow the guidelines. This is something we lose when we use automated librarians (also known as VersionControlSystems). If you are adding a new person to a good team, you should be able to use code reviews to make sure they are doing it right. If you are trying to set up a 10-person team from scratch, I suspect that PairProgramming is your only hope. -- DaveHarris
Or we could develop an automatic librarian that supplements the VersionControlSystem. It could, using some rules, take some action based on the rules during check-in.
Unfortunately, the thing that needs checking the most is the use of meaningful and consistent names. I recall a programmer who used to work for me who named variables "pig", "cow", "dog" ...
I'm sure we can all talk about BadVariableNames.
Regarding automatic librarians: My previous employer did something like this. Once a week, the entire codebase was run through a reporting tool which looked for standards violations. The appropriate reports were e-mailed to team leads, who let the appropriate coders know of their violations.
We weren't required to clean up every violation immediately, but there was general pressure to keep violations down.
It was effective, and I imagine that a more rigorous implementation would be useful.
We've discovered that clearly written standards and regular code inspections make adherence to a common style a little bit easier. It is also helping to tidy up an aging code body.
In addition common naming conventions have helped us find a few places where a routine has been written several times over.
-- MarkLevison
In my experience, I have found that coding style is much like writing style. No two people are going to have the exact same style, so don't kill yourself over it. Instead, strive to achieve uniformity through mutual agreement.
Consider that there are certainly better and worse styles. Strunk and White's ElementsOfStyle? illustrates some good and bad practices in English prose. Same thing with programming (e.g. SmalltalkBestPracticePatterns). Thus, attempt to find the best style you can, then follow it.
However, if you write an official coding standard, make sure you clearly document the reason for following a given practice, because beating people over the head with a ThreeRingBinder is only going to garner bruises. And just like any rational argument, be prepared to change it when someone can (clearly) show an improved practice.
For what it's worth, I've attempted to document some good guidelines on SelfDocumentingCode. -- SunirShah
The dissenting view, Sunir, is given by the C3 team and XP, above and other places. They do achieve the same style, and claim both success at that and that having the same style makes it easy to pick up, read, continue, change the another person's writing. -- AlistairCockburn
Perhaps I made a too strong statement when I suggested to "forget about it." I have (extensively) changed my statement above. I hope my opinion is clearer. My apologies. Thoughts?
The part about changing standards when improvements can be made comes from the following experience. I once had the misfortune of being hit with a ThreeRingBinder which contained the following piece of junk: prefix all function arguments with the macros IN, OUT and IN_OUT to document in, out and in/out arguments. For example:
void func( IN int foo, OUT int &bar, IN_OUT int *pBaz );However, C++ already has a mechanism for this and it's called const which is even stronger. A better documented standard would have been how to write const-correct code. -- SunirShah
Hmmm... One can find both good and bad in the above example(s). One could argue that "IN", "OUT", and "IN_OUT" can help someone that is reading through a Header File, and another could argue that "const" is not a good solution either, because one may be using (or forced to use) existing code that is not const-correct. I do not use the "IN", "OUT" stuff, nor have I ever seen a need for it, and solutions to const problems are only a "cast" away.
The point is that neither is a "perfect" solution. Coding Standards are good, but, IMHO, they cannot be a solution to a/any problem on their own. I suppose that is why this is a *part* of XP. -- JamesTwine
I don't get your "cast" argument. IN/OUT macros don't provide any protection at all. No casting required. Remember, in C++, there is no real protection at all, only compiler-assisted suggestions. You can always modify the header to make yourself a friend, and you can always cast away anything.
The '"Cast" away' was referring to the previous poster's comment about "const" as a sorta-way to document input, output and input/output parameters. My comment simply meant that having something as "const" is a contract that can be easily broken by the implementer of the function. (The same as the last part of your last sentence.)
I know that IN/OUT macros do not provide any protection. That is why I did not say that they did. -- JamesTwine
Personally, I'm fed up of reading the organizations 80 page document describing where I can place a semi-colon, then finding I'm with a team that hasn't realized dereferencing null pointers isn't such a great idea. Well, as long as it looks tidy, that's all that matters, eh!
I have found that CodingConventions are the ideal place to put comments on good practice - explain _why_ you are insisting on something, force the developers to think about how they write their code and you can usually improve on the quality of their code if anything more than the layout. When you work for an org that doesn't support PairProgramming then anything that improves individual developers is extremely beneficial. -- StuartScott
Some languages are easier to have a uniform team style in than are others. The more syntactic sugar in a language, the more style rules you need, and the more likely you'll need too many rules for agreement or practical enforcement.
Here I am thinking of Smalltalk as a language with very little syntactic sugar, and C++ as a language with an extreme amount of syntactic sugar. I'll bet you that the difficulty of creating and adhering to a coding convention is directly related to the language's syntactic complexity.
One idea that I have had for a while is a config mgmt tool that would handle all code formatting in a developer-keyed way. I'd check code out, modify it in my coding style, and check it in; the tool would run it through a formatter to a minimalist format (heck, no whitespace or tabs, perhaps). The next developer would then check out the module, and it would be formatted to their preferences by the tool before handing it to them to modify in their style. Nobody works on code that's not in their style, and a 3rd standard format can be found for review copies - people can stand reading code slightly off their style better than writing it. Since the checked-in code is all in some minimalist format, diffs are clearer (no tab/space issues, space before/after open paren, etc).
-- PeteHardie
And then I have to spend how long to get the configuration management tool to give me back code in the same format as I originally wrote? No thanks, I've had enough problems trying to do that in Word.
Seriously, how hard is it to get indent to produce your style? If a program cannot produce your style, perhaps there is something non-symmetric about it that might be worth examining for value - and perhaps adding to the formatter -- PeteHardie
There are two issues here.
From the description of your style (I assume it's yours), it sounds like you have several styles. In particular, the item about putting multiple statements on one line only some of the time seems to be somewhat arbitrary, even within your own file, as well as the alignment of similar arguments - how do you define similar in a way that someone else agrees with?
In any case, a tool that covered 80-95% of the coding styles would still be useful -- the remainder of the programmers could be convinced to alter their style slightly over time. I know that my idea of correct formatting has evolved as I discover new forms and reasons for them. And the goal of such a tool is to allow the system to provide true diffs -- from a fixed format, and to allow different coding styles to coexist without bickering over trivia such as placement of {'s and how many spaces per indentation. -- PeteHardie
I'm reminded of Orwell's sixth rule: "Break any of these rules sooner than say anything outright barbarous." The rest of that part of his "Politics and the English Language" could have relevance here as well.
(Coming back after thinking about it for years...)
I am not in favor of any coding standard that stretches the code out either horizontally or vertically. However, having any coding standard in place solves certain problems. On a gig I did a couple years ago a buddy of mine was the lead. He set a coding standard that I thought blew chunks in certain areas, but at least we had a standard to work with.
In that case the client had been frothing over stupid stuff for far too long and hadn't come up with any real conventions on a lot of the engineering process that should have been in place years earlier. After creating some new process docs for them to follow we whipped their boys into shape. Sorta. Don't know if they are still following any of those guidelines and conventions, because they haven't called us back in...
run it through a formatter to a minimalist format (heck, no whitespace or tabs, perhaps). I've often thought of this as an uglifier.
I mentioned this merely so that the issue of the checked-in format would be seen as a non-issue - nobody would work on code in that format, but in their own -- PeteHardie
Yeah, I've proposed a pretty printer such as indent at just about every client I've been at. My argument is that the pretty printer can make all the code look the same by setting up a filter that meets the group coding convention. Then, every team member can set up his own filter. That way code can be checked out, filtered to taste <ahem>, then put back into "conventional" shape again. Kinda useless in an XP environment, I know. But this is exactly what Pete Hardie was talking about above.
Also, the thing about the pretty printer not being able to exactly reproduce the source code format that a particular team member wants: so what? Remember, the library contains checked in code in a certain format. Any format that complies with a specified standard can be reproduced at will by the application of the formatting rules. The pretty printer simply applies those rules to the code in an automated fashion. If a certain decision about where to put a semicolon or a brace is not covered in the rules then the pretty printer will make no change to the source. What's the big deal, anyway?
I have thought the same yet cannot get past one important issue. How will I construct a build process that makes it possible for the "stack trace line numbers" to make sense and/or be useful? Often the official build is run by an automated process. It will not require formatted code.
If I remove all whitespace, check-in, and then kick off the official build, any errors that attempt to include line numbers aren't going to be very meaningful when I look at my pretty code. I suppose one could implement a system where there exists a "build-format beautifier" and if you have to trouble-shoot production code errors referencing line numbers, you can format your code using the official build's preferences. Seems a bit awkward. -- DavidMcReynolds
The solution is: don't remove whitespace. Use a popular coding convention for code inside the VersionControlSystem. CVS can automate formatting on checkin. Everyone checks code in in their own format and reformats to their preferred format on check out. If the automatically built version dumps a stack tracem they can still read the code that's in version control. What I've seen is that people eventually gravitate toward the common format out of laziness.
Should there be UnitTests for the coding standard? (The real question is, "Is it that important?")
If you are going to bother enforcing the standard, you might as well automate the process. I wouldn't call it a UnitTest.
May I suggest that well-factored code simplifies coding standards? Once you have well named methods and variables, your methods are kept short, and well organized in classes, a lot of the contentious parts of coding standards go away. Indentation issues, bracket placements, returns from the middle of a loop, etc., don't really matter when a full method fits on one screen. You can allow this level of variation and concentrate on things that really affect the code.
Hmm. Yeah, I suppose, but you still need a standard of some kind so that people don't get too wild.
One other reason for keeping to a coding standard is so that changes to a system are easy to change. If you have code checked into a VersionControlSystem and developers reformat it each time, then the changes (diffs) between versions can appear huge, even when the changes aren't that significant. Of course, it also reduces the size of the VersionControlSystem database, but that isn't the important part -- the fact that the changes appear huge is the important part.
Also, if you are using a decent IDE (I use Eclipse), then it can handle the reformatting for you against a customisable set of standards, and these standards can be shared in the VersionControlSystem as well. That way, everyone's IDE can format the same at developer rather than check-in time. -- AlexBlewitt?
Coding conventions are just a side-effect caused by developers continuing the now decades-old habit of using text editors to write software as 'code'. Think of all those man-centuries spent discussing coding conventions and reformatting 'code' to meet various arbitrary, incompatible (and therefore ultimately rather pointless) conventions that could have been put to better use solving real problems. Software doesn't need to be encoded. In fact, also think of all the machine-millenia spent parsing 'code'. Wouldn't it be better to store and work directly on an AbstractSyntaxTree? I guess the Lisp guys had the right idea. -- MikeAmy?
Are there any CodingConventionsExamples??
Only for those willing to tolerate Yet Another Religious War.
See: CodingStandard, CheckStyle
EditText of this page
(last edited November 3, 2013)
or FindPage with title or text search