Understanding Leo Code

[rengel]

This might be of interest to anyone who tries to understand and program Leo code.

http://www.laputan.org/mud/mud.html

It also might help to understand why it seems so difficult to find more Leo adopters.

[Edward K. Ream]

​Hmm.  Leo is not a big ball of mud.  It's architecture has remained almost completely unchanged for decades.  But the plumbing and wiring change continually ;-)

Leo's problems attracting users stem from other sources. Probably the most important is the need for .leo files.  In other words, people are unwilling to pay even small prices for better tools.

Edward

[Offray Vladimir Luna Cárdenas]

Hi,

But I think that .leo files (or the ideas behind it) are a bless for literate computing (as explained in detail in my other long post). A lot of user could come from there.

Cheers,

Offray

[rengel]

Leo is not a big ball of mud.

Isn't that in the eyes of the beholder?

Leo's problems attracting users stem from other sources. Probably the most important is the need for .leo files.  In other words, people are unwilling to pay even small prices for better tools.

For years, I've made a living by translating English computer literature into German, among others books by Martin Fowler and Bob Martin. Especially Bob Martin's 'Clean Code' has helped me a lot to clarify my own criteria for judging what are 'good' or 'better' tools.

On a very basic level, consider the almost universally accepted principle, that a software project should use 'consistent naming conventions' and then look at the function names in Leo's code. In far too many modules you find camel case function names mixed with underscore function names. You apply Python checkers, but then you don't adhere to the simplest PEP8 conventions that function names always should be lowercase and class name upper case.

Beyond that, there are many other small annoyances:
- In __doc__ strings, Leo code often states the obvious. Every Python progranmer knows, that __init__ is the constructor.
- Function __doc__ strings often state something, that should be better expressed in the function name itself. making the __doc__ string superfluous.
- Many functions, expecially in leoGlobals.py look like C-programming done in Python; i.e. the 'g.is_ws' function (that is called over eight thousand times during startup) could be replaced by a simple (ch in ' \t') expression instead of a 'g.is_ws' function call. This would reduce coupling and would be more as twice as fast. The same holds for some other is* functions.
- If you look at the commands you have sometimes three or four different versions to express the same command:
a hyphened version ('a-command'), an unscored version ('a_command'), a camel-cased version ('aCommand'), and quite different name ('doACommand'). Frankly, this should have cleaned up long ago. Don't expect newcomers to have the patience to sort that out.
- If you look at the menu definitions, you have the straight forward versions with a command name and a label ('do-a-command', 'Do &Command') and the assumedly 'smart' versions with a cryptic definition ('*do-a-&command') and a complicated algorithm. The latter makes internationalization exceedingly difficult.
- Modules that are 5000, 6000, or 7000+ lines long suggest an archictecture that might need some rework.
- The naming conventions in 'qt_frame' are quite confusing. Among others, it defines some classes '
QtSearchWidget, QtTabBarWrapper). Their names suggest that these classe are Qt classes proper, which is misleading, because they are not.

Even if this looks like nitpicking, it shows which kind of impression a cursory look at Leo's code probably conveys.
It is this very basic level that transports the overwhelmingly important first impression of the quality of Leo's code.
INMHO, this determines the decision if it might be worthwhile to dive into the code morde deeply or not.

To cite from the introduction of 'Big Ball of Mud':

The overall structure of the system may never have been well defined. If it was, it may have eroded beyond recognition. Programmers with a shred of architectural sensibility shun these quagmires. Only those who are unconcerned about architecture, and, perhaps, are comfortable with the inertia of the day-to-day chore of patching the holes in these failing dikes, are content to work on such systems.

Reinhard

[Edward K. Ream]

​​

On Tue, Jan 10, 2017 at 5:46 PM, rengel <reinhard...@gmail.com> wrote:

Leo is not a big ball of mud.

Isn't that in the eyes of the beholder?

​Sure. But Leo's problems emphatically do not arise from the structure of Leo's classes.  They are clean an

​d​

neat.  Kinda like an upscale housing development :-)

​> ​

On a very basic level, consider the almost universally accepted principle, that a software project should use 'consistent naming conventions' and then look at the function names in Leo's code. In far too many modules you find camel case function names mixed with underscore function names. You apply Python checkers, but then you don't adhere to the simplest PEP8 conventions that function names always should be lowercase and class name upper case.

​Pep 8 states the following:

"However, know when to be inconsistent...In particular: do not break backwards compatibility just to comply with this PEP!"

Much of Leo is effectively set in stone, because changing names might break existing code.  Leo is a programming environment. As such, it can't always be changed as easily as one might suppose.

> Many functions, especially in leoGlobals.py look like C-programming done in Python

That's because they were C functions that got converted to Python.  No, I wouldn't do it that way if I were starting over, but they can't be changed without breaking existing code.

I'm not going to comment on the other stylistic critiques of Leo's internals.  They have nothing to do with Leo's design or architecture. Small blemishes do not prevent me or others from working effectively with Leo's sources.

​Edward

[Edward K. Ream]

On Tuesday, January 10, 2017 at 5:46:51 PM UTC-5, rengel wrote:

Beyond that, there are many other small annoyances:

- In __doc__ strings, Leo code often states the obvious. Every Python programmer knows, that __init__ is the constructor.

Leo's cff command often finds matches in multiple ctors.  These supposedly redundant comments are a recent addition.  The docstrings are typically:

    '''ctor for x class.'''

They allow me to see to what the class each cloned ctor belongs.

EKR