Clean code: clean models?

In a recent customer conversation, I was asked if there was a mapping of Model-Based Design (MBD) constructs to the concepts of “smells” found in  Martin Fowler Clean Code. Fowler’s book was written targeting the Java, however, many of the concepts have direct mapping onto other programming languages.  Maping onto other object-oriented text-based languages are easily seen.  Hence the question of how OO smells could be mapped onto MBD.

Note: I am reviewing this in the context of developing embedded code using Simulink and Embedded Coder. The Clean Code was written with object-oriented user interfacing code (e.g. web pages, spreadsheets,…)

Fowler’s book defines 7 primary sources of smells:

  1. Comments:  Covers lack of comments, obsolete comments or out of date comments
  2. Environment: Covers the automation of build and test operations
  3. Functions: Covers definition of function interfaces and dead code
  4. General: 36 guidelines that cover a range of coding best practices
  5. Java: Issues specific to the Java programing language
  6. Names: Covers fundamentals of naming conventions
  7. Tests: Covers best practices for testing

Image result for 7 deadly sins

Quick overview

For some of the smells, there is a direct and easy mapping.

Comments: Models are, to an extent, self-documenting.  Additional documentation should be added as needed.  Fowler’s recommendation on keeping comments concise and up-to-date are directly mappable.

Environment: The smells in this section deal with automation of the build and test steps. There is a direct mapping for these smells and the recommendations for automation are standard for MBD environments

Naming conventions: For information on naming conventions (from and earlier MathWorks blog I wrote): A few thought on Naming Conventions

Tests: The smells for tests are standard recommendations for testing.  Earlier blog posts on testing can provide the mapping onto these smells.

Image result for quick

Deeper look

Of the 7 smells, I want to spend more time looking at both the “Functions” and “General” groupings.

Image result for the deep

Functions

Fowler has 4 smells related to functions, of the 4 MBD conforms to 1.5 of them.

  1. Too many arguments:  Control of physical systems require multiple bits of information.  Fowler’s recommendation of 0 ~3 input arguments doesn’t hold.  (It is also a function of object oriented programming that allows for that rule).  At the same time validate that the inputs to the function are required.  The MBD smell for function arguments is found in non-required inputs.
  2. Output arguments:  Like input arguments modeling control systems requires output arguments to continue the control flow.
  3. Flag arguments: Control algorithms frequently depend on modal conditions.  It is preferable to use these conditions to control enabled type subsystems or modal logic within a Stateflow chart.  Hence the .5 agreement on this one.
  4. Dead functions: Full agreement here; avoid dead functions at all cost.

Image result for enabled subsystem simulink

General

The generalImage result for general category includes 36 different code smells; I have subcategorized them into N themes

  1. Clear functionality: The behavior and function of the model should be clear from its construction.  Further, all functionality of the model should be implemented.
  2. Readability: The model should be easy to read.  The MAAB style guidelines have a direct mapping for this category.
  3. Encapsulation: The model’s functionality should exist within a scope of the model; e.g. there should not be calculations dependent on methods outside of the model.  I wrote about these issues in the Model Architecture section of this blog.
  4. Scope of  variables: With the exception of user defined I/O and parameters MBD tools automatically define the scope of variables making these rules, for the most part, irrelevant
  5. Reuse: Smells dealing with the reuse, and failure to reuse.  These rules are directly mappable looking at the use of Referenced Models and Libraries to achieve the aim.
  6. Object-oriented issues: Not applicable

Final thoughts

The concepts put forth in the book “Clean Code” represent a useful set of guidelines for understanding coding best practices.  To the extent that models map onto code the concepts behind “Clean Code” apply.    However, MBD abstracts many concepts behind coding into a higher level language, placing the clarity and encapsulation of the actual code into the hands of the code generation tool.

Side note:

Late in my conversation with the customer, I realized that I was talking to someone from Denmark about smells.  I regret that I did not take the opportunity to make a reference to Hamlet.  (Something is rotten in the state of Denmark)

Image result for hamlet

 

 

2 thoughts on “Clean code: clean models?

  1. I think the lack of a formal “class” or “interface” in model-based development doesn’t mean you can’t apply code smells related to classes and interfaces to model-based development. For example, you still probably have patterns that you expect modes, devices, or groups of signals to follow, and these are informal interfaces or classes. If you, for example, have a mode that behaves differently from the rest and requires a lot of special behavior, you’re probably going to have a few code smells like LSP and ISP violations. If you compute the health of a signal source multiple times at the last minute, you have a feature envy code smell.

    Like

    1. All of those are good points and I will encorporate them into future posts.
      It is common for “mature” users of Model-Based Design to have approved design patterns for how Models/subsystems I/O is defined.
      Also guidelines like the MAAB style guidelines discuss issues with modal behavior.

      Thank you for the feedback,

      Michael

      Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s