On Friday, October 11, 2013 4:40:48 PM UTC-5, Edward K. Ream wrote:
> It's at: http://leoeditor.com/theory.html > For the first time ever, it concentrates on the highest-level view of the code. Actually, the *intent* of the chapter has no changed: it no longer focuses on the knowledge you need to understand or change Leo. There *isn't* any, except for the most basic knowledge that leoCommands.py defines the Commands class, etc. Instead, the chapter is attempting (indirectly) to teach developers to focus on the *process* of (say) finding a bug: 1. You find a starting point (maybe one of the usual suspects, maybe another piece of code related to (say) a particular command. 2. Insert g.trace there, or maybe g.pdb. 3. Find out what is happening there, including, if useful, where the code came from (g.callers()). That's *it*. It's an exploration process. It's how I fix *every* non-trivial bug. Really, all anyone needs is a little bit of confidence. This lowers the bar a lot. I'll be making this implicit intention explicit in the next draft of this document. > It's *much* simpler than before, and I think it should be more useful. It was truly shocking how little detail is needed in this chapter. I actually felt disoriented. I made a list of reasons why short explanations are better than long ones. Alas, I deleted it by mistake. It was never part of the repo, so it seems to be gone for good. To recreate the list, at least in part: - People can understand short explanations more easily. - People are more like to read short explanations. - Short explanations make the major points more obvious. - Implementers, including myself, rarely remember any but the most general facts about a program. - The top-level structure of @file nodes in leoPy.leo is (really!) all you need to know to hack on Leo. - Details go out of date quickly, general principles can (and have) endured for decades. And so on. There may have been a few more points on the original list, but you get the idea. The irony is that these points are "deep background" for any writing. They can't be part of the writing itself because they are details to be omitted! And one more thing. Potential implementers really must feel comfortable reading Leo's code. It's not rocket science, and all one needs to do is get a feel for the shape and weight of the code. I remember such general things much longer than details. Indeed, it's almost always straightforward to find the code I'm looking for. When I get there, it often feels like somebody else wrote it: I don't remember anything about the actual code. OTOH, it's usually pretty easy for me to sense when somebody else wrote the code because of stylistic differences... Edward -- You received this message because you are subscribed to the Google Groups "leo-editor" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/leo-editor. For more options, visit https://groups.google.com/groups/opt_out.
