Hidden in Plain Sight (DLLs & Documents)

There seems to be a penchant from software to hide its true ability, to obfuscate the obvious and even publicly visible guts of itself, anyone whom has had to program - properly program - for the windows platform will know what I'm hinting at... All those little hidden nuances, undocumented features, or flat out bugs.

This isn't to say all of them are hidden, or secret, but lots of things are.  Either through being close source software, or whatever you want to call it, but point of fact is, if you publish an interface for people to use and in that interface they can see many many things, you need to document them, even if your document warns people off of them.

By not documenting them you're not going to keep people from seeing them, they're there, and you're not going to stop  people poking and prodding them.  So, what are you achieving by pretending these kinds of things are not available?  Or not there?

Lets look at a case study... You are working for "Software Matic Corporation" and you release the new "SMC Interface" as a dynamic link library, and in that library's documentation you list the calls you want people to use, and they are:

"Connect"

"Disconnect"

"GetStatus"

Three, pretty innocuous calls, and you document not to call "GetStatus" before "Connect" and not to call "Disconnect" too soon and all the other rules.  And you shuffle this out the door for release.

Then Mr Software user at the other end, opens your dynamic link library and takes a look and he see's other calls... like;

"TellSMCSecrets"

"FormatHarddrive"

"CrashSystem"

And he starts to poke and prod these calls you never mentioned, and never intended anyone to use, and what happens?... Well, at the worst case Mr Software guy crashes his software or ruins his machine.  But will he blame his software?  Or will be blame your DLL?...

After all YOUR software call caused the problem... YOU released software with that call in it... YOU put it in the public interface!

You never intended the calls to be used, so they should not have been exposed in the public interface, not simply omitted from the document, omitting from the document is just wrong, its the software equivalent of denying the sky is blue (note: the sky is blue folks).

And if you Do put something in an interface like this DO put it in the document, don't exercise this penchant for omitting things.  Even if you only give is cursory "PRIVATE FUNCTION DO NOT CALL" note, its better than risking the ire, or even bad PR which comes from not mentioning something which is sat right there begging to be used.