Draft: Store prototype API
-
I still don't like it to be called Store since it is used a lot in other contexts.
Hence I like to propose to use a term that makes it very clear we talk about non stationary stuff:
Cargo <- This is short, pregnant and definitive.If you think I'm nitpicking, think again.
Clear terminology is key for a good and comprehensible Codebase that is supposed to be used by others.
-
@mrfaul Are you a native English speaker? I'm not, so I use dictionaries a lot. This is what the Oxford Dictionary gives for "store":
A quantity or supply of something kept for use as needed.
βthe squirrel has a store of foodβ
Looks valid to me.
-
I'm not a native speaker and butcher the grammar frequently but German is really not far from English.
(for those native tongues who learning German and cursing me right now for that statement, sry for us the complexity goes down)
This is not about its definition, it is about distinction in context.
I have a B.E. in machine design and this is one of the biggest challenge in my profession.
German by its nature is a very precise language, this keeps a lot of potential misunderstandings in check since we have a word for almost everything.
However when translating this in English, a lot (I mean a shit load) of this precise information is lost since English simplifies and reuses a lot of words to a degree that they are able to have very different meanings.To combat this we have to make sure to use distinctive terminology in international conversations.
Now "Store" and "Cargo" are very similar with the distinction that "Cargo" is exclusively used for "stuff that is being transported"
This is the better term in this case since it will be used by structures and creeps.
Decide for your self what is easier to distinguish in a non written conversation or when you are hunting for bugs which may include typos:
Storage.store.[RESOURCE]
orStorage.cargo[RESOURCE]
"store" is a completely valid term but since it is already used it shouldn't be given a additional meaning.
P.S. And don't get me started on the difference between "american" and "british" English that deserves it own rant
-
@mrfaul
Storage.store[RESOURCE]
does look much better to me thanStorage.cargo[RESOURCE]
. "Store" is a more abstract term (e.g. an idiom "to have something in store"), and "cargo" is indeed mostly about transportation (thus irrelevant to game structures).I think we're fine with
store
, but it's interesting to hear some native speakers' opinion.
-
@artch said in Draft: Store prototype API:
"Store" is a more abstract term (e.g. an idiom "to have something in store"),
You do realize that it is exactly what I'm bitching about, don't you? Too abstract.
and "cargo" is indeed mostly about transportation (thus irrelevant to game structures).
How is this irrelevant, every fucking resource has to transported in this game before it can be used...
It only stops being cargo when it is used up, and that is the moment you call an intend with it.
Before that you can move it around freely.That said your call
-
As a native english speaker, I've never had an issue with store. I agree with @artch, "cargo" definitely has in transit connotation, eg. something being delivered. To me terminal.cargo doesn't make sense @MrFaul.
A word like contents might make slightly more sense due to being specific to the object itself (eg. the storage.contents, the contents of the tower), but tbh to me the extra characters probably wouldn't be worth it.
Store can be used as in "grain stores for the winter" and in my mind "store" was being used to represent a stockpile. My only qualm would be that terminal.store has an active verb definition of "to store" which is what comes to mind first, but it's a nitpick at best. The exact word choice isn't an issue, as what it's meant to be is clear, so I'd stick with store. My 2Β’ on it.
-
I would also prefer
store
.. it's short and I think it fits.
-
@davaned I know this seems like nitpicking but trust me I have seen markets shut down because of such little things like confusing naming conventions. (they switched logistic software)
Oh and cargo on a terminal makes perfect sense, just ask a port worker of your choice ^^And again I'm not bitching about the term, I'm bitching about the lack of distinction.
I guess I'm just sensitized to filter out those problems early... ( That day mentioned above was a fuck up above 7 digits)
-
- Tower.store - has verb implication, valid word choice
- Tower.cargo - has incorrect implication, not getting transported
- Tower.contents - most accurate, extra characters
Would you describe something stored in your pantry as "cargo"? Between the contents of the pantry and the cargo of the pantry I know which makes sense. Store is a little clunky, but I would not bother changing to an incorrect definition.
-
More bad options:
hold
. Same verb problem asstore
, same transit problem ascargo
. less charactersresources
, almost as good ascontents
, but longer, resources is often used abstractly in common english.quanta
, technically as correct as contents, horrifically confusing.bikeshed
, terrible, but think of the story we could tell new playersstuff
, also a verb likestore
, but most often used as a noun, often used to end bikeshed arguments.
Seriously though, the consistent use will be a huge boon to those learning the API. The debate about which name is truly just bike shedding. There are bad options, many good enough options, and no objectively best options. More important than picking among good enough names is that the devs remain productive and this gets rolled out before the next crop of new players shows up.
If switching to
contents
speeds up the refactor, awesome. If leaving it asstore
means less work overall even better.
-
Renaming commonly-used variables 5 years into a project is often a terrible idea
-
I'll miss
Creep.carry
, but.store
is my preferred way ofstore
ing things.
-
Personally, I'm going to be wrapping all my
.store/.carry
methods with.booty
and.plunder
-
@artch said in Draft: Store prototype API:
- Store.getUsedCapacity([resourceType])
-
- resourceType is undefined: equals to _.sum(store) with internal caching or null if this is not a general purpose store;
-
- resourceType is defined: returns capacity for that particular resource or null if this resource cannot be stored in this particular structure
It might be a case of copy paste, or just me nit picking, but I think in that last list point of
returns capacity for that particular resource
it should bereturns used capacity of that particular resource
.(and don't mind me not figuring out how to replicate the bullet list indentation properly)
-
-
Store.getUsedCapacity([resourceType])
-
resourceType
is undefined: equals to_.sum(store)
with internal caching ornull
if this is not a general purpose store; -
resourceType
is defined: returns used capacity for that particular resource ornull
if this resource cannot be stored in this particular structure
-
Should really be:
Store.getStored([resourceType])
resourceType
is undefined: equals to_.sum(store)
with internal caching ornull
if this is not a general purpose store;resourceType
is defined: returns stored amount for that particular resource ornull
if this resource cannot be stored in this particular structure
Store.getUsedCapacity([resourceType])
sounds more like you would get a float between 0-1 but you clearly want to return the actual amount.
-
-
Hello,
I like this proposal in this current state. Code will be much simpler for many situations.
The only improvement I'd favour would be to change store.getUsedCapacity([resourceType]) to store.getAmount([resourceType]), favoring concision to regularity, MrFaul's store.getStored looks a bit redundant to me, but I like the rest of his definition.
-
Remember that this method can (and in most cases will) be called without arguments.
Store.getStored()
orStore.getAmount()
are not definitive enough in terms of "get how much capacity in this store is used for all resources in total". I'd say thatStore.getAmount()
without arguments should return an object with all resources rather than one single number of total used capacity.
-
How about
getTotalAmount()
?
-
What's the behavior of zero capacity
Store
s?This happens when a Storage or Terminal has been RCL downgraded and with the loot Containers the caravans drop. It will also affect the Power Banks when they get a
.store
property.Currently
.storeCapacity
is set to 0 for these structures. I assumegetCapacity()
will likewise return 0.However as described now
getFreeCapacity()
will return a negative value. I did this in my own code and it caused all sorts of problems. I suggest the behavior be expanded to never return < 0.
-
@deft-code Yes,
getFreeCapacity
is more likeMath.max(0, getCapacity - getUsedCapacity)