Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Myself and another developer with the go ahead from our IT director have started a general purpose library in .NET with the intention that it will provide many common purpose classes that we use in our day to day development.

During discussions and design of the library we have come up with a set of standards that we want the library to follow to ensure it is maintained and expanded on in a consistent manner.

What is the best way to ensure these decisions we made for the library get feed to the other developers who might be using and adding to this library in the future. One of our decisions was to ensure we review all checked in code so we expect initially there to be some differences in coding styles of individuals not fitting in with the project standards.

Some ideas I had were:

  1. Add a Read-me.txt to the project that outline the guidelines and standards
  2. Send an email out to everyone in the team to let them know about the project etc
  3. Call a team meeting to go through this new project and our expectations and standards we were aiming to follow
  4. Try and enforce the standards via Visual Studio (not sure if this would be possible or how just an idea)

At the moment there is no general company programming standards so this would be a first really insofar as we are creating a standard that different project teams would need to adhere to.

share|improve this question
    
Does your company staff a technical writer? –  O.O Feb 14 '12 at 22:55
1  
I hope those "common-purpose" classes already exist, and you are just gathering them into this library. Attempting to write "common-purpose" classes in anticipation of a future need is almost invariably futile. –  kevin cline Feb 14 '12 at 22:56
    
Yes they exist. It's just a way to pull together the various resources help with sharing code that would be beneficial across teams and projects. –  dreza Feb 14 '12 at 23:12
    
@subt13 No we don't. Our code is our technical writing I guess –  dreza Feb 14 '12 at 23:12
1  
@dreza - self-documenting code only goes so far. You need well-written documentation if you expect your fellow developers to adhere to standards. –  O.O Feb 14 '12 at 23:14
show 1 more comment

3 Answers

up vote 4 down vote accepted

Use FxCop and StyleCop to analyze and enforce rules that describe the coding standard you expect for your library. You could also write up a document that explains your coding standard, but using code analysis is the best way to actual enforce them.

Edit:

See this question for more information about the code analysis available in certain versions of Visual Studio.

share|improve this answer
    
Thanks. These look like what I would want. Would all developers have to install this onto their pc's to ensure this is checked against. Would it be possible to have different style configurations against different projects. –  dreza Feb 14 '12 at 20:43
    
You can either have each developer install these tools on their machines or you can integrate these tools into a continuous integration server and publish the results there, which I definitely recommend. You can definitely configure the tools to use specific rules for specific projects. One way is to specify the set of rules to use in settings files. –  Bernard Feb 14 '12 at 20:47
    
Accepted this as other answers were good but this gave me links for the suggested tools. Am using looking at documenting as well to complement as suggested by subt13 and gbjbaanb –  dreza Feb 15 '12 at 19:59
add comment

Generally best to enforce standards using tools like FXCop/Visual Studio static analyser and StyleCop.

StyleCop is an open source static code analysis tool from Microsoft that checks C# code for conformance to StyleCop's recommended coding styles and a subset of Microsoft's .NET Framework Design Guidelines. StyleCop analyzes the source code, allowing it to enforce a different set of rules from FxCop (which, instead of source code, checks .NET managed code assemblies). The rules are classified into the following categories:

  • Documentation
  • Layout
  • Maintainability
  • Naming
  • Ordering
  • Readability
  • Spacing

StyleCop includes both GUI and command line versions of the tool. It is possible to create new rules to be used.

StyleCop was re-released as an open source project in April 2010...

share|improve this answer
2  
... because they can be enforced at build time through project build tasks, and the project rules and global exceptions can be easily managed through version control tools. –  JustinC Feb 14 '12 at 20:35
2  
@JustinC, yeap and in my experience documents are open to interpretation or people simply disregard them altogether. –  RichardOD Feb 14 '12 at 20:40
    
FYI: StyleCop is now an open source project hosted on CodePlex and can be found here. –  Bernard Feb 14 '12 at 20:41
    
@RichardOD - Enforcing standards, yes, learning the standards, no. I can just envision a new developer wading through compilation errors, and then doing the old build, error, build, error cycle until all the errors are gone. Probably not the best way for a new developer to learn. –  O.O Feb 14 '12 at 23:31
add comment

Internal style of the code is a secondary thing IMHO - its much more important to have a consistent set of documentation teaching the user of the library what's available and how to use it.

From that you need to start as you mean to go on, write this documentation with the correct format and depth, then expect all contributions to provide a similar level of documentation. This is difficult to enforce automatically, but you could prevent checkins unless the doc source files are present, and then decide whether it is acceptable in a 'code' review phase. Only those additions that pass are then incorporated into the trunk (assuming everyone adds their contributions to a branch).

Too many developers think that the code is all that matters. It isn't, and for a library its probably the least part of the whole. Get the documentation, with examples of use, descriptions of calls and parameters and you'll get better adoption and it'll save a lot of time for the users of your library. (yes, and its boring to do it, but too bad - do it properly)

share|improve this answer
    
Yes I agree that code is not the be all and end all. I'm hoping that the good documentation on the classes themselves will help with the useability of the library. +1 though for examples of use hadn't thought of that. I guess unit tests for each class could go a way to creating these examples. –  dreza Feb 15 '12 at 0:04
    
Need to think about the consumers of the library. Documentation is going to prevent them from reinventing the wheel. –  JeffO Feb 15 '12 at 16:34
    
@dreza: I think you're slightly missing my point, auto-generated doc is not good enough. You can dump out sandcastle or dozygen 'docs' but they're no better than just looking at the source code. You need something more like a wiki with examples of use and a 'knowledge base' of hints, use-cases, or design intentions for the classes. Don't try to do your doc 'on the cheap'. Try Asciidoc and use that to generate proper human-written documentation. –  gbjbaanb Feb 16 '12 at 23:10
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.