“Comentários são um cheiro de código” [fechado]

100

Um colega meu acredita que qualquer uso de comentários no código (ou seja, não método de estilo javadoc ou comentários de classe) é um cheiro de código . O que você acha?

Fishtoaster
fonte
44
Vou aprovar qualquer resposta que diga "não".
Nicole
2
@ Renesis Esse é o cheiro da divindade.
Ixtmixilix 27/09/10
107
Seu colega de trabalho fez uma generalização abrangente, o que significa automaticamente que ele está errado. :)
Alex Feinman
5
@ Mongus, eu discordo. Os comentários no seu exemplo são ruins, não porque são comentários, mas porque estão MUITO próximos do código que é alterado. Eles devem dizer PORQUE e não QUE .
5
@ Alex, isso não é uma generalização abrangente, que está, portanto, errada (resultando em ele não estar errado de qualquer maneira)?

Respostas:

167

Somente se o comentário descrever o que o código está fazendo.

Se eu quisesse saber o que estava acontecendo em um método ou bloco, leria o código. Espero, de qualquer maneira, que qualquer desenvolvedor que trabalhe em um determinado projeto esteja pelo menos familiarizado com a linguagem de desenvolvimento para ler o que está escrito e entender o que está fazendo.

Em alguns casos de otimização extrema, você pode estar usando técnicas que dificultam a alguém seguir o que seu código está fazendo. Nesses casos, os comentários podem e devem ser usados ​​para não apenas explicar por que você tem essas otimizações, mas o que o código está fazendo. Uma boa regra geral seria deixar alguém (ou várias outras pessoas) familiarizado com a linguagem e o projeto de implementação ver o seu código - se eles não conseguirem entender o porquê e o como, então você deve comentar o porquê e o como.

No entanto, o que não está claro no código é o motivo pelo qual você fez algo. Se você adotar uma abordagem que pode não ser óbvia para os outros, faça um comentário que explique por que você tomou as decisões que tomou. Eu suspeitaria que você nem percebesse que um comentário é necessário até depois de algo como uma revisão de código, onde as pessoas querem saber por que você fez X em vez de Y - você pode capturar sua resposta no código para todos os que o olham. no futuro.

O mais importante, no entanto, é alterar seus comentários quando você altera seu código. Se você alterar um algoritmo, certifique-se de atualizar os comentários com o motivo pelo qual você seguiu o algoritmo X sobre Y. Comentários obsoletos são um cheiro de código ainda maior.

Thomas Owens
fonte
8
Concordo com esta resposta em relação aos comentários, mas também a vi citada como desculpa pela falta de documentação, o que está errado. Ler código é um pé no saco às vezes. Você não precisa procurar no código um método para descobrir o que esse método faz. Você deve descobrir o nome e obter mais detalhes nos documentos. Ao ler o código, geralmente é necessário alternar de classe para classe e arquivo para arquivo. Isso é especialmente um problema em linguagens dinâmicas, onde escrever um IDE que possa lidar com tudo isso não é trivial.
Davidtbernal 14/09/10
1
De qualquer forma, às vezes você também deve comentar o HOW se for complicado (especialmente se for otimizado ou qualquer outro tipo de operação não trivial). Se eu tiver que gastar mais do que 5 minutos lendo um bloco de código para entender o que está fazendo, pode ser muito frustrante ...
Khelben
3
"Somente se o comentário descrever o que o código está fazendo." Ou se o comentário descreve o que o código costumava fazer; o código mudou, mas o comentário não.
Bruce Alderman
1
Como você testa se seu comentário está correto? Por que não escrever seu comentário como teste? Qualquer futuro mantenedor pode usar o teste como a documentação verificável do código. Se o comentário tiver algo a ver com a execução do código, esse algo / deve / deve ser afirmado. Se o comentário não tem nada a ver com a execução do código, o que está fazendo no código em que apenas os programadores procurarão?
Flamingpenguin
2
@ back2dos, se você costuma vomitar durante a leitura de código de outras pessoas, eu estou feliz que não estão compartilhando escritórios ...
110

Isso é particularmente irritante de ouvir no momento. Passei algum tempo neste fim de semana analisando códigos muito bem nomeados, limpos e não comentados, implementando um algoritmo de pesquisa (um que não é realmente publicado). Eu estou familiarizado com isso, o cara sentado ao meu lado foi o inventor e o código foi escrito há alguns anos por outra pessoa. Mal podíamos segui-lo.

Seu colega de trabalho não tem experiência suficiente, obviamente.

