Header File Template

Question

Is there a standard template to use for .NET source code files?

I am accustom to putting my header information between /* */ tags, but StyleCop is complaining about those.

Answer 1

Just a thought and by no means a standard (or for that matter, possibly a good idea). Have you thought about maybe using attributes? E.g.

[Author("Jonathan Dickinson")]
[Copyright("Copyright (c) Jonathan Dickinson 2009")]
[RevisionHistory(
        "jcd: Made the class.",
        "jcd: Made the class internal.")]
[License("GPL", LicenseType = LicenseType.CopyLeft)]
// Etc.
class Foo
{
}

Anyone have any ideas why this would be a terrible practice?

In any case - StyleCop was made primarily for commercial projects (who typically don't do code headers). In other words - ignore or disable the friggen warning. Time and time I have read that StyleCop and FXCop are too nit-picky. I have seen header comments in the following format.

// <code-header>
//  <author>Jonathan Dickinson</author>
//  <copyright>Copyright (c) Jonathan Dickinson 2009</copyright>
//  <license href="license.txt">New BSD</license>
//  <revisions>
//    <revision initials="jcd">Made the file and class</revision>
//    <revision intiails="jcd">Made the class internal</revision>
//  </revisions>
// </code-header>

It has obvious advantages - statistics (like Ohloh does) and verification of a code-base come to mind straight away.

Answer 2

Never put revision history in the source file, that's what your source control system is for.

as for headers I would suggest that #region is a good idea (since it is boiler plate that should be removed from your concern unless you are editing it at which point it doesn't matter if it is // or /*.

Since // is more robust (no nesting issues) // is preferred