Reference.StyleGuide History

Hide minor edits - Show changes to markup

June 04, 2010, at 07:11 PM by Equipo Traduccion -
Changed lines 132-135 from:

For digital input switches, the default is to use a pulldown resistor on the switch rather than a pullup. That way, the logic of a switch's interaction makes sense to the non-engineer.

Keep your circuits simple. For example, bypass capacitors are handy, but most simple inputs will work without them. If a component is incidental, explain it later.

to:

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.

June 04, 2010, at 07:05 PM by Equipo Traduccion -
Added lines 71-72:

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.

Changed lines 74-77 from:

Use the wiring/Processing-style variable types, e.g. boolean,char,byte,int,unsigned int,long,unsigned long,float,double,string,array,void when possible, rather than uint8_t, etc. The former are explained in the documentation, and less terse names.

Avoid numbering schemes that confuse the user, e.g.:

to:

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

Changed lines 82-83 from:

If you need to renumber pins, consider using an array, like this:

to:

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

Changed line 85 from:

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

to:

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

Changed lines 88-89 from:

This allows you to refer to the new pin numbers using the array elements, like this:

to:

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

Changed line 92 from:
  digitalWrite(myPins[1], HIGH);  // turns on pin 7
to:
  digitalWrite(misPines[1], HIGH);  // enciende el pin 7
Changed lines 95-96 from:

It also allows you to turn all the pins on or off in the sequence you want, like this:

to:

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

Changed lines 98-99 from:

