36
$\begingroup$

Mathematica has a lot of very useful undocumented features. For example a hash table, a built-in list of compilable functions, additional options to CurrentValue, {"Raw", n} histogram bin specification, etc...

A natural question that arises is: Why is this functionality undocumented? Is it because the feature is under development? Or because the syntax has not been finalized and may be changed? Something else?

Also: Is using this functionality safe in the sense that it will not cause problems when a new version is released?

Improve this question
$\endgroup$
8
  • 3
    $\begingroup$ Once some functionality is documented, the company making the software commits in a sense to maintaining it: keep it working in future versions, keep it stable (no incompatible API changes!), making sure it is reliable and safe (no wrong results, crashes, sharp edges). For example, scheduled tasks was available in 7, but they changed the API before documenting it in 8. Then there's Internal`Deflatten and Compile`GetElement, both of which are useful and fast, but will crash the kernel if you use them incorrectly. $\endgroup$
    – Szabolcs
    Commented May 23, 2012 at 9:19
  • $\begingroup$ Re: "will it work in a new version" -- if they change/remove some undocumented function from e.g. Internal` , then they will need to track down all internal usages of that function and replace it. Changing something that's widely used internally is likely to be a lot of work, so there must be a resistance to it. But of course it's still much easier to change it if they don't need to guarantee tha users' programs will work in future versions. $\endgroup$
    – Szabolcs
    Commented May 23, 2012 at 9:23
  • $\begingroup$ @Szabolcs You could post this as an answer instead of two comments. Actually it's the tone of this answer that prompted this question: "This answer may be unacceptable right from the outset because it uses undocumented functions." $\endgroup$
    – Ajasja
    Commented May 23, 2012 at 9:29
  • 1
    $\begingroup$ My comments were just some vague thought, they're not really an answer. Actually the question might be deemed too broad or unspecific ... Re: "unacceptable answer": The main reason I like to avoid undocumented functions is precisely that they're undocumented: it's trouble to find out how they work, and I might not be aware of all their quirks (that would be mentioned in a doc page). But at other times these functions are just so convenient! $\endgroup$
    – Szabolcs
    Commented May 23, 2012 at 9:32
  • 2
    $\begingroup$ @Ajasja: I added that remark mainly because I wasn't sure how others would regard using undocumented functions when they aren't strictly required. But it seems from the answers here that the views of the community quite closely follow my own: you can use them yourself if you're confident that you understand them well enough and are able to rely on their existence in a particular version, but encouraging others to use them uncritically is a very bad idea. In particular, I was concerned that providing ad-hoc documentation for them here would be viewed as an explicit endorsement. $\endgroup$
    – Oleksandr R.
    Commented May 24, 2012 at 2:02

3 Answers 3

Reset to default
32
$\begingroup$

The two main arguments against using undocumented functions are:

  1. Your code might not work as expected in future versions;
  2. Your code might not work as you intended in the current version, because you only have a partial understanding of a function or option that is undocumented.

In the case of Mathematica, though, there is no guarantee that even documented functions will remain unchanged in future versions.

The two main arguments for using undocumented functions are:

  1. Oftentimes they presage the permanent inclusion of that functionality in a future version. For example, ScalingFunctions is only documented for charting functions like BarChart, but it has been shown to work also for ListPlot and Plot (but not DateListPlot). I predict that they will get around to completing (and documenting) this functionality in a future version. (EDIT: In fact, that's exactly what happened in 10.4, even though the online version of the documentation doesn't make it clear that this is new.)
  2. The functionality might be documented, but not completely documented. For example, some option values (say PlotRegion) are documented as applying to "graphics functions", without specifying which ones. So the functionality is there, and might well remain stable for several versions.

Mathematica is a complex system with an enormous array of possibilities for the use and abuse of its rich functionality. Even with the massive documentation that exists, there are bound to be some undocumented or incompletely documented functions. Undocumented functions (and options) need to used with some care, but given the usefulness of some of the functionality they offer, it might well be worth the risk.

Improve this answer
$\endgroup$
0
19
$\begingroup$

Problems with undocumented functions

I think that this is one of the things that everyone has to decide on their own. The biggest problem for using undocumented functions is that nobody is responsible for maintaining them, and therefore, it becomes explicitly your responsibility to maintain their use in the piece of software you are building with it. And from this perspective, it is no different from any other piece of code you grab and use, for which:

  • no one is responsible
  • no source code is available.

It is this combination which makes it unattractive to use, since I would think at least one of the above should hold: either you use unmaintained code, but it is open-source, or you can use commercial code, but it is maintained. So, to put it another way, if I develop some functionality, then, from developer's point of view, I find the general idea of using undocumented functions unattractive, because I have no control over these functions whatsoever.

I certainly don't think that we should promote the widespread use of undocumented functionality on this site. Neither do I think that we should totally exclude such uses from our answers. But the "default" should be "No", I think - speaking of common practices and conventional wisdom. The arguments were partly given by @Szabolcs in comments, I will just list them for consistency:

  • No documentation means that you really don't know how the function works. This means in particular that you
    • Don't know corner cases
    • Can't distinguish between a bug and intended behavior
  • The function may change in future versions, which may range from implementation changes to the function being totally removed.

In some cases, you can be more or less sure that some undocumented function will not be removed or become incompatible, because you somehow know that too much of internal functionality depends on that (for example, I have such feeling for Internal`InheritedBlock). In such cases, I would be less hesitant to use these functions.

