Analogies are hard to parse

[itsgreggreg]

Great work, I love simplicity of the interaction model and programmer friendliness. You've managed to create what amounts to an AST for front end development that's easy to work with.

Ironically the metaphors used in describing cell are the most complicated part of understanding the whole thing. If you want people to be able to truly pick it up and understand it quickly I suggest doing away with the cell metaphor all together. I find the code in cell.js much easier to read and parse than GENESIS.md and I suspect many other people will have this same problem. Words like Genotype and Phenotype have no meaning to me and are hard to distinguish as I'm not a biologist and having to keep the biology metaphor active while I try to understand what's going on is just too much cognitive load to be useful. The name is great though search might not be the best: https://encrypted.google.com/search?hl=en&q=cell%20js .

Anyway, that's my 2c. Again, great work on the library!

[NxtChg]

Exactly! That's what I was talking about in another issue when I said "cute names are fun for 15 minutes, and in general should be avoided". Glad to see someone else sharing this sentiment.

[gliechtenstein]

Hi guys, I totally get where you are coming from, I wrote a post to explain the design decisions.

I talk about this exact issue at the bottom of the post (but i recommend you read the whole thing because they're all related)

Please check it out https://github.com/intercellular/cell/issues/111

p.s.

This is not 100% set in stone and I do welcome feedback. I just wanted to share the rationale behind my decisions so we can have an informed discussion. Please feel free to share your opinions on the thread after reading. Thanks!

[itsgreggreg]

I don't think this is going to hold true for many people:

3. In that case, thinking about it from a biological perspective will help you understand it much better.

And you kind of admit that the naming isn't that great in the code in that you have to explain every name:

// [God] God's only purpose is to create cells and get out of the way

Biology and cell function aren't common knowledge. You're going to have to teach people what these things are in order to teach them how to read your docs in order to teach them how to use your code. The inspiration is certainly important and possibly worth documenting, but it's not going to help people learn about what is essentially just objects and functions.

My biggest piece of advice is actually yours, simplify. Simplify to the point where you don't have to explain. And certainly simplify to the point where you don't have to explain your explanation.

[gliechtenstein]

@itsgreggreg

You're going to have to teach people what these things are in order to teach them how to read your docs in order to teach them how to use your code.

Are you talking about the users or people who want to fork and contribute?

Just to clarify, the "users" don't need to know about all the internal details. Just like 99% of jQuery users have never read the source code, 99% of Cell users won't need to even know that there are terms like Genotype, Phenotype inside. Those are private variables.

I guess I'm curious which pain point you're referring to (because we may be talking about completely different things), whether it's for people who want to contribute, or for people who just want to use the library...

[s0ber]

@NxtChg @itsgreggreg Those are just names. Does it really matter how things are named? If it is enough for you to understand what's going on by reading code of those functions, then changing their names to something meaningless like Item, Component, ComponentFactory or even ComponentFactoryFactory will not make it better in any way.

So, if this thing is inspired by biological principles and author tries to reflect those principles in code, then it makes sense to stick with them.

@gliechtenstein Thanks for the thing! Definitely worth diving in.

[jaimegomez]

I think it's important to keep the naming convention, because it directly reflects the thinking process used while constructing the library, along with the motivation and beliefs of the author. It's particularly relevant when trying to predict where this is heading, to gauge the investment one wants to make on it.

Analogies only get you so far, of course, and it may naturally evolve into something different, maybe bigger and more "standardized", but it'll be interesting to see what comes out of it, and give the author (and eventual leaders) time to fully realize this idea.

Otherwise, someone else could fork it, get away from the current constraints and win the users by proving an even better solution; don't know how, but it'll be very interesting to see as well!

[soapdog]

I really like this library but I find the metaphors distracting. The whole idea of god sound icky to me. The biology metaphors don't annoy me that much as the whole god thing even though they are kinda distracting.

Even though the authors train of thought moved through these metaphors to build this thing, I believe a rewrite in better or clearer terms might be a better fit for the future. It is not because it begun with such metaphors that the same concepts can't be explained using less murky metaphors now.

[devsnek]

you don't have to cult worship the god structure if you don't want to 👀

[gliechtenstein]

@soapdog thanks for the feedback!

To elaborate on the God concept, you may know an object oriented programming concept called God object.

Normally a god object is considered an anti-pattern because it refers to a global object that knows too much about the entire app, but in our case, there is no God object that runs the entire show. Our God is different, it simply creates self-aware cells and then gets out of the way, so you could say it's a new kind of God, which is one of the defining factors of Cell.js.

Lastly, I am not religious, but agnostic, so there's no hidden agenda to evangelize people to join a religion, if this makes you feel any better...

[soapdog]

@gliechtenstein thanks for getting back to me so fast. I am aware of said pattern, I am not implying that you had a ulterior religious motivation in naming it after the pattern. I understood why you did it, I just find it icky and suspect that more people will find it icky too. Call it Cell Factory, I don't know, I just don't enjoy religious terms inside programming. I know it sounds quite pedantic, sorry, I too have used similar terms in the past when developing games that had a God mode... Don't know, maybe I am just to grumpy these days.

My suggestion, ask your users, my opinion might not be representative enough to warrant an alteration.

[Caffeinix]

Since everybody is clearly clamoring for one more opinion on all of this, here's mine.

I can see both arguments here. Metaphors have always been powerful tools when writing software, and sometimes you have to reach just a bit further than seems reasonable to find good ones. Things that make perfect sense to us now — the concept of a "file", for example — were pretty far out there when they were first proposed. The real litmus test is, I think, how well the metaphor explains the behavior of the system without further explanation, and how much predictive power it has. For example, files can be created, edited, destroyed, and organized; they pertain to a single topic; they don't spontaneously vanish; you can put them in folders; etc. So the idea of using the metaphor of an organism is not, in and of itself, troubling to me.

That said, I must admit I've struggled with this one. The genotype/phenotype distinction makes sense despite the technical nature of it: the genotype is the template, and the phenotype is the instantiation of that template. But "cell" is troublesome, because unlike a file, a cell doesn't have any one particular distinctive feature to base the metaphor around. Is it the fact that it's self-replicating? The fact that it contains organelles? The fact that it contains a nucleus? I honestly don't know. Same thing with "God": the code makes it pretty clear that the defining characteristic in the metaphor is that it creates the universe and then rests, which is fair enough. But as @gliechtenstein alluded to, God is also typically omnipotent, and that's the characteristic that's usually being called out when one uses that metaphor, which makes it a confusing one. Membrane is another head-scratcher for me: GENESIS.md says it's the "shell", so I know the metaphor is about its function as a boundary and not the fact that it's semi-permeable or composed of two layers (this is the problem with technical metaphors), but that doesn't help me understand the code much. I'm not confident enough in the metaphor to be able to predict whether the membrane sticks around after the phenotype is instantiated or whether it is actually a structural wrapper around anything. And without having predictive power, a metaphor is not very useful.

Moreover, the methods of each object don't really fit the metaphor. Cell membranes don't inject cells into anything, so why does it have an inject method? What does it mean to build a genotype? If your nuclei are ticking, you might want to consult your doctor. It's hard to figure out where the metaphor is meant to apply and where it's not, which further confuses me.

I see a couple ways forward here. One would be to move the metaphor into documentation and use more recognizable names for the objects in code. Another would be to expand on GENESIS.md to fully clarify exactly why each object is named the way it is, where the metaphor applies, where it doesn't, and how each method maps to something relevant to that metaphor. If you can't come up with anything, consider rearchitecting to make the mapping clearer, or maybe reconsider the metaphor itself.

[ghost]

One of the benefits of a good interface is that the internal implementation is rather opaque. I just went through the main readme and there's actually no mention of any of the cell's internal naming. Now one could argue that $cell: true could more accurately be labeled $mount: true but that's besides the point.

What we're talking about here is developer or contributor friendly naming which might foster more community involvement. And since it's an internal API I would lean on obvious naming as the preferred method since the end user is not the consumer of the library rather it's the contributors. I think there's a chance that this could deter or split the potential user/contributor base. Metaphoric names are great but not if you risk someone just forking for library and renaming the internal API to something more friendly in their eyes. It comes down to how you want to run your project. Naming stuff is hard =) I'm certainly not good at it.

