Should using directives be inside or outside the namespace

Question

I have been running StyleCop over some C  code  and it keeps reporting that my using directives should be inside the namespace   Is there a technical reason for putting the using directives inside instead of outside the namespace

User · Answer

When citing Microsoft s internal guidelines  keep in mind that they re written by somebody who probably has less than ten years experience coding   In other words  they re likely based on nothing more solid than personal preference   Especially in something like C  that s so new  As a rule  external using directives  System and Microsoft namespaces for example  should be placed outside the namespace directive   They are defaults that should be applied in all cases unless otherwise specified   This should include any of your own organization s internal libraries that are not part of the current project  or using directives that reference other primary namespaces in the same project   Any using directives that reference other modules in the current project and namespace should be placed inside the namespace directive   This serves two specific functions   It provides a visual distinction between local modules and  other  modules  meaning everything else  It scopes the local directives to be applied preferentially over global directives   The latter reason is significant   It means that it s harder to introduce an ambiguous reference issue that can be introduced by a change no more significant than refactoring code   That is to say  you move a method from one file to another and suddenly a bug shows up that wasn t there before   Colloquially  a  heisenbug  - historically fiendishly difficult to track down  As an even more general rule  a good one to follow is this   If you see something intrinsic to a language that seems to be a useless option  assume that it s NOT   In fact  the harder it is to see why the option exists  the more important you should assume it is   Do the research about the specific differences between the two options and then think long and hard about the implications   You ll usually find an amazingly insightful and clever solution to an obscure problem that the language designer put in there specifically to make your life easier   Be appropriately grateful and take advantage of it

User · Answer

Another subtlety that I don t believe has been covered by the other answers is for when you have a class and namespace with the same name   When you have the import inside the namespace then it will find the class  If the import is outside the namespace then the import will be ignored and the class and namespace have to be fully qualified     file1 cs namespace Foo       class Foo                  file2 cs namespace ConsoleApp3       using Foo      class Program               static void Main string   args                          This will allow you to use the class             Foo test   new Foo                         file2 cs using Foo    Unused and redundant     namespace Bar       class Bar               Bar                         Foo Foo test   new Foo Foo                Foo test   new Foo      will give you an error that a namespace is being used like a class

User · Answer

Putting it inside the namespaces makes the declarations local to that namespace for the file  in case you have multiple namespaces in the file  but if you only have one namespace per file then it doesn t make much of a difference whether they go outside or inside the namespace   using ThisNamespace IsImported InAllNamespaces Here   namespace Namespace1       using ThisNamespace IsImported InNamespace1 AndNamespace2      namespace Namespace2             using ThisNamespace IsImported InJustNamespace2                 namespace Namespace3       using ThisNamespace IsImported InJustNamespace3

User · Answer

It is a better practice if those default using i e   references  used in your source solution should be outside the namespaces and those that are  new added reference  is a good practice is you should put it inside the namespace  This is to distinguish what references are being added

User · Answer

There is actually a  subtle  difference between the two  Imagine you have the following code in File1 cs      File1 cs using System  namespace Outer Inner       class Foo               static void Bar                         double d   Math PI                      Now imagine that someone adds another file  File2 cs  to the project that looks like this      File2 cs namespace Outer       class Math                 The compiler searches Outer before looking at those using directives outside the namespace  so it finds Outer Math instead of System Math  Unfortunately  or perhaps fortunately    Outer Math has no PI member  so File1 is now broken   This changes if you put the using inside your namespace declaration  as follows      File1b cs namespace Outer Inner       using System      class Foo               static void Bar                         double d   Math PI                      Now the compiler searches System before searching Outer  finds System Math  and all is well   Some would argue that Math might be a bad name for a user-defined class  since there s already one in System  the point here is just that there is a difference  and it affects the maintainability of your code   It s also interesting to note what happens if Foo is in namespace Outer  rather than Outer Inner  In that case  adding Outer Math in File2 breaks File1 regardless of where the using goes  This implies that the compiler searches the innermost enclosing namespace before it looks at any using directive

User · Answer

One wrinkle I ran into  that isn t covered in other answers    Suppose you have these namespaces    Something Other Parent Something Other   When you use using Something Other outside of a namespace Parent  it refers to the first one  Something Other    However if you use it inside of that namespace declaration  it refers to the second one  Parent Something Other    There is a simple solution  add the  global    prefix  docs  namespace Parent      using global  Something Other        etc

