Mam kod, który skrapia harmonogram harmonogramu College i generuje listę list list (list) takich jak:

[[[[start_time, end_time], [module_code, period_type, {period_number}], [room_code]], {next modules...}],{next_days...}]

Gdybym chciał udokumentować tego rodzaju zwróconych danych w Pythonie (a prawdopodobnie Java lub inne języki) Czy byłaby tak najlepsza praktyka do tego?

Uwaga: Spojrzałem na PEP, ale nie byłem w stanie znaleźć niczego związanego z tym

0
stephenfin 25 wrzesień 2012, 14:18

2 odpowiedzi

Najlepsza odpowiedź

Tworzysz proste klasy do przechowywania danych zamiast używania zagnieżdżonych list:

 class TimeTableEntry(object):
     def __init__(self, start, end, module, room):
         self.start = start
         self.end = end
         self.module = module
         self.room = room

Następnie dokumentuje, że metoda zwraca listę tych. Dodatkową zaletą jest to, że teraz możesz dodać dodatkowe metody na tych obiektach. Dodaj metodę __str__ ułatwiając wyświetlanie. Itp.

Przede wszystkim możesz udokumentować te obiekty wejścia o wiele wyraźniej niż można udokumentować zagnieżdżoną strukturę typów prymitywnych.

4
Martijn Pieters 25 wrzesień 2012, 10:25

Ten rodzaj struktury jest lepszy modelowany jako słownik; z kluczem jest kodem pokoju. Każdy klawisz kodu pokoju posiada listę, a ta lista ma krążki, które reprezentują każdy kurs / zdarzenie.

schedule = dict()
schedule['room_1'] = [(start_time,end_time,module_code,period_type,..),
                      (start_time,end_time,module_code,period.....),
                      ...
                     ]
schedule['room_2'] = [ ... ] # as above

Ułatwia to udokumentowanie, a także daje możliwość robienia takich rzeczy jak:

for i in schedule:
   print '{0} events scheduled for room {1}".format(len(schedule[i]),i)

Oto, jak można go udokumentować:

def foo(bar):
    '''
    Does some magic with `bar`.  Cats may be harmed and
    the space time continuum may be disturbed if you pass in
    silly things like None.

    Args:
        bar: The best name for a variable since foo.

    Returns:
        A dict mapping keys to the room and rows representing
        the room's schedule. A row is represented as a list.
        Each element of the list is a tuple of strings representing
        and event. For example:

        {'room_1': [(start_time,end_time,module_code,period_type,..)]}
    '''
2
Burhan Khalid 25 wrzesień 2012, 10:27