Code Smells in Application Structure
Summary
One of the terms the development community is fond of using is “Code Smell”. A code smell is an indication in code that there may be room for improvement. It does not mean something has been done incorrectly, or is wrong, but rather is a sign that you may want to take a closer look at the thinking that led to code being written a certain way. Often, it’s because there’s an anti-pattern or bad practice in use and while the code or application “works”, it may not be as maintainable or readable as it could be.
For some “smells”, you don’t even need to examine code to start sniffing something amiss. I’ll be going over a few indications that your application needs some TLC at a high level.
Large Files
If you are looking through your application and notice that it is not uncommon to see files that are long (exceeding 1000–2000 lines of code, for instance), it may be an indication that the unit of code within the file is doing too much. To be clear… I’m not saying every long file is doing too much, but if you have a file that keeps growing, and houses tons of different methods, services, classes, etc, it may improve the application organization if you split some of that logic out into their own files. Some questions to ask as you evaluate these files and whether this “smell” is indicative of a real area for improvement:
- Are there multiple classes in a single file?
- If it is a single file, are multiple business logic paths occurring?
- Do you have methods in the file that are 100’s of lines long?
The solution here is pretty straightforward… start splitting some of that out into their own classes/functions/methods/services/whateverinyourproject. Make sure to split your unit tests too, and you should end up with a more clearly segregated, better tested section of code.
Huge Directories
If you have a project where you expand a directory to find 100+ files, it’s likely that there could be some organizational improvement. Don’t get me wrong… most IDEs make it easy to find specific files, but often a good application structure can give you an idea of how the communication between components works, the architecture is structured, and even how pieces should be used. If you find that every file is stuck in the same directory, you lose the ability to infer anything about how the application is structured.
Organizational cleanup can be a pain if you have to hunt down references in a zillion places, so you’re better off following a clean convention from the start. The rule of thumb on how many files is too many in a single directory is similar to how much code you should put in a single file. Though, in this case, if you have to scroll through the files in a directory you DEFINITELY have too many files. Categorize them, create some directories, and start grouping them. Before you do this, make sure you have an established convention! If you get a few different developers taking this on without an established convention, you’ll be worse off than before.
Inconsistent Naming Conventions
Naming conventions can be quite the source of discontent on development teams. Some people like to be concise, others more verbose, and if you don’t have established standards in an organization you may see a code base that has several implementations without consistency. If you find that you have to translate the file name you’re looking at, it’s a good sign that you may need to define conventions everyone will follow. Not only will this make your codebase more readable and navigable, but it will make it easier for newer team members to find their way around.
Examples of fragmentation are pretty evident if you have a code base where you may find these examples in the same project:
- MyAgreementsService.{extension}
- MyAgrmntsSvc.(extension}
- MyAgreements.service.{extension}
- My-agreements-service.{extension}
- You get the idea
This may seem small, but it’s just one of many things that can make it difficult for new team members to understand what they’re supposed to be looking at in a code base.
Solution: Pick a single convention and move on with your life.
Conclusion
To some developers the above items/suggestions will seem like no-brainers, to other they will seem a bit nit-picky. Consistency and simplicity are huge factors in any project and will drastically improve the ability of new team members to understand the codebase and start contributing quickly. Every little bit helps when you have multiple people contributing to a project, so make sure you’re establishing some conventions and sticking to them.
