search

lsalzman / enet

ENet reliable UDP networking library
MIT License
2.66k stars 667 forks source link

Descriptive Naming #247

Closed cuppajoeman closed 3 months ago

cuppajoeman commented 3 months ago

When working with enet the naming of functions is unclear (to me at least).

Examples:

enet_host_service

Every time I see this I don't remember what it does, I always end up going to the documentation and reading:

waits for events on the host specified and shuttles packets between the host and its peers.

Also the word shuttling is not very descriptive to me. I looked in the source code and it seems to call enet_protocol_send_outgoing_commands and enet_protocol_receive_incoming_commands so by shuttling it would rather mean send and receive information between the server.

I don't get how the name enet_host_service captures this. What if we rename it to distribute_packets_to_and_from_server_for_duration (or something shorter, but still more descriptive)

Also the usage of the word peer is confusing. I went on wikipedia to see what they think a peer is:

Peer-to-peer (P2P) computing or networking is a distributed application architecture that partitions tasks or workloads between peers. Peers are equally privileged, equipotent participants in the network, forming a peer-to-peer network of nodes.[1]

So a peer is just a computer involved in the network from what I understand.

Looking at the struct ENetPeer it seems to represent connection information about a specific computer. Why not just call this ConnectionInfo or something. Because then it would be much clearer that this struct actually contains things like: incomingDataTotal etc...

Also what is the purpose of saying host rather than server?

It might be that I'm new to the api and over time this will make more sense but I thought I'd make a naively optimistic issue for this before I get normalized to the names of everything.

mman commented 3 months ago

It might be that I'm new to the api and over time this will make more sense

Exactly, it will make more sense as you use the library more.

ENetHost is host because it's not just server. It's server and client at the same time, thus host.

ENetPeer does indeed describe a connection between two hosts, but that is not full picture.

Host A can be talking at the same time to multiple peers B, C, D (all of which are hosts as well) but from the perspective of A they are peers.

This is a nomenclature used in networking since 1977.

cuppajoeman commented 3 months ago

It might be that I'm new to the api and over time this will make more sense

Exactly, it will make more sense as you use the library more.

ENetHost is host because it's not just server. It's server and client at the same time, thus host.

ENetPeer does indeed describe a connection between two hosts, but that is not full picture.

Host A can be talking at the same time to multiple peers B, C, D (all of which are hosts as well) but from the perspective of A they are peers.

This is a nomenclature used in networking since 1977.

I'll just continue using this library and hopefully those concepts will start to make more sense.

Also I had no idea this was the standard set of terminology that's been around for so long, I guess it's a good idea to respect our history and those who came before.

I'll close this issue for now. Thanks for the comments.