Geeks With Blogs

News



Microsoft Store

Support This Site


AddThis Social Bookmark Button

Locations of visitors to this page

Subscribers to this feed

TwitterCounter for @sdorman

Creative Commons License


Scott Dorman Microsoft MVP, Software Architect, Developer, Author

Code style and standards has been a passion of mine for a long time. I've helped a lot of different companies create and adopt code standards. One of the main problems with documenting code standards is that once the document is created, no one ever goes back and adjusts them as new languages and technologies are introduced, new guidelines are implicitly put into place, or existing guidelines are dropped. I refer to this as the “staleness problem.” To help combat the staleness problem, a lot of companies opted to put their standards documents online, either publicly or behind corporate firewalls. Again, just as with paper documents, the staleness problem would still occur. To make matters worse, for those documents that were put online publicly, no mechanism was provided for the larger community to provide feedback.

Another problem that I see, particularly for polyglot programmers, is that there isn’t a centralized place to go to find standards for multiple programming languages. Sure, there are publicly available standards for a lot of languages, but they are all individual silos of information.

To address these problems (and several others), I created codestyle.co.

What’s different about codestyle.co is that all of the standards are maintained in the codestyle.co GitHub repository and the code examples are maintained as a GitHub gist. This means anyone who wants to contribute only needs to follow these three simple steps:

  1. Fork the repository or gist (or both).
  2. Make their changes.
  3. Submit a pull request.

Anytime a change is checked in to the repository, a continuous integration build is triggered which uploads the content to the website. This allows me to maintain the content separately from the website and also means that I don’t have to republish the entire site just to make content changes.

Since all of the content is maintained in GitHub, the GitHub issue tracker is also available. If you see a bug in the website itself (which isn’t open sourced), or if you want to contribute but aren’t comfortable forking repositories and submitting pull requests, simply open an issue.

I’m hoping that by making the standards documents available as open source, the community at large will help maintain them by fixing mistakes, keeping guidelines current, or even adding new languages. In fact, I’m counting on the community stepping up to help maintain the standards and make codestyle.co the best place on the web to find code standards for any language.

Right now, there are standards available for .NET, HTML, and CSS. A general purpose language-agnostic standard is also available. I’ll be adding more languages and more guidelines over time, but I think what’s there now is a good start.

Posted on Friday, July 25, 2014 12:30 PM | Back to top


Comments on this post: Announcing codestyle.co

# re: Announcing codestyle.co
Requesting Gravatar...
Your .NET coding style guidance appear to be almost word for word repeat of the advice in Framework Design Guidelines, written by the authors of Microsoft's .NET framework.

http://www.amazon.com/Framework-Design-Guidelines-Conventions-Libraries/dp/0321545613

The work, in summary, also appears on MSDN:

http://msdn.microsoft.com/en-us/library/vstudio/ms229042%28v=vs.100%29.aspx

I notice you have no attribution links anywhere. Where did your style advice come from?
Left by Billy Hoffman on Jul 28, 2014 1:59 PM

# re: Announcing codestyle.co
Requesting Gravatar...
Billy,

The .NET guidelines do have an attribution link, right under the title of the page where it says "Adapted from the Framework Design Guidelines", which takes you to http://msdn.microsoft.com/en-us/library/ms229042(v=vs.110).aspx if you click on it.

The guidelines are not word-for-word repeats as I did try to paraphrase and summarize what the FDG states.
Left by Scott on Jul 28, 2014 5:07 PM

# re: Announcing codestyle.co
Requesting Gravatar...
I hope this takes off. We totally share your passion for standards and have a open source project called SolutionValidator (https://github.com/Orcomp/SolutionValidator), which helps team follow the same standards.
It has an MIT license, and everyone is welcome to contribute.
Left by Ben on Jul 28, 2014 11:03 PM

# re: Announcing codestyle.co
Requesting Gravatar...
Great job.
Any way to get those guidelines produce compile time warnings in .net?
Maybe using ReSharper or something?
I mean, if you can provide those definitions/templates as well on your site, that would be amazing.

Nice website too btw.
Left by Quintonn on Jul 30, 2014 3:47 AM

# re: Announcing codestyle.co
Requesting Gravatar...
You go on a dangerous path by suggesting how code should be indented.
Left by Stijn on Jul 30, 2014 4:23 AM

# re: Announcing codestyle.co
Requesting Gravatar...
Feedback and issue tracking would be awesome. For instance in the .NET section you don't mention that flag enumeration names should end with an 's', while normal enumerations should be singular. I'd love to see contributions there, and a more lively discussion.
Left by Florian on Jul 30, 2014 5:19 AM

# re: Announcing codestyle.co
Requesting Gravatar...
You don't suggest casing for constants in .net. They may not be good practice but they still have a place. I've always seen them done in full uppercase style.
Left by Kevin on Jul 30, 2014 9:24 AM

# re: Announcing codestyle.co
Requesting Gravatar...
Very nice, but it would be very good, if it was also supported by the IDE, to issue warning if there is no compliance, as stated by Quintonn.
Left by San kan on Jul 30, 2014 9:42 AM

# re: Announcing codestyle.co
Requesting Gravatar...
Quintonn and San kan, for the .NET guidelines you can enable FxCop (Code Analysis) and install StyleCop (http://stylecop.codeplex.com/) to get compile time checking.

Florian, you can use the issue tracking that is part of the GitHub repository.

Kevin, these guidelines are (and probably always will be) a "work in progress". There are a lot of additional guidelines (especially for .NET) that will be added in the next few weeks.

Stijn, I don't see this as a "dangerous path" at all. These are not "set in stone" rules that must be followed but guidelines/suggestions on how to structure and format your code. There is also nothing that says you have to adopt any of these guidelines or that you have to adopt all of them. You're free to choose the ones that best suit and/or change them for your needs.
Left by Scott on Jul 30, 2014 9:59 AM

# re: Announcing codestyle.co
Requesting Gravatar...
Florian, There is a guideline for enum naming:

◾Enumerations (also called enums) should follow all of the same naming rules as classes and structs, but should always be singular unless the values are bit fields (also called a flags enum), in which case the name should be pluaral.
Left by Scott on Jul 30, 2014 10:02 AM

# re: Announcing codestyle.co
Requesting Gravatar...
I mean that there's a difference between guidelines that are accepted by the majority of a community, and an indentation style guideline. The latter has been debated about for longer than I've been alive, and it isn't going to end anytime soon.

Perhaps a better guideline would be to pick something and stick with it, the important thing is that you're consistent about it throughout a code base.
Left by Stijn on Jul 31, 2014 7:30 AM

Your comment:
 (will show your gravatar)
 


Copyright © Scott Dorman | Powered by: GeeksWithBlogs.net | Join free