Specific situations

That said, I think it's OK if one decides to use undocumented functions in his/her work, as long as one takes full responsibility for that. The factors I would personally consider are:

  • Who will use your functionality
  • Who will maintain your code
  • How critical is the code using that undocumented function

Using undocumented functions is a calculated risk. You trade speed of development (and often execution) for possible maintenance problems. The use of undocumented functions will increase maintenance costs because

  • there are higher chances of regression bugs coming from versions incompatibility
  • It is harder to read and understand the code (particularly for someone else), because of the lack of documentation
  • It is harder to debug code

There are, of course, well-known techniques, such as writing unit tests, and make extensive comments in your code. These may to a large extent alleviate these problems.

Summary

So, in summary, I would distinguish between the "general advice" and specific situations. My "general advice" would be "don't use it". But, particularly if one is an experienced user, I don't think this rule should never be broken. What matters is to take responsibility for your code, particularly including future maintenance. So, what I would do in case I decide to use undocumented function is to leave extensive comments describing the functionality I count on, plus some tests to test that it works correctly in some representative use cases.

Improve this answer
$\endgroup$
4
  • 4
    $\begingroup$ There's one more case which you omitted (which covers actually a substantial part of my work with Mathematica): Stuff you run once to get a certain result, and afterwards is only stored in case something turned out to be wrong, in order to find the error. Indeed, >90% of the notebooks I've created I never ran again. Here the use of undocumented functions boils down to: Might I produce incorrect results that way. If the code happens to be more generally useful and I'm going to make a package from it, I'll have to do some re-working of it anyway (and often even change the interface). $\endgroup$
    – celtschk
    Commented May 23, 2012 at 11:01
  • 1
    $\begingroup$ @celtschk Yes, indeed. I thought about it actually. But, if it is a one-time thing, chances are that you are not automating something, but doing a calculation. In such cases, I always use several alternative means of checking my results, even when using documented functions. I described my opinion on Mathematica in this context rather extensively in my reply to Richard Fateman in this Mathgroup thread (should be my second post there on the linked page). $\endgroup$
    – Leonid Shifrin
    Commented May 23, 2012 at 11:08
  • $\begingroup$ I think the hardest thing is to determine if something is undocumented due to a QA oversight or because it is intended to be "experimental" (though not in the experimental context) and subject to change or removal in later versions or because it is/was intended to be used internally and not for users. Of these cases only the stuff subject to change would be "dangerous" to use. $\endgroup$
    – Mike Honeychurch
    Commented May 24, 2012 at 2:07
  • $\begingroup$ @Mike I agree in part, but using even things which are going to stay is risky just because those functions are not documented and therefore it is not clear what to expect from them, and how they are going to behave in some corner cases. The line is probably somewhat blurred, because one often needs experimentation also to figure out the details of the behavior for documented functions, but I think it is there. $\endgroup$
    – Leonid Shifrin
    Commented May 24, 2012 at 7:42
12
$\begingroup$

While the existing answers answer your question of whether/when it is a bad idea to use undocumented functionality, you didn't yet get an answer about your question why that functionality is undocumented. Of course, the ultimate answer to this question could only come from Wolfram (because they were making that decision), however here are several common reasons for leaving functionality undocumented (note that this is a general list, not one specific to Mathematica or Wolfram; I'm no Wolfram employee, nor do I personally know one):

  • The functionality was used internally to implement some documented feature, but not considered worthwhile enough to make it documented. Note that making it documented means more than just writing documentation for it (most likely there does exist internal documentation for each undocumented function at Wolfram). It means extensive testing of the function, especially in corner cases. Possibly it even means actually writing additional code for corner cases where for internal functions you'd just throw a "not yet implemented" error (or even just put a warning about wrong results for that case in the internal docs) because your internal usage doesn't need that corner case anyway.
  • The functionality is intended to go public in the future, but is not yet finished. However it is already included for the benefit of own code, which doesn't need the missing parts.
  • The functionality is basically finished and will go public in some later release, but you feel that it hasn't yet gotten enough testing to officially support it.
  • It might also just be an oversight (i.e. someone just forgot to add the corresponding documentation). This is certainly not the case for Internal` stuff (the name is a dead giveaway that it was only meant for internal use), but might be the case for some undocumented or partially documented option.
Improve this answer
$\endgroup$
2
  • $\begingroup$ As a particular example: the function RiemannR[] is currently a kernel function, but in previous versions, it was under the Internal` context. $\endgroup$
    – J. M.'s missing motivation ♦
    Commented May 23, 2012 at 16:17
  • $\begingroup$ just made a similar comment above and have scrolled down to read your answer which covers it all :) $\endgroup$
    – Mike Honeychurch
    Commented May 24, 2012 at 2:11

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.