9 Replies Latest reply on Dec 27, 2012 9:10 AM by TomSchindl

    Unfriendly api?

      As a seasoned Java developer I recognise the advances in look, feel and functionality that JavaFX offers over Swing, and I applaud the project.
      That said, have any of the developers read the likes of Josh Bloch (Effective Java) and Bruce Tate (Better, faster, lighter Java)?
      The JavaFX api disappoints me.

      Take for example the simple parameters of the Circle class constructor.
      Circle(double d, double d1, double d2, Paint paint)
      This is very unfriendly and with just a little bit extra thought and effort could be so much improved.
      According to the javadoc: -
      d is the center x - the coordinate on the x axis for the center of the circle
      d1 is the center y - the coordinate on the y axis for the center of the circle
      d2 is the radius
      paint or rather fill is how to fill the circle

      So why can't we have this information represented in the parameter names?
      Circle(double centerX, double centerY, double radius, Paint fill)
      There are many other examples with the api that would also, so easily benefit from a little more attention. You may well say that its not really important and that the functionality is far more important and further suggest that I stop moaning, but it is important and you are only letting yourselves down.

      If you don't agree with me, go enlighten yourself and read "Better, faster, lighter Java" and "Effective Java".
      Just saying :D

      I would be happy to offer my services to "practice what I preach" if that would help.
        • 1. Re: Unfriendly api?
          I agree, those look like IDE generated parameter names, which have no place in a public API (or even a non-public api for that matter, maybe for a simple private method that would do).
          • 2. Re: Unfriendly api?
            Perhaps you are missing something Sands, the Javadoc for the circle constructor you refer to is:
            public Circle(double centerX,
                  double centerY,
                  double radius,
                  Paint fill)
            i.e. the exact same naming scheme you are suggesting.


            On use of the constructor, when my IDE suggests parameter names, it uses the same names you are suggesting.
            Perhaps you just don't have the javadoc url configured correctly for your IDE, so it is just generating junk names for parameters?
            For Idea, see step 2 of this post => http://stackoverflow.com/questions/13407017/javafx-source-code-not-showing-in-intellij-idea
            Other IDEs (Eclipse and NetBeans) should work similarly when properly configured.

            If there are other specific issues you have with the API, please raise them in the forums under separate posts or on the jira link you can find in the sticky post - surely not everything is ideal.
            Contributions to the codebase can be submitted to: http://openjdk.java.net/projects/openjfx/
            • 3. Re: Unfriendly api?
              Well that explains. So it was just PEBKAC.
              • 4. Re: Unfriendly api?
                I've not missed the javadoc, indeed I state that the 'javadoc says...'.
                That only reinforces my argument because the javadoc specifies better names yet the api does not comply.

                We should not rely on the IDE to provide us with what the api should look like, the api is wrong and should be amended to match the javadoc; not least because leaving it as it is means that the developer maintaining the Circle class, and others, have to manage the badly named parameters within their code. They will be forced to use the d, d1, d2, etc. and that really makes no sense and harms both readability and maintainability.

                I believe the use of parameter names like d, d1, d2, etc. is indefensible.
                • 5. Re: Unfriendly api?
                  The source does not use parameter names like d, d1, d2.

                  • 6. Re: Unfriendly api?
                    Jonathan Giles-Oracle
                    I agree that names such as d, d1, d2, etc are indefensible, but that isn't actually our fault (technically) So, lets be clear what is going on (and I've had to rewrite this response far more times, on Christmas Eve, than I should have to do, but I want to be really clear) :-)

                    The JavaFX Circle class can be seen here: http://hg.openjdk.java.net/openjfx/8/graphics/rt/file/3d2641286b27/javafx-ui-common/src/javafx/scene/shape/Circle.java You should note that it is as you would expect, with proper parameter names.

                    So, if the Circle class looks like the JavaDoc output (which you also regard as fine), then what is going on? Put simply, IDEs can not always get the information out of the compiled classes, as it may be compiled without the names included. To rectify this, you need to specify either the path to the source code for OpenJFX, or the path to the javadoc file. Refer to http://stackoverflow.com/questions/6303943/why-eclipse-is-generating-argument-names-as-arg0-arg1-arg2-for-methods for more information.

                    As you should know, our Javadocs are generated from our code, so if you see something named poorly in javadoc, it will be the same in our code, and vice versa.

                    In short, the JavaFX developers (and I'm one of them) are not being lazy and using bad variable names. We put a lot of effort into naming, to make things as discoverable and understandable as possible. To 'fix' the problem is trivial - but it is between you and your IDE. I mentioned at the beginning that technically we could solve this problem, but that entails building our class files with debug information enabled, which substantially increases the size of our compiled jars, and is therefore not something that is attractive to us (given the ease of the alternative solution).

                    I hope that helps,
                    -- Jonathan
                    • 7. Re: Unfriendly api?
                      You are correct, my mistake. It seems the ide is responsible for the generated names.
                      • 8. Re: Unfriendly api?
                        Glad to hear that you do take naming seriously; I apologise for suggesting otherwise.
                        In a moment of frustration it seemed that it was the api but I stand corrected, I was using a new configuration that was insufficient.
                        • 9. Re: Unfriendly api?
                          The problem for IDE developers is that we need to point our users to a web URL. If e.g. they have not correctly setup the webproxy in their IDE will fail miserably! I hope this will be solved once all of JavaFX is opensourced with JDK8 and we IDE developers can point our code to the real sources.