Related
Similar questions: Styleguide for C# and StyleCop: a complete document
Ok, so I'm looking into some sort of style control at my workplace for the applications we develop in C#. I was initially just planning on producing a style guide (by collecting a number of existing style guides and picking the suitable parts from), however it seems like StyleCop might be a good addition or alternative to a style guide.
So, my question(s) are:
What are the potential problems with a style guide and/or StyleCop
that I am likely to run into?
If I use StyleCop how similar do I want the style guide to be? Do I want to attempt to prevent/limit any variation between the 2 methods? I ask because
if StyleCop doesn't enforce it then it could potentially be ignored (or is that not really too much of an issue?).
If I'm using StyleCop, is it even worth the time and effort of creating a style guide?
Are there any alternatives to StyleCop that a worthwhile looking into? (e.g. An alternative that has very good
usability/customization and "could" be considered sufficient on it's
own).
EDIT: Just a little bit of background, my workplace has a "software department" that is only really just forming now. There is 3 full time c# developers, 3 developers who may touch/use/alter the c# code, a number of BA's and no official testers.
After having been on a team that used/maintained/enforced a style guide and then on a team that used StyleCop, my advice is to use StyleCop exclusively. This is for several reasons:
It is compile-time enforceable. This is a huge advantage when it comes to something as persnickety as style. With a style manual there's always gray area, but there isn't any with a compiler error. This reduces style arguments from "This is wrong"/"No it isn't" to "Which should we prefer", which is (usually) a more civil argument.
If you create your own style, someone (or all of you) will need to be the human "style cop", which is a pretty miserable job. Developers (in my experience) tend to not like people making "style adjustments" to their committed code, and dislike even more when told to make their code conform to the style. This is also time consuming as it's another thing to review during code reviews (you are doing those, right?).
StyleCop comes with a pretty decent set of default rules, and using just these rules will let you match most other C# codebases out there. When I was using our own in-house style manual, all open-source code looked foreign because we used comment headers, capitalized parameters, some Hungarian notation, etc. But when I moved to StyleCop-enforced style with the default rule set, everything looked familiar!
Creating your style means you're going to spend a lot of time re-inventing the wheel, and then maintaining that wheel when edge cases and arguments appear. That's a non-zero amount of work and can chew up a lot of time; from my experience developers will always debate code style.
It has a decent editor to configure your rule set if you don't like some of the defaults or need to add abbreviations that StyleCop should ignore.
You can write your own rules or use those that others have published. For instance, some on our team hate trailing whitespace, so I include these rules to enforce that.
As far as alternatives, I don't know of any that are as seamless as StyleCop is. I should note that I've only ever used it in conjunction with Resharper/Visual Studio, so if you have a different environment then your mileage may vary.
FYI, the new StyleCop Analyzers NuGet Package is a major improvement on things. You can now hand-pick your StyleCop rules (or just use the default selections) by editing the project's rule set (Properties -> Code Analysis).
I just discovered they've even included three "alternative" rules for teams that follow the dark side... :-)
SX1101 - Do not prefix local calls with 'this.'
SX1309 - Field names must begin with underscore
SX1309S - Static field names must begin with underscore
The best thing you can do in your workplace is teach the value of:
Recognize existing style patterns in a body of code.
Follow the existing style patterns which you make changes to that body of code.
Regardless of the project you are working on, this practice leads to the overall lowest rate of submissions getting returned for style issues. It also requires the least amount of explanation in your style guide.
With that out of the way, you can focus on topics which are less easily inferred from looking at a single file, such as naming conventions used across the code base, threading models in effect, and the interaction between modules at a high level.
I am working on a project where we have several attributes in AssemblyInfo.cs, that are being multicast to methods of a particular class.
[assembly: Repeatable(
AspectPriority = 2,
AttributeTargetAssemblies = "MyNamespace",
AttributeTargetTypes = "MyNamespace.MyClass",
AttributeTargetMemberAttributes = MulticastAttributes.Public,
AttributeTargetMembers = "*Impl", Prefix = "Cls")]
What I don't like about this, is that it puts a piece of logic into AssemblyInfo (Info, mind you!), which for starters should not contain any logic at all. The worst part of it, is that the actual MyClass.cs does not have the attribute anywhere in the file, and it is completely unclear that methods of this class might have them. From my perspective it greatly hurts readability of the code (not to mention that overuse of PostSharp can make debugging a nightmare).Especially when you have multiple multicast attributes.
What is the best practice here? Is anyone out there is using PostSharp attributes like this?
Let me first answer to Max: indeed, aspects are not an alternative to good OOP patterns. They are a complement. Any good AOP design starts with a good OOP design. But OOP patterns sometimes force you to write a lot of plumbing code manually. For these cases, aspects can be used to automate the implementation of OOP pattern, not to replace them.
When you use AOP intelligently, your solution can become easier to understand (business code is not mixed with maintenance code), to test (you can test the aspect independently from business code, i.e. you don't have to test that any business method traces properly), change (you just have to change the aspect when you want to change the pattern, instead of changing every implementation of the pattern). Now, if you abuse from AOP, if you use it as a hacking tool, if you do not think in terms of OOP patterns before, then your're going to get more costs than benefits from AOP. As any sharp tool, AOP should be used intelligently.
Back to the original question.
Who tells you should put aspects in AssemblyInfo.cs? You could create a new file called GlobalAspects.cs and put all assembly-level aspects there. You're right that AssemblyInfo.cs should just be for assembly-level metadata.
But like you, I don't like assembly-level aspects. I think there should be avoided. The principal problem with assemly-level aspects is that they rely on naming conventions, and this is evil. (This evil is called pointcut fragility in the academic AOSD community.) Indeed, when you rename a class or namespace, you change the set of methods to which the aspect applies, and this can quickly become a nightmare. That's why I never use aspects based on naming conventions for myself.
What about code readibility? To a great extent, I think readable code is short code. If I have a business method called CreateProduct, I probably want to see just the code creating the product. Most of the time, I am not interested in code that handles transactions, exceptions, or tracing. It's enough if I know that some aspects handle that for me.
And how do I know? With PostSharp, you have the Visual Studio Extension. With AspectJ, you have the AspectJ plug-in for Eclipse (AJDT). They show you, inside the IDE, which aspects are applied to the code you currently see. And if you really want to see details (but you seldom really want), you can use the debugger to step into aspects, or use Reflector to see produced code.
Summary:
Good AOP design always starts with a good OOP design.
Avoid relying on naming conventions to apply aspects.
Use PostSharp extension for Visual Studio or AJDT to visualize aspects in your code.
I'm sure this will be an unpopular answer but maybe I can get my peer pressure badge...
Your instincts are correct. Putting logic in metadata of any kind is a horrible, horrible sin for which one burns eternally in the hellfire of unmaintainability.
I mean no disrespect by this although I'm certain it will be interpreted otherwise.
The best practice would be to not use "aspect-oreinted programming" tools, which are crutches that enable the lameness of poor design and testing practices. Instead, look at your design and ask yourself "why."
Why did I feel the need to use this
tool? What design problem was I
trying to solve?
Once you have a firm grasp of the problem, go pick up Design Patterns Explained (Shalloway & Trott) or Head First Design Patterns (Freeman, Robson, Bates, & Sierra).
In the end, a pattern-oriented solution will be easier to understand, easier to test, and easier to change. The only additional cost will be the one-time fee of mastering design patterns in place of the recurring charge of trying to figure out where all these aspects are, how they fit together, and how they influence one another every time you make a change.
I'm looking for advice as to coding conventions. The primary languages I use, in order of frequency are C#, JavaScript, and ActionScript. They are all ECMA-based languages, so for the most part, the syntax is interchangeable. What I would like to do is standardize the way I write code.
I looked around for documents on coding standards and found some, by various authors including Microsoft, Adobe, Doug Crockford, and the authors of various books I own. Much of the individual standards are identical. For example, do not use capitalization to differentiate between object identifiers. Okay, sounds good.
However, they are different in some ways, most notably to me in the naming conventions. For example, using underscores in naming private properties, or camel casing vs Pascal casing for method names.
The C# advice tends to differ more between the others than ActionScript and JavaScript do with each other, which makes it more difficult for me since it is a greater number of languages vs a greater amount of code written. There is also the issue of automatic formatting in the IDE (e.g. the placement of opening braces in functions in JavaScript vs C#).
Any advice as to how you might have approached this problem? Any big pitfalls I'm not seeing? I realize I may be being pedantic, and that I'm lucky enough to work in an environment where I don't have to conform to someone else's standard. I hope to gain some increase in productivity and more readable code. Thanks.
Idioms that make sense in C# aren't necessarily going to make sense in Javascript (and vice-versa), despite the fact that both use pointy braces and semicolons.
We use different coding styles - for the most part, standard Microsoft style for C# and for the most part, standard jQuery style for Javascript. It can be a bit strange-looking (the disjoint of Pascal versus camel case means that you have some C# objects that have "improper" casing because they're pretty much just there as JSON containers), but I wouldn't try to shoehorn what are two discrete languages into a single grammar.
I would stick to the standards proposed by the communities or creators of the languages instead of trying to create one standard that crosses boundaries. Doing otherwise tends to torque off developers that are passionate about and active in the communities surrounding the language.
We tried to do that at one of my employers with Delphi and C#, and no one was happy.
I'm lucky enough to work in an environment where I don't have to conform to someone else's standard
Personally I don't follow the Microsoft standard for C#: instead, all my method names and property names use camelCase (though my types still use UpperCase). And, I decorate my member data (so that it can't be confused with local variables, properties, and/or parameters).
I don't see why it's necessary to follow Microsoft's naming conventions; IMO it's even occasionally a good thing not to: when I subclass a Microsoft type, the case (e.g. 'add') distinguishes my methods from Microsoft's methods (e.g. 'Add') in the underlying base class.
Also when I'm writing C++, I don't follow the same naming conventions as the standard library authors (who use lower_case for their types whereas I use UpperCase).
It is true however that other developers may/do not like it; for example, someone commented on some example C# code that I posted in some answer here on SO, to criticise it not for its content but for its naming convention.
This is a matter of preference really, because that's just what coding standards are: standards. There is no obvious right or wrong here, enforcing every language's community standards has a lot going for it until you are working in 5 different languages frequently which all have subtle differences. You will not be able to keep up and start following neither standard.
What I have done before is use the same standard for languages in the same ballpark (PHP, Java, Ruby), and then some specific ones if it was absolutely impractical to use that same set of standards, and the code looks different enough for your brain to also make the switch (for BASH scripts for instance).
But really it's what you (and the rest of your team) agrees upon. You don't gain productivity from a specific set of coding standards, you gain productivity by having the same standards as the people you work with. If you want to go full out hungarian camel case with an underscore on top: more power to you, just make sure the entire team does it ;)
For those of us that have programmed enough I’m sure we have come across many different flavours of coding standards that you can use when it comes to programming.
e.g. http://msdn.microsoft.com/en-us/library/ms229042.aspx
You might derive your coding standards for the current company you work for or from the original author of the code you’re working on. Coding styles are often used for specific program languages and some styles in one coding language might not be considered appropriate for others. Of course some coding standards can be applied across many different program languages.
Thank you for your time.
EDIT: As we know there are many related articles on this subject, but C# Coding standard / Best practices in SO has some very useful links in there which is worth a visit. (Check out the 2 links on .NET/C# guidelines by ESV - Accepted Answer)
Google has a posted style guide for C++ here which I consult sometimes. Just reading through the explanations and reasoning, despite whether you end up agreeing with some of the styles or not, may teach you some things you might not have thought about.
My best advice regarding coding standards: don't let them get in the way when trying to get work done.
A big bureaucracy might actually hinder progress in projects instead of helping to achieve better team work. When people complain about not following coding standards instead of the actual quality of the code, then it is too much regulation.
Other than that, pick one from the many suggestions and try to stick with it for as long as possible to build a code base following a single standard that you are used to.
Coding standards are good, but coding standards written from scratch in which the company reinvents the wheel, or coding standards imposed by a single "prophet", can be worse than having no coding standards at all.
This means:
Coding standards should be discussed and agreed upon.
The coding standards document should include the reasons behind each rule.
Coding standards should be at least partially based on reliable sources.
The sources I know of for the languages in your tags are:
For C++: The book C++ Coding Standards by Sutter/Alexandrescu.
For C#: 4 or 5 PDF's I found googling for C# Coding Standards :)
Adam Cogan has a great set of rules on his web site. There are coding guidelines, but there is much more there also.
Adam Cogan's Rules to Better...
Coding standards are great. We've been using Lance Hunt's C# Coding Standards for .NET almost without modifications
If you are maintaining code that continue to use the same standard as the original code was developed in (there is nothing worse then trying to debug a problem when the code looks all higgildy piggeldy)
Some comment to the post suggesting looking at the Google C++ guidelines. Detailed discussion about some aspects of these guidelines are posted at comp.lang.c++.moderated.
Some weird or controversial points include:
We don't believe that the available
alternatives to exceptions, such as
error codes and assertions, introduce
a significant burden.
As if assertions were a viable alternative... Assertions are usually for programming errors and situations that should never happen, while exceptions can happen (are somewhat anticipated) in the execution flow.
Reference Arguments: All parameters
passed by reference must be labeled
const. ... In fact it is a very strong
convention that input arguments are
values or const references while
output arguments are pointers.
No comment, about weasel phrase a very strong convention.
Doing Work in Constructors: Do only
trivial initialization in a
constructor. If at all possible, use
an Init() method for non-trivial
initialization. ... If your object
requires non-trivial initialization,
consider having an explicit Init()
method and/or adding a member flag
that indicates whether the object was
successfully initialized.
Yes... 2-phase init to make things simpler... What if I have const fields? This rule is probably the effect of attitude towards exceptions.
Use streams only for logging
Which streams? IOStreams, standard C streams, other?
On one hand they advise to use macros only in exceptional situations, while they recommend using DISALLOW_COPY_AND_ASSIGN to prohibit copy/assign. They could have advised the approach with special class (like in Boost)
Do not overload operators except in rare, special circumstances.
What about assignment, or arithmetic operators for numeric calculations, etc?
Default parameters are more difficult to maintain because copy-and-
paste from previous code may not reveal all the parameters. Copy-and-
pasting of code segments can cause major problems when the default
arguments are not appropriate for the new code.
The what? Copy/paste from previous code?
Remember that reading any of the guidelines can introduce a bias to your way of thinking. And sometimes it won't be beneficial for you or your code. I agree with some other posts advising reading good books by good authors beforehand. When you have sufficient amount of knowledge, then you are able to look at the guidelines and find good and weak points easily, without creating a mess in your brain ;)
If you plan to introduce a code-formatting standard to an existing programming team, get input from each member of the team so they'll have "buy in" and be more likely to write code to that standard.
Programming styles are as difficult to change as habits, and you'll have to accept that some people won't make their code 100% compliant 100% of the time. It would be worth your time to find (or write your own) pretty-printer program and periodically run all your code through it to enforce consistency. (I always felt uneasy when manually checking in source code changes that only consisted of formatting corrections for other peoples' code; I worried that others would label me a nitpicker.)
Sun Java Code Conventions
Python Style Guide
Zend Coding Standard for PHP
Having asked this question. I found that the accepted answer proved to be sufficient for my needs.
However, I realise that this is not a 'one-size-fits-all' scenario, so there is a large quantity of information within the thread that you may find more or less useful. Weel worth a read!
For Java and other C-family languages I recommend Sofware Monkey's coding standards (of course, since they're mine).
In general, keep them simple, and provide examples and justification for every requirement.
What's in the standard doesn't really matter all that much. What matters is that you have one, and that your developers follow it.
It doesn't quite answer the question, but it's worth a mention...
I read Steve McConnell's Code Complete. Whilst it doesn't give you a pre-baked set of coding standards it does set out a lot of good arguments for the various approaches. It'll make you think about things you'd not thought of before.
It changed my little world for the better.
Coding standards themselves are great and all, but what I think is much, much, MUCH more important is keeping with the style of whatever code you're maintaining. I've seen people add a function to some class written one way and forcing their coding standard on just that function. It's inconsistent, it sticks out, and, in my opinion, it makes it harder to enjoy the class "as a whole".
Whenever you're maintaining code, look at the code around it. See what the style is. K&R braces? Capital Camel Case methods? Hungarian? Double-line comment blocks between every function? Whatever it is, you should do it too in that specific area.
Before I leave, one thing I'd like to note that's related - naming files. I'm mainly a C++ guy, so this may not apply to whatever else, but basically it goes _.h or .cpp. So, Foo::Bar would be in Foo_Bar.h. Common things (i.e. a precompiled header) for the Foo namespace would be in Foo_common.h (note the lowercase common). Of course, that's a taste thing, but everybody who has worked with this has come out in favor of this.
i think Code Craft - The Practice of Writing Excellent Code pretty much sums it all up
Very popular are Ellemtel rules for C++.
For C# I recommend Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries (2nd Edition) (Microsoft .NET Development Series).
Mono Coding Guidelines
The answers here a pretty complete, thus I am not pointing to another coding standard document. However, once you decided to stick to one style you should use an automated coding style enforcer throughout your team.
For Java there is checkstyle and for .NET Microsoft Style Cop.
Here is a similar discussion on Stackoverflow: C# Coding standard / Best practices
Camel and pascal casing alone solves a lot of coding standard problems
I've been arguing with my coworkers about Pascal casing (upper camel case) vs. lower CamelCasing. They are used to lower camel casing for everything from table names in SQL databases to property naming in C# code but I like Pascal casing better, lower camel casing for variables and Pascal casing for properties:
string firstName;
public string FirstName {
...
}
But they are used to this:
string _firstname;
public string firstName {
...
}
I try to keep up with their "standard" so the code looks the same but I just don't like it.
I've seen that at least the .NET framework uses this convention and that is how I try to keep my code, e.g.:
System.Console.WriteLine("string")
What do you use/prefer and why? I'm sorry if somebody else asked this question but I searched and did not find anything.
Update:
I've given a method example and not a property but it's the same. As I stated in the first paragraph my colleagues use the Pascal convention for everything (variables, methods, table names, etc.)
A link to the official design guidelines might help. Specifically, read the section on Capitalization styles.
In the grand scheme of things, Pascal vs Camel doesn't matter that much and you're not likely to convince anyone to go back over an existing code base just to change the case of names. What's really important is that you want to be consistent within a given code base.
I'm just happy as long as you're not using Hungarian.
I use what the Framework uses, as it's the de-facto best practice. However, so long as the code in your company is consistently using their style, then you're much better off getting used to it. If every developer has their own standard, then there's no standard at all.
You should have a look at Microsoft's new tool, StyleCop for checking C# source code.
Also keep an eye on FxCop for checking compiled .Net assemblies. FxCop focuses more on the details of what the code does, not the layout, but it does have some naming rules related to publicly visible names.
StyleCop defines a coding standard, which is now being promoted by Microsoft as an industry standard. It checks C# source code against the standard.
StyleCop adheres to your PascalCase style.
Getting people onto StyleCop (or any other standard for that matter) can be hard, it's quite a hurdle, and StyleCop is quite exhaustive. But code should be to a uniform standard - and a personal standard is better than none, company standard is better than a personal one, and an industry standard is best of all.
It's a lot easier to convince people when a a project starts - team is being formed and there is no existing code to convert. And you can put tools (FxCop, StyleCop) in place to break the build if the code does not meet standards.
You should use the standard for the language and framework - SQL code should use SQL standards, and C# code should use C# standards.
For public interfaces you should stick with the MS .NET framework design
guidelines: "Capitalization Conventions".
For non-exposed members then whatever you and your colleagues can agree on.
I (and my team) prefer to reserve initial capitals for class names.
Why? Java standards propagating, I think.
I just found Coding Standards for .Net.
From
.NET Framework Developer's Guide
Capitalization Conventions, Case-Sensitivity:
The capitalization guidelines exist
solely to make identifiers easier to
read and recognize. Casing cannot be
used as a means of avoiding name
collisions between library elements.
Do not assume that all programming
languages are case-sensitive. They are
not. Names cannot differ by case
alone.
Pascal casing should be used for Properties. As far as varible names go, some people use _ and some poeple use m_ and some people just use plain old camel casing. I think that as long as you ae consistant here, it shouldn't matter.
I guess you have to put up with what the coding standard says for your place of work, however much you personally dislike it. Maybe one day in the future you will be able to dictate your own coding standards.
Personally I like databases to use names of the form "fish_name", "tank_id", etc for tables and fields, whereas the code equivalent of the database model would be "fishName" and "tankID". I also dislike "_fooname" naming when "fooName" is available. But I must repeat that this is subjective, and different people will have different ideas about what is good and bad due to their prior experience and education.
Actually, there's no "standard" convention on this. There's a Microsoft edited guideline somewhere, and as with with any other naming convention guideline, surely there's another one refuting it, but here's what I've come to understand as "standard C# casing convention".
PerWordCaps in type names (classes, enums), constants and properties.
camelCase for really long local variables and protected/private variables
No ALL_CAPS ever (well, only in compiler defines, but not in your code)
It seems some of the system classes use underscored names (_name) for private variables, but I guess that comes from the original writer's background as most of them came straight from C++. Also, notice that VB.NET isn't case sensitive, so you wouldn't be able to access the protected variables if you extended the class.
Actually, FxCop will enforce a few of those rules, but (AFAIK) it ignores whatever spelling you use for local variables.
I like the coding conventions laid out in the Aardvark'd project spec
That example of .NET you posted was a function. The adopted "standard" for methods/functions is A capped camel-case (or Pascal, if you want to call it that).
I stick to camel case where I can. It lets you easily know the difference between a variable and a method.
Additionally, I'm a fan of sticking an underscore in front of local class variables. E.g.: _localVar.
Whichever you prefer is what matters, obviously adhering to the team's standard primarily.
In private you code however you want, it doesn't affect the finished product whether you named your variable someVariable or SomeVariable.
The day when i quit programming - its when Microsoft will make CamelCase in C# as standard. Because my grown logic has many reasons for PascalCase, unlike kid's logic, who cares only shorter names or easier to write.
And BTW: CamelCasing comes primarily from C++ STD library style, the native old language inherited from C. So Java inherited from C++. But C# - is entirely new language - clean and beauty, with new rules. Oldfags must programm on Java or C++, new generation people must programm on C# - and they should never interact.
Consider this example:
1) PascalCase: list.Capacity.ToString();
2) CamelCase: list.capacity.toString();
In (1) we have CAMEL CASE in long TERM!!! means listCapacityToString.
In (2) we have bullshit: listcapacitytoString.
Thats how i read. And why CamelCase is illogical for itselt. I could kill for PascalCase, never touch it, kids of any age.
Microsoft - forever or until they use PascalCase.