codingGuidelines.md: clarify some details about headers

.clang-format

@@ -21,6 +21,57 @@ BreakConstructorInitializers: BeforeComma
 BreakInheritanceList: BeforeComma
 ColumnLimit: '100'
 FixNamespaceComments: 'true'
+IncludeBlocks: Regroup
+IncludeCategories:
+
+  # Desired final ordering:
+  # 1. Related header
+  # 2. All private headers
+  # 3. All public headers from this repository (maya-usd)
+  # 4. Pixar + USD headers
+  # 5. Autodesk + Maya headers
+  # 6. Other libraries' headers
+  # 7. C++ standard library headers
+  # 8. C system headers
+  # 9. Conditional includes
+
+  # 1. Related header
+  #    Handled  by the default IncludeIsMainRegex regex, and auto-assigned
+  #    Priority 0
+
+  # 3. All public headers from this repository (maya-usd)
+  - Regex:           '^<(mayaUsd|hdMaya|AL|usdMaya)/'
+    Priority:        3
+
+  # 4. Pixar + USD headers
+  - Regex:           '^<pxr/'
+    Priority:        4
+
+  # 5. Autodesk + Maya headers
+  - Regex:           '^<(maya|ufe)/'
+    Priority:        5
+
+  # 7. C++ standard library headers
+  #    angle brackets, no directory, no extension
+  - Regex:           '^<[A-Za-z0-9_-]+>$'
+    Priority:        7
+
+  # 8. C system headers
+  #    angle brackets, no directory, end with ".h"
+  - Regex:           '^<[A-Za-z0-9_-]+\.h>$'
+    Priority:        8
+
+  # 2. All private headers
+  - Regex:           '^"'
+    Priority:        2
+
+  # 6. Other libraries' headers
+  - Regex:           '^<'
+    Priority:        6
+
+  # 9. Conditional includes
+  # Not reordered by clang-format, we need to manually make sure these come last
+
 MaxEmptyLinesToKeep: '1'
 NamespaceIndentation: None
 UseTab: Never

doc/codingGuidelines.md

@@ -148,44 +148,53 @@ In general, macros should be avoided (see [Modern C++](https://docs.google.com/d
 * Comments for users of classes and functions must be written in headers files. Comments in definition files are meant for contributors and maintainers.
 
 ### Include directive
+For source files (.cpp) with an associated header file (.h) that resides in the same directory, it should be `#include`'d with double quotes and no path.  This formatting should be followed regardless of with whether the associated header is public or private. For example:
+```cpp
+// In foobar.cpp
+#include "foobar.h"
+```
+
 All included public header files from outside and inside the project should be `#include`’d using angle brackets. For example:
 ```cpp
 #include <pxr/base/tf/stringUtils.h>
 #include <mayaUsd/nodes/stageData.h>
 ```
 
-Private project’s header files should be `#include`'d using the file name when in the same folder. Private headers may live in sub-directories, but they should never be included using "._" or ".._" as part of a relative paths. For example:
+Private project’s header files should be `#include`'d using double quotes, and a relative path. Private headers may live in the same directory or sub-directories, but they should never be included using "._" or ".._" as part of a relative path. For example:
 ```cpp
-#include “privateUtils.h"
-#include “pvt/helperFunctions.h"
+#include "privateUtils.h"
+#include "pvt/helperFunctions.h"
 ```
 
 ### Include order
 Headers should be included in the following order, with each section separated by a blank line and files sorted alphabetically:
 
 1. Related header
-2. C system headers
-3. C++ standard library headers
-4. Other libraries’ headers
+2. All private headers
+3. All public headers from this repository (maya-usd)
+4. Pixar + USD headers
 5. Autodesk + Maya headers
-6. Pixar + USD headers
-7. Your project’s headers
-8. Conditional includes
+6. Other libraries' headers
+7. C++ standard library headers
+8. C system headers
+9. Conditional includes
 
 ```cpp
-#include “exportTranslator.h"
+#include "exportTranslator.h"
+
+#include "private/util.h"
 
-#include <string>
+#include <mayaUsd/fileio/jobs/jobArgs.h>
+#include <mayaUsd/fileio/jobs/writeJob.h>
+#include <mayaUsd/fileio/shading/shadingModeRegistry.h>
+#include <mayaUsd/fileio/utils/writeUtil.h>
 
 #include <maya/MFileObject.h>
 #include <maya/MGlobal.h>
 #include <maya/MSelectionList.h>
 #include <maya/MString.h>
 
-#include <mayaUsd/fileio/jobs/jobArgs.h>
-#include <mayaUsd/fileio/jobs/writeJob.h>
-#include <mayaUsd/fileio/shading/shadingModeRegistry.h>
-#include <mayaUsd/fileio/utils/writeUtil.h>
+#include <string>
 
 #if defined(WANT_UFE_BUILD)
   #include <ufe/ufe.h>