3 ms·

Switching to Python examples from Go, but I believe it all applies just the same. > What does "use the same method signature but with different meaning" mean?

Switching to Python examples from Go, but I believe it all applies just the same. > What does "use the same method signature but with different meaning" mean? .draw(times: int) In your code that adds a shape to the canvas. In my code it adds a card to your hand. > What is my "duck typing code"? You collect everything with the draw signature as options to draw with. > Is duck typing part of your API? What do you mean “your API?”. Maybe I mention it in the docs, maybe I don’t. But that doesn’t really matter because if we’re going to compare intent, then this is subjective. And it really doesn’t matter because duck typing isn’t part of an API, it’s a technique / language feature. By just adding a method, I removed your ability to do something. My point with all this is your definition is lacking. You just shifted the pain of defining “breaking change” to the pain of defining “compatible API”. Which is fine if you’re then going to define that strictly (see Hickey’s talk on SemVer), but you haven’t.

paskozdilar 5y ago
An API is defined through two parts: 1) Machine-readable definitions of the functions and data types used 2) Human-readable explanation of what the previously defined functions do when passed each of the allowed data types, with a high-level explanation of how is the API supposed to be used. The first part is usually implemented as part of your programming language - in case of Python, type hints can be used as a substitution. The second part is necessarily informal, since it targets humans. But that does not mean it cannot be well-defined. For example: mmap() creates a new mapping in the virtual address space of the calling process. The starting address for the new mapping is specified in addr. The length argument specifies the length of the mapping (which must be greater than 0). There is no concept of "virtual address space" or "memory mapping" in C. All C knows about is functions and values. But we still know what mmap() does and there is absolutely no ambiguity to its behavior.

paskozdilar 5y ago

An API is defined through two parts: 1) Machine-readable definitions of the functions and data types used 2) Human-readable explanation of what the previously defined functions do when passed each of the allowed data types, with a high-level explanation of how is the API supposed to be used. The first part is usually implemented as part of your programming language - in case of Python, type hints can be used as a substitution. The second part is necessarily informal, since it targets humans. But that does not mean it cannot be well-defined. For example: mmap() creates a new mapping in the virtual address space of the calling process. The starting address for the new mapping is specified in addr. The length argument specifies the length of the mapping (which must be greater than 0). There is no concept of "virtual address space" or "memory mapping" in C. All C knows about is functions and values. But we still know what mmap() does and there is absolutely no ambiguity to its behavior.