Paul Nathan
fonte
16
Estou curioso para ver "código bem nomeado, muito limpo e não comentado" que é difícil de seguir. Qualquer código que eu classificasse como tal tem sido muito fácil de seguir. Eu certamente não iria tão longe quanto "Seu colega de trabalho não tem experiência suficiente, obviamente".
Liggy
8
@Liggy: eu faria. É um algoritmo de pesquisa, não um aplicativo de linha de negócios.
Paul Nathan
9
Certa vez, tive um pedaço de código em que era necessário preencher os campos em um objeto de coluna do banco de dados (terceiros) na ordem "errada" (definida pela "lógica" do processo e pelos nossos padrões de codificação) - faça-a na ordem em que usaria normalmente e iria falhar. Nenhuma quantidade de leitura do código poderia lhe dizer isso, de modo que absolutamente, absolutamente, tinha que ter um comentário - e não era um cheiro, pelo menos não no código sobre o qual tínhamos controle (que é o resultado final). Uma completa e absoluta falta de comentários é tanto um cheiro quanto comentários ruins.
Murph
29
Matemática, matemática, matemática. Nem todo código implementa cola trivial de IoC e 'preço * quantidade'. Matemática complexa não pode ser feita magicamente para se auto-explicar.
bmargulies
4
@Liggy, o código que implementa estruturas de dados complexas pode ser completamente incompreensível sem documentação extensa.
75

Os comentários devem explicar o porquê, não como.

Howos comentários do tipo geralmente são mais bem tratados com a refatoração. Pessoalmente, geralmente evito comentários a favor da refatoração.

Antes:

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

depois de:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)
Sam Saffron
fonte
26
Eu concordo com o porquê não como parte, e sua refatoração funciona neste exemplo, mas com código mais complexo, nenhuma quantidade de variável / função que renomeia / refatoração fará todo o sentido, e ainda serão necessários comentários.
GSto 9/09/10
3
Bom exemplo, mas por que o sistema está trabalhando com centavos em vez de dólares? Essa questão se torna relevante nos sistemas financeiros em que você pode ver a moeda fracionária entrar em jogo.
rjzii
3
@Stuart O nome da função deve dizer o que faz.
Alb
3
@ GSto, eu não poderia discordar mais. Se o código for complexo, ele deverá ser dividido em métodos / funções menores, com nomes apropriados que descrevam a ação.
CaffGeek
1
Você assume que tem controle completo sobre a base de código.
LennyProgrammers
32

Eu declaro seu colega de trabalho um herege! Onde estão minhas botas queimando hereges?

Obsessivo comentando é ruim e uma dor de cabeça de manutenção, e os comentários são nenhum substituto para métodos bem-nomeados, classes, variáveis, etc. Mas às vezes colocando por isso que algo está do jeito que está pode ser extremamente valiosa para os pobres idiota que tem de manter o código em seis meses - principalmente quando aquele pobre idiota acaba sendo você.

Alguns comentários reais do código em que estou trabalhando:


    // If this happens, somebody's been screwing around with the database definitions and
    // has removed the restriction that a given alarm may have only one entry in the 
    // notifications table.  Bad maintenance programmer!  Bad!  No biscuit!



    // If an alert is active on our side but inactive on theirs, that might mean
    // they closed the alert.  (Or that we just haven't told them about it yet.)  The
    // logic comes later; for now, we'll just compile it in a list.



    // If we know for a fact that an alarm isn't getting through, we're going to whine pretty
    // aggressively about it until it gets fixed.

BlairHippo
fonte
7
+1 para comentários legais. Nenhuma quantidade de código pode dizer "Se isso acontecer, alguém estará mexendo nas definições do banco de dados".
DistantEcho
9
@ Niphra, bem, nós poderíamos jogar um SomebodyScrewedAroundWithDatabaseException... #
@ Thorbjørn +1, se o código souber o que está errado, denuncie. Os clientes que suportam técnicos provavelmente podem recarregar seu banco de dados e evitar uma chamada de serviço.
precisa
@ Tim, como os clientes podem ver isso, uma nomeação mais neutra pode ser apropriada.
3
Claro, lembre-se: nunca use nomes bobos. O cliente sempre os verá.
Tim Williscroft
29

Idealmente, o código deve ser tão bem codificado que deve ser autoexplicativo. No mundo real, sabemos que às vezes também é necessário comentar um código de alta qualidade.

O que você absolutamente deve evitar é a "redundância de código de comentário" (comentários que não adicionam nada ao código):

i++; // Increment i by 1

Então, se houver um bom design de código (e mantido / alinhado) e documentação, comentar será ainda menos útil.

Mas, em algumas circunstâncias, os comentários podem ser uma boa ajuda na legibilidade do código:

while( foo )
{
     if( dummy )
     {
     }
     else // !dummy
     {
     }
} // end while( foo )

