[self-interest] Re: documentation!

Bystroushaak bystrousak at kitakitsune.org
Sun Jul 24 00:33:40 UTC 2016

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 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.

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.

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.

 > 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.

Truth is, that I am still at least 100 times more effective in python. 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.


* 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 

- 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.

More information about the Self-interest mailing list