I always give one example to .Net developers. Specially those who came into profession after .Net 2.0. In the initial versions of Visual Studio for .Net (2003, 2005) there was a prominent component bundled with the installer. It was the Obfuscator. We did not understand initially what this was for. Later on when we came across decompilers which converted MSIL code into a C# or VB.Net code, we realized that the obfuscator was very critical to protect IP of your code. It was off course not foolproof solution. But it made the job hard. Many young developers today are not aware of this concept. So I introduce them to this concept first and then I tell them that although this is important but you will not need it if you continue write code the way you write today. I call this as natural obfuscation. Even without obfuscation, the code is extremely hard to understand.
Natural obfuscation is a technique to protect your IP by writing the code that is naturally hard to read and harder to understand. Only the developers who wrote the code should be able to fix it.
Whenever I do code reviews I came across suffixes such as BAL, DAL and UI etc. Every class in a particular layer is suffixed with these terms. So the namespace goes like this: CompanyName.ClientName.ProductName.BusinessLayer and the class name goes like CompanyName.ClientName.ProductName.BusinessLayer.ClassNameBAL or ClassNameDAL.
The biggest challenge an Architect faces is to move the developers from the concept to actual implementation where architectural terms/patterns do not make the naming overly complex to read.
While describing the architecture, we define layers, within layers there are patterns and concepts. If the team does not have any architect for some reason, the team will typically split the project into three layers: presentation, business and data access. I have asked many candidates during interviews about why these three layers and they tell me about all bookish concepts like loose coupling etc. But in reality
if you have not defined interfaces and coded against those interfaces and if you have not implemented DI, you really will never have loose coupling. It is just separation of concerns.
But many a times that is name sake. The business logic is really spread across multiple layers, at minimum presentation, business and stored procedures. Coming back to the layers, to show that they have implemented these layers, the developers ensure that the namespaces or class names have these acronyms in there.
In another project we defined three primary components of the business layer namely business processes, core components, business rules. Idea is straightforward. Core components are responsible for single function, rules allow you to check for conditional logics and processes orchestrate the business using core components as individual steps and rules as conditional statements to change the flows. The team understood the concept very well. The namespace conversion of this was very interesting. There were three different assemblies.
CompanyName.ClientName.ProductName.BusinessLayer.BusinessProcessComponents
CompanyName.ClientName.ProductName.BusinessLayer.BusinessCoreComponents
CompanyName.ClientName.ProductName.BusinessLayer.BusinessRules
There were further more assemblies like
CompanyName.ClientName.ProductName.BusinessLayer.BusinessEntities.Core
CompanyName.ClientName.ProductName.BusinessLayer.BusinessEntities.Master
CompanyName.ClientName.ProductName.BusinessLayer.BusinessEntities.Configuration
Now it needs to be understood that you do not really always need to explicitly call your components by the concept you are using. A simplified version of these namespace could be
CompanyName.ClientName.ProductName.Business.Processes
CompanyName.ClientName.ProductName.Business.Core
CompanyName.ClientName.ProductName.Business.Rules
CompanyName.ClientName.ProductName.Business.Entities
CompanyName.ClientName.ProductName.Master.Entities
CompanyName.ClientName.ProductName.Configuration.Entities
IMHO, except for business rules, all other entities can be part of single assembly. What should be general rule for creating a separate project/assembly? I feels things which change together should stay together. In the above case unless you are sharing Entities across multiple layers/ components (E.g Services and Business), all other components can be part of the single assembly. Typically business processes will be exposed to higher layers via interfaces.
There is another issue with naming. This is related to names of classes and methods. In OO it is natural convention that class names are nouns and method names are verbs. However many newbies use verbs as class names and nouns as methods such as
public class BookConferenceRoom
{
public bool ForSlot(int ConfRoomId, DateTime StartTime, DateTime EndTime)
{
}
}
Now on the usage side this looks good. BookConferenceRoom().ForSlot(...) However this is more of a functional language syntax. In OO thos should look like BookingManager.BookConferenceRoom(...)
Lastly another issue which often annoys me but may be many people think it prevents bugs is that many developers use prefixes of suffixes for their variable or paramter names. E.g. a text box is named as txtFirstName, a string parameter is named as strDescription, an instance of a class is named as objPerson or oPerson. When .Net was first released, Microsoft released a guideline to avoid all such hungarion notation since all the languages are strongly typed. The recommendation was to use FirstNameTextbox, description, person with exactly same casing for the previously mentioned names. In case if you make error in assiging wrong typed value, compiler will let you know immediately. So I am all for avoiding hungarion notations. I am open to hear if you have another view.
I have listed down some of the issues related to naming conventions in .Net but there are many more issues which make reading & understanding the code difficult. Some of them are related to coding principles, which I will discuss later. But I would like to hear more from the readers about the challenges they face while reading someone elses code.