Não se esqueça que você deve manter e manter sincronizados os comentários ... comentários desatualizados ou errados podem ser uma dor terrível! E, como regra geral, comentar demais pode ser um sintoma de uma programação ruim.

Lorenzo
fonte
2
Uma boa convenção de nomenclatura e um código bem estruturado o ajudarão a diminuir a necessidade de comentários. Não esqueça que cada linha de comentários que você adicionar é uma nova linha para manter !!
Gabriel Mongeon 01/09/10
81
Eu odeio quando as pessoas usam esse segundo exemplo na sua pergunta. } //end whilesignifica apenas que o início do loop while está tão distante que você nem consegue vê-lo, e não há dicas de que o código que você está visualizando esteja em um loop. Refatoração pesada deve ser seriamente preferida a comentários sobre como o código está estruturado.
Carson Myers
4
@ Carson: embora manter os blocos curtos seja uma regra bem conhecida, isso não significa que sempre podemos aplicá-la.
usar o seguinte comando
4
@Carson: Um dos projetos em que trabalho tem uma revisão de código insuficiente, o que leva a uma coleção de JSPs com uma complexidade ciclomática de "OMFG APENAS SE MATE". Refatorar as coisas sangrentas representa dias de trabalho que precisam ser gastos em outros lugares. Esses } // end whilecomentários podem ser um salva-vidas.
BlairHippo
11
@BlairHippo: "O cheiro do código [A] é qualquer sintoma no código fonte de um programa que possivelmente indica um problema mais profundo". É claro que o comentário é um salva-vidas, mas o OMGWTF-circuito é o já mencionado "problema mais profundo" e a necessidade da proteção de vida é um indicador claro;)
back2dos
26

Definir categoricamente um método ou processo como um "cheiro de código" é um "cheiro de fanatismo". O termo está se tornando o novo "considerado prejudicial".

Lembre-se de que todos esses tipos de coisas devem ser diretrizes.

Muitas das outras respostas dão bons conselhos sobre quando os comentários são justificados.

Pessoalmente, uso muito poucos comentários. Explique o propósito de processos não óbvios e deixe a ameaça de morte ocasional para qualquer um que possa estar pensando em alterar as coisas por conta própria que exigiram semanas de ajuste.

Refatorar tudo até que um aluno do jardim de infância possa entender que provavelmente não é um uso eficiente do seu tempo e provavelmente não terá um desempenho tão bom quanto uma versão mais concisa.

Os comentários não afetam o tempo de execução, portanto, o único problema negativo a ser considerado é a manutenção.

Conta
fonte
8
Eu pensei que "anti-padrão" era o novo "considerado prejudicial". Um cheiro de código é apenas algo que precisa de uma revisão mais detalhada para possível limpeza.
Jeffrey Hantin
1
Não discordo que o antipadrão também se qualifique. Os dois se acostumam dessa maneira, com o antipadrão sendo usado em vez do olfato quando o design é complexo o suficiente para que seja obviamente uma escolha deliberada. Em qualquer um dos casos, discordo do conceito de que existe uma fonte absoluta de correção nessas coisas.
Bill
4
+1 em "Refatorar tudo até que um aluno do jardim de infância entenda que provavelmente não é um uso eficiente do seu tempo e provavelmente não terá um desempenho tão bom quanto uma versão mais concisa".
Earlz
23

Em alguns casos, nenhuma boa nomeação, refatoração etc. pode substituir um comentário. Veja este exemplo do mundo real (o idioma é Groovy):

  response.contentType="text/html"
  render '{"success":true}'

Parece estranho, não é? Provavelmente um erro de copiar e colar? Chora por uma correção de bug?

Agora o mesmo com os comentários:

  // DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
  response.contentType="text/html"  // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
  render '{"success":true}'         // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler
user281377
fonte
função prime_extjs_uploadform () {response.contentType = 'text / html'; tornar '{"sucesso": verdadeiro}'; } prime_extjs_uploadform ();
DrPizza 4/12
23

A questão principal aqui é o significado do termo "cheiro de código".

Muitas pessoas (incluindo você, eu acho) entendem que o cheiro do código é algo próximo a um erro ou pelo menos algo que precisa ser corrigido. Talvez você pense nisso como um sinônimo de "antipadrão".

Este não é o significado do termo!

A metáfora do cheiro do código é originária do Wards Wiki e enfatizam:

Observe que um CodeSmell é uma dica de que algo pode estar errado, não uma certeza. Um idioma perfeitamente bom pode ser considerado um CodeSmell porque geralmente é mal utilizado ou porque existe uma alternativa mais simples que funciona na maioria dos casos. Chamar algo de CodeSmell não é um ataque; é simplesmente um sinal de que é necessário um olhar mais atento.

