Documentazione / definizione delle strutture dati in Python

Se stai scrivendo un codice che può essere utilizzato da altri programmatori in isolamento, e stai utilizzando strutture di dati che vanno oltre i semplici built-in, considera se puoi incapsularli o meno come classi.

Osserviamo alcuni metodi di esempio e cosa restituiscono.

def getMatrix(**args):

Chiamando questo posso presumere che l'output sarà una lista di liste con un semplice valore all'interno. Non serve molto aiuto.

def getCharacterCounts(**args):

In questo, potrei presumere che in base alle argomentazioni otterrò un dizionario in cui ogni chiave è un carattere e quindi il valore sarà un conteggio basato sulle occorrenze in alcune stringhe.

def getPerson(**args):

Ah, ora ci stiamo mettendo nei guai. Una persona è una cosa complessa e potrei memorizzarla come un dizionario, in questo modo:

person = {  name:"Bob",
            age: 37,
            date_of_birth: "1932-01-15",
            hobbies:['programming','arguing on the internet', 'cross stitch'],
         }

Tuttavia, man mano che questa struttura dati diventa più grande, si verificano più campi, l'esempio diventa più grande e quindi la documentazione deve iniziare a comprendere come risolvere i problemi quando i valori sono in conflitto - ad esempio, a meno che non siamo trasportati indietro all'anno 1969, data di nascita ed età sono incoerenti.

In sommario , se stai usando una struttura di dati che è variata nella struttura e include alcuni "meccanismi algoritmici", allora forse è tempo di richiamare la potenza della programmazione orientata agli oggetti ^TM .

1. Nomi. Dovrebbero significare qualcosa. I nomi degli argomenti non dovrebbero essere d o a , più probabilmente user_id_to_instance_dict o qualcosa del genere.

2. docstring. Le funzioni e le classi possono avere stringhe di documentazione, puoi spiegarne i tipi e la struttura

   class UserRegistry:
       """
       Here we tell what does this class do.
   
       Fields:
       - some_public_field - this field is used to store such and such data
   
       Private fields:
       - _user_id_to_instance - this is dictionary mapping user ID to User instance.
       """
       <class code>
   

3. Annotazioni. Python3 ci consente di annotare gli argomenti delle funzioni e di produrre con un'espressione python arbitraria.

   def count_women(self, id_to_instance_dict: "dict( user id -> User instance)") -> int:
   
   def average_age(self, id_to_instance_dict: dict) -> float:
   

4. Commenti. Puoi anche descrivere campi con commenti: classe UserRegistry:

   some_field = {} # dict(str -> int)
   
   def __init__(self):
       self.another_field = [] # list(tuple(str, str))
   

PS. Qualcuno può aiutarmi con la formattazione?