User · Answer

As Jeppe Stig Nielsen said  this thread already has great answers  but I thought this rather obvious subtlety was worth mentioning too   using directives specified inside namespaces can make for shorter code since they don t need to be fully qualified as when they re specified on the outside   The following example works because the types Foo and Bar are both in the same global namespace  Outer   Presume the code file Foo cs   namespace Outer Inner       class Foo         And Bar cs   namespace Outer       using Outer Inner       class Bar               public Foo foo            That may omit the outer namespace in the using directive  for short   namespace Outer       using Inner       class Bar               public Foo foo

User · Answer

According to Hanselman - Using Directive and Assembly Loading    and other such articles there is technically no difference   My preference is to put them outside of namespaces

User · Answer

According the to StyleCop Documentation   SA1200  UsingDirectivesMustBePlacedWithinNamespace   Cause  A C  using directive is placed outside of a namespace element   Rule Description  A violation of this rule occurs when a using directive or a using-alias directive is placed outside of a namespace element  unless the file does not contain any namespace elements   For example  the following code would result in two violations of this rule   using System  using Guid   System Guid   namespace Microsoft Sample       public class Program                 The following code  however  would not result in any violations of this rule   namespace Microsoft Sample       using System      using Guid   System Guid       public class Program                 This code will compile cleanly  without any compiler errors  However  it is unclear which version of the Guid type is being allocated  If the using directive is moved inside of the namespace  as shown below  a compiler error will occur   namespace Microsoft Sample       using Guid   System Guid      public class Guid               public Guid string s                                 public class Program               public static void Main string   args                        Guid g   new Guid  hello                        The code fails on the following compiler error  found on the line containing Guid g   new Guid  hello      CS0576  Namespace  Microsoft Sample  contains a definition conflicting with alias  Guid   The code creates an alias to the System Guid type called Guid  and also creates its own type called Guid with a matching constructor interface  Later  the code creates an instance of the type Guid  To create this instance  the compiler must choose between the two different definitions of Guid  When the using-alias directive is placed outside of the namespace element  the compiler will choose the local definition of Guid defined within the local namespace  and completely ignore the using-alias directive defined outside of the namespace  This  unfortunately  is not obvious when reading the code   When the using-alias directive is positioned within the namespace  however  the compiler has to choose between two different  conflicting Guid types both defined within the same namespace  Both of these types provide a matching constructor  The compiler is unable to make a decision  so it flags the compiler error   Placing the using-alias directive outside of the namespace is a bad practice because it can lead to confusion in situations such as this  where it is not obvious which version of the type is actually being used  This can potentially lead to a bug which might be difficult to diagnose   Placing using-alias directives within the namespace element eliminates this as a source of bugs     Multiple Namespaces   Placing multiple namespace elements within a single file is generally a bad idea  but if and when this is done  it is a good idea to place all using directives within each of the namespace elements  rather than globally at the top of the file  This will scope the namespaces tightly  and will also help to avoid the kind of behavior described above   It is important to note that when code has been written with using directives placed outside of the namespace  care should be taken when moving these directives within the namespace  to ensure that this is not changing the semantics of the code  As explained above  placing using-alias directives within the namespace element allows the compiler to choose between conflicting types in ways that will not happen when the directives are placed outside of the namespace   How to Fix Violations To fix a violation of this rule  move all using directives and using-alias directives within the namespace element

User · Answer

There is an issue with placing using statements inside the namespace when you wish to use aliases  The alias doesn t benefit from the earlier using statements and has to be fully qualified   Consider   namespace MyNamespace       using System      using MyAlias   System DateTime       class MyClass                 versus   using System   namespace MyNamespace       using MyAlias   DateTime       class MyClass                 This can be particularly pronounced if you have a long-winded alias such as the following  which is how I found the problem    using MyAlias   Tuple lt Expression lt Func lt DateTime  object gt  gt   Expression lt Func lt TimeSpan  object gt  gt  gt     With using statements inside the namespace  it suddenly becomes   using MyAlias   System Tuple lt System Linq Expressions Expression lt System Func lt System DateTime  object gt  gt   System Linq Expressions Expression lt System Func lt System TimeSpan  object gt  gt  gt     Not pretty

