Update file and define conventions

1 files changed, 24 insertions, 17 deletions

diff --git a/Documentation/coding-guidelines/project-guidelines.md b/Documentation/coding-guidelines/project-guidelines.md
index 96c4507621..f18c501d42 100644
--- a/Documentation/coding-guidelines/project-guidelines.md
+++ b/Documentation/coding-guidelines/project-guidelines.md
@@ -97,20 +97,27 @@ Facade projects are unique in that they don't have any code and instead are gene
 
 TODO: Fill in more information about the required properties for creatng a facade project.
 
-##Defines for code #ifdefs
-Configuration base defines should match the name of the configurtion that is needs the fork in code. So either $(Platform), $(OSGroup), $(ConfigurationGroup), $(TargetGroup). These should only be used as a last resort and we should prefer using partial classes or configuration specific cs files for any necessary forking (see [File naming convention](file-naming-convention)).
-
-Feature based defines should be named like `FEATURE_[FeatureName]`. These can unique to a given library project or potentially shared (via name) across multiple projects.
-
-
-##File naming convention
-
-`<class name>.<group>.cs`
-
-Where `<group>` is:
-- Windows/Linux/Unix/Osx - For files specific to a given OS
-- WinRT - For files that are have unique WinRT dependencies
-- Target Runtime
- - NetFx - Files specific for the full .NET Framework/CLR runtime
- - CoreCLR - Files specific to the CoreCLR runtime
- - NETNative - Files specific to the .NET Native runtime (MRT) or toolchain.
+# Conventions for forked code
+While our goal is to have the exact code for every configuration there is always reasons why that is not realistic so we need to have a set of conventions for dealing with places were we fork code. In order of preference, here are the strategies we employ:
+
+1. Using different code files with partial classes to implement individual methods different on different configurations
+2. Using entirely different code files for cases were the entire class (or perhaps static class) needs to be unique in a given configuration.
+3. Using `#ifdef`'s directly in a shared code file.
+
+In general we perfer different code files over `#ifdef`'s because it forces us to better factor the code which leads to easier maintenance over time. 
+
+## Code file naming conventions
+Each source file should use the following guidelines
+- The source code file should contain only one class. The only exception is small supporting structs, enums, nested classes, or delegates that only apply to the class can also be contained in the source file. 
+- The source code file should be named `<class>.cs` and should be placed in a directory structure that matches its namespace relative to its project directory. Ex. `System\IO\Stream.cs` 
+- Larger nested classes should be factored out into their own source files using a partial class and the file name should be `<class>.<nested class>.cs`.
+- Classes that are forked based on configuration should have file names `<class>.<configuration>.cs`. 
+ - Where `<configuration>` is one of `$(OSGroup)`, `$(TargetGroup)`, `$(ConfigurationGroup)`, or `$(Platform)`.
+- Classes that are forked based on a feature set should have file names `<class>.<feature>.cs`.
+ - Where `<feature>`is the name something that causes a fork in code that isn't a configuration such as WinRT support. Ex. `FileSystemInfo..WinRT.cs`.
+ 
+## Define naming convention
+As mentioned in [Conventions for forked code](conventions-for-forked-code) `#ifdef`ing the code is the last resort as it makes code harder to maintain overtime. If we do need to use `#ifdef`'s we should following the conventions:
+- For defines based on conventions should be one of `$(OSGroup)`, `$(TargetGroup)`, `$(ConfigurationGroup)`, or `$(Platform)`.
+ - Examples: `<DefineConstants>$(DefineConstants),netcore50</DefineContants>`
+- Defines based on convention should match the pattern `FEATURE_[FeatureName]`. These can unique to a given library project or potentially shared (via name) across multiple projects.