Reference   Language (extended) | Libraries | Comparison | Changes

Guía de estilo Arduino

Esto es una guía para escribir ejemplos de Arduino claros que puedan ser leidos por principiantes, así como por expertos. No tienes que codifcar de esta forma, pero ayuda si quieres que tu código sea claro para todos los niveles de usuarios.

Esto no es un conjunto de reglas rígidas y rápidas, es un conjunto de guías. Algunas de estas guías pueden incluso tener conflictos con otras. Utiliza tu juicio para seguir las que estimes adecuadas, y si no estás seguro, pregunta a alguien que esté aprendiendo de lo que escribes qué tiene más sentido.

Escribiendo un tutorial (la mayoría está tomado prestado de varios editores a lo largo de los años)

Escribe usando la voz activa.

Escribe claro y a modo de conversación, como si la persona que está siguiendo tus instrucciones estuviesen en la habitación contigo.

Al dar instrucciones, escribe en segunda persona, de manera que el lector entienda que él es la única que lo está haciendo.

Utiliza frases cortas y sencilla más allá de frases compuestas. Es más sencillo para el lector digerir una instrucción cada vez.

Utiliza dibujos y esquemas más que sólo esquemas, Muchos componentes aficionados a la electrónica no saben leer esquemáticos.

Comprueba tus suposiciones. ¿Entenderá el lector todos los conceptos que has usado en el tutorial? Si no, explicalos o enlaza a otro tutorial que lo haga.

Explica las cosas conceptualmente, después ordéna las instrucciones para usarlas paso a paso.

Haz que tu ejemplo haga una cosa bien. No combines conceptos a nos er que sea un tutorial sobre combinar conceptos.

Escribiendo código de ejemplo

La eficiencia no es primordial, la legibilidad sí.

Los usuarios más importantes de Arduino son principiantes y gente que no se preocupa por el código, pero sacan proyectos adelante.

Piensa generosamente sobre gente que sabe menos que tú sobre código. No pienses que ellos deberían entender un concepto técnico. No lo harán, y no son estúpidos por no entenderlo. Tu código debería ser autoexplicativo, o usar comentarios que lo expliquen. Si es ncesario un concpeto complejo como registros, interrupciones, o punteros, en vez de explicarlo, pasa de ello.

Si te ves obligado a elegir entre técnicamente sencillo o técnicamente eficiente, elige el primero.

Introdude sólo conceptos cuando sean útiles y trata de minimizar el número de conceptos que introduces en cada ejemplo. Por ejemplo, muy al comienzo, puedes explicar funciones simples sin otro tipos de variables que int, ni utilices constantes int para definir los números de los pines. Por otro lado, en un ejemplo intermedio, podría querer introducir conceptos periféricos siempre que sean útiles. Conceptos como la utilización de constantes int cuando no necesitas más de 0 - 255, etc, son útiles, pero no importantes para empezar. Por lo tanto úsalas moderadamente, y explicalas cuando son nuevas en tu lección.

Pon tu setup() y tu loop() al comienzo del programa. Esto ayudará a los principiantes a da un vistazo al programa, ya que cualquier otra función es llamada desde esas dos.

Comentando tu código

Comenta cada variable o contante que declares con una descripción de lo que hace la variable.

Comenta cada bloque de código. Hazlo antes del bloque si es posible, para que el lectro sepa lo que viene a continuación.

Comenta cada bucle for

Expande las sentencias. Por simplicidad para el lector principiante, utilizar el formato bloque para todo, p.e. evita esto:

if (algoEsCierto) hazAlgo;

En su lugar, usa esto:

if (algoEsCierto == TRUE) {
   hazAlgo;
}

Evita punteros

Evita #defines

Variables

Evita nombres de variables de una sóla letra. Hazlas descrptivas

Evita nombres de varialbles como val o pin. Sé más descriptivo, como estadoBoton or pinConmutacion

Si quieres definir los nombres de los pines y otras cantidades que no van a cambiar, usa contantes enteras (cont int). Son menos problemáticas que los #defines, además te da la vñia de enseñar la diferencia entre una variable y una constante.

Utiliza tipos de variables del estilo de wiring/processing, p.e. boolean,char,byte,int,unsigned int,long,unsigned long,float,double,string,array,void si es posible, antes que uint8_t, etc. Las primeras se explican en la documentación, y nombres menos lacónicos.

Evita numerar los esquemas de forma que confundan al usuario, p.e.:

pin1 = 2
pin2 = 3
etc.

Si necesitas renumerar los pines, considera utilizar un array, como este:

int misPines[] = { 2, 7, 6, 5, 4, 3 };

Esto te permite referirte a los nuevos números de pines utilizando los elementos del array, como este:

  digitalWrite(misPines[1], HIGH);  // enciende el pin 7

También te permite encender o apagar todos los pines en la secuencia que tu quieras, como esta:

for (int estePin = 0; estePin < 6; estePin++) {
   digitalWrite(miPines[ESTEPin], HIGH);
   delay(500);
   digitalWrite(mIPinEs[estePin], LOW);
   delay(500);
}

Explica el código al principio

He aquí un buen bloque de títulos:

		
/*
	Título del Sketch 

        Describe lo que hace utilizando términos transitivo.
        Referencia los compoenentes conectados a cada uno de los pines	

	El circuito:
	* listado de los compoenentes conectados a cada entrada
	* listado de los compoenentes conectados a cada salida


	Creado día mes año
	Por nombre del autor
	Modificado día mes año
	Por nombre del autor

	http://url/del/tutorial/online.cc

*/

Circuitos

Para interruptores de entrada digital, por defecto se utiliza una resistencia de pulldowm en el interruptor, mejor que de pullup. De esta forma, la lógica de una interacción con el interruptor tiene sentido para el no ingeniero.

Haz tus circuitos sencillos. Por ejemplo, los filtros de condensadores están a la orden del día, pero la entrada más sencilla funcionará sin ellos. Si un componente es ocasional, explícalo después. Página principal Referencia

Correcciones, sugerencias, y nueva documentación deberán ser publicadas en el Foro (castellano) o en el Foro (inglés).

El texto de la referencia de Arduino está publicado bajo la licencia Creative Commons Reconocimiento-Compartir bajo la misma licencia 3.0. Los ejemplos de código de la referencia están liberados al dominio público.

Share