[python #TYU-608129]: Best Practice

Hello, and thanks for reaching out!

The `r""" ... """` quote blocks denote our docstrings for our functions. The 
guiding design here comes from a few Python Enhancement Proposals (PEPs) that 
offer best practices in terms of code style [1], [2]. As these best practices 
have been in place for 20 years now, this also comes with the benefit of 
interoperability! For example, our automatic documentation tools (Sphinx + 
Autodoc) can expect these standard docstrings and produce our documentation 
site on its own. The `r` before the string quotes denote to Python that this 
string is a "raw" string literal [3] and so will ignore any special characters 
or escapes and allow us better control on the docstring that will go through 
our documentation tools. For further reading, we also follow the NumPy 
documentation style guide: https://numpydoc.readthedocs.io/en/latest/format.html

Decorators are a powerful tool in Python that you might use for a variety of 
reasons. For MetPy, decorators enable us to keep our function definitions 
relatively straightforward and the process for tracing their origins and 
citations should be relatively smooth. They allow us to pull out common 
functionality (notably: units and xarray support) and apply them "outside" of 
each function with the decorator shorthand, with control over how the functions 
interact with this shared functionality. This also makes it a bit easier 
(sometimes) to add new functionality to existing functions without changing how 
they behave. I hope this nutshell description is helpful, and don't hesitate to 
let me know if you have further questions about their usage! Thanks for the 
questions.


All the best,

Drew


  [1] PEP 8 (Python Style Guide): https://www.python.org/dev/peps/pep-0008/
  [2] PEP 257 (Docstrings): https://www.python.org/dev/peps/pep-0257/
  [3] Python String Literals: 
https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals


> As only a recent python programmer (switch from C++/Java/Fortran), I would 
> like to learn best practices for python documentation and set up:
> 
> Can I ask you first is there a URL that discusses documentation using r""", I 
> googled this.
> Is this considered a best practice for documentation of a function?
> 
> Second, I'm fuzzy on the use of decorators here, in a nutshell why did you 
> use them?
> 


Ticket Details
===================
Ticket ID: TYU-608129
Department: Support Python
Priority: Low
Status: Closed
===================
NOTE: All email exchanges with Unidata User Support are recorded in the Unidata 
inquiry tracking system and then made publicly available through the web.  If 
you do not want to have your interactions made available in this way, you must 
let us know in each email you send to us.