Então, o que significa que os comentários são cheiros de código: significa que, quando você vê um comentário, deve fazer uma pausa e pensar: "Hmmm, sinto uma dica de que algo pode ser melhorado". Talvez você possa renomear uma variável, executar o "método de extração" - refatoração - ou talvez o comentário seja realmente a melhor solução.

É isso que significa que os comentários têm cheiro de código.

EDIT: Acabei de me deparar com estes dois artigos, o que explica melhor do que eu:

Rasmus Faber
fonte
2
Estou chocado que demorou 2 meses para que essa resposta surgisse. Demonstra quão difundido é o mal-entendido do termo.
Paul Butcher
A afirmação geral do caso ainda está errada. Você não diz: "Estou vendo código comentado. Isso é um mau sinal".
Stuart P. Bentley
1
@Stuart: Você está olhando para dois pedaços de código, ambos com níveis adequados de comentários. (Esta questão não é sobre o número apropriado de comentários, é sobre como você julga o código com base no número de comentários.) Um não tem comentários, o outro tem toneladas. Para quem você olha mais de perto? - Comentários são um sinal de que o código é complicado e sutil e, portanto, mais propenso a ter problemas.
David Schwartz
Essa é a resposta correta.
27512 vidstige
21

Eu acho que a regra é bem simples: imagine um completo estranho vendo seu código. Você provavelmente será um estranho ao seu próprio código em 5 anos. Tente minimizar o esforço mental para entender seu código para esse estranho.

LennyProgrammers
fonte
8
+1 Para qualquer dev que não foi trabalhando em um único projeto de longo o suficiente para experimentar isso, acreditem que vai acontecer. Sempre que aprendo isso da maneira mais difícil e preciso reaprender meu próprio código, não me permito cometer o mesmo erro duas vezes e comento-o antes de passar para outra coisa.
Nicole
Não, você deve imaginar um psicopata que sabe onde você mora: eles ficarão felizes em manter seu código?
Richard
4
Eu regularmente me torno um psicopata quando vejo código ilegível.
LennyProgrammers
3
5 anos? Mais como 5 minutos. ;)
Alex Feinman
11

Uma boa idéia para ter os comentários certos é começar escrevendo comentários.

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myFunction(parameters)
{
    // It will do some things to get started.

    // It will do more with the stuff.

    // It will end doing things with the stuff.
}

Isso permite que você extraia métodos facilmente para se livrar dos comentários,
deixe o código dizer essas coisas ! Veja como isso é reescrito (recortar / colar) de uma maneira muito agradável:

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myfunction(parameters)
{
  var someThing = initializedWithSomething;

  doSomethingWith(someThing);

  doMoreWith(someThing);

  endDoingThingsWith(someThing);

  return someThing;
}

// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
  parameters.manipulateInSomeWay();
  ... etc ...
}

... etc ...

Para coisas que não podem ser separadas, não extraia métodos e digite o código nos comentários.

É isso que eu vejo como uma maneira útil de manter o mínimo de comentários, é realmente inútil comentar cada linha ... Apenas documente uma única linha se for sobre uma inicialização de valor mágico ou onde faz sentido.

Se os parâmetros forem usados ​​demais, eles deverão ser membros privados da sua classe.

Tom Wijsman
fonte
1
Isto é o que eu faço. Se você acha que precisa de comentários, recomendo vivamente tentar isso como um substituto.
fácil
10

Eu acho que a resposta é a usual "Depende". Comentar código apenas para comentar é um cheiro. Comentar o código porque você está usando um algoritmo obscuro que é uma ordem de magnitude mais rápido economiza o programador de manutenção (geralmente eu 6 meses depois que o escrevi) meio dia examinando o código para determinar o que está fazendo.

Brandon
fonte
10
// Dear me in the future. Please, resolve this problem.

ou

// You think this code was written by somebody else. 
// No, it wasn't. You ([some name]) did it.
Zzz
fonte
Ah, pedidos sinceros ao futuro eu.
Anthony Pegram
8

Comentários de código definitivamente não são um "cheiro de código". Essa crença geralmente vem do fato de que os comentários podem ficar obsoletos (desatualizados) e podem ser difíceis de manter. No entanto, ter bons comentários que expliquem por que o código está fazendo algo de uma certa maneira pode (e geralmente é) importante para manutenção.

Bons comentários facilitam a compreensão do que o código está fazendo e, mais importante, por que ele está fazendo de uma maneira específica. Os comentários devem ser lidos pelos programadores e devem ser claros e precisos. Um comentário difícil de entender ou incorreto não é muito melhor do que não ter comentado nada.

