Some small suggestions regarding the new developments in 2.6 (and onwards)

[Ruben Vreeken]

I've noticed there is some significant work being done on panels, datalists, animators, the data layer etc. It's exciting to see that so much effort is put into making things more performant and in some cases more extensible.

However, while I appreciate the fact that most of these features are currently still in active development and not aimed at production release, much of the new code is more difficult to read and very poorly documented compared to other parts of the framework.

To make it easier to follow along or even collaborate on new developments, I'd like to make a few suggestions:

Variable Names:

I would greatly appreciate it, if variables could be given more descriptive names. Some of the new modules use many 1 or 2 character variable names, which are sometimes re-assigned to yet other 1 or 2 character variabels.

This makes it rather difficult to quickly scan what particular functions are doing. The structure of the code itself is not the problem (it's usually quite clean, really), but it's simply harder to grok what's going on if you have to scroll back every few lines to figure out what variables such as "d" or "ii" or "sp" actually mean.

Documentation:

I would greatly appreciate it, if new kinds could receive some degree of documentation earlier in their development. I understand things are often in flux especially early on in their development cycle, but most of the time there is probably a general idea of what a component is intended to accomplish by the time it's committed to the master branch. It would really help devs understand both the code as well as the underlying philosophy if the new kinds could have even just a little documentation (even if only at the top of the file), with a rough description of which problem it tries to solve and how it tries to solve it.

I hope the team will consider these suggestions and maybe even implement them in some form.

Thanks for all the hard work, I'm looking forward to trying out all these shiny new things that are coming our way.

[Gray Norton]

Hi, Ruben -

Regarding variable names — yes, there are certainly some overly cryptic names in some of the newer code, particularly in VirtualDataRepeater, NewDataList, etc. There are obviously tradeoffs; especially when writing code that does a lot of calculations and conditional assignments, I find that variable names longer than 4-5 characters make it noticeably harder to “see” the logic in the underlying code, which is why I ended up with a lot of very short names. That being said, it can be difficult even for me to remember what a given abbreviation means if I’m revisiting code I haven’t touched in a while, and it would obviously be worse for anyone who hadn’t written the code in the first place. I intend to do some cleanup before we do a public release of this code. One of the things I’m considering is sticking with fairly short names but by convention including comments alongside each declaration to serve as a “key” for anyone (myself included) reading the code. What do you think about that approach?

Regarding docs, agree with the goal to have more docs, earlier in the process. In practice, it has been difficult to meet that goal given the mode we’ve been operating in since joining LG, but we are not giving up on the goal. We’ll try to do better.

- G

--
You received this message because you are subscribed to the Google Groups "Enyo Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to enyo-developme...@googlegroups.com.
To post to this group, send email to enyo-dev...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/enyo-development/4e52cdc1-ef4b-4a0a-a304-7a6876787a0a%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Ruben Vreeken]

Hey Gray,

Fair points there about variable names. Personally, I suppose I prefer clear variable names over brevity, but beyond a certain point the complexity of calculations does tend to kick in. I think having a clear description of the variable is a very good compromise in such cases. I'm not sure if the point of declaration is always the best location for comments. I would probably try to insert comments where there is either some helpful context or where the need for clarity is strongest. For instance at the location when the variable gets its first value assigned or near a complicated calculation or a complicated set of conditions with many cryptic parameters.

As for docs, I can understand writing high quality documentation takes a lot of time and isn't always easy - especially under pressure - but even just a quick&dirty comment with a quicky description of the general idea of things really helps a lot. This kind of early documentation would mostly be for people that like to dive into the source anyways so it doesn't need to be pretty. Something along the lines of what you wrote in youre reply to my question about the future of lists and grids would already be a superb addition.

Thanks for the hard work and thanks for answering so quickly!