Document guidance for changes in unexported functions #12696
Conversation
|
The goal here is to explain how things currently work (not what we want to have!), and to provide some guidance. A few things to consider:
and 3) Is the guidance appropriate / sufficiently complete? |
| variables, functions, types, and the fields of composite types are publicly | ||
| accessible. Julia does not have corresponding "private" versions of these | ||
| items that are inaccessible from outside the module. However, a common | ||
| Julia convention is that names prefixed with an underscore (e.g., |
There was a problem hiding this comment.
Is it really true that this is a "common Julia convention"?
There was a problem hiding this comment.
No. We tried it out and it's too annoying.
There was a problem hiding this comment.
I'm not at all wedded to this language. Perhaps just "However, names prefixed with an underscore are private implementation details."
However, I just grepped base for " _" and found ~600 lines that look like names (primarily functions) intended to be private. For example, osutils.jl:12 has a function _os_test() that looks like it's used only in the macros just below, and it seems like it's intended only for internal consumption. So it does seem to have crept in there.
There was a problem hiding this comment.
Yeah, we were trying it out for a while and there's still a lot of these names hanging around.
|
I don't think its good to document this. While this is how it currently works, it strikes me as suboptimal and putting it into the documentation kind of says: We are happy about this. |
|
No, I don't see that we have to be happy about it, even if it's documented. I think writing this down helps to clarify what we don't like ("Unexported and undocumented"-- ugh). The documentation can change with the fixes. |
|
Maybe be explicit in the documentation that we are not happy with it, and it might change in the (hopefully near) future? |
Please, no. Language documentation should have an objective voice. Otherwise its just chaos. |
|
Yeah, I considered that, but came to the same conclusion as @aviks |
|
OK, good point, @aviks |
Fixes JuliaLang#12647 Explains the public nature of Julia names. Also provides guidance for breaking changes in public APIs vs. unexported names. [ci skip]
rsrock
force-pushed
the
rsr/doc-public-private
branch
from
22d62c3 to
88c7771
Compare
| may change at any time, with or without warning. Therefore, usage outside of | ||
| their parent module carries certain risks. We recommend that all such usage is | ||
| clearly commented in code. At the same time, unexported but externally "popular" | ||
| names should be considered for inclusion in the exported public API. |
There was a problem hiding this comment.
Perhaps this should be strengthened to include @tkelman point, that authors should make a good-faith effort to avoid unnecessary code churn.
|
Closing as #12647 is closed now and this is pretty old now. |
|
👍 I don't even like this anymore. |
Fixes #12647
Explains the public nature of Julia names, and how to obtain some measure of
privacy when needed. Also provides guidance for breaking changes in public APIs,
unexported names, and private (underscore) names.
[ci skip]