C/Estrutura e estilo: Diferenzas entre revisións

Contido eliminado Contido engadido
Gallaecio (conversa | contribucións)
m →‎Comentarios: <source lang="c">
Gallaecio (conversa | contribucións)
Liña 149:
Os comentarios de máis dunha liña son o máis útil para grandes explicacións de código. Poden utilizarse para notas relativas aos dereitos de autor ou a licenza, e tamén para explicar o propósito de toda unha ruta de código. Isto é dobremente útil: por unha banda, facilita a comprensión das funcións, e pola outra, facilita o descubrimento de erros (se sabes o que unha ruta de código debería facer, serache máis doado atopar a parte do código culpable).
 
Por exemplo, poñamos que temos un programa deseñado para imprimir na pantalla "Ola mundo!" un certo número de veces, nun certo número de liñas. Habería moitos bucles '''<font style="color:#bb2323"tt>for</fonttt>''' neste programa. Para este exemplo, chamaremos ao número de liñas ''<tt>i''</tt>, e o número de cadeas por liña ''<tt>l''</tt>.
 
Un bo exemplo dun comentario de máis dunha liña que di que o propósito do bucle '''<font style="color:#bb2323"tt>for i</fonttt>''' ''i'' é:
<source lang="c">
/* Bucle FOR (int i)
Reproduce o seguinte procedemento i veces (por número de liñas). Realiza o bucle FOR l en cada repetición,
Reproduce eo imprimeseguinte unhaprocedemento novai liñaveces ao(por finalnúmero de liñas). Realiza o bucle FOR l en cada repetición.,
e imprime unha nova liña ao final de cada repetición.
*/
 
</source>
Isto explica apropiadamente o que debe facer ''<tt>i''</tt>, sen afondar no que fai ''<tt>l''</tt>. Entrando en detalles respecto do que fai a ruta específica (e non unha interna), facemos máis doada a tarea de identificar erros na ruta.
 
De xeito similar, deberías incluír sempre un comentario de máis dunha liña ao comezo dunha función, para explicar o nome da función, os datos de entrada que vai recibir e o modo en que os vai recibir, a saída de datos, e o procedemento que debe realizar a función. Deixa sempre os detalles técnicos para rutas de código individuais dentro do programa, pois será máis doado identificar erros.
 
A descrición dunha función debería de ser algo semellante a isto:
<source lang="c">
 
/* Función : int olamundo (int i,int j)
Entrada : int i (número de liñas), int l (número de instancias por liña)
Saída : 0 (se todo vai ben)
Procedemento: Imprime "Ola mundo!" l veces, e unha nova liña de saída para i liñas.
*/
</source>
 
Este sistema permite unha explicación punto por punto do que debería facer a función. Podes despois entrar en detalles sobre como se archiva despois cada aspecto do programa no programa.
 
Para rematar, se che gustan as presentacións de calidade, este sistema de comentario de máis dunha liña, permíteche engadir bordos con asteriscos ao teu comentario. Isto fainos resaltar moito máis do que resaltarían sen o bordo (especialmente soterrados baixo unha grande cantidade de código). Debería ser algo coma:
<source lang="c">
/***************************************
* Isto ven sendo un comentario *
* de máis dunha liña rodeado por *
* un elegante bordo de asteriscos *
* que nin os de Zara. *
***************************************/
</source>
Aplicando isto ao noso programa orixinal:
<source lang="c">
#include <stdio.h>
 
int main(void)
/***************************************
{
* Isto ven sendo un comentario *
/************************************************************************************/</font>
* de máis dunha liña rodeado por *
* Función : int main(void) *
* un elegante bordo de asteriscos *
* Entrada : ningunha * que nin os de Zara. *
* Saída : Devolve 0 se todo vai ben *
***************************************/
* Procedemento: Imprime "Ola mundo!" e unha nova liña, e logo sae. *
<font style="color:blue">/************************************************************************************/
int i=0; // Variable temporal usada para o bucle "for"
 
printf("Ola mundo!");
Aplicando isto ao noso programa orixinal:
 
<font style="color:blue">/* Bucle FOR (int i)
<font style="color:#bc5ff8">#include</font> <font style="color:#ff48ff"><stdio.h></font>
Imprime unha nova liña e sae. */</font>
for (i=0; i<1; i++)
'''<font style="color:#1b991b">int</font>''' main('''<font style="color:#1b991b">void</font>''')
{
printf("\n");
<font style="color:blue">/************************************************************************************
break; // Saída do bucle "for"
* Función : int main(void) *
}
* Entrada : ningunha *
* Saída : Devolve 0 se todo vai ben *
* Procedemento: Imprime "Ola mundo!" e unha nova liña, e logo sae. *
************************************************************************************/</font>
'''<font style="color:#1b991b">int</font>''' i=<font style="color:#ff48ff">0</font>; <font style="color:blue">// Variable temporal usada para o bucle "for"</font>
printf(<font style="color:#ff48ff">"Ola mundo!</font><font style="color:#ff48ff">"</font>);
<font style="color:blue">/* Bucle FOR (int i)
Imprime unha nova liña e sae. */</font>
'''<font style="color:#bb2323">for</font>''' (i=<font style="color:#ff48ff">0</font>; i<<font style="color:#ff48ff">1</font>; i++)
{
printf(<font style="color:#ff48ff">"</font><font style="color:#a7a0d7">\n</font><font style="color:#ff48ff">"</font>);
'''<font style="color:#bb2323">break</font>'''; <font style="color:blue">// Saída do bucle "for"</font>
}
'''<font style="color:#bb2323">return</font>''' <font style="color:#ff48ff">0</font>;
}
 
return 0;
}
</source>
Isto permite a calquera usuario do programa unha forma fácil de entender o que fai o código, e como funciona. Tamén prevé confusións ocn nomes similares de funcións.