[Tutor] CONSTANTS -- Is it appropriate to use uppercase names within a function or method?

[Mats Wichmann]

On 11/12/19 2:00 PM, boB Stepp wrote:

> The program from which I drew today's posting was meant to be a
> simple, throw-away script to inspire me to actually read and study to
> the end the BIG BOOK OF PYTHON, i.e., "Learning Python, 5th ed." by
> Lutz.  Alas!  Its inspiration proved to be short-lived.  However, in
> typical boB style, I could not resist toying around with it to apply
> things to it as I learned them.

in my humble opinion, this is the way to go anyway - when something you 
read inspires you to tinker, stop there and do it.  don't wait to 
tinker... often I find I tried something out and after doing so I "got" 
that little tidbit the way I hadn't absorbed from what I read, and then 
that in turn helped out later when reading something further.

> 
> IF I were to use type annotations as you suggest, would there be any
> point to the more expansive docstring?  The combination of type
> annotations with already very descriptive variable names seems to make
> any more description superfluous.
> 

I don't think the community has settled on a style there, but in any 
case it should be what's comfortable.  I've been known to "tune out" 
descriptions that say too much without adding value in its repetition - 
something I'm painfully aware of as I'm prone to making that error as 
well (just see some past emails to tutor).  More is not always better 
when it comes to docs... Better is Better :)

certainly if you've used type hints, there's no need to add the type in 
the docstring as well.  there's docstring style (or perhaps more 
precisely, syntax that the popular Sphinx tool understands) for that 
otherwise, either

:param foo: description of foo
:type foo: int

which can be abbreviated if the type is simple enough:

:param int foo: description of foo

the type stuff there would be excessive if the signature were already 
type hinted.