Re: [Pharo-users] Behold Pharo: The Modern Smalltalk

I can't remember ever using API docs in any language, dynamic or not.  They give you the method signatures, but if you have, say, methodX(int, int, String), how are you supposed to guess what ints and what String the method actually needs, unless the methods are nothing but getters and setters (which I've never understood the point of) ?  (I know, most give (int somename, int someothername, String whatever), but how often do are method names well thought through enough to imply definitively what the method needs?.   It's my biggest issue with Algol-style syntax - the method caller is supposed to know how it works, rather than whoever actually wrote it.  It's probably at least one of the reasons for the amount of OSS in Java, and more recently in JavaScript (though the latter is more no- style than Algol-style).  I nearly always download the source to OSS libs although I rarely ever bother building it, so I know what a method does with the params, and I can be sure what params to give it. One of my favourite language fails can be reproduced by doing this:  Declare a field private final in Java, initializing it either in the declaration or the constructor, and provide only a getter.  Use the getter from another class and change the value of the local variable. Then use the getter again, but assign the value to a new local variable, and check the value.   Guess what? The value is whatever you changed it to in your other local variable, although the API docs claim javac won't compile it. I tested this with Java 8,  I haven't bothered to see if it was always like that or if they took the rule out of javac because it interfered with some syntactic parmesan, such as lambdas.  I should copy my test code into VisualAge for Java and see if in fact it compiles with JDK 1.4.2, or if javac was changed in between 4 and 8, since the addition of various flavours of syntactic parmesan mostly started with Java 5. Not that it's all that important in one sense.  If 'private' and 'final' were supposed to be guides for other developers to be careful if they're thinking about changing it, fine, anyone who doesn't isn't all that good a developer.  But given the number of 'not very good' developers I've had the misfortune to work with in Java, it's more problematic than it should be.  It also makes the pattern of a private field with a public setter even more useless, since the setter isn't needed to change the value.  I always get dinged by whatever lint companies use for not bothering with that pattern, though, and pointing out that declaring the fields public accomplishes exactly the same thing never helps my case, because whatever lint they use, it has to be right, there's no way a non-lint developer might be right. Andrew Glynn -----Original Message----- Date: Wed, 11 Oct 2017 10:01:20 -0500Subject: Re: [Pharo-users] Behold Pharo: The Modern SmalltalkTo: pharo-users@lists.pharo.orgReply-to: Any question about pharo is welcome <pharo-users@lists.pharo.org>From: Offray Vladimir Luna Cárdenas <offray.luna@mutabit.com>                   Yes. I know them. I mean API docs as static files. I don't really       sold on them compared with a live system and I don't think static       API docs are critical for Pharo success.     Cheers,     Offray               On 11/10/17 09:52, Dimitris Chloupis       wrote:          

Ah       and my static website was built with Pillar and Bootstrap, using       bootstrap templates was easy because Pillar supports mustache that       makes html manipulation much easier 

      

      http://www.kilon-alios.com

      

      Pillar of course is not made for generating websites but it’s an       awesome Pharo library that allows for great degree of freedom so I       thought , why not ?

               On Wed, 11 Oct 2017 at 17:48, Dimitris Chloupis           <kilon.alios@gmail.com> wrote:

                 

...

Docs are           available in static online html format , at least the book I           was working on 

          

          Pharo By Example 

          

          You can find those links here

          

          https://github.com/SquareBracketAssociates/UpdatedPharoBy Example

          

          Our documentation system , Pillar , outputs pdf , html and           markdown files. 

          

          If the book in question is built like PBE with CI of Inria           where most Pharo related official projects are built then it           should have at least pdf and html with online access so you           can easily link to.

          

          Don’t quote me on this but I think the html output of pillar           generate links even for paragraphs you can do an even more           process linking to the documentation. 

                       On Wed, 11 Oct 2017 at 17:40, Offray Vladimir               Luna Cárdenas <offray.luna@mutabit.com>               wrote:

                         

...

                               The more I use Pharo, the less I use web                   documentation. For me seems pretty suboptimal compared                   to live environment with code browser and GT- Spotter.                   Regarding the comment on Medium, it also took me                   little to find #raisedTo:, so the millage can vary.                   What I was missing was proper books for particular                   domains, but Pharo books are covering that. I don't                   know if a Q&A site could improve search-ability                   for newbies (certainly you can find little stuff in                   Stack Overflow).                 My bet is about trying to create more "end user"                   tools (Grafoscopio is kind of this), besides tools for                   developers. There is a broad community of people who                   can be active contributors and members of the                   community, welcome Pharo and live coding a lot and                   don't complain that much about stuff that is not                   already pretty similar to what they already know                   (being that only English MOOC or online static html                   docs).                 Cheers,                 Offray

                                               

                On                   11/10/17 07:34, Dimitris Chloupis wrote:

                                 

...

                  for me it is a yes and no situation,                     yes its very coold to have your entire system in                     your fingertips but Pharo has serious issues with                     code organisation and I find the lack of namespaces                     quite inconvenient. You have to be careful how to                     name your classes which does not sound to me very                     OOP friendly.                      

                                         Also the IDE does not handle spaggetification                       very well, sure you can find implementors ,                       senders etc but if the execution chain is complex                       , welcome to spaggeti hell. But that is a problem                       with most other IDEs if not all as well. Problem                       is in this case that we have the very good rule of                       using sort methods which multiplies this problem                       and makes navigation even harder. Code becomes                       much easier to read per method and messages but                       much harder to understand in a bird eye view.                     

                                         Some of that pain has been aleviated with the                       introduction of GTSpotter which I have praised                       quite a lot and I will continue to do so. But yeah                       there are more needed to be done in the department                       to make Pharo code navigation a more comfortable                       task.                                       

                                       On Wed, Oct 11, 2017 at 2:57 PM Vitor                       Medina Cruz <vitormcruz@gmail.com>                       wrote:

                                         

...

                                                                          I dunno, maybe I’m weird, but I find                           the System Browser a fantastic way to explore                           the class library. If you find a class or                           method that isn’t well documented, write a                           comment and send a change request. Stef told                           me this ages ago. I might add, if you find a                           bug you should write a test that exercises the                           bug and submit it on fogbugz (the bug tracking                           system).

                                                 

                                                                      I will reference of response of                           mine to a similar opinion made by Richard: https://medium.com/@vitormcruz/i-disagree-it-is-much -harder-to-find-anything-in-the-environment-c6bdd44f6eea                         My 2 cents.                         

                                                 

                                             

                        On Tue, Oct 10, 2017 at                           11:59 PM, john pfersich <jpfersich@ gmail.com>                           wrote:

                          

...

                              > On Oct 10, 2017, at 09:58, horrido                               <horrido.hobbies@gmail.com>                               wrote:

                              >

                              > Interestingly, I'm getting a fair                               amount of pushback on this. Personally, I

                              > think it would be very helpful to                               have a live (updatable, so as to keep it

                              > current) reference page for the class                               library, something that developers can

                              > easily look up what they need. After                               all, most of the power of Pharo comes

                              > from the class library and we need to                               make it as accessible as possible to

                              > less experienced Pharoers (i.e.,                               beginners).

                              >

                              > Exploring the class library through                               the System Browser is very inefficient.

                              > This is further exacerbated by the                               fact that many classes and methods are

                              > simply not well-documented                               (containing a cursory remark which is just                               barely

                              > useful).

                              >

                            I dunno, maybe I’m weird, but I find                             the System Browser a fantastic way to                             explore the class library. If you find a                             class or method that isn’t well documented,                             write a comment and send a change request.                             Stef told me this ages ago. I might add, if                             you find a bug you should write a test that                             exercises the bug and submit it on fogbugz                             (the bug tracking system).

                                                           

                                > I realize that creating a live                                 reference page is not easy to do. In                                 fact,

                                > it's a lot of work. But the absence                                 of such a page is a real obstacle to

                                > Pharo acceptance.

                                >

                                >

                                >

                                > horrido wrote

                                >> Thanks. I gave your answer                                 verbatim. I also added the following                                 paragraph:

                                >>

                                >> The problem I find with today’s                                 developers is that they are rather

                                >> closed-minded. They are rigid                                 and inflexible, and not willing to adapt                                 to

                                >> new and different ways of doing                                 things. In my generation (circa

                                >> 1980–1990),

                                >> people didn’t have a problem                                 with trying different technologies.                                 That’s

                                >> why

                                >> I had no issue with learning                                 Smalltalk 10 years ago, after I had                                 retired

                                >> from a 20-year-long career in C                                 systems programming and FORTRAN                                 scientific

                                >> programming.

                                >>

                                >>

                                >>

                                >> Sven Van Caekenberghe-2 wrote

                                >>>> On 6 Oct 2017, at                                 14:54, horrido <

                                >>

                                >>> horrido.hobbies@

                                >>

                                >>> > wrote:

                                >>>>

                                >>>> I received this comment                                 from someone who complained:

                                >>>>

                                >>>> *What about the lack of                                 documentation? From time to time I’ve                                 checked

                                >>>> some

                                >>>> SmallTalk                                 implementations like Squeak,                                 GNU-Smalltalk and now Pharo. Of

                                >>>> these, only                                 GNU-SmallTalk appears to have a free,                                 official programming

                                >>>> guide

                                >>>> and core library                                 reference that any serious programmer                                 expects from a

                                >>>> language.

                                >>>>

                                >>>> https://www.gnu.org/so ftware/smalltalk/manual-base/html_node/*

                                >>>>

                                >>>> I pointed to Pharo's                                 documentation but then he came back                                 with:

                                >>>>

                                >>>> *Then show me a link of                                 the free, maintained reference                                 documentation for

                                >>>> the

                                >>>> classes that form “the                                 core library”, like this one for Python

                                >>>> (https://docs.python.o rg/3/library/index.html)*

                                >>>>

                                >>>> It's true, most                                 Smalltalks do not have a core library                                 reference, not

                                >>>> even

                                >>>> VisualWorks! So what is                                 the proper response to this complaint?

                                >>>

                                >>> The first answer is that                                 Pharo/Smalltalk is unique in that a                                 running

                                >>> system/IDE contains _all_                                 source code, _all_ documentation (class,

                                >>> method,

                                >>> help, tutorial), _all_ unit                                 tests and _all_ runnable examples in a                                 very

                                >>> easy, accessible way. It                                 takes some getting used to, but this is                                 actually

                                >>> better and much more                                 powerful than any alternative.

                                >>>

                                >>> The second answer is that                                 there are lots of books and articles                                 that take

                                >>> the classic/structured                                 book/paper approach. There is

                                >>> http://books.pharo.org,                                 http://themoosebook.org,

                                >>> http://book.seaside.st/ book,                                 http://medium.com/concernin g-pharo                                 and many

                                >>> more.

                                >>>

                                >>>> Thanks.

                                >>>>

                                >>>>

                                >>>>

                                >>>> --

                                >>>> Sent from: http://foru m.world.st/Pharo-Smalltalk-Users-f1310670.html

                                >>>>

                                >>

                                >>

                                >>

                                >>

                                >>

                                >> --

                                >> Sent from: http://forum. world.st/Pharo-Smalltalk-Users-f1310670.html

                                >

                                >

                                >

                                >

                                >

                                > --

                                > Sent from: http://forum.w orld.st/Pharo-Smalltalk-Users-f1310670.html

                                >