From: Robert Weiner <rsw@gnu.org>
To: Eduardo Ochs <eduardoochs@gmail.com>
Cc: Org Mode <emacs-orgmode@gnu.org>
Subject: Re: Org, Hyperbole, and eev
Date: Tue, 28 Jun 2022 02:26:23 -0400 [thread overview]
Message-ID: <CA+OMD9hGUjV7Vo-k6RYBVEDxVo6nKuo0bAZVvSJ8dAU+jVLH2Q@mail.gmail.com> (raw)
In-Reply-To: <CADs++6gCOjqUazgso-JLd9HA08ESCD4Kjpcbc_j26+BKyAbF+A@mail.gmail.com>
[-- Attachment #1: Type: text/plain, Size: 4288 bytes --]
Hi Eduardo:
Many programmers refuse to document almost anything and expect the code to
speak for itself. Or they throw random comments throughout their code that
don't help elucidate things. The nice thing about most Elisp code is that
the inputs and outputs of functions are often pretty well documented, since
people learn from many good examples. I support you in wanting to document
and explain things very clearly for your readers. For most people,
Hyperbole is extensively documented down to the function-level. But you
want an 'atomic'-level description of the internals of Hyperbole which I
think would be useful to only a very small population.
Good programming is about producing and layering clean abstractions that
sometimes must mask internal complexity and expose only the interfaces
necessary for use (could be a UI, an API or a class abstraction). It's not
turtles all the way down as the 'physics' of different levels of
implementation varies. Hackers do build from lego blocks; they don't spend
their time trying to deconstruct everything just to get comfortable with
every component they use, in general. If you want to spend years trying to
wrap your mind around something a bit complex then read The Art of the
Meta-object Protocol many times. Then, if you survive, come back to
Hyperbole and its call tree will seem simple to you :-)
Seriously though, I get that you learn and document differently than many
other people, so just do your own thing, your own way. I am reminded of
the Hudsucker Proxy where the 'rube' is derided for his stupid idea until
later it turns out to be one of the most profitable inventions in history.
Maybe the rest of us just can't see what you see because of the way you
express it, though if we could, we would be enthralled. I know a bit what
that is like!
Best of luck,
-- rsw
On Tue, Jun 28, 2022 at 12:48 AM Eduardo Ochs <eduardoochs@gmail.com> wrote:
> On Sun, 26 Jun 2022 at 21:50, Robert Weiner <rsw@gnu.org> wrote:
> >
> > So here is a simple implementation that is not unlike your own
> > though the functions are a bit simpler and more clearly documented
> > _without a listing of every possible test case type_ and requires
> > neither Hyperbole nor Org until you want to activate things as
> > buttons:
>
>
> Hi Robert,
>
> I think that the part in "_..._"s above deserves a detailed answer.
>
> I started using GNU/Linux in the mid-90s. Before that my favorite
> languages were Icon and Forth. In Forth I could do AMAZING things in
> less than 50 lines of code, but my programs would usually become
> confusing and unmanageable when they grew bigger than that.
>
> There is a famous book by Fred Brooks called "The Mythical Man-Month",
> and one of its chapters is called "Plan to Throw One Away":
>
> https://wiki.c2.com/?PlanToThrowOneAway
>
> I took that slogan seriously. Most of the time when I realized that
> something that I was doing by hand could be automated I would write a
> first attempt to automate it - _as a prototype_, that I regarded
> partly a program and partly as a way to help me think how that task
> could be structured, and that would probably be "thrown away" if I
> needed a cleaner solution later.
>
> In Forth it was very easy to implement both strange interfaces and
> little languages, in this sense:
>
> https://wiki.c2.com/?LittleLanguage
>
> In Emacs less so, but I could still do lots of funny things using
> eval-last-sexp to use sexps as buttons.
>
> When we are writing throwaway code "planning to throw one away" then
> using tests in comments is a very good way to document the code. And
> when I rewrite my prototypes I usually prefer to document them using
> text ***AND*** executable examples rather than just text. One of the
> effects of using this style is that the users of eev see that they can
> use that style in their notes too - and with that their notes become
> much closer to being "executable notes", in this sense,
>
> http://angg.twu.net/eev-intros/find-here-links-intro.html
>
> than they would be if they believed that they had to write the docs of
> their functions as just text.
>
> You are sort of saying that having tests in comments is bad style.
> Well, it's not. =/
>
> [[]],
> Eduardo Ochs
> http://angg.twu.net/#eev
>
[-- Attachment #2: Type: text/html, Size: 6112 bytes --]
next prev parent reply other threads:[~2022-06-28 9:04 UTC|newest]
Thread overview: 33+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-06-26 15:56 Org, Hyperbole, and eev Eduardo Ochs
2022-06-26 16:28 ` Robert Weiner
2022-06-26 17:51 ` Eduardo Ochs
2022-06-26 18:23 ` Robert Weiner
2022-06-26 19:45 ` Eduardo Ochs
2022-06-26 20:23 ` Robert Weiner
2022-06-26 23:25 ` Eduardo Ochs
2022-06-27 0:49 ` Robert Weiner
2022-06-27 3:48 ` Eduardo Ochs
2022-06-27 4:11 ` Robert Weiner
2022-06-28 4:43 ` Eduardo Ochs
2022-09-27 15:10 ` Jean Louis
2022-09-27 16:22 ` Eduardo Ochs
2022-09-27 21:16 ` Jean Louis
2022-09-27 21:58 ` Jean Louis
2022-09-28 0:52 ` Eduardo Ochs
2022-09-28 6:04 ` Jean Louis
2022-09-28 10:15 ` Eduardo Ochs
2022-09-29 9:22 ` Jean Louis
2022-10-08 0:28 ` Eduardo Ochs
2022-10-08 1:25 ` Jean Louis
2022-10-11 2:42 ` Robert Weiner
2022-10-11 4:59 ` Jean Louis
2022-09-29 9:42 ` Jean Louis
2022-09-29 11:55 ` Quiliro Ordóñez
2022-09-28 3:52 ` Ihor Radchenko
2022-09-28 9:16 ` Jean Louis
2022-09-29 4:07 ` Ihor Radchenko
2022-09-29 9:59 ` Jean Louis
2022-06-28 4:48 ` Eduardo Ochs
2022-06-28 6:26 ` Robert Weiner [this message]
2022-09-27 14:43 ` Jean Louis
2022-09-27 14:16 ` Jean Louis
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CA+OMD9hGUjV7Vo-k6RYBVEDxVo6nKuo0bAZVvSJ8dAU+jVLH2Q@mail.gmail.com \
--to=rsw@gnu.org \
--cc=eduardoochs@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=rswgnu@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).