Por ejemplo, en lugar de una introducción, o de unas palabras explicando de qué va el documento, el primer texto que puedes leer es el siguiente:
¿Realmente crees que esta frase merece estar en el primer párrafo? "me extendería bastante al explicar, y no quiero extenderme en explicar eso, así que eso no lo explicaré". La primera página de tu documento es oro, es lo primero (y quizás, en este caso, lo único) que muchas personas van a leer. ¿De verdad esa frase que has escrito vale su peso en oro? De todas las frases, de todo lo que puedes explicar en la primera página, ¿es esto lo más importante?
No me sale bien hacer introducciones, o no tengo ganas, ya que el contenido se ve en el título o al ir leyendo. Dado que tanta gente critica Flash, explico que es sólo de ejemplo y por qué lo usé. Voy al grano...
Estás asumiendo de entrada que la gente ya sabe de qué va tu documento, no pones digamos un cesped para que la gente entre a tu casa con facilidad.
Pero está más o menos en el título. Sólo falta aclarar qué forma de IA es, lo cual se va explicando.
O en tu caso, a mí me ha invitado a no seguir.
A mí las introducciones me aburren, pero bueno ¿qué hubieras puesto?
- ¿Qué puedo aprender de este documento?
- ¿Qué necesito saber antes de leer el documento?
- ¿Para quién es útil este documento, y para quién no?
- ¿Quién es la persona que escribe el documento, y cuál es su experiencia?
Vale, intentaré algo de eso, aunque se pierda el ir al grano.
Así lo veo más bonito.
- No me interesa referirme a qué tipo de programa es más sencillo, esos serían print "hola mundo"; me interesa uno de los más sencillos dentro de cierto tipo.
- Lo de dar el ejemplo... Ok.
- Decir de qué forma se podría escribir... Ok, creo.
- Usar azul no, ya que va en blanco y negro (puede que lo imprima, sale más barato en ByN).
- Usar gris para los comentarios... Ok, creo.
- No hay un fin en un 4to paso. Fin del código eso sí. ¿Pero tiene sentido poner "fin del código"? ...Ok.
- Decir "en nuestro caso la duda es" en vez de decir "la duda es"... Ok, creo.
- Decir "Encuentra el número que..."... Ok, aunque decirlo de 3 formas may be too much.
- Tu simplificación al final... Ok supongo.
Y hablando de cosas bonitas: Justo en seguida de este primer ejemplo, has puesto un ejemplo que de sólo verlo me ha dado dolor de cabeza.
Este código es un horror de código, mezclando inglés, español
Conozco a alguien que es purista en el sentido de que no dice "troll" sino "cibergamberro" por ejemplo, detesta la mezcla de palabras nuevas en inglés si está hablando en español. A mí a veces me resulta más cómodo decir las cosas en inglés, pero si molesta veremos.
El lenguaje del código es en inglés. La mayoría de comentarios son en español. Hasta ahí supongo que vamos bien.
- "actions for fotograma 1" es una escritura automática de Flash cuando se copia el código, es como código...
- Base.VS tendría que haber explicado qué es, ok, aunque lo explico más adelante. Tal vez debí explicarlo a la vez como hice más adelante, haré el cambio.
- Depth es por costumbre, y es mucho más corto que "profundidad". Hasta diría que suena mejor.
- Si explicase algunas cosas quedaría más claro, ok, lo que pasa es que pensé que la gente lo viera y que se explicara después... No pensé que fuese algo mal.
- A algunas variables me gusta llamarles en inglés. Además las abrevio para que no ocupen mucho de la línea cuando se usan con eval o cosas así.
En fin...
¿A qué le llamas código fuente? Creo que es el mismo de este foro. Trebuchet MS 14. Si te refieres a Action Script, entiendo, casi todos dicen lo mismo, pero yo ya expliqué que no discutiría sobre eso.
Me estás obligando a usar mi cerebro para entender tú código, en vez de usarlo para entender lo que me estás tratando de enseñar.
Se podría decir que una cosa requiere la otra... pero ok, intentaré que el código se presente junto a una explicación al lado.
¿Te has dado cuenta que te hicieron falta 3 páginas para explicar el código? En lugar de escribir de forma bonita, un programa que se entienda leyendo el código fuente, has incluido un código confuso, que requiere 3 veces más texto para entender lo que hace. ¿Te suena aquello del Clean Code?
Ten en cuenta que el código fue puesto 2 veces, pero bueno, en una nueva versión será sólo 1.
Una cosita más: Nunca digas
Si ya de entrada me dices que no se te da bien, ¿por qué se te tendría que dar bien escribir un documento sobre el tema?
Porque no soy un genio (y bastante mediocre si de explicar se trata) aunque se puede aprender algo de mí. Es como si un cavernícola intentase explicar cómo hacer fuego diciendo "uh, um, ah"; ya se sabe que la explicación es horrible pero lo que se intenta decir es útil.
Y quiero ser sincero, no debería causar problema.
Mostrar Mensajes
