[self-interest] Re: documentation!
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
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