Naming convention: Types of routes

[elliottwilliams]

I noticed in #19 that our terminologies for the varying route:station representations are drifting. Here's what I've been using:

Description	Term	Proper	Shark
Unordered list of the stations on a given route	"associated stations"	Route.stations	route.associated_objects[Shark::Station]
The full sequence of stations a vehicle will visit along a given route	"itinerary"	Route.itinerary	route.stations
The deduplicated loop that vehicles on a given route take, including conditional stations or segments	"canonical route"	CanonicalRoute.stations	n/a

The main thing I see here that's somewhat confusing is how "itinerary" to Proper is called "stations" to Shark. If it's alright with you, and you like the terms I'm using enough, I propose renaming route.stations to route.itinerary.

Additionally, Proper's Route.stations could be renamed to Route.associatedStations to reduce ambiguity, but it's typed as a Set, which makes it clear it doesn't imply any order like an itinerary does.

Let me know what you think, and if there's a better place for system design discussions not directly related to any application.

[faultyserver]

Oh man, I wish GitHub supported issues at an organization level. It might be worth making some sort of distinct knowledge base for things like this, though I think it makes sense to talk about it here, since Shark is the provider and essentially determines naming/type conventions. I think a more immediate step would be to start writing wiki pages for things like this (similar to the WAMP Events and RPCs page).

That said, I think renaming stations to itinerary is a good move. I'll make the change when I get a chance this afternoon.

[faultyserver]

Closed by 5a416ce.