Add Type Hints and Docstrings to Future PR Requirements

[Sj-Si]

I think that going forward, it would be helpful for future PRs to require type hints and Docstrings in any function/class definitions. Of course it would be a stupid amount of work to update the existing code with this change, but it would be helpful to require any new changes to include this.

As for the Docstrings, I can take or leave that one... It would be nice to have but I can see where it would be annoying having to police the way that people write their documentation. I can already see a lot of cases where people go overboard with it and cases where people simply write terrible documentation that has to be fixed.

Type hints, however, should be fairly straight forward to implement.

Old PR:

def my_function(a, b):
    return str(a + b)

New PR:

def my_function(a: int, b: int) -> str:
    """Adds two numbers and returns the sum as a string."""
    return str(a + b)

or

def my_function(a: int, b: int) -> str:
    """Adds two numbers and returns the sum as a string.
    
    Args:
        a[int]: The first number to add.
        b[int]: The second number to add.
    
    Returns:
        str: The sum of the inputs represented as a string,
    """
    return str(a + b)

Of course for this simple example function, the second example would be overkill and just the single line docstring would suffice. But for more complex functions using the Args and Returns parts of the docstring could help.

If anyone has any additional suggestions or any feedback on this, please let me know.

[aalbacetef]

Some notes on this.

Type hints

Absolutely! I'm all for it and think it'd be great, specially if we all agree changes to old code should add type hints (i.e: progressively modernize the codebase). I would be opposed to purely annotation PRs though.

Would we be adding something like pyre or pyright to check for types? I think it'd be great to run this on the CI.

Docstrings

Agreed with two remarks though:

• docstrings are no replacement for good typing and proper naming
• PEP 8 and PEP 257 are a must

I'd stick with your first example, as it is more in line with PEP 257, namely focus on what the function does, not its signature.