Add and improve type annotations by oprypin · Pull Request #1401 · Python-Markdown/markdown (original) (raw)

I'm saying that a user will never call a private method, so no it does not need to be documented in the way that a public method would be. Of course, the method may need to have some documentation written for the developer of the code. However, that documentation can be more terse and make assumptions about the knowledge and understanding of the reader that would not be appropriate for user documentation. Sometimes, that documentation is nothing more than well chosen method and argument names. Other times, some comments are necessary as well.

As an example, take the case of a method which returns None. I think it is reasonable to assume that the developer of the code knows that a lack of a return statement will result in the method returning None. Therefore, the explicit return statement is not needed. Neither is an annotation or a comment. Such things are just noise which offer no value. However, if this is a method which may be called by a user, then those assumptions should not be made and it is necessary to add the noise via comments, annotations and maybe even a return statement.

I prefer that terse documentation in code comments. Even as a user of a library, when reading through unfamiliar code to understand how it works, I personally prefer that. And with nearly 20 years of reading Python code without type annotations, I see the annotations as noise.

Maybe I'm being a grump old guy here. But I'm just trying to explain my point of view. If I don't see any value in it, my first reaction is to reject it. So I ask, because maybe there is a point of view I'm missing.

If these changes are being suggested just so we can say the code has complete annotations and there is no other value in having them, then I'm inclined to so no thanks. But if there is real value, then that's fine. And I realize that just because I don't see the value that there isn't any. I just want to make sure there actually is and that someone isn't adding annotations because they think "everything must be annotated."