0

Estou com uma dúvida em fazer comentário descritivo relacionado aos parâmetros dessas 3 funções abaixo.

int proximoClientePreferencial(CLIENTE *filaPreferencial){
void mostrarFilaPreferencial(CLIENTE *filaPreferencial){
void adicionarFilaPreferencial(CLIENTE *filaPreferencial, int 
 tempoUtilizando){

Concordam com tais comentários:

// inteiro representando filaPreferencial    
int proximoClientePreferencial(CLIENTE *filaPreferencial){

// ponteiro de um nó filaPreferencial
void mostrarFilaPreferencial(CLIENTE *filaPreferencial){

// ponteiro de um nó filaPreferencial
// inteiro representando o tempo de atendimento em uma Fila Preferencial
void adicionarFilaPreferencial(CLIENTE *filaPreferencial, int 
 tempoUtilizando){
1
  • Amigo faça como desejar em seus comentários, quando comento algum código sempre tento ser o mais objetivo possível, como já falaram aqui, ser explícito para qualquer um entender. Porque futuramente alguém pode dar manutenção em seu código, por isso tente ser o mais claro possível, comentando tudo, sobre os nomes das funções eu acredito que está correto, está sendo claro, pelo menos é essa minha visão sobre sua dúvida. Espero ter ajudado. Qualquer coisa é só chamar. Commented 2/06/2017 às 17:44

1 Resposta 1

5

Um pouco de história

Resolvi responder porque há uma visão criada nos anos 50/60 de que deve comentar código. Era muito necessário porque programavam em Assembly que não tem como ser claro no código, ou ainda em linguagens que tinham limitações na quantidade de caracteres dos identificadores, ou ainda quando haveria algum tipo de custo em alguma fase do desenvolvimento ou execução em ter identificadores maiores.

Conforme as linguagens evoluíram e os computadores passaram ter capacidade que não dificulta se tem identificadores mais significativos, além de ter ferramentas que ajudam escrever código mas legíveis sem esforço, os comentário deixaram de ser tão úteis assim.

Porque comentário é útil

Eles ainda são úteis para indicar porque algo não intuitivo e foi feito daquela forma. Comentários que dizem o que o código está fazendo não tem mais sentido.

Acontece que muitas pessoas que se transformaram em professores aprenderam programar naquela época que fazia sentido, e não perceberam a mudança de paradigma na codificação. Continuaram repetindo o mantra de comentar tudo.

Isso mostra que mesmo no passado as pessoas já gostavam de aprender por receita de bolo, por boa prática, que nada mais são do que regras que as pessoas seguem cegamente sem saber porque estão fazendo aquilo. Fica parecendo mandinga, superstição.

Engenheiro só devem fazer algo quando eles sabem porque estão fazendo aquilo.

Esses professores formaram profissionais e outros professores com a mesma ideia de comentar tudo e de seguir regrinhas de ouro sem saber o fundamento daquilo. E hoje quase todo mundo que aprende um pouco programar se consideram professores informais e podem ensinar outras pessoas, mesmo que elas mesmas não saibam bem sobre aquilo. Percebeu como vira um telefone sem fio? Havia um motivação real para os comentários em tudo, hoje a motivação é outra, mas as pessoas ainda adotam o que ouviram falar sem questionar.

Comentários são ruins

Se o código for bem escrito futuramente ele será fácil de dar manutenção sem comentários. Se os comentários existem em excesso, ou eles são redundantes ou eles estão consertando um defeito de legibilidade do código. Conserte o defeito certo.

E ser redundante é ruim, fere o DRY, cria problemas de manutenção já que se a pessoa preferiu dar a legibilidade pelo comentário em vez do código ela dificilmente manterá sempre o código e o comentário sincronizado. Qualquer coisa que exige sincronização pede pra dar problema no futuro e criar problemas ainda maiores de legibilidade.

Seu código

Ele está bem legível. Talvez dê para melhorar um pouco mais, mas não vejo necessidade de comentário, e se tiver, então melhore o código. Colocar comentário nesse caso é consertar o defeito errado, se é que tem defeito. É gambiarra, é seguir receita de bolo para zero benefício.

Algumas pessoas dirão que tem até redundância no próprio código, mas em C acho que é normal, ele não tem mecanismos melhores pra resolver certas ambiguidades. Parabéns pelo código, meus pêsames por achar que precisa de comentários. Espero que evolua nesse ponto, de resto está acima da média.

Conclusão

Não sou voz dissonante na comunidade de desenvolvedores:

Coloquei no GitHub para referência futura.

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .