6

I'm going to confess: I am the type of developer that creates the ExcruciatinglyLongAndSpecificClassNameObject with the UtterlyDetailedExplanationMethod. It's just a thing I keep doing, despite voiced frustrations from people I've worked with. It just feels right in the mindset of self-documenting code

And while I acknowledge this isn't a flawless process, I see no other way around without losing information. I've tried alternatives, but everything feels like trading one issue for another:

- Abbreviations work as long as they are well known (XML, HTML, ...). As soon as you add your own (even if they make sense in the business context) you can bet your ass someone is going to have no idea what you're talking about. Even remembering your own shit is difficult after X months.

- Removing redundant naming seems fine until it isn't redundant anymore (like when a feature with similar traits gets added). and you can bet your ass no-one is going to refactor the existing part to specify how it differs from the newly added stuff.

- Moving details to namespaces is IMO just moving the problem and pretending it doesn't exist. Also have had folks that just auto-include namespaces in VS without looking if they need the class from namespaceA or namespaceB and then proceed to complain why it doesn't compile.

So, since I am out of ideas, I'd like to ask you folks: Is it possible to reduce class/method name lengths without losing information? Or is self-documenting code just an ideal I'm trying too hard to achieve? Or are long names not a problem at all? I'm looking forward to your answers.

Comments
  • 0
    Good Javadoc / method spec / whatever you call them, accessible through the IDE.
    Describe functions and classes, explain the caveats etc.
  • 7
    Divide the code in your methods into even more smaller methods. That will distribute the details and the method names become shorter naturally.

    Use comments and documentation only in rare cases to add meaning if it can not be provided by code or the method name.
    Don’t ever add comments for every method that just repeats the method name and doesn’t add any value.
  • 3
    I have to disagree with @ess3sq

    If you need to describe details and caveats in comments, you are not fixing the cause. You are just treating the symptoms.

    Instead, redesign and refactor your code and it becomes clear without the need for comments.
  • 1
    I'd fully support you. Self documenting longer method names are better than commenting on every method or maintain a doc.
    Tbh the IDEs are smart enough to provide suggestions on the method names from the very second time while typing, I don't find any issue with that.
  • 1
    I’ll take that any day over stuff like “data” and “run”
  • 1
    Usually categorisation/ namespaces / packages...
  • 2
    @RikaroDev I do take issue with it, not because of the writing but because of the reading. Especially with chaining it becomes horridly complex. Concise is nice.
    @Lensflare provides a way better solution.

    Also the more internal it gets the more context you have and less verbose your naming needs to be. If there is only one fetch method and that method takes a parentId param than the method can just be fetch(parentId) instead of fetchByParentId(parentId) for example.
  • 2
    It’s smelly IMO, it could mean you’re trying to make a golden hammer, or that the rest of the code base is overly complex and tangled forcing you to make something way too specific.

    But sometimes you can’t do much about that. I just ran into this, and my pride wouldn’t let me write a long ass name, so I made it vague and then heavily documented it.
  • 1
    Personally I believe that code can't be verbose enough to be self-documenting without sacrificing usability. Actual documentation is vital for wider adoption.
  • 1
    Oh yeah some practical advice: using object composition. The class can be described by the names of the classes that it’s composed of as well
  • 0
    For me it’s exponentially harder to follow code with no self descriptive variables or methods than code with overly descriptive naming conventions.
  • 1
    for one thing:
    namespaces if available,
    directories/modules alternatively.

    for the other:
    don't be fooled by "self documenting code". you or others have to understand the code one way or another anyways.
    just document properly.
  • 3
    I don't mind 3-4 word function names.

    As long as they don't contain "And".

    I think that it's easier to search the entire codebase for a function name than having to first find the file by name. (Unless there's a consistent structure where tons of files do the same thing and have the same function. like if you have tons of view components which mainly just consist of a render function. Then there's no need for a renderA renderB and renderC. But if you just have a single file of that kind - by all means call it renderArticle
  • 1
    OK, thanks everyone. I've seen some good ideas. Refactoring/composition and namespaces are something I already try to apply. In fact, it's generally by applying composition that my names get longer.

    Assume I have a BusinessObject, I would create a BusinessObjectEditView and BusinessObjectEditViewModel. And since I want to separate button logic from the view model, I also create a BusinessObjectEditViewModelCommandFactory. I consider this name to be lengthy already, since BusinessObject could be a longer name too, like VehicleMaintenancePlan or AquaticEnvironmentConfiguration or something.

    I could reduce the name to EditViewModelCommandFactory, but this will only hold as long as no related entity is dropped in the same namespace...

    Maybe my approach is not right. I will give it some more thought. Feel free to keep adding tips here.
  • 1
    @HerrNyani I had the feeling it would be something like this when you mentioned your concerns in the rant.

    It largely depends imho on the language in this case - especially due to handling of namespaces / packages.

    Architecture plays a major role, too.

    First would be: Package by feature, imho.

    In case of DDD / octa / hexagonal or similar architecture: Package by domain and future.

    BusinessObject is wrong imho for multiple reasons - I think you just wanted an exemplary name, so you didn't mean it seriously.

    Let's say the feature is "reports".

    Architecture plays now a role - if you have monolith, most likely you will have to create a deeper path (more subdirectories), given that there will be a *lot* more code.

    In a microservice, I'd expect no ambiguity with "reports" - the microservice should do one thing and only one thing.

    So we would be in a DDD e.g.:
    infrastructure/reports/...
    (microservice)
    infrastructure/statistics/fiscal/reports (monolith)

    I know some people get herpes with deeply nested structures, but packages and namespaces are *ideal* for a hierarchical database. A short namespace most often means a lot of trouble - as one namespace then consists of a myriad of files, which leads to your aforementioned possible clashing problem.

    E.g. in the example for a monolith… the deep namepackage allows code reusage with clear distinction by *namespace*.

    If I refer to a class by full namespace path statistics.utils.DateUtils it is obvious that that should contain general methods, if I refer to statistics.fiscal.utils.DateUtils it should be obvious that this should contain only fiscal related date methods.

    Small distinction, but I've seen a lot of devs struggle with it. End result of the struggle is a giant StatisticsDateUtils class where you can easily mispick a function - as it makes a difference wether you want a general date calculation or a fiscal one (e.g. the fiscal ones only respecting work days, not *all* days in a year).
  • 2
    Adding the namespace to the class name is another, yet debatable, thing.

    If you look at the last example, I explicitly create subfolders - be it factorys, models, utils, ... .

    In my opinion, one has a hierarchical name. One imports via a hierarchical path. The full path *must* be unique.

    So we have a hierarchical database.

    Imho, if one starts duplicating the database name and table name in a database column, I'd doubt their sanity.

    As such, I'm against repeating the namespace path in the class name.

    I'm not against repeating the last path element (e.g. DateUtils if the last namespace element is utils) if the devs feel more comfortable with it.

    Most people argue that this leads to finding multiple classes by name.

    Which is a dumb argument in my opinion... After all, we created a hierarchical database for a reason.

    You don't search all databases, all tables and all columns in a large RDBMs either - cause it makes no sense. So it neither makes sense to ignore a hierarchical system and just look up a file name... Unless you're a lazy bum.

    :)
  • 2
    @HerrNyani I gotta say, BusinessObjectEditViewModelCommandFactory sounds insanely convoluted. Not the name itself but the idea of needing a "CommandFactory" for a viewmodel. Sounds like one of the jokes told by those who have been working in "enterprise development" previously - about how overcomplicated things were.

    I know it's part of the standard paradigm in some cases so I might be out of line but I would think twice if you really need all that separation between a button view model and it's logic.

    Imagine if you had all the button code in a single js file - would it really be all that horrible? Could it actually be simpler to gather all the button code in a single file instead of spreading it out over tons of files? Is it REALLY motivated to separate the view from the logic when they might be kinda tightly coupled?

    (You'd still have separate files for services etc, that might be called by the button code)
  • 1
    @jiraTicket Thanks for the input. Let me add some more context of how I ended up here...

    I always feel like ViewModels (in C#.NET) get incredibly cluttered super fast:

    - There's all the binding properties, which are thankfully simplified by libraries providing some boilerplating for INotifyPropertyChanged

    - All the ICommand logic goes in there.

    - Validation logic using the INotifyDataErrorInfo.

    This breaks SRP in my opinion, so I've factored out each bullet point into its own set of classes. Problem I encountered with the ICommand is that I have circular references, since the command sometimes needs to update the viewmodel that owns it. So I solved it using another layer of indirection which is the CommandFactory. It also allows me to detach dependencies (like EntityFramework) from the VM and inject it into the factory instead.

    If you've got a more elegant solution or idea, I'm all ears.
  • 0
    @HerrNyani BusinessObjectEditViewModel sounds like you’re creating a data model for your BusinessObjectEditView, I’m not sure why you would need that. Looking at those names I’d assume there’s some functionality that is too tightly coupled and should be factored out
Add Comment