docstring on obvious functions

[Rudi Hammad]

This not strictly related to maya but I wonder how you feel about it.

In sumary, I found my self in similar situations as this:

docstring example

I think the link above isn't really answering what is was asked.

He was asking about docstrings and people where responding to comments. I agree that unless necesarry your code shouldn't need any comments if you respect some programing princpiples. So you never find your self in long functions that requieres explanations with comments.

But what about the docstring in that example? If you are methodic in your documentation and document everything, you will end up many times writing docstrings longer than the functions it self. I don't think it is something bad,  just annoying.

Also some programs generate automatically documentation for your api. For instance I use sphinx-doc and all exisiting docstrings are parsed and nicely documented automatically.

what is your take on this?

R

[Justin Israel]

My take is that I want to see docstrings on public functions (which as you pointed out are different from comments). 

One added benefit of writing a docstring is that doc generators like sphinx, and IDEs, can produce helpful type linking and hinting. So if your function takes a certain type and returns a certain type, you may be able to get links to those types for more information. Also docstrings are helpful for an IDE to perform type hinting in python2. I know that in python3 we gain proper language-level type annotations, but for now we have to do it through comments and docstrings in python2.

It may be subjective for a developer to think that calculate_inverse(matrix) "obviously" accepts a numpy ndarray as its input type, and then chooses not to document it in a docstring. But what if there are different types that could be considered a matrix object and it is really not so obvious to someone reading the docs or the signatures and only sees that your api expects a "matrix"? Better to just use the appropriate docstring formats to add type information, until everything is python3 and you can do it all via type annotations.

--
You received this message because you are subscribed to the Google Groups "Python Programming for Autodesk Maya" group.
To unsubscribe from this group and stop receiving emails from it, send an email to python_inside_m...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/01a95b10-0d22-424d-9d10-b8642efbfab9n%40googlegroups.com.

[Alok Gandhi]

I would say it depends on the use case. The best practice is always to name things explicitly so you do not need docs (or comments). On that note, there was a movement called extreme programming (XP) in the late 90's that advocated use of no comments at all, amongst other things.

Anyway; having said that, I think docstrings have their place. If you are writing public API, and your user will look for the signatures, it is better to document. In that case, you might have to even be consistent and write docstrings for every single function/class, for the sake of uniformity and making your product look professional and polished, even if it seems redundant to do so. On the other hand, if your users are a small dev team working within a close group, use common sense and document where needed. Here, the rule of thumb would be - if your code can't explain what it is doing, use documentation.

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/CAPGFgA2MmtAPei1x2rWGzPD6YkjqsTMdxNKBeGLt3-u0GgwMVw%40mail.gmail.com.

[Rudi Hammad]

Cool, thanks for your input.

Personnally I am not a big fan of python's 3 typing (at least yet). I understand that being a duck typed language, having the type of return and to the argument type in the same function definition could be useful, but they don't replace the docstring do they? You still have to wright docstrings because most of the time you want to a little description. Also the IDE, by just hovering over the function, it tells you what you wrote in the docstring. I don't know, i am not sure how to feel about that in python 3. It seems adding redundancy in code.

So you don't docstring protected or private methods ( understanding that there is no 'protected' or 'private'  in python, but that's another discussion). Protected methods are meant to be used in subclasses so I think you probably want to docstring them too. Maybe just skip private's docstring then?

R

[Rudi Hammad]

El domingo, 2 de mayo de 2021 a las 21:51:11 UTC+2, Alok Gandhi escribió:

 In that case, you might have to even be consistent and write docstrings for every single function/class, for the sake of uniformity and making your product look professional and polished, even if it seems redundant to do so.

 

yes, i document everything just for consistency, and sometimes i run into those simple methods that really don't need explanation, but since i use sphinx-doc to document my api I do it anyway.

[Alok Gandhi]

I wouldn't say you can comoletely ignore private methods while documenting your code. It would save a lot of time(and pain) for the maintainer, whether it's you reading it after 3 months or somebody else for that matter. 

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/fb391bd2-1019-4be7-9eae-07aa42d12589n%40googlegroups.com.

[Justin Israel]

Alok makes a good point that "it depends". You can poll for opinions but ultimately you have to make a decision about the project and just be consistent. 

I tend to lean towards the side of docstrings making it easier for the reader to quickly pick up what they need to know about the function/method/class, and it is not always the case that the docstring would only say a short sentence that matches the name of the function. It may need to describe other behaviours about the implementation. You should not require that a user actually dive into the source code to know what kind of exceptions the function might raise or when it decides to return a certain value. And at that point, you should probably be consistent with all the public symbols.

On Mon, May 3, 2021 at 7:56 AM Rudi Hammad <rudih...@gmail.com> wrote:

So you don't docstring protected or private methods ( understanding that there is no 'protected' or 'private'  in python, but that's another discussion). Protected methods are meant to be used in subclasses so I think you probably want to docstring them too. Maybe just skip private's docstring then?

I do add docstrings to private and protected functions if I think they need some explanation for the reader, but I think its less required than members of your public API. 

 

R

El domingo, 2 de mayo de 2021 a las 21:27:18 UTC+2, justin...@gmail.com escribió:

My take is that I want to see docstrings on public functions (which as you pointed out are different from comments). 

One added benefit of writing a docstring is that doc generators like sphinx, and IDEs, can produce helpful type linking and hinting. So if your function takes a certain type and returns a certain type, you may be able to get links to those types for more information. Also docstrings are helpful for an IDE to perform type hinting in python2. I know that in python3 we gain proper language-level type annotations, but for now we have to do it through comments and docstrings in python2.

It may be subjective for a developer to think that calculate_inverse(matrix) "obviously" accepts a numpy ndarray as its input type, and then chooses not to document it in a docstring. But what if there are different types that could be considered a matrix object and it is really not so obvious to someone reading the docs or the signatures and only sees that your api expects a "matrix"? Better to just use the appropriate docstring formats to add type information, until everything is python3 and you can do it all via type annotations.

On Mon, May 3, 2021 at 6:30 AM Rudi Hammad <rudih...@gmail.com> wrote:

This not strictly related to maya but I wonder how you feel about it.

In sumary, I found my self in similar situations as this:

docstring example

I think the link above isn't really answering what is was asked.

He was asking about docstrings and people where responding to comments. I agree that unless necesarry your code shouldn't need any comments if you respect some programing princpiples. So you never find your self in long functions that requieres explanations with comments.

But what about the docstring in that example? If you are methodic in your documentation and document everything, you will end up many times writing docstrings longer than the functions it self. I don't think it is something bad,  just annoying.

Also some programs generate automatically documentation for your api. For instance I use sphinx-doc and all exisiting docstrings are parsed and nicely documented automatically.

what is your take on this?

R

--
You received this message because you are subscribed to the Google Groups "Python Programming for Autodesk Maya" group.
To unsubscribe from this group and stop receiving emails from it, send an email to python_inside_m...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/01a95b10-0d22-424d-9d10-b8642efbfab9n%40googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "Python Programming for Autodesk Maya" group.
To unsubscribe from this group and stop receiving emails from it, send an email to python_inside_m...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/python_inside_maya/fb391bd2-1019-4be7-9eae-07aa42d12589n%40googlegroups.com.