Am I buying a ticket for a user or am I buying a ticket from a user? We've lost the relationships between the action, direct object, and indirect object. What are the side effects? What account is being used to provide funds, some global?
What does the function return? Maybe True/False depending on if the transaction succeeded? Or maybe it returns some type of receipt and throws some exception if it fails? I don't know.
This is just as scary when I modify the function as when I use it. I don't know what the implicit API contract is and I don't know if my modifications might break existing calling functions in strange ways. Its possible that I do something that misses all paths for a reasonably robust set of unit tests in the package.
While I agree that some effort should be but into self-explanatory code, its simply too tall an order in principle, and impossibly difficult in practice to explicitly state the full behavior of a function in its name and call signature - even with static typing or type hinting. I'll also admit that for private or locally scoped informal helper functions that won't be called outside the module or functional unit its ok to lack a specification.
So for the above function one could write a docstring or specially formatted comment as follows:
def user_buy_concert_ticket(user, ticket):
"""
Buy a ticket from a user, and return True if the transaction succeeded, False otherwise.
Funds to purchase the ticket are taken from the configured global account general.
"""
Now I have an API contract that I can test against, depend on when I call it, and understand my limitations when I make changes. Even better, with some minimal tooling I can use properly formatted comment or docstring to autobuild the API documentation. So when I change the function, I can change the documentation.
There are even tools and approaches where you can embed tests into your docstring so the comments so that the API contract is stated, documented, and checked all in the same place right alongside the code.
I also think it makes the what and how of the code easier to read after one has placed the contract summary into their head. Furthermore, consumers of the function don't need to read the code at all, everything they need to know is in the docstring.
I just gave a simple example, of course, maybe I should add more examples and not only at the beginning of the function, in fact I didn’t provide any context, it just was trying to explain why we should put more emphasis on naming and proper variable name usage, I didn’t specified if that was an API, etc.
I’m totally agree what you did but that is the difference between leaving comments and create documentation, you are using embed tools for creating an a contract for an API, documentation is much higher level, I stated the difference. I’m agree with creating docstrings( in python for example) but it is a difference thing from leaving comments. If you are in the middle of the function, you can’t use docstring. If you need to leave a comment to explain what are you doing: 1. Likely your function is doing more than One Thing and I don’t recommend that 2. Your code isn’t clear 3. And if your change your logic you need to mantain code and comment as well.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
So even with the improved version I'm a bit confused:
Am I buying a ticket for a user or am I buying a ticket from a user? We've lost the relationships between the action, direct object, and indirect object. What are the side effects? What account is being used to provide funds, some global?
What does the function return? Maybe True/False depending on if the transaction succeeded? Or maybe it returns some type of receipt and throws some exception if it fails? I don't know.
This is just as scary when I modify the function as when I use it. I don't know what the implicit API contract is and I don't know if my modifications might break existing calling functions in strange ways. Its possible that I do something that misses all paths for a reasonably robust set of unit tests in the package.
While I agree that some effort should be but into self-explanatory code, its simply too tall an order in principle, and impossibly difficult in practice to explicitly state the full behavior of a function in its name and call signature - even with static typing or type hinting. I'll also admit that for private or locally scoped informal helper functions that won't be called outside the module or functional unit its ok to lack a specification.
So for the above function one could write a docstring or specially formatted comment as follows:
Now I have an API contract that I can test against, depend on when I call it, and understand my limitations when I make changes. Even better, with some minimal tooling I can use properly formatted comment or docstring to autobuild the API documentation. So when I change the function, I can change the documentation.
There are even tools and approaches where you can embed tests into your docstring so the comments so that the API contract is stated, documented, and checked all in the same place right alongside the code.
I also think it makes the what and how of the code easier to read after one has placed the contract summary into their head. Furthermore, consumers of the function don't need to read the code at all, everything they need to know is in the docstring.
I've never used docstrings, sounds like something I should check out! With the added testing it sounds even more useful.
Hi,
I just gave a simple example, of course, maybe I should add more examples and not only at the beginning of the function, in fact I didn’t provide any context, it just was trying to explain why we should put more emphasis on naming and proper variable name usage, I didn’t specified if that was an API, etc.
I’m totally agree what you did but that is the difference between leaving comments and create documentation, you are using embed tools for creating an a contract for an API, documentation is much higher level, I stated the difference. I’m agree with creating docstrings( in python for example) but it is a difference thing from leaving comments. If you are in the middle of the function, you can’t use docstring. If you need to leave a comment to explain what are you doing: 1. Likely your function is doing more than One Thing and I don’t recommend that 2. Your code isn’t clear 3. And if your change your logic you need to mantain code and comment as well.