Yeah, I chose the word “strive” because I agree with you. I think great internal documentation should be a priority, but certainly not an expectation or requirement.
Edit to add quote
1 Like
@gdalle, You are right - although in that particular reply, I was replying to what @Benny wrote about the stability: mainly, there are other things to consider than just properly warning the users about a package having a version less than 1.
But I like how @liuyxpp formulated the larger issue in terms of black magic.
If there is a change for the code to look like black magic to those willing to contribute (and are knowledgeable about the language by the norms of “what is documented”), maybe some additional comments are needed to accommodate the potential contributor.
I don’t want my comments to sound like a brake in the path of innovative solutions or to limit any developer’s expression as he feels right - I am only looking here at the side where some approaches might be less welcoming to those who want to contribute but are less versed in the said black magic.
1 Like
Oh and there’s a flip side to my last comment about communication. To be clear, even if a developer is too busy and overworked to work on a package how they’d like, they will communicate with interested developers if they care about the package, especially if this is a change of package maintainers. They’d probably appreciate someone who would comment the code more thoroughly.
But if you run across a package that hasn’t seen a serious commit in a few years and you can’t get in regular communication with any of the main developers, it’s a good sign that this is an inactive project. If the project is interesting to you enough to fork it and independently revive it, go for it, but I’d look for any active alternatives before that. Basically, communication is a more than just thorough comments.
1 Like
Playing devil’s advocate here: there is also something to be said for black magic. When I read code with a particular syntax I don’t understand, sure it bothers me… but then I look it up and I get a teensy bit smarter. And maybe I’ll reuse it in my own code soon enough.
There are always gonna be various levels of code writing. There are some packages that make me feel like I’m an amateur musician watching a Queen concert. The real challenge is to allow everyone to play the songs at their level.
One way is to publish the sheet music, aka write better code and comments and docs systematically. That’s really hard to enforce. But what’s so great about the Julia ecosystem is that you can also ask Freddy Mercury directly, and he’ll answer you in a matter of days.
7 Likes
I can agree with this - but in such a scenario, I think the author of such code should have a duty to document (locally) that code properly and not let fellow (potential) contributors spend time searching the documentation for things that are certainly not there.
I cannot underline enough that I am not against innovative solutions - and again, I greatly respect people at that level. But I think it is both a sign of respect and quality assurance documenting when you know that something you write is going to be hard to track down. Also - you increase the chance of making the potential contributor feel comfortable enough to start working on that project (instead of making him feel intimidated and consider that he is not yet at the right level to start contributing).
1 Like
I don’t want to derail the conversation, but I would love to be educated here. My understanding of “internals” is methods that are defined in a package/Base which are not documented or documented as experimental, but getproperty(::MyType, ::String) is not implemented at all in Base. There might be an undocumented fallback if I don’t provide a type to dispatch on, but in this case, the developer of the package is defining the behavior of this call, so it won’t be broken by a minor release.
Where am I going wrong here?
3 Likes
As I said in my original post: I also feel that I learn a lot by code reading. And I am also aware that by keeping doing it (and “stealing” the tricks in my code), I make steps to close that gap slowly.
Over the years, I slowly migrated to Julia language as my main language (from F#), and it was a painful experience sometimes (giving up static + type inference + many other bits that make F# special was not easy).
These days I feel that I really want Julia to flourish, and sometimes I have to imagine that some of my painful experiences are also felt by some other programmers that are roughly at the same level I am (and this was an important part of what motivated my original post).
This topic now has a few branches, and not every participant has the time to keep up with all the exchanges.
I will stop here - I have no intention of starting any kind of controversy.
I am thankful to everybody that wrote any public package (using or not black magic). And some black magic is really special - if that were not there, I would have zero opportunity to learn that specific and important lesson.
And yes - it is a great opportunity to be able to come here and have great developers answering almost real-time to any of my questions.
Thank you all.
3 Likes
I wouldn’t consider the signature getproperty(::MyType, ::String) itself a Base internal for that reason, but as my earlier comments show, it’s more about how the parser deals with dot syntax. You can’t put arbitrary subexpressions after the dot to call getproperty, but you can put a Symbol, String, an Int with some difficulty, or interpolate a value. But x.a is the only documented use of that syntax, even the equivalent x.:a isn’t.
3 Likes
Interesting discussion, but is Julia really (very/that much/at all) different from other languages?
- Performance oriented code often looks very different from idiomatic or scripting code.
- Type-safe and generic code often requires many checks and error handling or more abstract thinking in order to cover all possible use cases.
- Libraries striving for a convenient syntax often rely on meta-programming, clever idioms or other black magic. Some communities admire this (Ruby on Rails) whereas others tended to avoid it for longer, but also Python has received many features in this direction.
Another major stumbling point in Julia seems to be multiple dispatch which is vastly more open and extendable than users coming from other languages are used to.I agree with @Benny that getproperty has some uncommon/-documented interaction with parsing of the dot syntax. getindex has methods for all kinds of type combinations without issues – maybe because all kinds of things can be written between [ ] in other languages whereas obj.field seems the only reasonable possibility.
Just to list a few other languages where code can seem very different for any of the three reasons above:
- Common Lisp/Clojure: “Standard code” vs highly type annotated and imperative performance code vs macro heavy libraries.
- Scala: Javaesque code vs highly abstract functional code ala Haskell
- Ruby/Smalltalk: Basic OOP code vs clever syntax extension using black magic idioms
- Javascript: Just pick some SPA frameworks and compare their idioms or even language extensions
- Add your favourite language here …
6 Likes
I have used several languages over the years and as others have said, your Q is true of --all-- of them. 
But at the same time, it’s kind of sad. Documenting any language is impossible to be np-complete. Most of the time, I programmed in C and even after several years of use and abuse, and studying/reading of several good books on it, I still learn new “stuff.” People are very inventive and there is no such thing as a “cookbook” for any particular language. Of all the half-dozen languages I routinely used AND the 4 or 5 I had to use intermittently, Julia is BY FAR the most difficult to wrap my little pea brain around except for the very most basic concepts.
Sure is FUN!!!
4 Likes
There’s an interesting discussion throughout this thread on whether getproperty(value, ::String) is a public method or merely an implementation detail. I agree that it’s currently unclear although the docstring for getproperty to me implies that only getproperty(value, ::Symbol) is public. @Sukera wrote a proposal last month that would allow marking specific methods and not just functions as part of the public API. I was originally skeptical of how much utility that kind of distinction had, but this is a good example of where it would be useful; I think I’m becoming convinced.
6 Likes
Yes; it’s exactly this kind of fuzziness that I wanted to target with the proposal. I think this discussion shows quite well why per-symbol API markers really aren’t enough - the fact of the matter is that “reading code” is merely a good tool for learning to write correct syntax that’s accepted by the compiler; not “good code” or even “supported code”.
3 Likes