ASM51

Para fazer a descrição de uma função no código, existe alguma ferramenta que gere um padrão de comentário?

obs: em C

Comentarios sao inuteis, condigo bom dispensa comentarios, pelo menos eh o que acho no presente.

No Presente podem parecer inutil os comentários

mas, se você tiver que rever daqui 3 , 4 , 5 anos verá falta que faz não os haver colocado


DJ

olha na epoca do delphi, eu usava MUITO...

colocava um resumo no inicio do arquivo, e antes de cada função, e em cada comando colocava sua açãa junto com uma explicação...

nos dias de hj tento por o menos possivel pq percebi que aumentava o tamanho do .exe... agora nunca parei para ver se tambem afeta nos .hex ... muitos falam que não pois o compilador não é uma ação a ser observada para o compilador, mas outros falam que implica no tamanho, pois o compilador ira adcionar dentro do hex o comentario tb... vai la saber....

rcakto,

Pode comentar a vontade, nada vira .hex

e manga com leite também não faz mal

Digo isso, porque codigo bem feito, eh alto explicativo. Comentario apenas em niveis de abtracao muito elevado.

Ja trabalhei com codigos de 12 anos, os comentarios sao apenas tempo perdido, para que comentar o que a rotina faz? Gostaria de comentarios mais voltados ao problema em si.

Hoje uso uma técnica, que me tem ajudado, mesmo após ter esquecido quase tudo do programa (qualquer que seja).
1 - Faço um arquivo no Word com todo o projeto. Tanto a parte prática como a teórica.
2 - Crio figuras, gráficos, fluxogramas etc., de outros softwares.
3 - Incluo no Word, figuras, gráficos, fluxogramas etc., gerados pelos softwares do item 2 (Ctrl + C e Ctrl + V).
3 - Incluo equações no Word via "Equation Editor" Menu>Inserir>Campo>Eq.
4 - Coloco anexos no final do arquivo.doc.
5 - Coloco todos os arquivos gerados, referentes ao projeto, em um diretório com nome sugestivo.
6 - Aí, baseado nesse arquivo, faço o meu firmware, além de incluir o máximo de comentários.
Depois que passei a fazer isso, nunca mais tive problemas em "lembrar" das coisas do projeto.
Como minhas PROMs estão virando RAMs voláteis e meu clock já não é o mesmo, tive que partir para essa solução. Hehe!
MOR_AL

Isso MOR_AL

Você esta fazendo a Documentação completa.

Coisa que todos nós deveriamos cuidar

Eu incluido

DJ

Mas, há que ter bom senso

Excesso de comentários atrapalha

Há Instruções tão explicitas que o Comentário passa a ser redundante

DJ

Concordo com a opinião de alguns de que os comentários atrapalham.
Na minha época de programação em C, eu criava funçoes com nomes gigantescos para cada nível hierárquico de função ( ex.: MonitoraFuncionamentoDoRelogio ou VerificaSeEhNumeroASCII ).

Algumas pessoas comentam cada função do programa, inserindo cabeçalhos, o que me parece exagero.
Também já vi programas em que literalmente entre cada linha de código havia um comentário. Isso faria sentido no mundo academico, mas não no profissional.

Também acho que uma documentação externa ao código ( fluxograma / Equation / etc... ) não compromete a inteligibilidade do código.

+++

Jonowsky,

Existem alguns tipos de comentários muito usados. Eu mesmo postei no Boteco uma piada sobre comentarios, em inglês, que pode mostrar alguns exemplos bastante usados.

Existem ferramentas para isso:

JavaDocs - Ferramenta para Java que pode servir de exemplo

Doxigen - http://www.doxygen.org/ - Usada para C++, porém tem configurações para adaptá-la para o C.

DocJet and NDoc - http://www.tall-tree.com/home.php4

CWeb - http://www-cs-faculty.stanford.edu/~knuth/cweb.html

Comentários são extremamente importantes. Os programas produzidos são investimento da empresa, caso o funcionário morra, se demita ou seja demitido a empresa faria novo investimento para o mesmo produto?

Eu sou um programador que está entre meia-boca prá 1/4 de boca. Eu descobri duas coisas, que são referentes ao meu ser próprio e particularizado:
- se não entupir meu código de comentários, eu esqueço o que ele faz e como ele faz, depois de 15 minutos de escrito (sério).
- escrever o comentário sobre o que o código faz logo a seguir, antes de escrever o código, me ajuda a pensar no problema. É bastante comum vir uma idéia boa enquanto escrevo o comentário.

E também descobri que, comigo, não existe essa de código auto-explicativo.

Mas cada um é cada um.

Eu acho que tem código que é auto-explicativo, mas outros não.

eu coloco na maioria das funções o comentário antes dela, inclusive as revisões feitas nesta rotina, para que servem os parâmetros, etc...

se não fossem os comentários, eu iria perder muito tempo para analisar códigos que eu mesmo fiz a mais de cinco anos... ( eu quis dizer a mais de 5 horas heheheh )...

Acho comentários super necessários.

Quando eu programava em assembler (a muitos anos atrás), aconteceu o caso de esquecer a solução que eu havia dado para um problema alguns dias após eu ter resolvido e o comentário me mostrou como eu havia resolvido o problema. Para quem programa em assembler ou já programou, sabe do que eu estou falando.

Em "C" também já aconteceu do comentário me relembrar qual solução eu havia dado para determinada encruzilhada que me deparei ao programar e tempos depois, precisar rever ou alterar o código.

Acho válido sim, inserir comentários, mas isso é uma decisão pessoal.
Apesar de se perder tempo inserindo notes, um dia ele pode te tirar de uma enrascada.

Hoje, uma das minhas atividades de trabalho é fazer melhorias em softwares escritos em c++ e c# por outras pessoas e adaptá-los à realidade de Hardware e Softwares da fábrica do Brasil. Quando há comentários feitos pelos programadores, facilita em muito a minha vida.

Realmente,

Os comentários são necessários sim, mas a dosagem depende do grau de "inteligibilidade" do código, na minha opinião.
Cada um aqui de fato pode estar opinando baseado na sua estruturação dos programas próprios, mas a prática de documentar num abiente corporativo é importante, ainda mais se não for estabelecido uma norma de geração de código.

Lembrando o humor inteligente do xultz num outro tópico :
"...Por via das dúvidas, eu entupo meus códigos de comentários para me proteger de mim mesmo..." ( http://www.asm51.eng.br/phpbb/viewtopic ... r&start=15 )

Enfim, cada caso é um caso e depende de cada pessoa ou norma da empresa empresa, também levando em conta o grau de complexidade e estruturação do código. Não faz sentido colocar um comentário em cada linha do código para um sistema cujo código tenha poucas páginas, mas já vi isso acontecer. É preciso dosar...

+++