Recommending use of namespaces

[ehennestad]

This discussion is ongoing in issue #31, but I thought it deserves a separate issue.

As this repository describes the best practices, I would really like to see a recommendation for use of namespaces, and specifically also using a root namespace specific to each toolbox, i.e toolbox/+<toolboxname>/all-code-goes-here

There are many good reasons for using namespaces:

• Supports using the same function names scoped to different namespaces, i.e avoids potential path conflicts
• Maintaining the search path is easier. For users updating repositories via git, if all functions are inside namespaces, newly added functions are guaranteed to be added to the search path, whereas if code is organised in regular subfolders, functions in new subfolders are not and add the extra burden of communicating this to users.
• When reading code, the full namespace name + function name gives a lot of useful context, like which toolbox the function is part of and potentially what subdomain it belongs to. I also immediately know that this is not a builtin MATLAB function.

On the other hand:

• Might feel awkward for smaller repositories with one or two or three functions.
• Is not so widespread, so familiarity might be a problem.
• Coming up with good namespace names can be hard.

I think the benefits outweigh the disadvantages, and this repo can serve to set good examples for people to follow and inspire more widespread use of namespaces.

Interested in hearing other opinions :)

[rpurser47]

I'm a big fan of promoting the use of namespaces more. Let me draft something (probably as a separate document) and we'll see how it evolves. We can debate it when I've got a branch with a strawman artifact to discuss.