• Revista PROGRAMAR: Já está disponível a edição #53 da revista programar. Faz já o download aqui!

dnascimento

Comentar Código

14 mensagens neste tópico

Boas,

estou a desenvolver o meu 1º projecto de programação. Ao que sei é bastante importante comentar o código. Há um conjunto de "regras" que seja normal todos seguirem? Quais são?

0

Partilhar esta mensagem


Link para a mensagem
Partilhar noutros sites

Como assim? A comentar? Que eu saiba não. A não ser o comentário dever ser correspondente à linha que se segue. Basicamente, comentar o código serve para tu, ou se outra pessoa pegar no código, este ser mais fácil de interpretar. :)

0

Partilhar esta mensagem


Link para a mensagem
Partilhar noutros sites

Existem várias convenções para comentar o código, mas normalmente depende da linguagem que estás a usar.

Por exemplo, para Java e usando Javadoc tens aqui a documentação formal:

http://java.sun.com/j2se/javadoc/writingdoccomments/

(podes fazer scroll ao longo da página para ver exemplos)

Diga-se que as regras de Java aplicam-se (com as devidas diferenças) a quase todas as linguagens.

0

Partilhar esta mensagem


Link para a mensagem
Partilhar noutros sites

Em Scheme  :) :) E depois vai ser em Assemble, C, etc.... Como é para avaliar... É que se fosse para mim escrevia a meu gosto  :confused:

0

Partilhar esta mensagem


Link para a mensagem
Partilhar noutros sites

Mais um aluno da FEUP suponho.

Isto deve-te dar jeito:

http://www.cs.sfu.ca/CC/310/jim/Coding_Conventions.pdf

De modo geral, tenta comentar o que faz cada função, que argumentos recebe, restrições sobre os argumentos, o que retornar, restrições e garantias sobre o que retorna.

Por exemplo, se queres fazer uma função para achar a raiz quadrada de um número, referir o que faz, que o número deve ser >= 0, e que o resultado garante uma dada precisão, por exemplo.

Isto para ser completa, claro que não se aplica a todas as funções.

0

Partilhar esta mensagem


Link para a mensagem
Partilhar noutros sites

Tal como o documento que o Warrior te deu diz, não sejas de extremos nos comentários, isto é, não é correcto deixar o código não comentado, mas também não vais fazer comentários linha a linha.

Foi-me transmitido essencialmente que comentários ajudam outros a perceber o teu código, ou mesmo tu próprio, passado algum tempo sem pegares nos projectos. Tenta imaginar-te nestas situações e fazer comentários apenas daquilo que achas que é menos usual, um caso particular de uma função/rotina, etc.

0

Partilhar esta mensagem


Link para a mensagem
Partilhar noutros sites

A regra que eu sigo é mais ou menos a seguinte:

Não comentar o que o código que escrevi faz, mas comentar PORQUE fiz aquele pedaço de código.

Normalmente tenho um desses por classe, nos métodos auxiliares e ciclos mais esquisitos.

0

Partilhar esta mensagem


Link para a mensagem
Partilhar noutros sites

Para quem utliza o Visual Studio 2008, há uma funcionalidade muito util:

- Basta antes da declaração de classes  e membros das classes, inserir um comentário inserindo três apostrofes ('''), que logo aparece um local para colocar o sumario, a lista de parametros, o valor de retorno e mas alguma informação util.

Estas informações aparecem no Object Browser e também consoante escrevemos o código.

0

Partilhar esta mensagem


Link para a mensagem
Partilhar noutros sites

isso não é só no 2008. referes te ao '''<summary>Info</summary>?

já o 2005 tem isso... uso regularmente para comentar as funções,estruturas etc....

0

Partilhar esta mensagem


Link para a mensagem
Partilhar noutros sites

Eu se calhar faço mal, mas tenho a mania de explicar num comentário o que cada determinada parte do código faz. E se precisar numa linha mais manhosa, deixo lá algo à frente. Isto leva é a muito comentário no código, mas acho que é daquelas coisas que é melhor a mais que a menos..

0

Partilhar esta mensagem


Link para a mensagem
Partilhar noutros sites

Eu se calhar faço mal, mas tenho a mania de explicar num comentário o que cada determinada parte do código faz. E se precisar numa linha mais manhosa, deixo lá algo à frente. Isto leva é a muito comentário no código, mas acho que é daquelas coisas que é melhor a mais que a menos..

Eu depende. Quando me lembro comento tudo, ou então não comento nada. :)

