What are the best ways to improve the standards of coding-styles at a company? Let's use C# as an example here.
I guess there are many differences between developers that need to be taken into consideration. The concrete ones could be education, experience and past programming-languages.
How does one justify that something is right over something else?
One person may say "I move my body to the place where I earn my money with my 4-wheeled vehicle". So why is it more "right" to say "I drive to work in my car"?
Some people might like code more explicit with more lines of code. Some might like more tight code.
// Explicit
string text = defaultValue;
if (string.IsNullOrEmpty(text)) {
text = fallbackValue;
}
// Tighter
string text = defaultValue ?? fallbackValue;
Or the old protective programming-style, where you check for error-cases in the beginning and not wrap the whole method body inside a positive if-clause:
public string ChangeText(string text)
{
if (!string.IsNullOrEmpty(text))
{
// Do a lot of stuff
}
else {
throw new Exception();
}
}
// vs.
public string ChangeText(string text)
{
if (string.IsNullOrEmpty(text)) {
throw new Exception();
}
// Do a lot of stuff
}
Is the old "I'm having troubles reading this code" valid here? It's the same situation that was when Generics was introduced to C#, people had an initial trouble reading it.
Where is the line drawn between unreadable code and code that some developers are not used to?
Which part of Phil Haacks "7 Stages of new language keyword grief" has valid points here?
Are there any easy ways to set coding-standards and uphold them in a company?
UPDATE: Take in consideration things like variable-naming, that can't really be defined in a document. Or can it?
The easiest way to set coding-standards at a company:
Create a Standards Document and enforce it.
...people love to complain about code quality, but few will sit down and take the time to create a standards document. It's worth the effort and as long as you can enforce it (code reviews, etc.) then you're bound to notice an improvement in your code.
You always can use free tools like StyleCop from Microsoft.
You can disable or modify rules you don't like
There are two main sides of coding style:
"Where do I put the opening brace?" type issues - These are usually unimportant, i.e. there are no real reasons to prefer one style over the other.
Actual coding rules, like do we use return's in the middle of a function.
The way I see it, for #1 type issues, there is no point in any debate. Just set a standard in a standards document, and enforce it (more on this later).
As for the second issue, I'm honestly not sure whether it should be regulater. I personally love sprinkling functions with return values to check for error conditions, and I know some people who cringe at the practice. But at the end of the day, we can usually read each other's code just fine. These kinds of issues are much more about how you prefer expressing yourself, what is easier for you to write, and I wouldn't want a company making rules that get to this level.
As for how to enforce things, standards documents are good, but in my experience, are just never read or followed closely, and are soon forgotten. The best way is to have some kind of automated tool which tells you that you're violating the standard.
For example, even as a completely new Java programmer, I knew when to uppercase/lowercase my identifiers, simply because Eclipse let me (quietly, unobtrusively) know what the standard is.
First, you will always have to enforce the coding styles - there will never be a consent.
That's, why I would try to automate the check for consistency. Depending on your language you can use StyleCop (for .Net) or something like indent under linux.
Every developer can work with his own code style in his environment (the reformat can be very easy, depending on your environment), but all checked-in code has to be of the company's style.
Which style do you choose? Well, often there are already popular styles - depending on the language. For your example (C#) I would choose the Microsoft style. At last: only the project manager (senior programmer) has the right to adjust it.
Most companies use Coding-Style-Guidelines/Conventions. These are documents telling that you should always do braces around the if body even for one command, that you should indent with tabs/spaces, and so on.
There are a lot of tools for (automatically) check and enforce the coding-style. (An example for the java-world is checkstyle, which can be integrated into eclipse and also in a continuous integration solution like 'hudson'.)
How does one justify that something is
right over something else?
Easy: just don't. Pick a coding style, communicate it, and enforce it.
I think consistency is important here. There's not a lot of point in getting into a semantic debate over which way is better than the other unless the current methodology is particularly bad.
What is important is that the team writes their code consistently so that if someone resigns or gets hit by a bus then his/her colleagues know what is going on with the code when they are forced to work with it.
Related
Let's say you've inherited a C# codebase that uses one class with 200 static methods to provide core functionality (such as database lookups). Of the many nightmares in that class, there's copious use of Hungarian notation (the bad kind).
Would you refactor the variable names to remove the Hungarian notation, or would you leave them alone?
If you chose to change all the variables to remove Hungarian notation, what would be your method?
Refactor -- I find Hungarian notation on that scale really interferes with the natural readability of the code, and the exercise is a good way of getting familiar with what's there.
However, if there are other team members who know the code base you would need consensus on the refactoring, and if any of the variables are exposed outside of the one project then you will have to leave them alone.
Just leave it alone. There are better uses of your time.
Right click on the variable name, Refactor -> Rename.
There are VS add-ins that do this as well, but the built-in method works fine for me.
What would I do? Assuming that I just have to maintain the code and not rewrite it any significant way? Leave it well alone. And When I do add code, go with the existing style, meaning, use that ugly Hungarian notation (as dirty as that makes me feel.)
But, hey, if you really have a hankerin' fer refactorin' then just do a little at a time. Every time you work on it spend ten minutes renaming variables. Tidying things up a little. After a few months you might find it's clean as a whistle....
Don't forget that there are two kinds of Hungarian Notation.
The original Charles Simonyi HN, later known as App's Hungarian and the later abomination called System Hungarian after some peckerhead (it's a technical term) totally misread Simonyi's original paper.
Unfortunately, System HN was propagated by Petzold and others to become the more dominant abortion that it is rightfully recognised as today.
Read Joel's excellent article about the intent of the original Apps Hungarian Notation and be sorry for what got lost in the rush.
If what you've got is App's Hungarian you will probably want to keep it after reading both the original Charles Simonyi article and the Joel article.
If you've landed in a steaming pile of System Hungarian?
All bets are off!
Whew! (said while holding nose) (-:
if you're feeling lucky and just want the Hungarian to go away, isolate the Hungarian prefixes that are used and try a search and replace in file to replace them with nothing, then do a clean and rebuild. If the number of errors is small, just fix it. If the number of errors is huge, go back and break it up into logical (by domain) classes first, then rename individually (the IDE will help)
I used to use it religiously back in the VB6 days, but stopped when VB.NET came out because that's what the new VB guidelines said. Other developers didn't. So, we’ve got a lot of old code with it. When I do maintenance on code I remove the notation from the functions/methods/sub I touch. I wouldn't remove it all at once unless you've got really good unit tests for everything and can run them to prove that nothing's broken.
How much are you going to break by doing this? That's an important question to ask yourself. If there are a lot of other pieces of code that use that library, then you might just be creating work for folks (maybe you) by going through the renaming exercise.
I'd put it on the list of things to do when refactoring. At least then everyone expects you to be breaking the library (temporarily).
That said, I totally get frustrated with poorly named methods and variables, so I can relate.
I wouldn't make a project out of it. I'd use the refactoring tools in VS (actually, I'd use Resharper's, but VS's work just fine) and fix all the variables in any method I was called upon to modify. Or if I had to make larger-scale changes, I'd refactor the variable names in any method I was called upon to understand.
If you have a legitimate need to remove and change it I would use either the built in refactoring tools, or something like Resharper.
However, I would agree with Chris Conway to a certain standpoint and ask you WHY, yes, it is annoying, but at the same time, a lot of the time the "if it aint't broke done't fix it" method is really the best way to go!
Only change it when you directly use it. And make sure you have a testbench ready to apply to ensure it still works.
I agree that the best way to phase out hungarian notation is to refactor code as you modify it. The greatest benefit of doing this kind of refactoring is that you should be writing unit tests around the code you're modifying so that you have a safety net instead of crossing your fingers and hoping that you don't break existing functionality. Once you have these unit tests in place, you are free to change the code to your heart's content.
I'd say a bigger problem is that you have a single class with 200(!) methods!
If this is a much depended on / much changed class then it might be worth refactoring to make it more usable.
In this, Resharper is an absolute must (you could use the built in refactoring stuff, but Resharper is way better).
Start finding a group of related methods, and then refactor these out into a nice small cohesive class. Update to conform to your latest code standards.
Compile & run your test suite.
Have energy for more? Extract another class.
Worn out - no trouble; come back and do some more tomorrow. In just a few days you'll have conquered the beast.
I agree with #Booji -- do it manually, on a per-routine basis when you're already visiting the code for some other good reason. Then, you'll get the most common ones out of the way, and who cares about the rest.
I was thinking of asking a similar question, only in my case, the offending code is my own. I have a very old habit of using "the bad kind" of Hungarian from my FoxPro days (which had weak typing and unusual scoping) — a habit I've only recently kicked.
It's hard — it means accepting an inconsistent style in your code base. It was only a week ago I finally said "screw it" and began a parameter name without the letter "p". The cognitive dissonance I initially felt has given way to a feeling of liberty. The world did not come to an end.
The way I've been going about this problem is changing one variable at a time as I come across them, then perform more sweeping changes when you come back to do more in-depth changes. If you're anything like me, the different nomenclature of your variables will drive you bat-shiat crazy for a while, but you'll slowly become used to it. The key is to chip away at it a little bit at a time until you have everything to where it needs to be.
Alternatively, you could jettison your variables altogether and just have every function return 42.
It sounds to me like the bigger problem is that 200-method God Object class. I'd suggest that refactoring just to remove the Hungarian notation is a low-value, high-risk activity in of itself. Unless there's a copious set of automated unit tests around that class to give you some confidence in your refactoring, I think you should leave it well and truly alone.
I guess it's unlikely that such a set of tests exists, because a developer following TDD practices would (hopefully) have naturally avoided building a god object in the first place - it would be very difficult to write comprehensive tests for.
Eliminating the god object and getting a unit test base in place is of higher value, however. My advice would be to look for opportunities to refactor the class itself - perhaps when a suitable business requirement/change comes along that necessitates a change to that code (and thus hopefully comes with some system & regression testing bought and paid for). You might not be able to justify the effort of refactoring the whole thing in one go, but you can do it piece by piece as the opportunity comes along, and test-drive the changes. In this way you can slowly convert the spaghetti code into a cleaner code base with comprehensive unit tests, bit by bit.
And you can eliminate the Hungarian as you go, if you like.
I am actually doing the same thing here for an application extension. My approach has been to use VIM mappings to search for specific Hungarian notation prefixes and then delete them and fix capitalization as appropriate.
Examples (goes in vimrc):
"" Hungarian notation conversion helpers
"" get rid of str prefixes and fix caps e.g. strName -> name
map ,bs /\Wstr[A-Z]^Ml3x~
map ,bi /\Wint[A-Z]^Ml3x~
"" little more complex to clean up m_p type class variables
map ,bm /\Wm_p\?[A-Z]^M:.s/\(\W\)m_p\?/\1_/^M/\W_[A-Z]^Mll~
map ,bp /\Wp[A-Z]^Mlx~
If you're gonna break code just for the sake of refactoring, I would seriously consider leaving i alone, specially, if you are going to affect other people in your team who may be depending on that code.
If your team is OK with this refactoring, and investing your time in doing this (which may be a time-saver in the future, if it means the code is more readable/maintainable), use Visual Studio (or whatever IDE you are using) to help you refactor the code.
However, if a big change like this is not a risk your team/boss is willing to take, I would suggest a somewhat unorthodox, half-way approach. Instead of doing all your refactoring in a single sweep, why not refactor sections of code (more specifically, functions) that need to be touched during normal maintenance? Over time, this slow refactoring will bring the code up to a cleaner state, at which point you can finish the refactoring process with a final sweep.
Use this java tool to remove HN:
Or just use "replace"/"replace all" with regex like below to replace "c_strX" to "x":
I love Hungarian notation. Don't understand why you would want to get rid of it.
I just refactored some code that was in a different section of the class I was working on because it was a series of nested conditional operators (?:) that was made a ton clearer by a fairly simple switch statement (C#).
When will you touch code that isn't directly what you are working on to make it more clear?
I once was refactoring and came across something like this code:
string strMyString;
try
{
strMyString = Session["MySessionVar"].ToString();
}
catch
{
strMyString = "";
}
Resharper pointed out that the .ToString() was redundant, so I took it out. Unfortunately, that ended up breaking the code. Whenever MySessionVar was null, it wasn't causing the NullReferenceException that the code relied on to bump it down to the catch block. I know, this was some sad code. But I did learn a good lesson from it. Don't rapidly go through old code relying on a tool to help you do the refactoring - think it through yourself.
I did end up refactoring it as follows:
string strMyString = Session["MySessionVar"] ?? "";
Update: Since this post is being upvoted and technically doesn't contain an answer to the question, I figured I should actually answer the question. (Ok, it was bothering me to the point that I was actually dreaming about it.)
Personally I ask myself a few questions before refactoring.
1) Is the system under source control? If so, go ahead and refactor because you can always roll back if something breaks.
2) Do unit tests exist for the functionality I am altering? If so, great! Refactor. The danger here is that the existence of unit tests don't indicate the accuracy and scope of said unit tests. Good unit tests should pick up any breaking changes.
3) Do I thoroughly understand the code I am refactoring? If there's no source control and no tests and I don't really understand the code I am changing, that's a red flag. I'd need to get more comfortable with the code before refactoring.
In case #3 I would probably spend the time to actually track all of the code that is currently using the method I am refactoring. Depending on the scope of the code this could be easy or impossible (ie. if it's a public API). If it comes down to being a public API then you really need to understand the original intent of the code from a business perspective.
I only refactor it if tests are already in place. If not, it's usually not worth my time to write tests for and refactor presumably working code.
This is a small, minor antipattern but it so irritates me that whenever I find it, I expunge it immediately. In C (or C++ or Java)
if (p)
return true;
else
return false;
becomes
return p;
In Scheme,
(if p #t #f)
becomes
p
and in ML
if p then true else false
becomes
p
I see this antipattern almost exclusively in code written by undergraduate students. I am definitely not making this up!!
Whenever I come across it and I don't think changing it will cause problems (e.g. I can understand it enough that I know what it does. e.g. the level of voodoo is low).
I only bother to change it if there is some other reason I'm modifying the code.
How far I'm willing to take it depends on how confident I am that I won't break anything and how extensive my own changes to the code are going to be.
This is a great situation to show off the benefits of unit tests.
If unit tests are in place, developers can bravely and aggressively refactor oddly written code they might come across. If it passes the unit tests and you've increased readability, then you've done your good deed for the day and can move on.
Without unit tests, simplifying complex code that's filled with voodoo presents a great risk of breaking the code and not even knowing you've introduced a new bug! So most developers will take the cautious route and move on.
For simple refactoring I try to clean up deeply nested control structures and really long functions (more than one screen worth of text). However its not a great idea to refactor code without a good reason (especially in a big team of developers). In general, unless the refactoring will make a big improvement in the code or fix an egregious sin I try to leave well enough alone.
Not refactoring per-say but just as a matter of general housekeeping I generally do this stuff when I start work on a module:
Remove stupid comments
Comments that say nothing more than the function signature already says
Comments that are pure idiocy like "just what it looks like"
Changelogs at the top of the file (we have version control for a reason)
Any API docs that are clearly out-of-sync with the code
Remove commented-out chunks of code
Add version control tags like $Id$ if they are missing
Fix whitespace issues (this can be annoying to others though because your name shows up for a lot of lines in a diff even if all you did was change whitespace)
Remove whitespace at the end of the lines
Change tabs->spaces (for that is our convention where I work)
If the refactor makes the code much easier to read, the most common for me would be duplicate code, e.g. an if/else that only differs by the first/last commands.
if($something) {
load_data($something);
} else {
load_data($something);
echo "Loaded";
do_something_else();
}
More than (arguably) three or four lines of duplicate code always makes me think about refactoring. Also, I tend to move code around a lot, extracting the code I predict to be used more frequently into a separate place - a class with its own well-defined purpose and responsibilites, or a static method of a static class (usually placed in my Utils.* namespace).
But, to answer your question, yes, there are lot of cases when making the code shorter does not necessarily mean making it well structued and readable. Using the ?? operator in C# is another example. What you also have to think about are the new features in your language of choice - e.g. LINQ can be used to do some stuff in a very elegant manner but also can make a very simple thing very unreadable and overly complex. You need to weigh these two thing very carefully, in the end it all boils down to your personal taste and, mostly, experience.
Well, this is another "it depends" answer, but I am afraid it has to be.
I almost always break >2 similar conditionals into a switch... most often with regards to enums. I will short a return instead of a long statement.
ex:
if (condition) {
//lots of code
//returns value
} else {
return null;
}
becomes:
if (!condition)
return null;
//lots of code..
//return value
breaking out early reduces extra indents, and reduces long bits of code... also as a general rule I don't like methods with more than 10-15 lines of code. I like methods to have a singular purpose, even if creating more private methods internally.
Usually I don't refactor the code if I'm just browsing it, not actively working on it.
But sometimes ReSharper points out some stuff I just can't resist to Alt+Enter. :)
I tend to refactor very long functions and methods if I understand the set of inputs and outputs to a block.
This helps readability no end.
I would only refactor the code that I come across and am not actively working on after going through the following steps:
Speak with the author of the code (not always possible) to figure out what that piece of code does. Even if it is obvious to me as to what the piece of code is doing, it always helps to understand the rationale behind why the author may have decided to do something in a certain way. Spending a couple of minutes talking about it would not only help the original author understand your point of view, it also builds trust within the team.
Know or find out what that piece of code is doing in order to test it after re-factoring (A build process with unit tests is very helpful here. It makes the whole thing quick and easy). Run the unit tests before and after the change and ensure nothing is breaking due to your changes.
Send out a heads up to the team (if working with others) and let them know of the upcoming change so nobody is surprised when the change actually occurs
Refactoring for the sake of it is one of the roots of all evil. Please don't ever do it. (Unit tests do somewhat mitigate this).
Is vast swaths of commented out code an antipattern? While not code specifically, (it's comments) I see a lot of this kind of behaviour with people who don't understand how to use source control, and who want to keep the old code around for later so they can more easily go back if a bug was introduced. Whenever I see vast swaths of code that are commented out, I almost always remove them in their entirety.
I try to refactor based on following factors:
Do I understand enough to know whats happening?
Can I easily revert back if this change breaks the code.
Will I have enough time to revert the change back if it breaks the build.
And sometimes, if I have enough time, I refactor to learn. As in, I know my change may break the code, but I dont know where and how. So I change it anyways to find out where its breaking and why. That way I learn more about the code.
My domain has been mobile software (cell phones) where most of the code resides on my PC and wont impact others. Since I also maintain the CI build system for my company I can run a complete product build (for all phones) on the refactored code to ensure it doesnt break anything else. But thats my personal luxury which you may not have.
I tend to refactor global constants and enumerations quite a bit if they can be deemed a low refactor risk. Maybe it's just be, but something like a ClientAccountStatus enum should be in or close to the ClientAccount class rather than being in a GlobalConstAndEnum class.
Deletion/updating of comments which are clearly wrong or clearly pointless.
Removing them is:
safe
version control means you can find them again
improves the quality of the code to others and yourself
It is about the only 100% risk free refactoring I know.
Note that doing this in structured comments like javadoc comments is a different matter. Changing these is not risk free, as such they are very likely to be fixed/removed but not dead certain guaranteed fixes as standard incorrect code comments would be.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 8 years ago.
Improve this question
Years ago when I was starting a small development project, the other developers and I sat down and agreed on a compromise brace and indentation style. It wasn't anybody's favourite, but it was something that nobody really hated. I wrote a .indentrc configuration file to that style, and had a check-in trigger that would run indent on every file as it was being checked in. That made it so that it didn't matter what style you wrote your code in, it would end up being the group standard before anybody else saw it. This had the advantage of consistency. But I've never seen anybody else do it this way before or since.
So what say the rest of you? Great idea, or abomination?
I'd say good idea. I'd take it a step further and make everyone use the config file in their IDE so that they were writing in the agreed upon style by default. If they're going to have to look at everyone else's code in the neutral style, they might as well get used to it. Even their own code should be in the neutral style after one check-in check-out cycle, so why develop new code in their own personal style?
Adopting a neutral coding style is definitely a good idea. However, only enforcing the coding style when the source is checked in may or may not be a good idea (see also Bill's and Elie's answers below).
Using the check-in hook:
Pro: Allows coders to write however they wish, so they don't have to think about the standard or change the way they write code. This minimizes resistance to the policy, and won't negatively impact their productivity when writing code.
Con: Your coders may have only a passing familiarity with the neutral style, so you aren't getting the full benefit of everyone using "the same" style. If your programmers ever have to work together in a pair programming setup, they are still going to be subjected to one another's programming style on the screen, which is going to be different from their own style or the neutral style.
Going one step further, using the neutral style during development:
Pro: Encourages fluency in the neutral style, everyone can always read everyone else's code before and after it's checked in.
Con: You'll encounter more resistance from your developers doing it this way. Depending on your culture, it could be more trouble than it is worth.
If you limited it to enforcing style on braces and indentation, then I think it's a good idea. However, if you were to try to enforce every single formatting standard, then it probably wouldn't be. In my opinion, there are times when it makes sense to break the standard. For example, I prefer
int x = y * z;
to
int x = y*z;
because it's easier to read. However, I vastly prefer
int a = b*c + d*e;
to
int a = b * c + d * e;
because the spacing represents the order of operations.
So your policy of enforcing indentation and braces sounds really good. But if someone ever tried to blindly enforce other spacing rules, I don't think it would work well.
That sounds like a good idea. As long as the style you end up with is not something completely strange, that's a good way to make sure your developers use the style. And it has the added benefit that they don't have to code that way - it will get reformatted for them when they check in their changes. It would be nice to have a tool like that available that you can plug into your CVS (generic term).
We use TFS with a check in policy that runs a set of Stylecop rules. If your code doesn't pass, you can't check it in. Works very well indeed. Aside from a consistant style and good commenting throughout, it also seems to have increased the general quality of the code - perhaps because the developer is forced to describe what every method, event, etc does they are forced to think about the code more before check in.
Only an MS solution, but worthwhile if it's available to you.
The biggest problem with using automatic code formatters is when the code formatter can't handle every scenario.
For example, if you have lots of SQL in your code, you probably format the SQL automatically. But if your SQL is longer than one line (how long is a line, anyway?) then
you have to format it. So far I've yet to see a good formatter than can deal with this properly.
Example:
String sql = "SELECT * FROM USERS WHERE ID = ? AND NAME = ? AND IS_DELETED = 'N'";
vs
String sql =
"SELECT * " +
"FROM USERS " +
"WHERE ID = ? " +
" AND NAME = ? " +
" AND IS_DELETED = 'N'";
The second format is more readable when you have really long queries. Most formatters would de-format that into one long line up to the line length.
However if all you're doing is turning
if(x=1) print("blah"); else print("eep!");
into
if (x = 1) {
print("blah");
} else {
print("eep!");
}
then the formatter is ok. We do something similar at work; it isn't enforced by the CVS tool but rather by the IDE. Works reasonably well.
There is a project called EditorConfig can somewhat solve the issue. However, it currently only solves indentation issues.
EditorConfig contains plugins for many different editors, and a file format standard. By creating an .editorconfig file in the root of your project, and installing the corresponding plugin, the editor will format your code when you type them.
This is a general way (unlike indentrc, not limited to C/C++), but you can still take a look at this solution.
I believe you have decided on your development environment by now. If you use Eclipse you can enable the Format Source save action on the Java editor, which reformats at every save. The major benefit from this is that source chances are marked in your source repository at the time when they were done, not when the source was reformatted later.
Make it an automatic step. You will appreciate it later.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
I've worked on a couple of projects where we spent a great deal of time discussing and writing elaborate coding standards covering everything from syntax layout to actual best practices. However, I have also found that these are rarely followed to the full extent. Many developers seem to hesitate to reject a code review based on coding standard violations alone. I.e. violations are committed to the repository on a regular basis.
My questions are: Do you have coding standards? What do they cover? Are they followed by everyone? And what do you do (if anything) to make sure everybody is following the standards?
I'm aware that there is a similar question here, but my concern is not so much how you could do it, but how you are actually going about it and what are the perceived benefits?
I've worked in places with barely-followed coding practices, and others where they're close to being enforced - or at least easily checked.
A few suggestions:
The most important thing is to get buy-in to the idea that consistency trumps your personal preferred style. There should be discussion of the coding standard both before and after it's instituted, but no-one should be allowed to just opt out of it.
Code reviews should be mandatory, with the checkin comment including the username of the reviewer. If you're using a suitably powerful SCM, consider not allowing checkins which don't have a valid reviewer name.
There should be a document which everyone knows about laying out the coding standards. With enough detail, you shouldn't get too much in the way of arguments.
Where possible, automate checking of the conventions (via Lint, CheckStyle, FXCop etc) so it's easy for both the committer and the reviewer to get a quick check of things like ordering import/using directives, whitespace etc.
The benefits are:
Primarily consistency - if you make it so that anyone can feel "at home" in any part of the codebase at any time, it gives you more flexibility.
Spreading best practice - if you ban public fields, mutable structs etc then no-one can accidentally plant a time bomb in your code. (At least, not a time bomb that's covered by the standard. There's no coding standard for perfect code, of course :)
EDIT: I should point out that coding standards are probably most important when working in large companies. I believe they help even in small companies, but there's probably less need of process around the standard at that point. It helps when all the developers know each other personally and are all co-located.
Do you have coding standards?
Yes, differs from project to project.
What does it cover?
Code(class, variable, method, constant), SQL naming and formatting convention
Is it being followed by everyone?
Yes, every new entrant in project could be asked to create a demo project following organization coding convention then it gets reviewed. This exercise makes developer feel at ease before starting real job.
And what do you do (if anything) to make sure everybody is following the standard?
Use StyleCop and FxCop to ensure they are religiously followed. It would show up as warning/error if code fails to comply with organization coding convention.
Visual Studio Team system has nice code anlysis and check-In policies which would prevent developers checking in code that does not comply
Hope, it helps
Thanks,
Maulik Modi
We take use of the Eclipse's save actions and formatters. We do have a suggested standard, but nobody is actually enforcing it, so there are some variations on what is actually formatted, and how.
This is something of a nuisance (for me), as various whitespace variations are committed as updates to the SVN repository...
StyleCop does a good job of enforcing coding layout practices and you can write custom rules for it if something isn't covered in the base rules that is important to you.
I think coding standards are very important. There is nothing more frustrating than trying to find the differences between two revisions of a file only to find that the whole file has been changed by someone who reformatted it all. And I know someone is going to say that that sort of practice should be stamped out, but most IDEs have a 'reformat file' feature (Ctrl-K Ctrl-D in Visual Studio, for example), which makes keeping your code layed out nicely much easier.
I've seen projects fail through lack of coding standards - the curly-brace wars at my last company were contributary to a breakdown in the team.
I've found the best coding standards are not the standards made up by someone in the team. I implemented the standards created by iDesign (click here) in our team, which gets you away from any kind of resentment you might get if you try to implement your own 'standard'.
A quick mention of Code Style Enforcer (click here) which is pretty good for highlighting non-compliance in Visual Studio.
I have a combination of personal and company coding standards that are still evolving to some extent. They cover code structure, testing, and various documents describing various bits of functionality.
As it evolves, it is being adopted and interpreted by the rest of my team. Part of what will happen ultimately is that if there is concensus on some parts then those will hold up while other parts may just remain code that isn't necessarily going to be up to snuff.
I think there may be some respect or professional admiration that act as a way of getting people to follow the coding standards where some parts of it become clear after it is applied, e.g. refactoring a function to be more readable or adding tests to some form, with various "light bulb moments" to borrow a phrase from Oprah.
Another part of the benefit is to see how well do others work, what kinds of tips and techniques do they have and how can one improve over time to be a better developer.
I think the best way to look at coding standards is in terms of what you hope to achieve by applying, and the damage that they can cause if mis-applied. For example, I see the following as quite good;
Document and provide unit tests that illustrate all typical scenarios for usage of a given interface to a given routine or module.
Where possible use the following container classes libraries, etc...
Use asserts to validate incoming parameters and results returned (C & C++)
Minimise scope of all variables
Access object members through methods
Use new and delete over malloc and free
Use the prescribed naming conventions
I don't think that enforcing style beyond this is a great idea, as different programmers are efficient using differing styles. Forcing programmers to change style can be counter productive and lead to lost time and reduced quality. Standards should be kept short and easy to understand.
Oh yes, I'm the coding standard police :) I just wrote a simple script to periodically check and fix the code (my coding standard is simple enough to implement that.) I hope people will get the message after seeing all these "coding convention cleanups" messages :)
We have a kind of 'loose' standard. Maybe because of our inability to have agreement upon some of those 'how many spaces to put there and there', 'where to put my open brace, after the statement or on the next line'.
However, as we have main developers for each of the dedicated modules or components, and some additional developers that may work in those modules, we have the following main rule:
"Uphold the style used by the main developer"
So if he wants to do 3 space-indentation, do it yourself also.
It's not ideal as it might require retune your editor settings, but it keeps the peace :-)
Do you have coding standards?
What does it cover?
Yes, it has naming conventions, mandatory braces after if, while ... , no warning allowed, recommendations for 32/64 bits alignment, no magic number, header guards, variables initialization and formatting rules that favor consistency for legacy code.
Is it being followed by everyone?
And what do you do (if anything) to make sure everybody is following the standard?
Mostly, getting the team agreement and a somewhat lightweight coding standard (less than 20 rules) helped us here.
How it is being enforced ?
Softly, we do not have coding standard cop.
Application of the standard is checked at review time
We have template files that provide the standard boilerplate
I have never seen a project fail because of lack of coding standards (or adherence to them), or even have any effect on productivity. If you are spending any time on enforcing them then you are wasting money. There are so many important things to worry about instead (like code quality).
Create a set of suggested standards for those who prefer to have something to follow, but leave it at that.
JTest by ParaSoft is decent for Java.
Our coding standards are listed in our Programmer's Manual so everyone can easily refer to them. They are effective simply because we have buy in from all team members, because people are not afraid to raise standards and style issues during code reviews, and because they allow a certain level of flexibility. If one programmer creates a new file, and she prefers to place the bracket on the same line as an if statement, that sets the standard for that file. Anyone modifying that file in the future must use the same style to keep things consistent.
I'll admit, when I first read the coding standards, I didn't agree with some of them. For instance, we use a certain style for function declarations that looks like this:
static // Scope
void // Type declaration
func(
char al, //IN: Description of al
intl6u hash_table_size, //IN/OUT: Description of hash_table_size
int8u s) //OUT: Description of s
{
<local declarations>
<statements>
}
I had never seen that before, so it seemed strange and foreign to me at first. My gut reaction was, "Well, that's dumb." Now that I've been here a while, I have adjusted to the style and appreciate how I can quickly comprehend the function declaration because everyone does it this way.
I am writing a coding standards document for a team of about 15 developers with a project load of between 10 and 15 projects a year. Amongst other sections (which I may post here as I get to them) I am writing a section on code formatting. So to start with, I think it is wise that, for whatever reason, we establish some basic, consistent code formatting/naming standards.
I've looked at roughly 10 projects written over the last 3 years from this team and I'm, obviously, finding a pretty wide range of styles. Contractors come in and out and at times, and sometimes even double the team size.
I am looking for a few suggestions for code formatting and naming standards that have really paid off ... but that can also really be justified. I think consistency and shared-patterns go a long way to making the code more maintainable ... but, are there other things I ought to consider when defining said standards?
How do you lineup parenthesis? Do you follow the same parenthesis guidelines when dealing with classes, methods, try catch blocks, switch statements, if else blocks, etc.
Do you line up fields on a column? Do you notate/prefix private variables with an underscore? Do you follow any naming conventions to make it easier to find particulars in a file? How do you order the members of your class?
What about suggestions for namespaces, packaging or source code folder/organization standards? I tend to start with something like:
<com|org|...>.<company>.<app>.<layer>.<function>.ClassName
I'm curious to see if there are other, more accepted, practices than what I am accustomed to -- before I venture off dictating these standards. Links to standards already published online would be great too -- even though I've done a bit of that already.
First find a automated code-formatter that works with your language. Reason: Whatever the document says, people will inevitably break the rules. It's much easier to run code through a formatter than to nit-pick in a code review.
If you're using a language with an existing standard (e.g. Java, C#), it's easiest to use it, or at least start with it as a first draft. Sun put a lot of thought into their formatting rules; you might as well take advantage of it.
In any case, remember that much research has shown that varying things like brace position and whitespace use has no measurable effect on productivity or understandability or prevalence of bugs. Just having any standard is the key.
Coming from the automotive industry, here's a few style standards used for concrete reasons:
Always used braces in control structures, and place them on separate lines. This eliminates problems with people adding code and including it or not including it mistakenly inside a control structure.
if(...)
{
}
All switches/selects have a default case. The default case logs an error if it's not a valid path.
For the same reason as above, any if...elseif... control structures MUST end with a default else that also logs an error if it's not a valid path. A single if statement does not require this.
In the occasional case where a loop or control structure is intentionally empty, a semicolon is always placed within to indicate that this is intentional.
while(stillwaiting())
{
;
}
Naming standards have very different styles for typedefs, defined constants, module global variables, etc. Variable names include type. You can look at the name and have a good idea of what module it pertains to, its scope, and type. This makes it easy to detect errors related to types, etc.
There are others, but these are the top off my head.
-Adam
I'm going to second Jason's suggestion.
I just completed a standards document for a team of 10-12 that work mostly in perl. The document says to use "perltidy-like indentation for complex data structures." We also provided everyone with example perltidy settings that would clean up their code to meet this standard. It was very clear and very much industry-standard for the language so we had great buyoff on it by the team.
When setting out to write this document, I asked around for some examples of great code in our repository and googled a bit to find other standards documents that smarter architects than I to construct a template. It was tough being concise and pragmatic without crossing into micro-manager territory but very much worth it; having any standard is indeed key.
Hope it works out!
It obviously varies depending on languages and technologies. By the look of your example name space I am going to guess java, in which case http://java.sun.com/docs/codeconv/ is a really good place to start. You might also want to look at something like maven's standard directory structure which will make all your projects look similar.