Adicionar comentários claros e precisos ao seu código significa que você não precisa confiar na memória para entender o "o quê" e o "porquê" de uma seção do código. Isso é mais importante quando você olha para esse código mais tarde, ou alguém deve olhar para o seu código. Como os comentários se tornam parte do conteúdo textual do seu código, eles devem seguir os bons princípios de escrita, além de serem claramente escritos.

Para escrever um bom comentário, você deve fazer o possível para documentar a finalidade do código (o porquê, não como) e indicar o raciocínio e a lógica por trás do código da maneira mais clara possível. Idealmente, os comentários devem ser escritos ao mesmo tempo em que você escreve o código. Se você esperar, provavelmente não voltará e os adicionará.

Sams ensina-se Visual C # 2010 em 24 horas , pp 348-349.

Scott Dorman
fonte
1
Os comentários podem ficar obsoletos, mas isso é verdade para tudo que não é verificado por um compilador ou um teste de unidade, como o significado dos nomes de classe, função e variável.
LennyProgrammers
@ Lenny222: Sim, os comentários podem ficar obsoletos ... o que geralmente é indicativo de programadores preguiçosos. Se o comentário descreve por que uma decisão foi tomada, por que o código usa um algoritmo específico para computação ou descreve como o código funciona, não há razão para o comentário ficar obsoleto, a não ser que alguém mude a implementação e não atualize o comentário de acordo. - o que equivale a ser preguiçoso.
Scott Dorman
2
Concordo. O que quero dizer é que há o risco de ficar obsoleto, sim. Mas quando eu tenho uma função doBar () e depois de 3 anos ela não "bar", mas "bar and foo, exceto às quartas-feiras", o significado das funções também pode ficar obsoleto. E nomes de variáveis. Mas espero que ninguém tome isso por uma razão para não atribuir nomes significativos às funções e variáveis.
LennyProgrammers
6

Se o código foi escrito de uma maneira específica para evitar um problema presente em uma biblioteca (uma biblioteca de terceiros ou uma biblioteca que acompanha o compilador), faz sentido comentá-lo.
Também faz sentido comentar o código que precisa ser alterado em versões futuras, ou ao usar uma nova versão de uma biblioteca, ou ao passar do PHP4 para o PHP5, por exemplo.

kiamlaluno
fonte
6

Mesmo o livro mais bem escrito ainda provavelmente tem uma introdução e títulos de capítulo. Os comentários no código bem documentado ainda são úteis para descrever conceitos de alto nível e explicar como o código está organizado.

maravilhoso
fonte
Comentários desse tipo fornecem boas dicas visuais para que você não precise ler todas as linhas para encontrar o início da seção que está procurando. Como meu avô costumava dizer, "tudo com moderação".
Blrfl
4

De menção honrosa é o anti-padrão:

Tenho a impressão de que, às vezes, os preâmbulos de licença do FLOSS são frequentemente usados no lugar da documentação do arquivo. A GPL / BSDL produz um bom texto de preenchimento e, depois disso, você raramente vê qualquer outro bloco de comentários.

mario
fonte
4

Não concordo com a ideia de que escrever comentários para explicar o código seja ruim. Isso ignora completamente o fato de que o código possui bugs. Pode ficar claro o que o código faz sem comentários. É menos provável que fique claro o que o código deve fazer. Sem comentários, como você sabe se os resultados estão errados ou estão sendo usados ​​incorretamente?

Os comentários devem explicar a intenção do código, para que, se houver um erro, alguém lendo o código dos comentários + tenha a chance de encontrá-lo.

Geralmente, me pego escrevendo comentários embutidos antes de escrever o código. Dessa forma, fica claro o que estou tentando escrever código e reduz a perda de um algoritmo sem realmente saber o que você está tentando fazer.

Danny Tuppeny
fonte
1
Os testes de unidade ajudam muito a determinar se os resultados estão errados. Se você lê algum código e acha que ele faz X quando, na realidade, faz Y, é possível que o código não seja escrito de maneira legível o suficiente. Não sei o que você quer dizer com os resultados serem usados ​​incorretamente. Um comentário não o protegerá contra alguém que consome seu código de maneiras estranhas.
Adam Lear
"Se você lê algum código e acha que ele faz X quando na realidade ele faz Y" Não foi isso que eu disse. Estou falando de entender o que o código faz , mas não o que ele deve fazer. Digamos que você suspeite de um erro pontual. Como você sabe que o erro de um por um não está no código de consumo ou nesse código? Os comentários explicam a intenção do código, o que ajuda enormemente no rastreamento de bugs.
Danny Tuppeny
Por outro lado, os comentários podem apenas dizer o que o código deveria fazer a partir do momento em que os comentários foram escritos. O código em si pode estar dizendo o que ele deve fazer agora. Comentários não compilam. Você não pode testar comentários. Eles podem ou não estar corretos.
Anthony Pegram
3

