Permalink
0878d9b Jun 22, 2017
@sharwell @vweijsters
102 lines (76 sloc) 3.24 KB

SA1633

TypeName SA1633FileMustHaveHeader
CheckId SA1633
Category Documentation Rules

Cause

A C# code file is missing a standard file header.

Rule description

A violation of this rule occurs when a C# source file is missing a file header.

The file header should begin at the start of the file, and it may only be preceded by whitespace.

The file header should be formatted as a block of comments containing either Xml or preconfigured text, as follows:

//-----------------------------------------------------------------------
// <copyright file="NameOfFile.cs" company="CompanyName">
//     Company copyright tag.
// </copyright>
//-----------------------------------------------------------------------

or

// Copyright (c) Tunnel Vision Laboratories, LLC. All Rights Reserved.
// Licensed under the Apache License, Version 2.0. See LICENSE in the project root for license information.

The type of header to use depends on the setting of the xmlHeader property. See the configuration section for details on how to set this up.

Examples

For example, a file called Widget.cs from a fictional company called Sprocket Enterprises should contain a file header similar to the following:

//-----------------------------------------------------------------------
// <copyright file="Widget.cs" company="Sprocket Enterprises">
//     Copyright (c) Sprocket Enterprises. All rights reserved.
// </copyright>
//-----------------------------------------------------------------------

The dashed lines at the top and bottom of the header are not strictly necessary, so the header could be written as:

// <copyright file="Widget.cs" company="Sprocket Enterprises">
//     Copyright (c) Sprocket Enterprises. All rights reserved.
// </copyright>

It is possible to add additional tags, although they will not be checked or enforced by StyleCop:

//-----------------------------------------------------------------------
// <copyright file="Widget.cs" company="Sprocket Enterprises">
//     Copyright (c) Sprocket Enterprises. All rights reserved.
// </copyright>
// <author>John Doe</author>
//-----------------------------------------------------------------------

A file that is completely auto-generated by a tool, and which should not be checked or enforced by StyleCop, can include an "auto-generated" header rather than the standard file header. This will cause StyleCop to ignore the file. This type of header should never be placed on top of a manually written code file.

// <auto-generated />
namespace Sample.Something
{
    // The contents of this file are completely auto-generated by a tool.
}

How to fix violations

To fix a violation of this rule, add a standard file header at the top of the file.

How to suppress violations

[SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1633:FileMustHaveHeader", Justification = "Reviewed.")]
#pragma warning disable SA1633 // FileMustHaveHeader
#pragma warning restore SA1633 // FileMustHaveHeader