Wikibooks

C/Estrutura e estilo: Diferenzas entre revisións

Explorar o historial de forma interactiva
← Edición máis vellaEdición máis nova →
Contido eliminado Contido engadido
VisualTexto wiki
Gallaecio (conversa | contribucións)
4.675 edicións
Gallaecio (conversa | contribucións)
4.675 edicións
→‎Comments: Traduzo un anaco
Liña 106:
É preciso comentar que algúns editores de texto xa automáticamente realizan as tabulacións ao premer na tecla intro.
 
== Comments Comentarios==
Os comentarios poden ser moi útiles nun código para diversos propósitos. Son o modo máis doado para explicar o funcionamento e propósito de partes específicas dun programa, e mesmo supoñen unha separación visual entre varias partes do código. Comentar correctamente o teu código fará moito máis doado recordar para que servían moitas partes específicas do código.
 
Os comentarios en C (e noutras moitas linguaxes de programación) poden introducirse de dous xeitos:
Comments in code can be useful for a variety of purposes. They provide the easiest way to point out specific parts of code (and their purpose); as well as providing a visual "split" between various parts of your code. Having a good commentary throughout your code will make it much easier to remember what specific parts of your code do.
 
<font style="color:blue">// Comentarios dunha soa liña</font>
Comments in modern flavours of C (and many other languages) can come in two forms:
ou
<font style="color:blue">/*Comentarios de
máis dunha liña*/</font>
 
Nótese que o uso dos comentarios dunha soa liña é relativamente recente, e podería darse o caso de compiladores que non os entendesen, máis unha versión ao día do GCC da [[w:GNU|GNU]] non terá ningún problema.
//Single Line Comments
and
/*Multi-Line
Comments*/
 
Este capítulo centrarase nos diversos usos de cada un deles.
{{Warning|Note that Single line comments are only a very recent addition to C, and that some compilers may not support them. A recent version of [[Wikipedia:GNU Compiler Collection|GCC]] will have no problems supporting them.}}
 
===Comentarios dunha soa liña===
This section is going to focus on the various uses of each form of commentary.
 
Os comentarios dunha soa liña son o máis útil para comentarios na marxe que expliquen o que fan certas partes do código. O mellor lugar para situar estes comentarios é a continuación das declaracións de variables, e anacos de código que poidan precisar dunha explicacións.
=== Single-line Comments ===
 
Partindo do noso anterior programa, haberá dous lugares idóneos para situar un comentario dunha soa liña:
Single-line comments are most useful for simple 'side' notes that explain what certain parts of the code do. The best places to put these comments are next to variable declarations, and next to pieces of code that may need explanation.
 
<font style="color:#bc5ff8">#include</font> <font style="color:#ff48ff"><stdio.h></font>
Based on our previous program, there are two good places to place comments
*Line 40, to explain what 'int i' is going to do
'''<font style="color:#1b991b">int</font>''' main('''<font style="color:#1b991b">void</font>''')
*Line 80, to explain why there is a 'break' keyword.
{
'''<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:#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>;
}
 
===Comentarios de máis dunha liña===
This will make our program look something like
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">for</font>''' neste programa. Para este exemplo, chamaremos ao número de liñas ''i'', e o número de cadeas por liña ''l''.
10 #include <stdio.h>
11
20 int main(void)
30 {
40 int i=0; //Temporary variable used for 'for' loop.
41
50 printf("Hello, World!");
51
60 for (i=0; i<1; i++)
61 {
70 printf("\n");
80 break; //Exits 'for' loop.
90 }
91
100 return 0;
110 }
 
Un bo exemplo dun comentario de máis dunha liña que di que o propósito do bucle '''<font style="color:#bb2323">for</font>''' ''i'' é:
=== Multi-line Comments ===
/* ForBucle LoopFOR (int i)▼
 
Reproduce o seguinte procedemento i veces (por número de liñas). Realiza o bucle FOR l en cada repetición,
Multi-line comments are most useful for long explanations of code. They can be used as copyright/licensing notices, and they can also be used to explain the purpose of a path of code. This can be useful in two facets: They make your functions easier to understand, and they make it easier to spot errors in code (if you know what a path is ''supposed'' to do, then it is much easier to find the piece of code that is responsible).
e imprime unha nova liña ao final de cada repetición.
 
As an example, suppose we had a program that was designed to print "Hello, World! " a certain number of times, on a certain number of lines. There would be many for loops in this program. For this example, we shall call the number of lines ''i'', and the number of strings per line as ''j''.
 
A good example of a multi-line comment that describes 'for' loop ''i'''s purpose would be:
▲ /* For Loop (int i)
Loops the following procedure i times (for number of lines). Performs 'for' loop j on each loop,
and prints a new line at end of each loop.
*/
 
Isto explica apropiadamente o que debe facer ''i'', sen afondar no que fai ''l''. 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.
This provides a good explanation of what 'i's purpose is, whilst not going into detail of what 'j' does. By going into detail over what the specific path does (and not ones inside it), it will be easier to troubleshoot the path.
 
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.
Similarly, you should always include a multi-line comment as the first thing inside a function, to explain the name of the function; the input that it will take, how it takes that input; the output; and the overall procedure that the function is designed to perform. Always leave the technical details to the individual code paths inside your program - this makes it easier to troubleshoot.
 
A function descriptor should look something like:
Traído desde «https://gl.wikibooks.org/wiki/C/Estrutura_e_estilo»