Tengo una gran cantidad de documentación sobre mí, ya que cada vez que encuentro un tipo de pato complejo, necesito decir "este tipo de pato", pero me atrapan en un ciclo interminable de "su función requiere esto de esta entrada, pero no lo documenta ", y luego lo documenta. Esto se traduce en la documentación hinchado, repetitivo, tales como los siguientes:¿Cómo documentar un tipo de pato?
def Foo(arg):
"""
Args:
arg: An object that supports X functionality, and Y functionality,
and can be passed to Z other functionality.
"""
# Insert code here.
def Bar(arg):
"""
Args:
arg: An object that supports X functionality, and Y functionality,
and can be passed to Z other functionality.
"""
# Insert code here.
Y así sucesivamente, y así sucesivamente, para Baz, Qux, y otras funciones. Necesito una forma más breve de escribir "arg es un (tipo de objeto)".
Para algunos tipos de pato, es tan fácil como "un objeto parecido a un dict": sabemos lo que esperamos de un dict, y entonces, sabemos qué pasar. A dict, o algo que pueda imitarlo.
Creo que C++ tiene el mismo problema con los tipos de plantilla. Haskell lo tendría, pero uno puede usar la definición de una clase de tipo para documentarlo. (Nota: Haskell classes! = Clases en Java/C++/Python/etc.) (Nota: realmente no programo en Haskell, así que discúlpeme si es un ejemplo horrible)
¿Debo ir a la tradicional? OO route, y solo escribe una clase base, y dices, "algo como esta clase base" en los documentos? El código no exigiría derivar de la clase base (ya que no hay ningún requisito para que el objeto se derive de ella), y la clase base no agrega ningún valor excepto para documentar las propiedades de la interfaz, esencialmente.
Por otro lado, estoy programando Python, y trato de programar dentro de las expresiones idiomáticas de un idioma. (De lo contrario, usualmente duele). Las clases base son buenas para heredar la funcionalidad, pero cuando la clase base es completamente abstracta, no parece agregar valor en un lenguaje de pato.
EDITAR: Para las respuestas: Yo sé lo que es la tipificación de pato (que debería ser evidente a partir de la entrada). ¿Dónde lo documenta? Es la pregunta, esp. cuando no existe una clase para adjuntar documentación a.
Me gusta el término "actúa como" y mantengo los requisitos documentados en general a menos que haya una razón específica para exponer más detalles. Por ejemplo, si solo se necesita un indizador y una cuenta, aún diría que "actúa como una lista". Para otros tipos, es lo mismo: "x actúa como un animal", donde presumiblemente la idea de que un "perro es un animal" está documentada/asegurada en otra parte. –
@pst: Sí, pero ¿qué es un animal, y qué esperamos del animal, y dónde lo documentamos? – Thanatos
'clase Animal' y' clase Dog' en alguna parte, con su propia documentación :) Python está muy enraizado en el modelo de instancia de clase. –