[self-interest] Re: documentation!

[David Ungar]

- David (from iPad, typos likely)

> On Jul 23, 2016, at 5:33 PM, Bystroushaak bystrousak at kitakitsune.org [self-interest] <self-interest at yahoogroups.com> wrote:
> 
> Dne 23.7.2016 v 02:58 David Ungar ungar at me.com [self-interest] napsal(a):
>> I have found that comments that document code tend to lie. Machine-checkable
>> info is more reliable.
> 
> I've seen this approach, but never understood it. Lying comments are 
> bugs, which should be fixed and updated mercilessly. For me, it is no 
> different from the bug in the code.

In my experience such comments do not get fixed. Redundancy that is enforced manually is both ineffective and immoral. Ineffective because things do get out of sync. Immoral because it uses people's time for something that could be automated, decreasing the amount of time for creativity in the world. But all this is relative to my experience and value system. We could discuss which of us has more experience, but we are unlikely to change each other's values.
> 
>> In a live environment, such as Self, you can just try something out to
>> see if you are passing in the right argument. It's a different way
>> to work.
> 
> Yes, I've noticed. But this is really hard for beginners, because it 
> forces you to try everything in various ways, before you can make 
> assumptions what the method does and use it. Result is, that it takes me 
> 2 hours of testing and putting together mental image of the API to write 
> the 30 lines long method.

That's not how I recall learning Smalltalk, but maybe you'll get faster as you keep at it. I don't think the Blue Book existed when I learned Smalltalk.

> 
> This is also partially because I have to search for things and browse a 
> lot of outliners and the environment is not really effective* and 
> sometimes I just wish that there would be fuzzy full text search ala google.

Yes that would be nice. You might be aware that findSlot implements limited regular expressions. Do you have any interest in writing such a search tool? All the reflective facilities are there.

> 
> Also for non-native english speaker, it is sometimes really hard to get 
> what the method does just from the name and what the "k" argument means. 
> From my experience, short description would be really helpful.

Why do you think it is harder for a non-native English speaker to understand "k" than a native one? Could you show us the method where the "k" argument was confusing? I find that the method itself usually furnishes a nice short description.

> 
>> Dynamically-typed languages without live, graphical IDEs are the worst
>> of both worlds.
> 
> I work as a python programmer. I've worked with larger codebases (40k+ 
> cloc) and only way how this is manageable is extensive documentation. 
> Also linters can help a lot.

IMO, Python is probably broken because it has neither static typing, nor a live environment. But I little experience in it. It doesn't surprise me that extensive, manually-maintained documentation would seem attractive given such a state of affairs. But there are far better ways.
> 
> Truth is, that I am still at least 100 times more effective in python.

How long have you worked with Python? How long with Self? The trouble you are feeling with Self may well be the result of learning new ways to think. I also suspect your factor of 100 is an exaggeration. Have you timed yourself with a stopwatch?

Have you read Hanenberg's work? He has measured the effects of various language tradeoffs on productivity, carefully. Confirmation bias makes us all poor evaluators of our informally-assessed experiences.


> I 
> know, that Self offers more, but for me, it is really hard to master it. 
> Not the language, but the environment and stdlib. It feels like a toy 
> with rough edges not worn out by a lot of users. But I like what it offers.

Thank you for the kind words. I am sorry you are frustrated. But it's different. You may find it easier to pick up Smalltalk first. The Self project developed much of what become ubiquitous later, including the use of cartoon animation techniques for interfaces, mirrors for reflection, and adaptive optimization and deoptimization. It also came up with a prototype-based object model that heavily influenced NewtonScript, and somewhat influenced JavaScript. All this in about seven years and with 6 people, on computers with 16Mb of RAM that ran much more slowly than today. Since 1993, it has been largely unfunded. If you find rough edges, I hope you fix them! It is amazing to me that Russell and others do as much as they do. 

You might want to watch an experienced Self developer work sometime. One can really fly! No need to edit-and-compile. Write your code in the debugger. Move things around, arrange columns of yanked-out method outliners from here and there to keep all the things you need to look at in one place. Fix a bug and restart where the bug hit. Shortcuts for implementers, senders, findSlot. 

I'll come back to my suggestion that you learn Smalltalk. Once you're comfortable there, try Self again.

BTW, have you find the double-click shortcut for the triangles? 

And I can't resist this--thanks in advance for understanding--
"The fault, dear Brutus, is not in our stars,
But in ourselves" -- Shakespeare

(You should have seen me learning a functional type system last year!)

> 
> ---
> 
> * So far, I've been able to notice following annoyances in UI:
> 
> - Ridiculous amount of scrolling (with the mouse, only vertical 
> scrolling works).
> 
> I think there is need for some kind of shortcut to jump half the page 
> up/down/left/right. Maybe cmd+arrow. I know, that radar view may be used 
> for jumping around, but I forget it somewhere all the time and also it 
> is mouse oriented.
> 
> - Ridiculous amounts of clicking on triangles to expand categories and 
> subcategories in outliners.
> 
> Maybe it would help to expand everything by default. I will have to try 
> this.
> 
> - Editor. I know that there is some kind of basic emacs shortcuts 
> support, but I think this will need to be updated and configurable. 
> Mainly because no one who began using computer in the windows era knows 
> the emacs shortcuts, if he is not already using the emacs. Also support 
> for indentation, highlight and infinite undo/redo would be nice.
> 
> -
> 
> Note: I did write it here to discuss this, not because I expect that 
> someone will fix this.
> 
> 
> 
> ------------------------------------
> 
> ------------------------------------
> 
> 
> ------------------------------------
> 
> Yahoo Groups Links
> 
> 
>