BlueStyle

BlueStyle copied to clipboard

The BlueStyle conventions are great!

I was wondering if people would be interested in discussing adding some guidelines on when to use export and how that relates to the current section on using using and import. Additionally, it would be nice to clarify if how this guideline on module imports changes if at all in various contexts (REPL, scripts, packages, etc).

My personal opinion everything that is part of your public API should be exported. And if that results in name clashes for your users, then they should deal with it, via const load = JLSO.load or const load = FileIO.load. Or via explict using JLSO: JLSO to avoid bring things they do't want into scope.

---

But I think most people move towards the position the YASGuide has. And I would be down for that for sake of convergence. And because it does have solid upsides.

It's friendly to selectively export module bindings, but unfriendly to export everything. A module should export unambiguously named bindings that are part of the module's intended API. It's also okay to not export (but document) functions that are intended to be called in qualified form, e.g. CSV.read.

I would also be okay with adding the YASGuide advice to the Blue style

The actual style for writing exports is basically the same as for writing imports, i.e something like

Exports should occur towards the top of the file after imports. Files loaded via an include should avoid specifying their own exports and should instead add them to the file in which the module was declared (e.g. "src/Example.jl").

Exported should be grouped into: constants, types, macros, and functions. These groupings should be specified in that order and each group's contents should be sorted alphabetically. As pseudo-code: export $(sort(constants)...) export $(sort(types)...) export $(sort(macros)...) exports $(sort(functions)...)

Thanks for the links and the comments, this is all very useful!

This is not directly related to a guideline suggestion, but I was experimenting in the REPL just now, and this caught me by surprise.

Case 1

1. Create a module Foo that exports a symbol that exists in Base (e.g. read)
2. Open a new REPL and type using Foo.
   • No warnings or errors
3. Use the conflicting symbol in any way (e.g. read(), read("test.jl"), read(`ls`))
   • Warning and the user gets a UnDefVarError that the symbol in question is not defined. Any further use of the symbol results in a UnDefVarError.

Case 2

1. Create a module Foo that exports a symbol that exists in Base (e.g. read)
2. Open a new REPL and use the symbol that will be conflicting in the future (e.g. read("test.jl"))
3. Type using Foo.
   • Warning is issued about a conflict.
4. Use the conflicting symbol (e.g. read(), read("test.jl"), read(`ls`))
   • The user gets a UnDefVarError if the symbol exported is a method that will be dispatched on. All other uses of the symbol do not raise a UnDefVarError error.

It seems like if you export a symbol that causes a conflict, it may result in breaking existing code, as described in Case 1 / screenshot top right. It'll only not result in errors if a method by the same symbol name in question has already been dispatched on (? not sure if I'm missing something here), as seen in Case 2 / screenshot bottom right.

My takeaway from this contrived example seems to be that, because as a package developer you don't know ahead of time what name conflicts might occur in the user environment, you should export as minimally as required, only using export to make some interfaces easier to call for the user from REPL environment, and that exported symbols are not tied to the public interface. The intended API is only what is documented to be so. This is similar to the YASGuide suggestion, but leans towards being more conservative on what symbols to export.

Thoughts?