for (int thisPin = 0; thisPin < 6; thisPin++) {

   digitalWrite(myPins[thisPin], HIGH);
to:

for (int estePin = 0; estePin < 6; estePin++) {

   digitalWrite(miPines[ESTEPin], HIGH);
Changed line 101 from:
   digitalWrite(myPins[thisPin], LOW);
to:
   digitalWrite(mIPinEs[estePin], LOW);
Changed lines 106-107 from:

Explain the code at the start

Here's a good title block:

to:

Explica el código al principio

He aquí un buen bloque de títulos:

Changed lines 111-114 from:
	Sketch title
to:
	Título del Sketch 

        Describe lo que hace utilizando términos transitivo.
        Referencia los compoenentes conectados a cada uno de los pines	
Changed lines 116-117 from:
	Describe what it does in layman's terms.  Refer to the components
	attached to the various pins.
to:
	El circuito:
	* listado de los compoenentes conectados a cada entrada
	* listado de los compoenentes conectados a cada salida
Changed lines 121-123 from:
	The circuit:
	* list the components attached to each input
	* list the components attached to each output
to:
	Creado día mes año
	Por nombre del autor
	Modificado día mes año
	Por nombre del autor
Changed lines 126-132 from:
	Created day month year
	By author's name
	Modified day month year
	By author's name

	http://url/of/online/tutorial.cc
to:
	http://url/del/tutorial/online.cc
Changed line 130 from:

Circuits

to:

Circuitos

June 04, 2010, at 06:51 PM by Equipo Traduccion -
Changed lines 66-70 from:

Avoid single letter variable names. Make them descriptive

Avoid variable names like val or pin. Be more descriptive, like buttonState or switchPin

If you want to define pin names and other quantities which won't change, use const ints. They're less messy than #defines, yet still give you a way to teach the difference between a variable and a constant.

to:

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.

June 04, 2010, at 06:39 PM by Equipo Traduccion -
Changed lines 41-48 from:

Comment every variable or constant declaration with a description of what the variable does.

Comment every code block. Do it before the block if possible, so the reader knows what's coming

Comment every for loop

Use verbose if statements. For simplicity to the beginning reader, use the block format for everything, i.e. avoid this:

to:

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:

Changed line 50 from:

if (somethingIsTrue) doSomething;

to:

if (algoEsCierto) hazAlgo;

Changed line 53 from:

Instead, use this:

to:

En su lugar, usa esto:

Changed lines 55-56 from:

if (somethingIsTrue == TRUE) {

   doSomething;
to:

if (algoEsCierto == TRUE) {

   hazAlgo;
Changed lines 60-63 from:

Avoid pointers

Avoid #defines

to:

Evita punteros

Evita #defines

June 04, 2010, at 06:31 PM by Equipo Traduccion -
Changed lines 38-43 from:

Introduce concepts only when they are useful and try to minimize the number of new concepts you introduce in each example. For example, at the very beginning, you can explain simple functions with no variable types other than int, nor for consts to define pin numbers. On the other hand, in an intermediate example, you might want to introduce peripheral concepts as they become useful. Concepts like using const ints to define pin numbers, choosing bytes over ints when you don't need more than 0 - 255, etc. are useful, but not central to getting started. So use them sparingly, and explain them when they're new to your lesson plan.

Put your setup() and your loop() at the beginning of the program. They help beginners to get an overview of the program, since all other functions are called from those two.

Commenting Your Code

to:

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

June 04, 2010, at 06:29 PM by Equipo Traduccion -
Changed lines 33-36 from:

A

When forced to choose between technically simple and technically efficient, choose the former.

to:

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.

June 04, 2010, at 06:22 PM by Equipo Traduccion -
Changed lines 25-27 from:

Writing Example Code

Efficiency is not paramount; readability is.

to:

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.

A

Deleted lines 34-37:

The most important users of Arduino are beginners and people who don't care about code, but about getting projects done.

Think generously about people who know less than you about code. Don't think they should understand some technical concept. They don't, and they're not stupid for not understanding. Your code should explain itself, or use comments to do the same. If it needs a complex concept like registers or interrupts or pointers, either explain it or skip it.

June 04, 2010, at 06:17 PM by Equipo Traduccion -
Changed lines 7-24 from:

Writing a tutorial (most of this is borrowed from various editors over the years)

Write in the active voice.

Write clearly and conversationally, as if the person following your instructions were there in the room with you.

When giving instruction, write in the second person, so the reader understands that she's the one who'll be doing it.

Use short, simple sentences rather than compound sentences. It's easier for the reader to digest one instruction at a time.

Use pictures and schematics rather than just schematics alone. Many electronics hobbyists don't read schematics

Check your assumptions. Does the reader understand all the concepts you've used in your tutorial? If not, explain them or link to another tutorial that does.

Explain things conceptually, then lay out instructions on how to use it step-by-step.

Make your example do one thing well. Don't combine concepts unless it's a tutorial about combining concepts.

to:

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.

June 04, 2010, at 06:09 PM by Equipo Traduccion -
Changed lines 5-7 from:

This is not a set of hard and fast rules, it's a set of guidelines. Some of these guidelines might even conflict with each other. Use your judgment on when they're best followed, and if you're not sure, ask someone who'll be learning from what you write what makes the most sense.

to:

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.

June 04, 2010, at 06:05 PM by Equipo Traduccion -
Changed lines 1-4 from:

Arduino style guide

This is a guide for writing clear Arduino examples that can be read by beginners and advanced users alike. You don't have to code this way, but it helps if you want your code to be clear to all levels of users.

to:

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.

July 01, 2009, at 01:08 PM by Tom Igoe -
Added lines 38-39:

Put your setup() and your loop() at the beginning of the program. They help beginners to get an overview of the program, since all other functions are called from those two.

Deleted line 133:

Put your setup() and your loop() at the beginning of the program. They help beginners to get an overview of the program, since all other functions are called from those two.

July 01, 2009, at 01:08 PM by Tom Igoe -
Added lines 92-102:

It also allows you to turn all the pins on or off in the sequence you want, like this:

for (int thisPin = 0; thisPin < 6; thisPin++) {
   digitalWrite(myPins[thisPin], HIGH);
   delay(500);
   digitalWrite(myPins[thisPin], LOW);
   delay(500);
}

July 01, 2009, at 01:05 PM by Tom Igoe -
Changed lines 45-49 from:

Use verbose if statements. For simplicity to the beginning reader, use the block format for everything, i.e.: Avoid this: if (somethingIsTrue) doSomething;

Instead, use this:

to:

Use verbose if statements. For simplicity to the beginning reader, use the block format for everything, i.e. avoid this:

Changed lines 48-50 from:

if (somethingIsTrue == TRUE) {

   doSomething;

}

to:

if (somethingIsTrue) doSomething;

Added lines 50-56:

Instead, use this:

if (somethingIsTrue == TRUE) {
   doSomething;
}

Changed lines 60-61 from:

Avoid #defines

to:

Avoid #defines

July 01, 2009, at 01:01 PM by Tom Igoe -
Added lines 78-89:

If you need to renumber pins, consider using an array, like this:

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

This allows you to refer to the new pin numbers using the array elements, like this:

  digitalWrite(myPins[1], HIGH);  // turns on pin 7

April 29, 2009, at 01:19 AM by Tom Igoe -
Changed lines 78-83 from:

Circuits

to:

Explain the code at the start

Here's a good title block:

[@ /*

	Sketch title
Changed lines 85-89 from:

For digital input switches, the default is to use a pulldown resistor on the switch rather than a pullup. That way, the logic of a switch's interaction makes sense to the non-engineer.

Keep your circuits simple. For example, bypass capacitors are handy, but most simple inputs will work without them. If a component is incidental, explain it later.

Put your setup() and your loop() at the beginning of the program. They help beginners to get an overview of the program, since all other functions are called from those two.

to:
	Describe what it does in layman's terms.  Refer to the components
	attached to the various pins.
Changed lines 88-92 from:

Here's a good title block:

[@ /*

	Sketch title
to:
	The circuit:
	* list the components attached to each input
	* list the components attached to each output
Changed lines 92-93 from:
	Describe what it does in layman's terms.  Refer to the components
	attached to the various pins.
to:
	Created day month year
	By author's name
	Modified day month year
	By author's name
Changed lines 97-99 from:
	The circuit:
	* list the components attached to each input
	* list the components attached to each output
to:
	http://url/of/online/tutorial.cc

  • /

@]

Circuits

Changed lines 103-111 from:
	Created day month year
	By author's name
	Modified day month year
	By author's name

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

  • /

@]

to:

For digital input switches, the default is to use a pulldown resistor on the switch rather than a pullup. That way, the logic of a switch's interaction makes sense to the non-engineer.

Keep your circuits simple. For example, bypass capacitors are handy, but most simple inputs will work without them. If a component is incidental, explain it later.

Put your setup() and your loop() at the beginning of the program. They help beginners to get an overview of the program, since all other functions are called from those two.

April 29, 2009, at 01:16 AM by Tom Igoe -
Changed lines 36-37 from:

Consider the level of the reader for this particular example, and choose your concepts appropriately. Try to minimize the number of new concepts you introduce in each example. For example, at the very beginning, there's no need for variable types other than int, nor for consts to define pin numbers. On the other hand, in an intermediate example, you can introduce peripheral concepts as they become useful. Concepts like using const ints to define pin numbers, choosing bytes over ints when you don't need more than 0 - 255, etc. are useful, but not central to getting started. So use them sparingly, and explain them when they're new to your lesson plan.

to:

Introduce concepts only when they are useful and try to minimize the number of new concepts you introduce in each example. For example, at the very beginning, you can explain simple functions with no variable types other than int, nor for consts to define pin numbers. On the other hand, in an intermediate example, you might want to introduce peripheral concepts as they become useful. Concepts like using const ints to define pin numbers, choosing bytes over ints when you don't need more than 0 - 255, etc. are useful, but not central to getting started. So use them sparingly, and explain them when they're new to your lesson plan.

Changed line 50 from:
	[@
to:

[@

April 29, 2009, at 01:10 AM by Tom Igoe -
Deleted line 0:
Changed lines 60-61 from:

Variables

to:

Variables

Changed line 78 from:

Circuits

to:

Circuits

April 29, 2009, at 01:09 AM by Tom Igoe -
Added lines 1-108:

Arduino style guide

This is a guide for writing clear Arduino examples that can be read by beginners and advanced users alike. You don't have to code this way, but it helps if you want your code to be clear to all levels of users.

This is not a set of hard and fast rules, it's a set of guidelines. Some of these guidelines might even conflict with each other. Use your judgment on when they're best followed, and if you're not sure, ask someone who'll be learning from what you write what makes the most sense.

Writing a tutorial (most of this is borrowed from various editors over the years)

Write in the active voice.

Write clearly and conversationally, as if the person following your instructions were there in the room with you.

When giving instruction, write in the second person, so the reader understands that she's the one who'll be doing it.

Use short, simple sentences rather than compound sentences. It's easier for the reader to digest one instruction at a time.

Use pictures and schematics rather than just schematics alone. Many electronics hobbyists don't read schematics

Check your assumptions. Does the reader understand all the concepts you've used in your tutorial? If not, explain them or link to another tutorial that does.

Explain things conceptually, then lay out instructions on how to use it step-by-step.

Make your example do one thing well. Don't combine concepts unless it's a tutorial about combining concepts.

Writing Example Code

Efficiency is not paramount; readability is.

The most important users of Arduino are beginners and people who don't care about code, but about getting projects done.

Think generously about people who know less than you about code. Don't think they should understand some technical concept. They don't, and they're not stupid for not understanding. Your code should explain itself, or use comments to do the same. If it needs a complex concept like registers or interrupts or pointers, either explain it or skip it.

When forced to choose between technically simple and technically efficient, choose the former.

Consider the level of the reader for this particular example, and choose your concepts appropriately. Try to minimize the number of new concepts you introduce in each example. For example, at the very beginning, there's no need for variable types other than int, nor for consts to define pin numbers. On the other hand, in an intermediate example, you can introduce peripheral concepts as they become useful. Concepts like using const ints to define pin numbers, choosing bytes over ints when you don't need more than 0 - 255, etc. are useful, but not central to getting started. So use them sparingly, and explain them when they're new to your lesson plan.

Commenting Your Code

Comment every variable or constant declaration with a description of what the variable does.

Comment every code block. Do it before the block if possible, so the reader knows what's coming

Comment every for loop

Use verbose if statements. For simplicity to the beginning reader, use the block format for everything, i.e.: Avoid this: if (somethingIsTrue) doSomething;

Instead, use this:

	
if (somethingIsTrue == TRUE) {
   doSomething;
}

Avoid pointers

Avoid #defines

Variables

Avoid single letter variable names. Make them descriptive

Avoid variable names like val or pin. Be more descriptive, like buttonState or switchPin

If you want to define pin names and other quantities which won't change, use const ints. They're less messy than #defines, yet still give you a way to teach the difference between a variable and a constant.

Use the wiring/Processing-style variable types, e.g. boolean,char,byte,int,unsigned int,long,unsigned long,float,double,string,array,void when possible, rather than uint8_t, etc. The former are explained in the documentation, and less terse names.

Avoid numbering schemes that confuse the user, e.g.:

pin1 = 2
pin2 = 3
etc.

Circuits

For digital input switches, the default is to use a pulldown resistor on the switch rather than a pullup. That way, the logic of a switch's interaction makes sense to the non-engineer.

Keep your circuits simple. For example, bypass capacitors are handy, but most simple inputs will work without them. If a component is incidental, explain it later.

Put your setup() and your loop() at the beginning of the program. They help beginners to get an overview of the program, since all other functions are called from those two.

Here's a good title block:

		
/*
	Sketch title

	Describe what it does in layman's terms.  Refer to the components
	attached to the various pins.

	The circuit:
	* list the components attached to each input
	* list the components attached to each output

	Created day month year
	By author's name
	Modified day month year
	By author's name

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

*/

Share