I think if the metaphors stay (btw the boundaries between each subsystem make perfect sense) each line of source code needs hand-holding levels of documentation so there is no magic and will reduce the anxiety of buying into what you're doing here.

[Kelerchian]

@gliechtenstein Hi fellow agnostic.

Seeing the philosophy of this enthroned yet grandiose non-framework framework, I'm ready to worship it.

Jokes aside, I think the issue here is that some people think to much about the metaphor.

It might help to provide some reminders that the names are not necessarily to be interpreted as methaphorically correct, nor that people need to understand biology in order to understand cell. Read the description... Read the code... Heed the word...

Anyway, who would think "Angular" ends up being the name of frontend framework instead of a name of trigonometry expert system software, and "tree" being a type of graph instead of "divides", "HTMLElement" instead of "HTMLPart".

@kingoftheknoll 's statement about the "risk (of) someone just forking for library and renaming the internal API to something more friendly in their eyes" -- It is wise to be put into consideration as well.

And for those who dislike "cute names" or "three letters that represents possible deity that creates the universe under certain cases", I suggest self-analysis and reflection, as different types of upbringing programs different reactions towards certain circumstances, some of which create biases that could possibly hinder the advancement of humanity.

Nice idea, and I would love to contribute.

[gliechtenstein]

@Kelerchian thanks for understanding! would really appreciate contribution going forward!

[gliechtenstein]

Hey I kept this thread open because I wanted to understand the problem better.

And from reading through the comments I think I have a much better understanding. Although this thread is phrased as "analogies are hard to parse", I think the real problem is that it's simply not easy to understand what's going on in the code because:

1. The library has an unconventional architecture
2. The code has near 0 comments

So I went ahead and added a bunch of comments to the code. I hope this solves the comprehensibility problem. I created an issue to discuss how the current version of the comments can be improved. Please feel free to ask questions and provide feedback here https://github.com/intercellular/cell/issues/137