See the BizTalk: BizTalk Solution Naming Conventions article.
In small application we do not really care about names. When the number of objects start growing, we start pay attention to the names. Experienced developers working with big projects are recognizable by the carefully crafted names in the developed code.
When a new developer start working in a new team, he/she spent first several hours to read the general level documentation and the naming convention usually is a part of it. Then he/she start to develop and now time should be spent to review the existed code base to become accustomed to the coding standards, and again the naming conventions are the main parts of them.
So the naming conventions document are important but the existed code base is also important. The documentation could be not up to date, but the code always is.
The code example easily could replace the the documentation, that’s why I decided to show the BizTalk naming convention in the real-life examples.
Example description
This BizTalk deployment is compounded from many BizTalk applications. Each of application has 1-10 Visual Studio projects. The applications were developed through the many years by different development teams. Applications integrate several systems. Some systems have just one interface, some systems have many interfaces. In most cases one system interface is integrated with another system interface. Sometimes several systems are integrated with one system interface.
One solution is chosen for this example. Why the GLG.Samples.Name.Shared.Schemas solution was created in real life?
As we know an interface in BizTalk defined by a protocol and one or several XML schemas. In many cases those schemas are dictated by the integrated system not by the BizTalk application developer. Usually the BizTalk developer uses the Adapter Wizard to generate/import these schemas. These schemas are managed (created, modified) not by BizTalk application developer but by the external system owners. Let’s call these schemas the external schemas.
One interesting aspect of the external schemas is one schema can be used by several BizTalk applications. As we know the schemas for the receive locations should be unique, they cannot be deployed in several assemblies. That means if we want to use the same schema in several projects we should share an assembly with this schema, reference this assembly from all these projects.
In this situation the special attention is paid to these schemas.
All external schemas are placed in a separate Visual Studio solution. The schemas are grouped by the systems. Inside each system the schemas are grouped by the interface names.
This design gives us one more useful feature. Here we always know where to find the external schemas. They are not spread through many projects and application but always placed and can be found in one solution.
The sample provide two versions of the naming conventions. I called them "Long Names" and "Short Names".
Long Names
It is the Solution Explorer view:
It is the folder view:
Short Names
It is the Solution Explorer view:
It is the folder view.
Comparing
The Short Name convention looks more clean. There are no generic prefixes (GLD.Samples.Names.Shared.Schemas) inside the Project and folder names. If you fight the well-known issue with the TFS limitation on the size of the full file names, it would be a preferable variant.
I personally prefer the Long Name conventions. The project name is equal to the project namespace and the project assembly name. The full project names are better in situations where a project might be included in several Visual Studio solutions or the projects could be frequently shuffled between solutions.
Q&A :
- Is it OK to use the names compounded from 4 and more pieces like GLD.Samples.Names.Shared.Schemas?
- Do we need the GLD.Samples prefix in the BizTalk application name, in the solution name?
- Why we use the _Ops suffix for the SystemA, SystemB, and SystemC projects?
BizTalk Applications
Here is the BizTalk Administration Console view:
As you can see the GLD.Samples.Names.Shared.Schemas solution is deployed as the Names.Shared.Schemas application. The GLD.Samples prefix is removed because all deployed solutions are using this GLD.Sample prefix. If all artifacts has the same name part, this part definitely can be removed. Why this part is not removed from the solution/project name? Because projects (assemblies) are working together with many system, Microsoft and others assemblies in one global name space, in .NET run-time space. All assemblies should be placed in GAC, where GLD.Samples prefix helps us to find out our assembles. This is an answer on the second question. 
This is the Short Name convention for the application names.
The Long Name convention is simple:
the BizTalk Application Name equal the Visual Studio Solution Name
I personally prefer the Long Name convention as a faster way to work, copy/past without any change, and do not guess the full name of the assemblies.
How complex could be the name hierarchy?
For example, we have such name as GLD.Samples.Names.Shared.Schemas.Sap.AV_CREDIT_STATUS_MODIFY. Isn't it too complex?
Not at all. All parts of this name are here for a reason. Each part shows the grouping of an object. Our names unambiguous show us the object hierarchy. Just try to avoid some parts to get something shorter and you would be in trouble. You would create not one but numerous naming conventions and numerous rules how to use them.
Hierarchical naming conventions is the king of the BizTalk projects. These projects are complex enough to create the object grouping hence hierarchy. But they are not too complex to push us in the areas, where the hierarchical grouping is not working well, where keys or tags are working better.
I hope this is an answer for the first question.
Now the answer for the third question. Why we use the _Ops suffix for the SystemA, SystemB, and SystemC projects?
For instance, we have GLD.Samples.Names.Shared.Schemas.SystemA.CreditCheck_Ops project
why it is not just
GLD.Samples.Names.Shared.Schemas.SystemA.CreditCheck ?
The problem is, this project has a schema which has several roots and one of them is the CreditCheck. What is wrong with it, why we cannot use the same name for a part of the project name and for a schema root?
The XML schema is serialized into the .NET classes, and a schema root serializes into one such class. So we will get a class with full qualified name as GLD.Samples.Names.Shared.Schemas.SystemA.CreditCheck.ChreditCheck. And while the project is building, we got an error like this:
Description would be a little bit different from the picture about: “symbol ‘GLD.Samples.Names.Shared.Schemas.SystemA.CreditCheck’ is already defined; the first definition is in assembly…”.
For some reason the .NET builder parses the names sometimes left-to-right, sometimes right-to-left and this creates this kind of errors.
To avoid this kind of error we have to avoid creating .NET classes with name equal one of the namespace part. The "_Opr" suffix is used for this purpose.
This is an implementation detail, but we have to take care of it in the naming conventions.
Conclusion
There is no single naming convention for all and every situation. Be reasonable and do not create an over engineered conventions. They are not the goal in development but the helpers.
Quiz for readers ![Smile]()
- Propose your improvements to these naming conventions.
- What are the Pros and Cons of placing the external schemas in a separate solution?
- This solution could be very big. Would be this a problem?