C/Estrutura e estilo: Diferenzas entre revisións
Contido eliminado Contido engadido
m →Comentarios: <source lang="c"> |
m →Comentarios de máis dunha liña: <source lang="c"> |
||
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
Un bo exemplo dun comentario de máis dunha liña que di que o propósito do bucle
<source lang="c">
Reproduce
e imprime unha nova liña ao final de cada repetición.
</source>
Isto explica apropiadamente o que debe facer
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">
</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">
* 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 *
▲ * de máis dunha liña rodeado por *
▲ * un elegante bordo de asteriscos *
* Entrada : ningunha
▲ ***************************************/
int i=0; // Variable temporal usada para o bucle "for"
printf("Ola mundo!");
▲Aplicando isto ao noso programa orixinal:
for (i=0; i<1; i++)
{
printf("\n");
▲ <font style="color:blue">/************************************************************************************
break; // Saída do bucle "for"
▲ * Función : int main(void) *
▲ }
▲ * Saída : Devolve 0 se todo vai ben *
▲ * Procedemento: Imprime "Ola mundo!" e unha nova liña, e logo sae. *
▲ ************************************************************************************/</font>
▲ <font style="color:blue">/* Bucle FOR (int i)
▲ Imprime unha nova liña e sae. */</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.
|