Prefiere ejemplos sobre documentación. ¿Es un problema de comportamiento?

Cada vez que me encuentro con una nueva API o lenguaje de programación o incluso simples páginas de manual de Linux , siempre (desde que recuerdo) los evité y en su lugar me basé perezosamente en ejemplos para comprender nuevos conceptos.

Inconscientemente, evito la documentación / API siempre que no sea sencillo o críptico o simplemente aburrido. Han pasado años desde que comencé a programar y ahora siento que necesito corregir mis costumbres, ahora me doy cuenta de que estoy causando más daño al abstenerme de leer documentación críptica / difícil, ya que todavía es un millón de veces mejor que los ejemplos como el oficial. La documentación tiene más cobertura que cualquier otro ejemplo. Incluso después de darse cuenta de que los ejemplos deben tratarse como un valor "agregado" en lugar de la fuente "primaria" para el aprendizaje.

¿Cómo puedo romper este mal hábito como programador o estoy pensando demasiado?

El hábito de confiar con preferencia en los ejemplos no tiene nada de malo: para usted, es solo la forma más rápida de obtener su respuesta. Además, los ejemplos son visuales. Es más fácil analizar visualmente un ejemplo en lugar de leer párrafos de texto y extraer la información que necesita.

Ejemplo:

Para enumerar los productos, uno debe usar la Indexacción del Productscontrolador, dado que GETes el único verbo posible aquí (consulte [Afectar productos] para obtener más información sobre las acciones utilizadas para crear, modificar y eliminar los productos de la base de datos).

Para obtener información detallada sobre un producto específico, agregue su identificador único al final del URI. Si desea obtener la lista de todos los productos disponibles, no agregue nada. También puede usar filtros, como se describe en la sección [REST filtros para seleccionar datos] del manual. Tenga en cuenta que la lista de productos está limitada a mil artículos. [Paginación] se puede usar para recorrer la lista completa, dado que cada página todavía está limitada a mil elementos.

También puede obligar al servicio a actualizar las cantidades en stock. Esto se hace configurando el refresh-quantitiesa uno.

es detallado, pero aburrido y apenas legible. El hecho de que necesites seguir enlaces empeora las cosas. Si agregamos algunas muestras, se vuelve mucho más fácil de entender:

Productos GET / Índice /
Productos GET / Índice / 12345 /
Productos GET / Índice /? Skip = 100 & take = 20
Productos GET / Índice /? Categoría = 12
Productos GET / Índice /? Precio = 0..39.90
Productos GET / Índice /? categoría = 12 y saltar = 100 y tomar = 20

El hecho de que use solo los ejemplos puede ser un problema. No deje de usar los ejemplos, pero recuerde que una vez que tenga la idea, una documentación más detallada puede ayudar. Por ejemplo, el ejemplo anterior no muestra que la lista de productos esté limitada a 1 000: debe leer la documentación para eso.

¿Cuándo sabes que deberías leer la documentación?

Cada vez que la API o la biblioteca no se comporta como esperaba. Por ejemplo, tomas la muestra y haces:

OBTENER Productos / Índice /? Skip = 6000 & take = 3000

Por alguna razón, devuelve menos de 3 000 artículos, mientras que tiene más de veinte mil productos en su base de datos. En este caso, la API no se comporta como se esperaba, por lo que es un buen tiempo para leer la documentación detallada.

La información proporcionada por la documentación se divide en tres categorías:

• Receta.
• Referencia.
• Conocimiento experto.

Recetas o ejemplos hacen un puente entre el dominio del problema y las funcionalidades del software. La referencia describe completamente algunas funcionalidades y es útil si desea adaptar una receta a un caso específico.

(El conocimiento experto asigna conceptos del dominio del problema a conceptos de documentación, es útil si los conceptos se pueden expresar de varias maneras o si los usuarios del software no son expertos en el campo).

¿Cómo puedo romper este mal hábito como programador o estoy pensando demasiado? Cualquier sabiduría de los compañeros programadores es apreciada.

No creo que tu hábito sea malo. Cuando aprende una API, primero tiene una idea de qué problemas se pueden resolver y qué metodologías se proporcionan con la ayuda de Recetas (sus ejemplos). La documentación de referencia le ayuda a ajustar las metodologías a casos especiales.

Ejemplos son la documentación. No creo que sea malo familiarizarse con el punto de vista de la API. Si es la única documentación que observa, puede ser un problema. La mayoría de los ejemplos escatiman en la verificación de errores, lo que puede conducir a un código demasiado frágil si no regresa y recoge las piezas faltantes de la documentación de referencia.

Diferentes personas aprenden mejor de diferentes maneras. Algunas personas son como tú y aprenden mejor de los ejemplos. Algunas personas son como yo y aprenden mejor de la documentación detallada. Tener ambos en la documentación parece cubrir bastante bien a la mayoría de los desarrolladores. Hable con un maestro, pueden decirle media docena de formas en que las personas aprenden.