Comentários inseridos porque alguém acha que é bom ter 700 linhas em um método são um cheiro.

Os comentários que existem porque você sabe que, se não fizer um comentário, alguém cometerá o mesmo erro mais uma vez.

Comentários inseridos porque alguma ferramenta de análise de código exige que também seja um cheiro.

Pessoas que nunca colocam um comentário ou escrevem uma pequena ajuda para outros desenvolvedores também são um cheiro. Estou impressionado com quantas pessoas não escrevem coisas, mas depois se viram e reconhecem que não conseguem se lembrar do que fizeram há três meses. Não gosto de escrever documentos, mas gosto de contar às pessoas a mesma coisa repetidamente e menos ainda.

MIA
fonte
3

Vou responder com uma pergunta minha. Você pode encontrar o bug no código não comentado abaixo?

tl; dr: A próxima pessoa a manter seu código pode não ser tão divina quanto você.

 [org 0x7c00]

 main:
  mov ah, 0x0e
  mov bx, string
  call strreverse
  call print

 stop:
  jmp $

 strreverse:
  pusha
  mov dx, bx
  mov cx, 0

 strreverse_push:
  mov al, [bx]
  cmp al, 0
  je strreverse_pop
  push ax
  add bx, 1
  add cx, 1
  jmp strreverse_push

 strreverse_pop:
  mov bx, dx

 strreverse_pop_loop:
  cmp cx, 0
  je strreverse_end
  pop ax
  mov [bx], al
  sub cx, 1
  add bx, 1
  jmp strreverse_pop_loop

 strreverse_end:
  popa
  ret

 print:
  pusha

 print_loop:
  mov al, [bx]
  cmp al, 1
  je print_end
  int 0x10
  add bx, 1
  jmp print_loop

 print_end:
  popa
  ret
 string:
  db 'Boot up', 0

 times 510 -( $ - $$ ) db 0
 dw 0xaa55
Formiga
fonte
Mas hoje em dia você não está usando um idioma de alto nível?
lan
2
@Ian: O programa é um gerenciador de inicialização IBM-PC. Você não pode gravá-lo em outra coisa que não seja montagem, porque você precisa de controle total de exatamente onde o programa está localizado na RAM, onde o último short aparece e parte do hardware é interrompida. Sério, pegue uma cópia do NASM. Monte-o, grave-o no setor de inicialização de um disquete ou pendrive e inicie-o. Embora você provavelmente descubra que não funciona como o esperado por causa do bug. Agora encontre o bug ... Independentemente disso, tenho certeza de que daqui a 20 anos as pessoas farão a mesma coisa com Java não comentado.
Ant
Certamente o código pode ser escrito em C ou C ++, e o binário montado a partir do código do objeto C e de alguma ferramenta externa.
precisa
Infelizmente não. Dê uma olhada nesta página no CodeProject: codeproject.com/KB/tips/boot-loader.aspx - "idiomas de alto nível não possuem as instruções necessárias". Não apenas isso, mas você só tem 512 bytes para jogar em um gerenciador de inicialização. Às vezes, você só precisa acessar diretamente o hardware.
Ant
1
Ao codificar a montagem, eu faria o que todo mundo faz - comente cada linha com o que está fazendo. A linha em questão teria o comentário "verificar se a letra é 0", pois o código usa seqüências terminadas em 0 no estilo C. Com esse comentário, é fácil ver que o código está fazendo um cmp com 1, o que significa que ele fica preso em um loop infinito ou imprime lixo até atingir um 1 aleatório na RAM. Eu também poderia ter adicionado um comentário sobre o fato de que as strings foram terminadas em 0, o que não é aparente no código. Existe o teste de unidade automatizado para codificação de montagem?
Ant
2

Você precisa manter um equilíbrio entre o código e os comentários ... Normalmente, tento adicionar alguns comentários que retomam um bloco de código. Não porque eu não seja capaz de entender o código (bem, isso também), mas porque posso ler mais rapidamente meu próprio código e localizar seções específicas nas quais as coisas importantes estão acontecendo.

Enfim, meus próprios critérios pessoais são "em caso de dúvida, comente". Prefiro ter uma linha redundante do que uma linha completamente enigmática que não vou conseguir entender. Sempre posso remover comentários em uma revisão de código depois de um tempo (e geralmente faço)

Além disso, comentários são bastante úteis para adicionar "advertências" como "Cuidado! Se o formato da entrada não for ASCII, esse código precisará ser alterado!"

