7

I've been drilling into a lot of Matlab recently trying to interface with an in house algorithm engineer's work to modularize it for use in a test bench outside his suite of applications. I've come across several links from several different areas and concepts that connect to this undocumented MATLAB website.

I've been hesitant to dive into any solutions proposed there since I've always been taught not to rely upon undocumented behavior, since well it may be deprecated and is generally subject to change. I suppose however for the sort of software that would be developed in MATLAB such implementation shake ups wouldn't bring too large of a house crumbling down to be refurbished, but I was curious is there something to the way Mathworks develops that they manage to allow so many hooks into their undocumented architectures and frameworks? What could be preventing them from formalizing these things.

Just as a concrete example while researching UI layout techniques for programmatic GUI creation one of their articles made mention of this uiflowcontainer, which if you get the documentation on it you find it is undocumented.

>> help uiflowcontainer
  This function is undocumented and will change in a future release

In general I find it very curious and amusing that such a development tool has built such a following to its undocumented internals. Any thoughts on that reality? Is it foolish, crafty, or something in between?

gnat
  • 21,442
  • 29
  • 112
  • 288
jxramos
  • 359
  • 1
  • 9
  • "supports undocumented code" is maybe misleading. Not sure how best to express that, encourages undocumented code use maybe? Or leaves the door open for undocumented code use? Something along those lines, support makes it sound formal but it's a contradiction in terms if you think about it. – jxramos Jun 17 '15 at 00:46
  • 1
    The code may in fact be documented at MATLAB HQ but tagged in such a way that things that aren't supposed to be visible to the rest of the world are scrubbed out on the way to a release. – Blrfl Jun 17 '15 at 04:30
  • That's a good distinction, absolute documentation or existence of internal documentation vs publicly released documentation. Tagging sounds reasonable to me and I wouldn't be surprised that's how they do it. – jxramos Jun 17 '15 at 19:15

2 Answers2

11

Neither foolish nor crafty I believe: MATLAB software is used for very serious engineering, science, finance, and many other fields. This being the case, MathWorks (the company that develops Matlab) are very careful not to publicly document things that they are not 100% certain will remain as-is in future Matlab versions. There are numerous examples of such functions and features/functionality, and uiflowcontainer is just one of them. In the vast majority of cases, these undocumented features/functions have remained unchanged for many years, 10-15 years or more. In some cases (e.g., uitable in R2008a or uitab in R2014b) they eventually become fully documented/supported, and in other cases they remain undocumented. In rare cases they are significantly modified at some point in time.

The bottom line is that using such features/functions can significantly improve your existing Matlab code and will probably not require any major rework in the near future. However, the down-side is that a rework might indeed be necessary at some future time if you upgrade to a new Matlab release that changes the undocumented behavior. So is it worth the risk? The answer to this depends on the specific feature and its usage in your work: the benefit it gives you today vs. the risk of needing to recode it tomorrow.

p.s. – I and my website (http://UndocumentedMatlab.com) are entirely independent and not affiliated with MathWorks in any way. All the undocumented things that I publish in my website and books are entirely due to self-made discoveries, and were not provided to me by MathWorks. In fact, MathWorks are extremely careful not to divulge to me any undocumented things. They do not support or promote my undocumented work in any way.

Yair Altman
  • 211
  • 1
  • 3
  • 1
    Fantastic perspective with some of the historical details. That alone makes me want to take the gamble, although maybe just for my own personal Matlab work. I'd probably become criticized inhouse if it was leaked that I was using these sorts of things :D It's all a tradeoff as we know, but 10-15 years, that sort of span one would not in the least be surprised to discover the need for some degree of rework. I'm with Scott Hirsh and you good sir, let's indeed have fun poking around. Thanks so much for the feedback and perspective. – jxramos Jun 17 '15 at 00:42
3

TL;DR

  1. Leakage of implementation detail due to MATLAB ".m" files being shipped in source code form.
  2. Frequent changes of software requirements, features, and implementation detail.
  3. Complexity due to many different underlying dependencies, all of which suffer from the phenomenons listed here.

Every complex software system (consisting of multiple architectures, layers, languages, and evolving a lot of generations over many decades) will have lots of implementation details.

The reason that the undocumented functionality in MATLAB is discoverable is because:

First, anything that Mathworks chooses to implement in its own MATLAB language will be shipped with the MATLAB application in source code form. This makes it possible for licensees to see its implementation detail. On the contrary, anything Mathworks chooses to implement in Java and C (MEX) will be shipped in compiled form.

However, this doesn't invalidate the general engineering advice that one should depend on the documented API, not on implementation details that could change from versions to versions. Just because something is possible (visible to you) doesn't mean it's a good idea (to use it).

Second, MATLAB prides itself on satisfying customer requests. Sometimes such requests require behavior changes. As a result, MATLAB has undergone many behavior changes.

Sometimes, some other customers will ask for the old behavior back. For this reason, switches are provided to make all customers happy.

Third, MATLAB uses a lot of existing technologies, such as the Java GUI. From versions to versions, the behavior of Java GUI also changes. Switches are needed to ensure compatibility with behavior changes inside Java GUI.

rwong
  • 16,695
  • 3
  • 33
  • 81