Teacher feedback from 2017-2018:
En esta página vas a usar campos de entrada para permitir que un bloque haga diferentes cosas.
En la página anterior se usaron los programas asterisco y molinillo, cada uno de ellos tenía una entrada indicando el número de ramas a desplegar. Ahora vas a aprender cómo crear un bloque propio con campos de entrada.
Los programas son esencialmente él mismo; la única diferencia radica en que algunos de los valores de entrada cambian. En lugar de hacer muchas copias, se puede hacer un bloque general 
que dibuje todos los diseños. El bloque debe funcionar para una gran variedad de valores de entrada.
molinillo con un campo de entrada para ingresar el número de ramas. Las instrucciones se encuentran a continuación, adicionalmente es posible ver el proceso en un video más adelante.
pinwheel, branches:.
Este bloque va a mover tu personaje o cursor, es una buena idea elegir la categoría "Movimiento" en la paleta de funciones.
El uso de la coma o los dos puntos no son necesarios, se usan únicamente como ayuda para dar mejor claridad al ejercicio.
branches:", ingresa el nómbre del campo de entrada y haz clic en "Aceptar" para agregarlo. Para este proyecto, haz clic en + luego de la palabra "branches:" e ingresa número de ramas como identificador del valor a ingresar.
pinwheel dentro de un bloque con forma de sombrero es llamado prototipo del bloque. A medida que se agregan campos de entrada, título y más detalles, se logra visualizar el bloque de la forma en que se presentará al usuario final. La única excepción es que el campo de entrada, en este ejemplo el óvalo naranja, contendrá valores.
pinwheel previamente creado.
molinillo.
¿Qué tipo de datos puede ser utilizado como campo de entrada? Todos los tipos de datos. En este ejemplo el campo de entrada espera un número, pero cualquier tipo de valor puede ser usado en el campo de entrada. Por ejemplo, se ha visto en ejercicios anteriores el bloque list, es posible recordar que recibía cadenas de texto. En Snap!, cualquier tipo de dato puede ser usado como entrada, puede ser reportado por un bloque, o puede ser incluido como elemento de una lista.
Al inicio, has hecho cinco copias del código del programa de molinillo para crear cinco diferentes tipos de figuras. Ahora, has hecho un procedimiento que incluye todos los pasos similares en las cinco versiones y usa un parámetro para manejar las diferencias.
Oh, about the orange box on 1.3.3, I think the comment on the hat block is okay, but the comment on the turn is exactly the sort of thing I wouldn't do. In fact I might make a point of saying that when you're /teaching/ someone, you (we) put in comments that you wouldn't use if you were just programming for yourself.
But the hat block comment in the movie isn't very good documentation. It should say "Draws a REGULAR five-sided polygon, with SIDE LENGTH set by the input." (Not really capitalized; I just did that to emphasize to you what's missing.)
Really it's hard to give an example of useful commenting that doesn't look stupid unless you have a big project. Then, for example, when some global variable is used without being set, you might want to attach a comment "FOO is set in procedure BAR that's called in the initialization."
Agregar comentarios a tu código puede ayudarte a recordar en qué pensabas al incluir ese bloque y la funcionalidad del mismo. Los comentarios ayudan a otras personas que leen el código a entenderlo mejor, y puede ayudar a evitar incluir errores gracias a que se incrementa su claridad. Por el contrario, no ayuda comentar todas las líneas de código, debes ser claro indicando únicamente cómo funcionan los bloques seleccionados dentro de tu código. Se pueden agregar comentarios en Snap! usando clic-derecho (o control-clic) en el área de trabajo y seleccionando la opción "Añadir comentario." Haz clic para ver una animación del proceso.
Se puede agregar un comentario sobre el bloque sombrero en el editor de bloques para crear un mensaje de ayuda que explique brevemente su funcionalidad. Es la mejor práctica recomendada para hacer comentarios ya que las personas pueden leer la descripción de que hace el bloque sin necesidad de ver dentro.
| Mala práctica de comentarios: | Buena práctica de comentarios: |  | |
 |
 |
 |
La importancia de incluir comentarios detallados radica en que programamos en lenguaje de programación con instrucciones cortas y sencillas, por lo que no podemos incluir nombre de variables largos o nombres de procedimientos tan detallados. (Normalmente no es posible incluir espacios en blanco en los títulos ya que se tendría que escribir ese nombre largo cada vez que se use la variable o procedimiento.) Es por eso que es común ver nombres como substLcUc en lugar de substituir todas las palabras en minúscula por mayúscula en una cadena. En el caso que un programa esté lleno de nombres abreviados para variables y procedimientos, es muy importante que el código tenga una buena documentación.
Comentar es otra forma de documentación. No es la mejor forma ya que agregar comentarios a un punto particular en el programa documenta únicamente un procedimiento o segmento de código, pero no explica como interactúan las diferentes partes del programa. Sin embargo, el uso de comentarios representa una forma sencilla de documentar pequeños detalles.
La documentación puede ser externa (escrita por los usuarios del programa) o interna (escrita por los desarrolladores del programa). Ambos tipos de documentación son importantes en el caso que el programa sea utilizado por personas diferentes a quién lo programa. Usualmente deben ser documentos separados, otra razón por la que los comentarios no deberían ser los únicos medios de documentación.
Si escribes un programa solo para tí, puede parecer innecesario incluir documentación interna. "Yo sé bien cómo funciona mi programa." Sin embargo, en el caso que el programa se use un año después, probablemente sea necesario un mantenimiento, y muy probablemente hayas olvidado los detalles de la implementación. En una clase de programación, como esta, la mayoría de programas que se escriben son muy pequeños, y se pueden entender sin problema. Pero toma en cuenta que los programas reales son generalmente mucho más grandes, ya que estos laboratorios han sido diseñados para tomarte menos de una hora de trabajo.
Es recomendable que el primer intento de documentar un código se haga antes de empezar a programar. La documentación expresa la funcionalidad esperada del programa (externo) y la estructura planeada (interna). Estos documentos pueden ser usados posteriormente para probar el código y asegurarse que se comporta según el plan.
Toma nota que cuando se manda a ejecutar un procedimiento dentro de un programa (por ejemplo pinwheel), el procedimiento es completado completamente antes de continuar con el resto de bloques dentro del programa.
pinwheel y el bloque set pen color. Crea tu propio arte.
