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

 

 

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s