Khelben
fonte
Você poderia explicar o que você quer dizer com "comentários que resumem um bloco de código"?
Mark C
2

Lendo isso, lembro-me de algo que li pela primeira vez (de uma lista mais longa, preservada ao tirar fotocópias) algumas décadas atrás:

Programadores de verdade não escrevem comentários - se foi difícil escrever, deve ser difícil ler

Um cheiro um pouco mais velho parece.

Murph
fonte
2

Eu acho que o código comentado começa muito mal na vida. Hoje não sei, mas quando aprendi a programar na escola, recebi atribuições da natureza de "Escreva um programa que imprima os números de um a dez em linhas separadas. Certifique-se de comentar seu código". Você seria marcado se não adicionasse comentários porque comentar seu código é uma BOA COISA.

Mas o que há a dizer sobre um processo tão trivial? Então você acaba escrevendo o clássico

i++; // add one to the "i" counter.

apenas para obter uma nota decente e, se você tiver alguma dúvida, formar instantaneamente uma opinião muito baixa dos comentários do código.

Comentar código não é uma BOA COISA. É uma coisa às vezes necessária, e Thomas Owens na resposta superior fornece uma excelente explicação das situações em que é necessário. No entanto, essas situações raramente surgem em tarefas do tipo lição de casa.

De muitas maneiras, adicionar um comentário deve ser considerado uma opção de último recurso, quando o que precisa ser dito não pode ser dito claramente nas partes ativas da linguagem de programação. Embora a nomeação de objetos possa ficar obsoleta, vários mecanismos de falta de feedback humano e computador facilitam o esquecimento de manter comentários e, consequentemente, os comentários ficam obsoletos muito mais rapidamente do que o código ativo. Por esse motivo, sempre que uma opção é possível, a alteração do código para torná-lo mais claro deve sempre ser preferida à anotação de código pouco claro com comentários.

Alohci
fonte
+1 por apontar que os maus hábitos de comentários começam com as primeiras aulas de programação. -1 por concluir que os comentários são apenas uma opção de último recurso.
ASHelly #
1

É claro que os comentários são um cheiro de código ...

todo programador sabe que todos acabamos ficando loucos devido à quantidade de trabalho, depuração ou loucura que encontramos.

"Fazem isto!" seu gerente de projeto diz.

Você responde: "Isso não pode ser feito".

Eles dizem: "Então encontraremos alguém para fazer isso".

Você diz: "OK, talvez isso possa ser feito".

E depois passe o próximo número X de dias .. semanas .. meses .. tentando descobrir isso. Durante todo o processo, você tentará e falhará, e tentará e falhará. Todos nós fazemos isso. A resposta verdadeira é que existem dois tipos de programadores, aqueles que comentam e outros que não.

1) Aqueles que o fazem estão facilitando seu próprio trabalho documentando para referência futura, comentando rotinas com falha que não funcionaram (o cheiro não é excluí-las depois de encontrar a que funciona) ou quebrando o código com comentários formatação para espero torná-lo um pouco mais fácil de ler ou compreender. Sério, não posso culpá-los. Mas no final, eles se encaixam e você tem o seguinte: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

2) Aqueles que não estão fingindo ser um super-herói ou estão vivendo em uma caverna . Eles simplesmente têm um desprezo imprudente pelos outros, eles mesmos, e podem se importar menos com o código, ou com o significado que isso possa ter para mais tarde.

Agora, não me interpretem mal. As variáveis ​​e funções auto-documentadas podem evitar isso completamente. E confie em mim: você nunca pode limpar o código o suficiente. Mas a verdade simples é que, enquanto você mantiver backups, você SEMPRE poderá excluir comentários.

Talvi Watia
fonte
1
Em resposta a 1. O verdadeiro cheiro nas rotinas comentadas não é excluí-las imediatamente quando você decide que podem ser becos sem saída e deseja tentar algo diferente --- isso ocorre porque eles devem estar disponíveis no controle de versão se você decidir revisá-las .
Sharpie
1

Eu diria que não usar alguns comentários no seu código é um cheiro de código. Embora eu concorde que o código deva se auto-documentar o máximo possível, você chega a um certo ponto em que verá um código que não faz sentido, independentemente de quão bem o código esteja escrito. Eu já vi algum código em aplicativos de negócios em que os comentários são praticamente obrigatórios porque:

  1. Você precisa fazer algo caso a caso e não há uma boa lógica para isso.
  2. O código provavelmente será alterado em um ano ou dois quando as leis forem alteradas e você desejar encontrá-lo novamente rapidamente.
  3. Alguém editou o código no passado porque não entendia o que o código estava fazendo.

