Jump to content
Sign in to follow this  
dnascimento

Comentar Código

Recommended Posts

dnascimento

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?

Share this post


Link to post
Share on other sites
scorch

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. :)


scorch_pp.png

PS: Não respondo a perguntas por mensagem que podem ser respondidas no fórum.

Share this post


Link to post
Share on other sites
Warrior

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.

Share this post


Link to post
Share on other sites
dnascimento

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

Share this post


Link to post
Share on other sites
Warrior

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.

Share this post


Link to post
Share on other sites
softklin

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.


Nick antigo: softclean | Tens um projeto? | Wiki P@P

Ajuda a comunidade! Se encontrares algo de errado, usa a opção "Denunciar" por baixo de cada post.

Share this post


Link to post
Share on other sites
edsousa

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.


Tharis Fan ClubMay Tharis bless you

Share this post


Link to post
Share on other sites
FreiNando

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.


O caminho mais curto para conseguir fazer muitas coisas é fazer uma de cada vez. Samuel Smiles

Share this post


Link to post
Share on other sites
Gooden

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....

Share this post


Link to post
Share on other sites
JoaoRodrigues

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..

Share this post


Link to post
Share on other sites
scorch

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. :)


scorch_pp.png

PS: Não respondo a perguntas por mensagem que podem ser respondidas no fórum.

Share this post


Link to post
Share on other sites
djthyrax

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.

Não peças ajuda por PM! A tua dúvida vai ter menos atenção do que se for postada na secção correcta do fórum!

Share this post


Link to post
Share on other sites
falco

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.

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
Sign in to follow this  

×
×
  • Create New...

Important Information

By using this site you accept our Terms of Use and Privacy Policy. We have placed cookies on your device to help make this website better. You can adjust your cookie settings, otherwise we'll assume you're okay to continue.