Fine with me as long as we don't over do it with tags (i.e. KISS).
We start with just a minimal description, we document parameters and return values which are non-obvious, and we can always add more information about a given function's purpose later on. I doubt overdocumentation will be an issue.
- Execution speed. I don't think it is easy for a naive, or not so
naive, compiler to make direct calls to the functions. Say you have a module foo which calls memory.ptrAdd(x,y). How will you tell the compiler in foo that "memory" is a namespace object?
As I said, we can make memory a read-only global object property, and we can make any of its properties read-only as well, in the worst case, to completely enforce non-redefinability, so performance is a non-issue.
- It obfuscates the code. I think it is much clearer (and in fact
somewhat shorter and with less indenting) to use identifier prefixing
That's because you're very used to this naming *scheme*.
- You can only use functions from that namespace once the whole namespace
object is constructed. This will make the construction of constant tables awkward (when the elements of the table are objects whose constructor is defined in the namespace). This happens for example in scanner.js, and I expect it to occur in many other places in the compiler.
That's a good point. However, we could also use a different syntax where we define the module first as the empty object, and add functions later. This would address that issue, you then simply have to make sure that functions were defined before calling them. And as I've just said, these could be made read-only.
KISS... so I propose we use identifier prefixing at first. If it becomes a problem we can refactor the code (changing client code is trivial... a sed script to map "memory_" to "memory.").
It's mostly a problem with JsDoc. It doesn't separate functions by file, or sort them by name, as far as I've noticed... Because JavaScript programmers don't tend to just write all functions in the top level.
So I propose this notation instead:
/** @namespace */ memory = {}
/** Adds a signed offset to a pointer value @param ptr pointer to raw memory @param val signed offset */ memory.ptrAdd = function(ptr, offset) { }
/** Computes the difference between two pointers */ memory.ptrSub = function(ptr1, ptr2) { }
Because: - JsDoc can document this effectively - It's easy to understand - Solves the ordering issue you mentioned - It's also a clearer, more sensible style - It's more in line with the way people actually use JavaScript
So I propose we *KISS* and not worry about premature optimization. We should hope that our compiler will be able to properly optimize such a simple case, and if not, we can fall back to making the modules and their function properties read-only.
- Maxime