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.
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.
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.