0

Partilhar esta mensagem


Link para a mensagem
Partilhar noutros sites

Eu se calhar faço mal, mas tenho a mania de explicar num comentário o que cada determinada parte do código faz. E se precisar numa linha mais manhosa, deixo lá algo à frente. Isto leva é a muito comentário no código, mas acho que é daquelas coisas que é melhor a mais que a menos..

Comentar bloco a bloco? Também fazia isso, agora limito-me a ter no inicio da função p.e. o que é que ela faz e qual é o processo. Depois tenho antes de cada bloco um comentário a dizer que parte aquilo faz (preparação, ir buscar dados) e quando tenho código mais manhoso tenho um comentário a explicar o que ele faz/como o faz.
0

Partilhar esta mensagem


Link para a mensagem
Partilhar noutros sites

estou a desenvolver o meu 1º projecto de programação. Ao que sei é bastante importante comentar o código. Há um conjunto de "regras" que seja normal todos seguirem? Quais são?

No que toca a estilos de código, não há um conjunto de boas práticas que todos sigam. Há diversos estilos com diversas boas práticas. O que tens que fazer é encontrar um estilo bem definido que resulte bem para ti e para quem trabalha contigo.

Depois há variações que dependem do tipo de linguagem. Não concordo com quem diz que as regras do java se devem aplicar a todas as outras, ou perto disso. Por exemplo os comentários em Perl são bastante diferentes e há estilos bastante diferentes a malta do Java é que tem a mania de aplicar as regras deles às outras coisas...

Por exemplo em Perl existe um livro que fala de boas práticas a respeito de vários aspectos de programação em Perl. Que é seguido por muitos, mas não é seguido por todos e abordo nos primeiros capítulos alguns dos diferentes estilos de código utilizados em várias linguagens.

Mas por exemplo eu deixo comentários nas seguintes situações:

* No topo do ficheiro, explicando que ficheiro é aquele, quem o fez, referências a documentação, etc...

* Quando defino uma função, deixo sempre um comentário que resume o que ela faz;

* argumentos de funções que não sejam muito óbvios;

* sempre que inicio um novo bloco de código (ou conjunto de blocos que estejam relacionados) explico o que faz esse bloco (isto é particularmente importante em casos de blocos de código dentro de outros blocos);

* sempre que uso alguma feature da linguagem que é menos utilizada;

* sempre que uso uma expressão regular que não seja muito, muito, muito muito simples (e mesmo assim às vezes também uso para estas);

* tento dividir todo o código que faço dentro de um bloco em partes separadas de acordo com os passos que eles fazem (e não justifique ser uma função à parte), coloco um comentário de poucas palavras sobre passo em causa;

Tenho o objectivo de fazer com que qualquer programador iniciante que não conheça a linguagem em causa ache trivial entender e modificar o código que eu faço. A programação não deve ser algo difícil, mas sim trivial.

Por isso tento fazer com que o código seja facilmente entendido e os comentários ajudam bastante.

0

Partilhar esta mensagem


Link para a mensagem
Partilhar noutros sites

Crie uma conta ou ligue-se para comentar

Só membros podem comentar

Criar nova conta

Registe para ter uma conta na nossa comunidade. É fácil!


Registar nova conta

Entra

Já tem conta? Inicie sessão aqui.


Entrar Agora