Além disso, os guias de estilo da empresa podem solicitar que você faça algo de uma certa maneira - se eles disserem que você poderia ter comentários descrevendo o que os blocos de código em uma função estão fazendo, inclua os comentários.

rjzii
fonte
1

Há uma grande diferença fundamental entre comentários e código: os comentários são uma maneira de as pessoas comunicarem idéias a outras pessoas, enquanto o código é destinado principalmente ao computador. Existem muitos aspectos no "código" que também são apenas para humanos, como nomeação e recuo. Mas os comentários são escritos estritamente para humanos, por humanos.

Portanto, escrever comentários é tão difícil quanto qualquer comunicação humana escrita! O escritor deve ter uma concepção clara de quem é o público e de que tipo de texto será necessário. Como você pode saber quem lerá seus comentários em dez, vinte anos? E se a pessoa for de uma cultura completamente diferente? Etc. Espero que todos entendam isso.

Mesmo dentro da pequena cultura homogênea em que vivo, é tão difícil comunicar idéias a outras pessoas. A comunicação humana geralmente falha, exceto por acidente.

user15127
fonte
0

Eu tenho que concordar com seu colega de trabalho. Eu sempre digo que se eu comentar meu código, isso significa que eu estou preocupado que eu não será capaz de descobrir o meu próprio código no futuro. Este é um mau sinal.

A única outra razão pela qual eu coloco comentários no código é chamar algo que parece não fazer sentido.

Esses comentários geralmente assumem a forma de algo como:

//xxx what the heck is this doing??

ou

// removed in version 2.0, but back for 2.1, now I'm taking out again
Ken
fonte
1
Ou, alternativamente, o comentário pode refletir o fato de que o código está abordando um algoritmo complexo em que o código se torna inerentemente não óbvio ou porque o código está fazendo algo estranho devido a fatores fora do seu controle (por exemplo, interagindo com um serviço externo).
Murph
Muito verdadeiro. Há razões pelas quais um bom código pode não ser óbvio. Na maioria das vezes, o código desconcertante é desconcertante porque é escrito de uma maneira ofuscada.
Ken
Parece que você não escreveu código para processadores incorporados, onde você tem apenas 32k para jogar, e as coisas parecem obscuras. Comentários são salva-vidas.
precisa saber é o seguinte
0

Comentários de código que fornecem, onde aplicável, unidades de argumentos e retornos de função, campos de estrutura e até variáveis ​​locais podem ser muito úteis. Lembre-se do Mars Orbiter!

dmuir
fonte
Muito melhor incorporar as unidades nos nomes das variáveis, para que o programador deficiente não precise se lembrar delas. Em vez de 'comprimento duplo // em metros', diga 'double length_m'. O melhor de tudo é usar uma linguagem mais poderosa, para que você possa simplesmente dizer Comprimento l; Força f; Torque t = l * f; print (t.in (Torque.newtonMeter));
Kevin cline
0

Aqui está minha regra de ouro:

  • Escreva o código e armazene um breve resumo do código em um documento separado.
  • Deixe o código em paz por vários dias para trabalhar em outra coisa.
  • Retorne ao código. Se você não conseguir entender imediatamente o que deve fazer, adicione o resumo ao arquivo de origem.
Maxpm
fonte
0

Não, os comentários não são um cheiro de código, são apenas uma ferramenta que pode ser abusada.

Exemplos de bons comentários:

// Acho que isso está em cm. É necessária mais investigação!

// Essa é uma maneira inteligente de fazer X

// É garantido que a lista não esteja vazia aqui

Andres F.
fonte
O terceiro é um comentário ruim da IMO. Por que não Assert(list.IsEmpty)?
CodesInChaos
@CodeInChaos IMO Assert(!list.isEmpty())não é exatamente um contrato, como no terceiro comentário, mas simplesmente um comportamento (por exemplo, "lançar IllegalArgumentException se o argumento estiver vazio") que deve ser testado por unidade como qualquer outra lógica do programa. Observe a diferença sutil no comentário, que indica quando o método pode ser usado, mas não especifica nenhum comportamento se a pré-condição não for atendida. Ainda melhor do que o comentário seria impor contratos em tempo de compilação. Mas isso excede o escopo da minha resposta;)
Andrés F.
Você não deve poder exercer Asserts, pois eles descrevem coisas que nunca deveriam acontecer, mesmo que a API pública receba argumentos inválidos.
CodesInChaos
@CodeInChaos Retiro minha opinião. Aqui está o que a Sunacle tem a dizer sobre afirmações . Parece que você estava certo. Bem, você aprende algo todos os dias!
Andres F.