Conventions are a good thing for many reasons like the maintainability and quality of a project. Like the force, if you use it, it can save you from some real sticky situations but ideally avoid those sticky situations to begin with.
Then you get good conventions and not-so-good ones; for instance like the hungarian notation. It’s from the same period as the classic Star Wars films, but unlike those films, it isn’t as timeless and should be superseded by more intelligent and descriptive conventions.
Let’s review some of the conventions we already know and might take for granted.
Naming Conventions: Human’s aren’t droids
Like the mechanical speak of droids, humans who don’t, won’t understand the subtleties of droid-speak, like where the rebel base is and possibly not understand what IVK_ is.
If you are like me and even if you do understand the significance of IVK_, I have to translate it as I read it, meaning I read slightly slower.
Writing naturally, like talking naturally makes more sense. Instead of BCo_ why not write BeforeCommit_? Sure it is longer to type, but you only type once, but you read it a couple of hundred times. Impeding readability for writability’s sake doesn’t pay off as much as we would hope it does. Besides, you don’t call your friend FN-2187 right?
There are at least 22 acronyms every new Mendix Business Engineer should know before you can let him or her loose on a project if you are worried about conventions. We shouldn’t abolish convention, but we should make it real easy.
Naming your microflows UI-centric, has reusability challenges too. Consider the following example.
A Microflow gets called on a field’s “On change” event, and also on it’s “On Enter” event. Do you create 2 microflows that in turn call 1 other microflow, one called OEN_,one OCH_ and a third API-like microflow? This adds more microflows to your model.
Or could call a single microflow called OEN_OCH_. That’s useful for finding ui event-types of microflows but I think this is ugly. What happens if you decide to stop using that microflow on the On Change and forget to rename this microflow? The convention isn’t strongly enforced, so you loose reliability of use.
These UI conventions mixes concerns between views and controllers and affects the way we interpret our domain model, because the naming convention is UI-centric instead of being business-centric.
I suggest a DSL-like notation. For UI-type events or microflows, find a term that implies a verb or action but make it universal and descriptive, for instance call any event microflow On_. This way we think of conceptual events or actions at the business-level. Now I can reuse a UI-inspired microflow inside of other microflows. I no longer have the imply a UI-event took place inside of my microflow, but that a DSL or business significant event took place. For instance if I had a Microflow that would recalculate a customer’s Risk-Rating on the change event of a field, I would call it On_RecalculateRiskRating. This reads well in both the UI and inside other microflows.
Massive projects and conventions, think Starkiller base
Now this is something a few Mendix teams need to worry about, but woe the day you work on a massive app with little or no project conventions or design. You might be creating a Starkiller base that might kill you.
Conventions should be constructed around business events because once you think like a business person or analyst and less like a coder, something magically happens. Your ramp-up for new projects are much faster, since understanding the business is where the bulk of your time-investment goes in any project, as the technology is and should be a no-brainer.
Here is a couple of suggestions for conventions on big projects.
Domain-layer structure vs document grouping structure
This depends largely on your project size and your design philosophy (if you have one). Usually we write small monolithic apps and artefacts are relatively easy to find and we’ll use document type-grouping for our folder structures.
If layer your application, it becomes important to know where to put and find things in their respective layers, based upon their concerns.
As described in the Mendix documentation, the idea is to separate domain model artefacts like entities from process related artefacts. The thinking goes even further if you adopt something like an MVVM-type pattern for instance. (Which I’ll write about next) You group Model, View and ViewModel documents in a layered-type folder structure and then organised by type. This is an ideal, and won’t be perfect at first but the aim here is to organise things in the right layer. I recommend at least 5 high-level folders, namely Documentation, Model, ViewModel/Controller, View/UI and _Review.
- Documentation is overlooked in Mendix projects. But this is valuable for ramping up resources and tracking fundamental assumptions. Oh, and conventions.
- Model – here you find things like event handlers, business enumerations, domain logic etc. Domain model stuff (DSL-like) or things that live close to the data or model-layer.
- ViewModel – here you’ll find things like microflows used on the UI, web-services, app-services etc and reusable or API kind of microflows. The “Controller” equivalent of MVC.
- View – here you will find things like forms, snippets, images, layouts etc. Almost exclusively view-type stuff
- _Review – This folder is where we find balance in the force. Conventions could impede the speed at which we develop, so this is where we give space for the dark-side by doing our rapid prototyping of our project. It’s messy and serves as a incubation space for us to work and then every so often, we do code review and move things out of _Review into its right place.
A handy tip for writing Documentation in Mendix, is to create something like a ReadMe page, that you mark as “Excluded from project”. That way it’s not carried along when you build the project. Here’s an example:
Microflows intended for reuse like an API get prefixed with a Verb_ prefix. Then those microflows eventually gets wrapped with an integration layer to expose Application- or SOAP services. This way the core logic is in 1 place and you expose it in different ways but it’s clear from a mode-perspective what your application allows you to do.
Have you got any cool convention ideas? We’d like to hear from you either by comment or email.