[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Opaque objects and Emacs documentation
From: |
Dmitry Gutov |
Subject: |
Re: Opaque objects and Emacs documentation |
Date: |
Wed, 22 Jul 2020 00:17:18 +0300 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0 |
Hi Alan,
On 21.07.2020 22:36, Alan Mackenzie wrote:
What precisely forces you
to use such difficult and arcane facilities? What does it gain you that
you couldn't get out of plain Emacs Lisp (without things like
cl-generic)?
Sorry, could you just read this thread? Or the description of the package.
As I said, the closest alternative would be using functions with
OO-style dispatch arguments, akin to completion tables. I don't think
you'd like that option better.
This is sorted out by each individual backend which knows how to access
fields inside "project instances" belonging to it, and which implements
the aforementioned protocol for that instance type.
Trouble is, when I'm trying to debug a problem involving such code, that
style of coding adds an order of magnitude onto the time and effort
needed.
Sometimes, when we need more advanced capabilities for our programs,
that can indeed result in less trivial debugging. The alternative would
be not writing said program at all.
if it is not documented in detail, it will add another order of magnitude
onto the time to debug it; anybody needing to know the structure of a
return value in detail, possibly to check it's valid, would first have to
read and understand the intricate details of the source code, and
effectively recreate in her private notes the details missing from the
doc string.
You can only know it's valid by looking at the "Implementations:" list
in 'M-x describe-function RET project-root RET'.
You won't know it is valid just by reading some examples of return values.
That isn't fun. Not so long ago I gave up on an Edebug bug because the
proliferation of inadequately documented cl- functions in edebug.el just
made it too tedious to continue.
Edebug is difficult. So far I have no idea why that is: perhaps because
of the coding style, but more likely just due to the problem domain.
But we indeed have old code that is unnecessarily difficult. At some
point, I had a lot of trouble following the code in etags.el. Lots of
implicit state and dynamic variables everywhere.
Eli did some cleanups after that, but I'm yet to form an opinion on how
much they changed things.
I am adamantly against this because it's against the design (clients
should program against the public interface, not against the
implementation), and is likely to encourage incorrect programs.
That's known as "security by obscurity", I think.
No, abstraction and security are largely orthogonal.
I think your fear is
misfounded. For a start, if the public interface is adequate, people
will use it in preference to dissecting internal structures.
That means documenting the public interface adequately first. And for
that, the description needs to be abstraction-oriented.
When gaps
are found in that interface, people will use the internal details to
craft a workaround whether the documentation is there or not. (I have
done this at least once in the past.)
Either inadequate public interface, or inadequate documentation, or
programmer laziness (or "cowboy-ism"). I wouldn't presume to say which
was the cause more, but I've seen this in practice pertaining to the
package under discussion.
- Re: Opaque objects and Emacs documentation, (continued)
- Re: Opaque objects and Emacs documentation, tomas, 2020/07/21
- Re: Opaque objects and Emacs documentation, Eli Zaretskii, 2020/07/21
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/21
- Re: Opaque objects and Emacs documentation, Eli Zaretskii, 2020/07/21
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/21
- Re: Opaque objects and Emacs documentation, Eli Zaretskii, 2020/07/22
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/22
- Re: Opaque objects and Emacs documentation, Eli Zaretskii, 2020/07/22
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/22
- Re: Opaque objects and Emacs documentation, Alan Mackenzie, 2020/07/21
- Re: Opaque objects and Emacs documentation,
Dmitry Gutov <=
- Edebug (was: Opaque objects and Emacs documentation), Stefan Monnier, 2020/07/21
- Re: Opaque objects and Emacs documentation, Eli Zaretskii, 2020/07/22
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/22
- Re: Opaque objects and Emacs documentation, Eli Zaretskii, 2020/07/22
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/22
- Re: Opaque objects and Emacs documentation, Richard Stallman, 2020/07/23
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/23
- Re: Opaque objects and Emacs documentation, João Távora, 2020/07/22
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/17
- Re: Opaque objects and Emacs documentation, Dmitry Gutov, 2020/07/17