On coding standards

Clearing out old drafts… 

Yes, a team needs to agree on a coding standard and consistently follow that standard. That being said, I think the coding standard should be kept as simple as possible and only grow as needed. I think elaborate coding standards that are hard to remember or require developers to go out of their way to follow it do more harm than good.  A couple years ago I watched a client organization spend a tremendous amount of energy enforcing an elaborate coding standard in coding reviews and completely neglect the (poor) structure of their design.  There's a point of diminishing returns on coding standards and it comes up fast.  Learn to like the default "{}" placement in VS.Net or a simple configuration of ReSharper and live with it.

There's tons of coding standards on the web that you can download and use built by acclaimed .Net experts.  I'd bypass all of them.  A team is much more likely to follow a standard that they've built themselves.  Let the coding standard grow organically as you encounter new needs.  There's absolutely no need to spend a week defining a 200+ point standard upfront because nobody will be able to follow it anyway.

And the silliest coding standard I've ever seen was the initial C# coding standard at a past employer that was made before anybody had written a single line of C# code.  Here's the highlights as I recall:

  • Always use abstract classes instead of interfaces because you can reuse functionality in the abstract classes.  There are reasons why the language includes both constructs.
  • Every method should have a comment block listing the history of changes to that method.  Source control anybody? 

In the words of Forrest Gump, "that's all I've got to say about that."

About Jeremy Miller

Jeremy is the Chief Software Architect at Dovetail Software, the coolest ISV in Austin. Jeremy began his IT career writing "Shadow IT" applications to automate his engineering documentation, then wandered into software development because it looked like more fun. Jeremy is the author of the open source StructureMap tool for Dependency Injection with .Net, StoryTeller for supercharged acceptance testing in .Net, and one of the principal developers behind FubuMVC. Jeremy's thoughts on all things software can be found at The Shade Tree Developer at http://codebetter.com/jeremymiller.
This entry was posted in Uncategorized. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • http://codebetter.com/blogs/jeremy.miller jmiller

    What’s wrong with “On Error Resume Next”? It was the magical elixir that you sprinkled all over your code to make it “work!”

  • karl

    I totally agree…but….

    Just because a language includes something, doesn’t mean it should be used.

    On Error Resume Next
    Option Explicit Off
    Option Strict Off

    ok..so they are all vb.net (which I really do like).

  • Marcos

    Jeremy, thanks a lot for the reply. I’m taking notes of your advices. I agree that naming standard is not so difficult, and now I’m thinking (loud) about having another doc with coding advice with their proper explanation.

    BTW, I don’t like the spaces in someClass.SomeCall( 1, “name”, true ); :P, I usually do the Ctrl + K,D thing in Visual Studio. It’s like a tick :)

    Thanks again.

  • http://codebetter.com/blogs/jeremy.miller jmiller

    Marcos,

    I think in your shoes I would be looking for a very tiny core standard that is shared across projects, but let the teams own the extensions and specifics. How you name private fields, public properties, and private vs. public methods are easy to standardize. Other naming standards are going to vary by toolsets being used or the patterns employed by the project. I’d still rather the developers in the front line being responsible for their own standards. Time and time again I’ve observed that by giving more specific advice or guidance you generally end up shutting down the mind of whoever’s on the receiving end.

    It sounds like you’re also giving out design and coding advice beyond simple naming convention. If you’re going to do that, my very, very strong advice is to write up the “why” and even “why not” as well.

    “build a new standard with a team of architects from different projects and needs that should be shared across the different projects”

    — Danger Will Robinson! I’d be cautious about doing that with a room full of architect types outside the context of a specific codebase. Architects divorced from code can easily adopt something unnecessarily complicated that looks good on paper and turns out to be a total pain in the ass in real usage. And I’m speaking both from the vantage point of a former “central” architect and the guy who used to fight with the central architects. Sharing ideas is good, premature standardization may be bad.

    As far as leaning on a tool for some of the formatting & standards, I’m really thinking small like having ReSharper know that class fields are prefixed with “_” and lowercase while public getters & setters are capitalized. Specifically, I really hate to see human being time being wasted on turning this:

    someClass.SomeCall(1,”name”,true);

    into (note the extra spaces):

    someClass.SomeCall( 1, “name”, true );

    P.S. I was thinking about the IDesign coding standards as a matter of fact;)

  • http://www.geekswithblogs.net/marcost Marcos

    Jeremy, your post came in a great moment. We (at work) are starting to work in a new version of our C# coding standard. Right now, I’m trying to realize, in which “shoulders we should stand up”. I’ve read “Framework Design Guidelines”, and I see it as the Microsoft standard, but also, I’ve read the IDesign C# Coding Standard (I think you mention it indirectly ;)). I like the content of the first, but I like the presentation of the second one for example.
    What we need right now it’s standard in order to give us consistency and best practices. Since our company hires a lot of new programmers (I mean, students in their first time position as programmers), I would like to have a standard that gives to our fellow programmers a “guide” to rely on, or to take doubts away, something like foundations for their careers (well, OK, maybe I’m too ambitious).
    I’m 100% agree with you that a standard should group up when is need it, but I’m not agree that you should depend on a tool in order to help you how you should write code.
    Well, here is the dilemma, write a new standard from scratch (and possibly build the wheel again) for each team in each project, or build a new standard with a team of architects from different projects and needs that should be shared across the different projects?? What would you do Jeremy?
    Thanks a lot in advance!

  • http://weblogs.asp.net/bsimser Bil Simser

    It’s a place full of VB6 data guys which is saying a lot I guess. At least I think I’ve made some roadways with them and it’s what keeps me challenged every day.

    I’ve managed to get them onto a project using Scrum, managed to get them using Scrum on a new project, convinced them that writing a data access layer is the stupidest thing in the world (generate it or use ORMs, anything), showed them what unit testing is about and the benefits, started them down the path of TDD and continuous integration, and dipped their feet in DDD and trying to get them to think about objects first, UI and data later when they need it. It’s been a long road and there’s much more to do, but I feel good with the successes we’ve had. Just have to keep at them with the comment thing (I did manage to convince them to remove the names in comments as I thought that was all blame game and had little value).

    Thanks.

  • http://codebetter.com/blogs/jeremy.miller jmiller

    I don’t know Bil, I just really don’t think it’s that hard to see code changes in SVN. You could even just archive the check in emails.

    Do you have Fisheye or something similar? Heck, even the SVN Repository Browser in TortoiseSVN alone fits my needs.

    By chance, is there some COBOL guys in here somewhere? That attitude seems to go hand in hand with people that favor large blocks of code and do big check ins. The shop I was describing was extremely sloppy with their source control management.

  • http://weblogs.asp.net/bsimser Bil Simser

    Completely agree with you. However I’m fighting a group right now that lives and dies by the “history in comment header” standard. I think it’s silly and just defer to source control and the comment when the code was checked in. The argument is that they want to see what’s changed in the code so they don’t have to resort to looking it up in source control and what if the developer didn’t enter a comment when he checked code in? Any ideas as to how to argue this as I’m running into dead ends with the “source control anyone” statement.