Codethulhu's API menagerie


  • Discourse touched me in a no-no place

    From the documentation of a client library I'm looking at (written in Java; a DSS is a “data store server” which is a component of the service that this is a client for)…

    tryLinkToContents

    java.io.File tryLinkToContents(java.lang.String overrideStoreRootPathOrNull)
                           throws InvalidSessionException
    

    Returns a File, if possible, that directly references the contents of a data set in the data store server. This is only possible if the file system used by the DSS is also mounted locally.
    Parameters:
    overrideStoreRootPathOrNull - A path, in the context of the local file system mounts, to the DSS' store root. If null, paths are returned in the context of the DSS' file system mounts.
    Returns:
    Returns null if the operation is not possible (e.g. when the data set is a container), a File that references the contents of the data set otherwise.

    First thing to note, those fonts are about right; the description of the parameter and the result really are formatted like that in the docs (because raisins).

    Secondly, starting a method name with try is very strange in Java. The only way it could have been much odder is if it had started with Try. Do or do not, there is no try.

    But the real weird parts are the way it loves doing special behaviour with a null argument — complete with odd naming of argument, of course — and the way it indicates failure by returning null. (Except if you don't have a session with the server, which is a part that must have been written by someone else, someone who isn't a knucklehead.)

    Done right, this would have been two methods with sane signatures and sane failure modes. Yes, that might have made things more different from the wire protocol used for talking to this server, but it would have stopped users of the code from having to gaze into the abyss of stupid.


    This method isn't very special by comparison with the rest of the client API either. It's also less :wtf:-ridden than the server, but that's just such a mess I don't feel up to summarising it yet…


  • BINNED

    @dkf said in Codethulhu's API menagerie:

    Done right, this would have been two methods with sane signatures and sane failure modes.

    The whole way it works smells of PHP, TBQH.


  • Discourse touched me in a no-no place

    @Onyx It's Java and Python. I installed the fucker in a VM. It's definitely Java and Python.

    It would probably have been better if it had been PHP… 😱


  • BINNED

    @dkf The complaints you raised sound like something someone would do in PHP is what I meant:

    1. PHP cannot overload methods
    2. PHP functions do this return shit a lot. Like, strpos, given how similar it is to C you'd expect 0 or positive integer if substring found, -1 if not found. Nope! It's boolean FALSE in case it's not found. Many functions do this.


  • This post is deleted!

Log in to reply