Sync Copilot knowledge base

.github/Guidelines/Coding.md

@@ -13,6 +13,20 @@ In general, here is my preference for any languages:
   - DRY requires finding if a feature has already been implemented somewhere else before implementing it. avoiding massive duplication.
     - If the existing implementation is not sharable, refactoring is preferred.
 
+## C++ Coding Convention
+
+- Although C++ does not require this but we want to have `extern` on all function forward declarations.
+  - In general we don't use `inline` in header files unless such function is performance critical, e.g. very simple comparison operators.
+- Rules for C++ header files:
+  - Guard them with macros instead of `#pragma once`.
+  - In a class/struct/union declaration, member names must be aligned in the same column at least in the same public, protected or private section.
+  - Keep the coding style consistent with other header files in the same project.
+- Extra Rules for C++ header files in `Source` folder:
+  - Do not use `using namespace` statements; the full names of types are always required.
+- Rules for cpp files:
+  - Use `using namespace` statement if necessary to prevent from repeating namespace everywhere.
+  - `vl::stream::` is an exception, always use `stream::` with `using namespace vl;`, DO NOT use `using namespace vl::stream;`.
+
 ## Basic C++ Library Leveraging
 
 - This project uses C++ 20, you are recommended to use new C++ 20 features aggressively.
@@ -29,22 +43,13 @@ In general, here is my preference for any languages:
   - Always use `FilePath` for file path operations.
   - Use my own collection types vl::collections::* instead of std::*
   - Check out `REPO-ROOT/.github/KnowledgeBase/Index.md` for more information on how to choose the correct C++ data types.
-- Rules for expressing unavailable values:
+- To attach availability semantic to a value:
   - If any number is expected to be valid only when non-negative, you could use `-1` to represent invalid value.
   - If an object is expected to be valid only when non-null, you could use `nullptr` on `T*` or `Ptr<T>` to represent invalid value.
   - Use `Nullable<T>` to represent any invalid value if possible.
     - DO NOT use `Nullable<T*>`, `Nullable<Ptr<T>>` or `Nullable<Nullable<T>>`, this is too confusing.
   - Only when there is no other choice, use an extra `bool` variable.
     - This could happen when "null" semantic is valid.
-- Rules for C++ header files:
-  - Guard them with macros instead of `#pragma once`.
-  - In a class/struct/union declaration, member names must be aligned in the same column at least in the same public, protected or private section.
-  - Keep the coding style consistent with other header files in the same project.
-- Extra Rules for C++ header files in `Source` folder:
-  - Do not use `using namespace` statements; the full names of types are always required.
-- Rules for cpp files:
-  - Use `using namespace` statement if necessary to prevent from repeating namespace everywhere.
-  - `vl::stream::` is an exception, always use `stream::` with `using namespace vl;`, DO NOT use `using namespace vl::stream;`.
 
 ### Regular Expression
 
@@ -90,12 +95,18 @@ When `VlppParser2` is available to the current project, complex parsers always r
   - Avoid using an expression that creates temporary objects in `for(... : HERE)` or `for(... : indexed(HERE))`. The current C++ destroys the temporary object too early; therefore this becomes UB.
 - Prefer Inversion of Control (IoC) and other design patterns, over trivial virtual functions, over switch-case on types, over if-else on types.
 - Prefer static dispatching over dynamic dispatching when possible and reasonable.
+- Unless explicitly instructed:
+  - You are not allowed to test if `VCZH_DEBUG_NO_REFLECTION` is defined.
+  - You are not allowed to test if `VCZH_DEBUG_METAONLY_REFLECTION` is defined.
+  - You are not allowed to call any function that does not work with `VCZH_DEBUG_NO_REFLECTION`.
+  - Reflection registration is an exception follow the document for recommended patterns.
 
-## Workflow Script Generation Rules
+## Keep C++ Code Cross Platform
 
-- When generating Workflow script, avoid building text, you should always build the AST. The AST type for a complete Workflow script module is `WfModule`.
+- All source files must aim for cross platform unless the file name has `.Windows` or `.Linux.`.
+- Use FilePath to normalize file path, for file path operations and delimiter access.
 
-## Workflow Script Authoring Rules
+## Workflow Script Coding Convention
 
 - Avoid explicit type specification whenever possible:
   - Prefer `var v = e;` whenever `T` can be omitted.
@@ -104,3 +115,7 @@ When `VlppParser2` is available to the current project, complex parsers always r
   - Prefer `cast *` over `cast T` when the context accepts `T`.
 - Nested `try-catch` and `try-finally` can be merged into one single `try-catch-finally` statement.
 - Prefer strong typed collections in Workflow, but when writing C++ reflectable interfaces, use `Ptr<IValue*>`.
+
+## Workflow Script Generation in C++
+
+- When generating Workflow script, avoid building text, you should always build the AST. The AST type for a complete Workflow script module is `WfModule`.