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.
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.