The thinking in this post is applicable to the class as well as modules. However, in this post, I’ll use the word class.
Let me walk you through some of the bad and good examples first and show you the useful notes at the end of the post.
Uglier ways of naming modules or classes
- myClass: Lazy ways of naming classes. Does it answer it’s purpose clearly?
- Anything that is suffixed by general words like Manager, Helpers, Info, Data, Details, Utility.
- CSVHelper: Is it formatting, serializing, converting data into CSV? Are you sure it is answering the questions?
- XMLUtility: Same as above.
- AppointmentEntity: Is this a Transfer object?
AppointmentBOBO: Business object; doesn’t your programming language have namespace or package?
- Common, Utility, Helpers: Wow! Put all the garbage here. The magnet class that attracts all lazy developers. They do their sins in this class.
- StudentData, StudentDetails, StudentInfo, StudentInformation: What will happen if I simply give a name:`Student`? It is also a piece of student information, isn’t it?
- QC: Avoid abbreviations. We are here to solve the problem and make collaboration easy within the team. Avoid abbreviations.
- BatchJob: This was a base class for all jobs that can be queued in a batch. Does that convey anything related to base class?
- JWTAuthentication: Are you yelling at others about implementation?
Let’s go through some of the good examples of naming classes.
Cleaner ways of naming classes:
- Appointment: You have ways to locate your classes using namespace so instead of appending general words like Entity, or BO, or AppointmentEntity, use namespaces wisely.
- DateFormatter: It formats the date based on the given format. Makes more sense than DateHelper or DateUtility, right?
- MeetupSerializer: It serializes the meetup object into a string representation. Intuitive?
- DocumentFileStorage: It tells you about its central purpose like Reading/Writing a document to a file system.
- UserRepository: It tells you that it’s a repository pattern for User. If your language supports generics, then Repository<User> could be a better solution.
- MoneyFormatter: It formats the money.
- ColorCodeProvider.getColorCode(value). It gives you a color code for a given value.
- QualityCheck is better than QC
- StudentProgramSearch, The search entity that contains fields related to a student and his education program.
- ControllerFactory: It creates controllers.
- UpdateCommandSanitizer: It should ignore some of the fields from user input like CreatedAt and UpdatedAt fields and prepare update command for updating other fields.
- PersonDataSanitizer: It clears some of the person fields like phone, email, address and sends data for remaining fields.
Giving a name to a class is art. To learn that art, I would recommend you to read, understand and apply: Abstraction, Cohesion, and Single responsibility principle. You will also need to understand the conventions of the framework you are using e.g. MVC as well as learn design patterns.
Don’t forget to ask these questions while naming the class.
- Does your class name describe its central purpose? and doing those things only? Example: Abstract data types like Stack, Queue, etc.
- Does your class answer your questions like what it is doing? Rather than how is it doing?
- Name your classes using a noun, according to their domain and architectural meaning.
- What do you want to achieve? Ask repeated questions. For e.g. Formatting? what kind of formatting? Money? Then the name should be MoneyFormatter…. Similarly, Converting document into JSON? OK, but why are you doing it? Do you want to serialize document? Then it should be named DocumentSerializer rather than JsonConverter.
- Can a class be treated as a black box? Visibility of the members? Use class diagrams for clarity.
- Does class make assumptions about the consumer of that class?
- Does your class name feel more generic or specific?
One thought to “Naming Modules or Classes”
Really cool article , beautifully illustrates the need to have better thought out names.Thanks for sharing.