User · Answer

The technical reasons are discussed in the answers and I think that it comes to the personal preferences in the end since the difference is not that big and there are tradeoffs for both of them  Visual Studio s default template for creating  cs files use using directives outside of namespaces e g   One can adjust stylecop to check using directives outside of namespaces through adding stylecop json file in the root of the project file with the following         schema    https   raw githubusercontent com DotNetAnalyzers StyleCopAnalyzers master StyleCop Analyzers StyleCop Analyzers Settings stylecop schema json        orderingRules            usingDirectivesPlacement    outsideNamespace                You can create this config file in solution level and add it to your projects as  Existing Link File  to share the config across all of your projects too

User · Answer

This thread already has some great answers  but I feel I can bring a little more detail with this additional answer   First  remember that a namespace declaration with periods  like   namespace MyCorp TheProduct SomeModule Utilities               is entirely equivalent to   namespace MyCorp       namespace TheProduct               namespace SomeModule                       namespace Utilities                                                                     If you wanted to  you could put using directives on all of these levels   Of course  we want to have usings in only one place  but it would be legal according to the language    The rule for resolving which type is implied  can be loosely stated like this  First search the inner-most  scope  for a match  if nothing is found there go out one level to the next scope and search there  and so on  until a match is found  If at some level more than one match is found  if one of the types are from the current assembly  pick that one and issue a compiler warning  Otherwise  give up  compile-time error    Now  let s be explicit about what this means in a concrete example with the two major conventions    1  With usings outside   using System  using System Collections Generic  using System Linq    using MyCorp TheProduct    lt -- uncommenting this would change nothing using MyCorp TheProduct OtherModule  using MyCorp TheProduct OtherModule Integration  using ThirdParty   namespace MyCorp TheProduct SomeModule Utilities       class C               Ambiguous a            In the above case  to find out what type Ambiguous is  the search goes in this order    Nested types inside C  including inherited nested types  Types in the current namespace MyCorp TheProduct SomeModule Utilities Types in namespace MyCorp TheProduct SomeModule Types in MyCorp TheProduct Types in MyCorp Types in the null namespace  the global namespace  Types in System  System Collections Generic  System Linq  MyCorp TheProduct OtherModule  MyCorp TheProduct OtherModule Integration  and ThirdParty   The other convention    2  With usings inside   namespace MyCorp TheProduct SomeModule Utilities       using System      using System Collections Generic      using System Linq      using MyCorp TheProduct                               MyCorp can be left out  this using is NOT redundant     using MyCorp TheProduct OtherModule                   MyCorp TheProduct can be left out     using MyCorp TheProduct OtherModule Integration       MyCorp TheProduct can be left out     using ThirdParty       class C               Ambiguous a            Now  search for the type Ambiguous goes in this order    Nested types inside C  including inherited nested types  Types in the current namespace MyCorp TheProduct SomeModule Utilities Types in System  System Collections Generic  System Linq  MyCorp TheProduct  MyCorp TheProduct OtherModule  MyCorp TheProduct OtherModule Integration  and ThirdParty Types in namespace MyCorp TheProduct SomeModule Types in MyCorp Types in the null namespace  the global namespace     Note that MyCorp TheProduct was a part of  3   and was therefore not needed between  4   and  5      Concluding remarks  No matter if you put the usings inside or outside the namespace declaration  there s always the possibility that someone later adds a new type with identical name to one of the namespaces which have higher priority   Also  if a nested namespace has the same name as a type  it can cause problems   It is always dangerous to move the usings from one location to another because the search hierarchy changes  and another type may be found  Therefore  choose one convention and stick to it  so that you won t have to ever move usings   Visual Studio s templates  by default  put the usings outside of the namespace  for example if you make VS generate a new class in a new file    One  tiny  advantage of having usings outside is that you can then utilize the using directives for a global attribute  for example  assembly  ComVisible false   instead of  assembly  System Runtime InteropServices ComVisible false

[c#] Should 'using' directives be inside or outside the namespace?

Examples related to c#

Examples related to .net

Examples related to namespaces

Examples related to stylecop

Examples related to code-organization