[Top][All Lists]

[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

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

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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]