Question about documenting functions
Question about adding documentation into your code (either for a future you or someone else). I'm self taught and I've been making a real effort to figure out home to do things the "right" way or more Pythonic way since I finished my PhD.
Is there a standard way of documenting your functions?
Below are two examples. The first is what I do now. I'm forgetful, so this helps when I come back to code much MUCH later. I don't have to parse the code much to know what it does. The second is what I think is closer to what people do? I recently learned about the 'typing' module and also learned about doc strings (like, six months ago).
If there's a standard, are these close? Is there a better way to do it? Am I worrying about minutia that I should just not worry about? Any advice would be super helpful. Thanks in advance (and sorry about formatting)!
Examples:
def heavilyDocumented(a, b, c):
"""
Purpose: Here's what it does
Args: a (int) - here's what the number represents
b (dict) - {"this is a descriptive key" : its_value}
c (str) - again, just saying what this represents
Return: Here's a description of what the return is (str)
"""
print("and the code goes here")
def lessDocumented(a: int, b: dict, c: str) -> str:
"""Here's what the function does"""
print("and the code goes here")