Shakespeare has written That's obviously true but in Software Engineering (and may be in other areas also), there is actually a lot in the Name, and that makes the process of Naming of things important. That's what we will explore in this post. "What is in a name? That which we call a rose. By any other name would smell as sweet." In the case of Software Engineering, A Name (or a Term) generally represents a concept, a description or a thing. Example: "A class has a private constructor and a public static method to get the instance of the class. The class creates the its own instance and keeps it as a private static member of the class.". Above description is what is popularly known as . . Singleton Pattern When someone reads or hear , it becomes clear what is meant by that. There is no need to repeat the above description of the concept Singleton Pattern What if the authors (GoF) named it instead of Singleton Pattern. Nobody would have objected to it because it was their choice. But is a better name because . Private Constructor Single Instance Pattern Singleton Pattern it precisely conveys the concept, and an additional advantage is it is easier to remember and mention Names / Terms in a Software can be divided in two parts. : Names exposed to the End Users. External View : Names that are relevant only for Software Engineering Team. Internal View Names in the are given by the Product Management and Marketing functions based on various factors. We won't be focusing on that. External View In the , the names used for Releases, Projects, Initiatives, Teams, etc. are temporary and are relevant only till they are in use e.g., every Android release used to have some name like Marshmallow (6.0), Oreo (8.0), etc. These are names used internally during the development. . Internal View It has no usage after the work is complete, so the names in this category are not so important from Software Engineering point of view We will focus on other names in the . They can be categorized further in two buckets: Internal View : Names of things you can see. Tangibles : Names of logical concepts, definitions, etc. Abstracts Names in both these categories are relevant throughout the lifetime of the Software, but they have limited Memory Life Span. So these names should be meaning they should easily convey the meaning of what they represent when someone reads them. self-explanatory as much as possible How to make names ? These naming practices can help: self-explanatory Reflect the details Use names that reflect as much details as possible. We will understand with few examples: Method Name Consider following two code snippets. There is a class that writes to a file and it is used by the program to write a Report. Focus on the code in method and see which one is more self-explanatory. ReportWriter main Snippet 1 Snippet 2 The code in method of is more self-explanatory than . In , one has to find out the meaning of second boolean parameter to know what each line does. But in , each line clearly conveys its details through the name of the function. main Snippet 2 Snippet 1 Snippet 1 Snippet 2 Configuration Parameter When calling an external API, the timeout period is configurable in the Software. The timeout can be configured using Environment Variable. Consider following names of the Environment Variable: API_REQUEST_TIMEOUT API_REQUEST_TIMEOUT_MILLISEC Second is better because in the name clearly conveys what is expected input. This is important because when the Software is in Production use, these values may be set by Operations team. They will not have to find out the details in the documentation - provided the documentation is up-to-date! _MILLISEC Artifact Name A Software has number of modules and each module requires some common Utility implementation like String Validations, Log Formatting, Numbers Validations, etc. There is a common library that all modules use. Consider following names for this library: utils-lib common-lib common-utils-lib is better name because the name itself conveys (a) it is common or shared by all modules and (b) it has utility classes. Other names convey only one of these two pieces of detail. common-utils-lib Algorithm Name Whether a user can perform some operation or not is decided based on many rules. There is an algorithm designed for that which will be used on every API request to know whether user can perform the operation or not. Inputs to Algorithm: User Operation Output Yes or No Consider following names for the Algorithm: User Permission Check API Request Authorization User Operation Authorization conveys the details more accurately. User Operation Authorization Convention Conventions are very useful in making something self-explanatory. Let's see some examples: Artifact Name We have already seen in previous example was added to the name of a Library. Similar post-fixes like for Background Services, for Web Services, etc. can make the names of Artifacts convey more details about them. -lib -svc -web Class Name In MVC pattern, it is common to have post-fix to Class names. Similarly, using for Classes that interact with Database is also widely used convention. Controller Repository Cloud Service Instance In Cloud deployments, Environment pre-fix or post-fix can be added like (S3 Bucket), (Database), etc. Just looking at the name tells the Environment one is dealing with. static-images-qa appdb-qa Consistency One aspect of Consistency is to . follow conventions consistently everywhere Another important aspect is to . Let's understand with an example: maintain consistency in naming across different parts We will continue external API request timeout example earlier in section. There is a default configuration in the database but that can be overridden using Environment Variable. Consistency demands the following: Reflect the Details The database field should be named api_request_timeout_millisec Environment Variable should be API_REQUEST_TIMEOUT_MILLISEC Class member and getter method should also be of same name. Maintaining consistency is important when working on existing Software, generally called . Many people would have worked on it and many may work on it in future. So rather than starting a new trend, it is better to continue using existing naming and convention so that there is Consistency - even if it does not make sense. Legacy System Having names can significantly of the Software. It will make it easier for any new person joining the team to understand the Codebase, Deployment, Design, etc. self-explanatory improve the Maintainability Some name will be given anyway so just paying a little attention to naming . can improve Maintainability without significant efforts Domain Driven Design Domain Driven Design (DDD) is an approach that advocates Software design to match the model of the business domain. One of the important principles of DDD is called : common terminology between business domain and the Software. To explain it in current context, DDD says same term (name) should be used throughout from business domain to the source code level. Let's see an example: Ubiquitous Language In most countries, individuals are required to their annually. Note the Business Domain term is - not complete or submit. So everything in the Software should consistently use the same term. file Income Tax Return file All Design and other documentation should use the term or . file filing Database table should be like income_tax_return_filing Classes should be like , IncomeTaxReturnFilingController IncomeTaxReturnFilingRepository Method name should use or . file filing As we can see, there is a lot in the name! Please share your feedback in comments.
