Issues

Issue #609 resolved

love.filesystem naming

hahawoo
created an issue

love.filesystem.mkdir is a good name because it's very obvious to people who know what "mkdir" means. When I first saw it, I'm sure I knew exactly what it did, and you, whoever is reading this, probably did too.

However, I'd say there are many people out there who don't know what "mkdir" mean, and for them this name could be confusing.

It's also unpronounceable (well, I'm sure we have our own pronunciations of it. :D), seems to not fit in with the general naming aesthetic IMO, and also it doesn't really have anything to do with the command line program mkdir, other than what it does.

love.filesystem.enumerate is also a bit of a puzzling name. Having to guess what this function does if I had never used it or read about it, I would have no idea.

So I was thinking... maybe... love.filesystem.makeDirectory and love.filesystem.getDirectoryItems? I know these names are longer... but maybe their obviousness is worth it?

Comments (20)

  1. Bart van Strien

    I'd say mkdir and others are standard names, except for enumerate, maybe. The problem with enumerate is that it accurately describes what's going on, enumerateItems (what else?), enumerateFiles (what about directories?) and other alternatives I've come up with don't seem to cut it.

    EDIT: Oh, and getDirectoryItems doesn't suggest being an iterator.

  2. hahawoo reporter
    • changed status to open

    mkdir is certainly a standard name, but is it a good name? :D I dunno, I think makeDirectory is better, because you can say it, and it translates directly to what it does; it makes a directory. And it's easier for people who don't know what "mkdir" means, and it's just aesthetically consistent with LÖVE's API.

    getDirectoryItems definitely doesn't suggest an iterator. But unless it's been changed, it's not an iterator, it returns a table. I think getDirectoryItems is a good name, because like makeDirectory, it says what it does: it gets the items in a directory.

  3. hahawoo reporter

    Why is an iterator needed when there is pairs?

    I think the current enumerate function is more flexible than an iterator.

    You can get the number of items in a directory...

    #love.filesystem.enumerate(dir)
    

    You can sort items, maybe by name, or file extension, or something...

    t = love.filesystem.enumerate(dir)
    table.sort(t, sorting_function)
    

    And of course you can iterate with pairs.

    for _, item in pairs(love.filesystem.enumerate(dir)) do
    

    The reason why an iterator is useful for something like lines is (correct me if I'm wrong!) that it only reads a line at a time, instead of having the load the whole thing first.

  4. hahawoo reporter

    Oh yeah totally, but it's the difference between this:

    for _, item in pairs(love.filesystem.enumerate(dir)) do
    

    and this

    for item in love.filesystem.enumerate(dir) do
    

    at the cost of flexibility.

    Edit: It's analogous to love.window.getModes. That could be an iterator too, but you might to sort it, for example.

  5. hahawoo reporter

    And in regards to having both, I think iterating with pairs and iterating with an iterator just isn't different enough to warrant the shortcut. love.window.getHeight() is pretty different to select(2, love.window.getMode()), love.mouse.getY() is pretty different to select(2, love.mouse.getPosition()), Canvas:renderTo(f) is pretty different to love.graphics.setCanvas(Canvas) f() love.graphics.setCanvas(), love.filesystem.write(name, data) is pretty different to do local File = love.filesystem.newFile(name, 'w') File:write(data) File:close() end, etc.

    Edit: What I mean to say is, I don't think what it offers is worth the additional API complexity of having it.

  6. Kingdaro

    What about love.filesystem.list instead of love.filesystem.enumerate? It's shorter, clearer, and sufficiently explains the function's purpose.

  7. Alex Szpakowski

    I like love.filesystem.list. I don't think an iterator function is needed, (i)pairs works fine and I think calling table.sort on the table is maybe not too uncommon.

  8. hahawoo reporter

    I like the conciseness of list, but it doesn't fit LÖVE's naming scheme. Functions which return something (other than a single boolean) and don't have any side effects generally start with get.

    It's also not very descriptive about what exactly it's a list of.

  9. Alex Szpakowski

    I don't think it's necessarily a good idea to name things in a contextless void. When you do that, names start to get way more descriptive than they ever actually need to be (see: Java, Cocoa.)

  10. hahawoo reporter

    Agreed!

    list is still inconsistent by not starting with get though. And if it were getList, the question could still be asked, what is it a list of? Mounted directories/archives?

    Perhaps there aren't so many alternative interpretations, but it's still not super obvious it's about directory items.

    I think getDirectoryItems says what it does succinctly and isn't longer or more verbose than quite a few other functions.

  11. Alex Szpakowski

    If the name is supposed to be following LÖVE's conventions instead of POSIX-ish ones, why makeDirectory instead of createDirectory or newDirectory or something?

  12. hahawoo reporter

    The new prefix seems to be used for creating new LÖVE objects, which this function doesn't do.

    createDirectory sounds fine to me!

  13. Alex Szpakowski

    As was discussed above, enumerate probably fits better as an iterator.

    getDirectoryItems doesn't imply files, either.

    That's a good thing, because it doesn't just return files.

  14. Log in to comment