"internal" folder doesn't achieve it's desired objectives

[michellehirsch]

The best practices recommend:

"Any supporting code should be put in an internal folder at the top level of the toolbox folder to make it clear that these functions are not intended for end users. If you have a lot of internal functions, consider creating subfolders to group them logically."

Since folder names don't show up in programmatic interfaces, there are no hints to an end user that functions in internal aren't meant for them. So I don't think this standard achieves the desired objective.

I would expect the recommendation to be to use a private folder so it is functionally off the path. For more complex toolboxes that need to call internal functions/classes from code in multiple folders, we could recommend +internal, or better yet, +arithmetic+internal.

[rpurser47]

We intentionally avoided private here because the scoping rules of MATLAB make code in private folders only visible to the parent directory, making it unsuitable for toolbox-wide utilities classes. I'd prefer using namespaces, and doing +arithmetic/+internal would make a lot of sense, but we have not seen a lot of adoption of namespaces in MATLAB code, and so it felt inappropriate to introduce a relatively esoteric feature for most MATLAB authors.

[alexander-hagerman-bose]

We intentionally avoided private here because the scoping rules of MATLAB make code in private folders only visible to the parent directory, making it unsuitable for toolbox-wide utilities classes. I'd prefer using namespaces, and doing +arithmetic/+internal would make a lot of sense, but we have not seen a lot of adoption of namespaces in MATLAB code, and so it felt inappropriate to introduce a relatively esoteric feature for most MATLAB authors.

Namespaces are something that we had seem some initial resistance to, but over time there has been some acceptance because users and developers understand how problematic shadowing is, and that namespaces are one of the best ways to prevent shadowing (in our experience). That said there isn't a lot of Mathworks published code that leverages namespaces, so I'm not sure if the lack of adoption is indicative that namespaces are not well received, but rather they are not something that is part of Mathworks code examples while reading the docs, so it's not something a toolbox developer immediately reaches for when authoring their toolbox. Additionally I have found that most toolboxes start out on one persons machine, then may get shared with their team before getting promoted to a wider context where name collision/shadowing becomes a problem.

I also like that namespaces provide the opportunity to convey additional context as you demonstrated with +arithmetic/+internal.

[michellehirsch]

Thanks. My pull request includes these recommendations. I start with private folder since that's easy and serves many users well and recommend use of a namespace for users who need to call from multiple folders. There's already another section of the guide lightly recommending the use of namespaces, so I'm not concerned about adding it here for users with bigger toolboxes.

[rpurser47]

I'm OK with doing +<toolboxname>/+internal instead of internal. I'd like to avoid bringing private into the conversation, since it can lead to some hard to diagnose situations where a utility function isn't accessible once a toolbox grows beyond a single directory. Thoughts @gulley , @bpancras ?

[rpurser47]

@michellehirsch Per our in-person discussion, we agreed that we'd leverage the decision point around greater than 20 commands and recommend toolbox/private in the case of 20 or fewer commands, and recommend the namespace toolbox/+<mytoolboxname>/+internal in the case when you have more than 20 commands. Can you update #32 to reflect this?

[rpurser47]

Premature close. Reopen until #32 is merged.

[rpurser47]

@alexander-hagerman-bose Thanks for your thoughts on this! Love to hear other insights. I agree that we should probably promote the use of namespaces more in toolboxes. What do you think of the idea of recommending the use of a top-level namespace like +arithmetic?