Programador, voc� tem o costume de comentar seu c�digo de forma meticulosa e detalhada?�
Como a maioria das pessoas, voc� respondeu (ou ao menos gostaria de responder) SIM!
Mas ser� que seus coment�rios de c�digo realmente adicionam valor, ou est�o deixando seu c�digo pior?
Ficou curioso de como seus coment�rios podem piorar seus c�digos? Ent�o acompanhe o post que preparamos hoje!
Sobre a nossa profiss�o, Phil Kalton disse:�
S� existem duas coisas dif�ceis em Ci�ncia da Computa��o: invalida��o de cache e escolher nomes das coisas.�
Como supostamente temos c�rebros anal�ticos e gostamos de problemas complexos, focamos sempre na primeira dificuldade. Mas clareza na comunica��o nunca � demais quando trabalhamos em bases de c�digo grandes com outros desenvolvedores.
Dar nomes claros e objetivos para fun��es, par�metros e vari�veis � dif�cil.
Tal falta de clareza, em alguns casos, � contornada com a utiliza��o de documenta��o � na forma de coment�rios inline. Por�m nem sempre mais documenta��o � melhor. �s vezes essa documenta��o � redundante, sintoma de problemas de clareza no seu c�digo, ou at� uma desculpa para n�o melhorar o c�digo.
Hoje em dia v�rias comunidades de desenvolvedores consideram que o antigo objetivo de comentar o m�ximo poss�vel � uma pr�tica obsoleta e at� danosa. Por exemplo, um dos mais populares guias de estilo de Ruby postula que:
O bom c�digo � sua pr�pria melhor documenta��o. Quando voc�s estiver prestes a adicionar um comentrio, se pergunte, \"Como eu posso melhorar o c�digo para que o este coment�rio n�o seja necess�rio?\" Melhore o c�digo e ent�o o documente para torna-lo ainda mais claro.Steve McConnell
Veja a fun��o abaixo, que era utilizada internamente em nosso produto.
/*\n Function to hide element\n stop -> Minimum height for hiding\n el -> Target element to be hidden\n Info: The class 'hidden' is used to hide the element\n*/\nfunction hideElement(stop, el) {\n if (window.pageYOffset > stop) {\n el.className.add(\"hidden\");\n } else {\n el.classList.remove(\"hidden\");\n }\n}Esses coment�rios aparentemente inofensivos s�o sintomas de problemas maiores com o nome das fun��es e seus par�metros.�
Vamos ver quais s�o estes problemas?
// Function to hide element
Perceba que a linha acima n�o faz nada mais do que repetir o a primeira linha de c�digo da fun��o, de forma quase literal:
function hideElement(stop, el) {J� essa linha de c�digo n�o cont�m nenhuma ambiguidade quanto a seu objetivo. Sendo assim, � poss�vel remover o trecho de coment�rio sem nenhum preju�zo para a documenta��o.Existe um segundo problema com o nome desta fun��o, mas falaremos dele mais tarde.
stop -> Minimum height for hiding\nel -> Target element to be hidden
Nesse caso, o nome dos par�metros � bastante vago. O que � el? E esse stop? � um verbo no imperativo, ou um substantivo?�
Esse tipo de ambiguidade atrapalha a utiliza��o da fun��o, e �s vezes exige que o programador leia seu c�digo inteiro antes de utiliz�-la.
Lendo os coment�rios podemos observar que � bem f�cil resolver isso, j� que eles pr�prios indicam nomes melhores.�
O par�metros stop poderia ser minHeight.�
J� o par�metros el poderia se chamar targetElement.
Essas duas pequenas mudan�as n�o ajudariam apenas a remover os coment�rios redundantes, como melhoraram a leitura da parte interna da fun��o.
Info: The class 'hidden' is used to hide the element
Essa pequena informa��o � um sintoma de outros dois problemas. Primeiramente, por repetir uma informa��o que j� existe dentro da fun��o � o que quebra o princ�pio DRY.
A string hidden aparece duas vezes dentro do nosso c�digo. O segundo problema � que essa string � similar a um n�mero m�gico, e aparece no nosso c�digo e no coment�rio sem um contexto e sem um nome auto-explicativo.
Como j� estamos utilizando ES6, a solu��o mais pr�tica foi refatorar esta fun��o e utilizar par�metros opcionais.�
Isso permitiu tanto que a fun��o se tornasse auto-document�vel, quanto trouxe esta flexibiliza��o. Veja como ficou:
function hideElement(minHeight, targetElement, hidingClass = \"hidden\") {\n if (window.pageYOffset > minHeight) {\n el.className = hidingClass;\n } else {\n el.classList.remove(hidingClass);\n }\n}Acredite, existe um problema ainda mais grave aqui! O nome da fun��o n�o � fiel a seu comportamento.
Ao ler o c�digo, � poss�vel ver que ela n�o est� simplesmente \"ocultando o elemento\" � como o nome indica. Ela apenas aplica a classe \"hidden\" quando o offset y da p�gina � maior que o valor stop, e o soltando quando o valor � igual ou menor.
A �nica maneira de obter-se esta informa��o � lendo o corpo da fun��o e se deparando com a linha com a condi��o window.pageYOffset > minHeight.
A solu��o para o problema � dar um nome mais descritivo, que realmente captura a funcionalidade.
No fim das contas, nosso c�digo ficou assim:
function hideElementAfterHeight(minHeight, targetElement, hidingClass = \"hidden\") {\n if (window.pageYOffset > minHeight) {\n el.className.add(hidingClass);\n } else {\n el.classList.remove(hidingClass);\n }\n}O objetivo deste artigo foi demonstrar o lado nocivo dos coment�rios de c�digo. Come�amos o artigo com uma fun��o simples, por�m com nomes que dificultavam sua usabilidade, e a transformamos em um trecho de c�digo que dispensa a documenta��o adicional. Qual � a �moral da hist�ria�?
O bom c�digo n�o deve focar apenas na performance de execu��o, mas tamb�m em sua simplicidade, legibilidade e facilidade de manuten��o por outros programadores.
E o objetivo dos coment�rios de c�digo n�o deve ser simplesmente repetir o que j� estamos dizendo no c�digo, ou mascarar problemas de legibilidade do mesmo.
E a�, este conte�do te ajudou? Acha que pode ajudar mais algu�m? Ent�o compartilhe nas suas redes sociais!
"}]],"sections":[[10,0]]} html:Programador, voc� tem o costume de comentar seu c�digo de forma meticulosa e detalhada?�
Como a maioria das pessoas, voc� respondeu (ou ao menos gostaria de responder) SIM!
Mas ser� que seus coment�rios de c�digo realmente adicionam valor, ou est�o deixando seu c�digo pior?
Ficou curioso de como seus coment�rios podem piorar seus c�digos? Ent�o acompanhe o post que preparamos hoje!
Sobre a nossa profiss�o, Phil Kalton disse:�
S� existem duas coisas dif�ceis em Ci�ncia da Computa��o: invalida��o de cache e escolher nomes das coisas.�
Como supostamente temos c�rebros anal�ticos e gostamos de problemas complexos, focamos sempre na primeira dificuldade. Mas clareza na comunica��o nunca � demais quando trabalhamos em bases de c�digo grandes com outros desenvolvedores.
Dar nomes claros e objetivos para fun��es, par�metros e vari�veis � dif�cil.
Tal falta de clareza, em alguns casos, � contornada com a utiliza��o de documenta��o � na forma de coment�rios inline. Por�m nem sempre mais documenta��o � melhor. �s vezes essa documenta��o � redundante, sintoma de problemas de clareza no seu c�digo, ou at� uma desculpa para n�o melhorar o c�digo.
Hoje em dia v�rias comunidades de desenvolvedores consideram que o antigo objetivo de comentar o m�ximo poss�vel � uma pr�tica obsoleta e at� danosa. Por exemplo, um dos mais populares guias de estilo de Ruby postula que:
O bom c�digo � sua pr�pria melhor documenta��o. Quando voc�s estiver prestes a adicionar um comentrio, se pergunte, "Como eu posso melhorar o c�digo para que o este coment�rio n�o seja necess�rio?" Melhore o c�digo e ent�o o documente para torna-lo ainda mais claro.Steve McConnell
Veja a fun��o abaixo, que era utilizada internamente em nosso produto.
/*
Function to hide element
stop -> Minimum height for hiding
el -> Target element to be hidden
Info: The class 'hidden' is used to hide the element
*/
function hideElement(stop, el) {
if (window.pageYOffset > stop) {
el.className.add("hidden");
} else {
el.classList.remove("hidden");
}
}Esses coment�rios aparentemente inofensivos s�o sintomas de problemas maiores com o nome das fun��es e seus par�metros.�
Vamos ver quais s�o estes problemas?
// Function to hide element
Perceba que a linha acima n�o faz nada mais do que repetir o a primeira linha de c�digo da fun��o, de forma quase literal:
function hideElement(stop, el) {J� essa linha de c�digo n�o cont�m nenhuma ambiguidade quanto a seu objetivo. Sendo assim, � poss�vel remover o trecho de coment�rio sem nenhum preju�zo para a documenta��o.Existe um segundo problema com o nome desta fun��o, mas falaremos dele mais tarde.
stop -> Minimum height for hiding el -> Target element to be hidden
Nesse caso, o nome dos par�metros � bastante vago. O que � el? E esse stop? � um verbo no imperativo, ou um substantivo?�
Esse tipo de ambiguidade atrapalha a utiliza��o da fun��o, e �s vezes exige que o programador leia seu c�digo inteiro antes de utiliz�-la.
Lendo os coment�rios podemos observar que � bem f�cil resolver isso, j� que eles pr�prios indicam nomes melhores.�
O par�metros stop poderia ser minHeight.�
J� o par�metros el poderia se chamar targetElement.
Essas duas pequenas mudan�as n�o ajudariam apenas a remover os coment�rios redundantes, como melhoraram a leitura da parte interna da fun��o.
Info: The class 'hidden' is used to hide the element
Essa pequena informa��o � um sintoma de outros dois problemas. Primeiramente, por repetir uma informa��o que j� existe dentro da fun��o � o que quebra o princ�pio DRY.
A string hidden aparece duas vezes dentro do nosso c�digo. O segundo problema � que essa string � similar a um n�mero m�gico, e aparece no nosso c�digo e no coment�rio sem um contexto e sem um nome auto-explicativo.
Como j� estamos utilizando ES6, a solu��o mais pr�tica foi refatorar esta fun��o e utilizar par�metros opcionais.�
Isso permitiu tanto que a fun��o se tornasse auto-document�vel, quanto trouxe esta flexibiliza��o. Veja como ficou:
function hideElement(minHeight, targetElement, hidingClass = "hidden") {
if (window.pageYOffset > minHeight) {
el.className = hidingClass;
} else {
el.classList.remove(hidingClass);
}
}Acredite, existe um problema ainda mais grave aqui! O nome da fun��o n�o � fiel a seu comportamento.
Ao ler o c�digo, � poss�vel ver que ela n�o est� simplesmente "ocultando o elemento" � como o nome indica. Ela apenas aplica a classe "hidden" quando o offset y da p�gina � maior que o valor stop, e o soltando quando o valor � igual ou menor.
A �nica maneira de obter-se esta informa��o � lendo o corpo da fun��o e se deparando com a linha com a condi��o window.pageYOffset > minHeight.
A solu��o para o problema � dar um nome mais descritivo, que realmente captura a funcionalidade.
No fim das contas, nosso c�digo ficou assim:
function hideElementAfterHeight(minHeight, targetElement, hidingClass = "hidden") {
if (window.pageYOffset > minHeight) {
el.className.add(hidingClass);
} else {
el.classList.remove(hidingClass);
}
}O objetivo deste artigo foi demonstrar o lado nocivo dos coment�rios de c�digo. Come�amos o artigo com uma fun��o simples, por�m com nomes que dificultavam sua usabilidade, e a transformamos em um trecho de c�digo que dispensa a documenta��o adicional. Qual � a �moral da hist�ria�?
O bom c�digo n�o deve focar apenas na performance de execu��o, mas tamb�m em sua simplicidade, legibilidade e facilidade de manuten��o por outros programadores.
E o objetivo dos coment�rios de c�digo n�o deve ser simplesmente repetir o que j� estamos dizendo no c�digo, ou mascarar problemas de legibilidade do mesmo.
E a�, este conte�do te ajudou? Acha que pode ajudar mais algu�m? Ent�o compartilhe nas suas redes sociais!
comment_id: 5ba14fe9cd4b330001500cde plaintext: Programador, voc� tem o costume de comentar seu c�digo de forma meticulosa e detalhada? Como a maioria das pessoas, voc� respondeu (ou ao menos gostaria de responder) SIM! Mas ser� que seus coment�rios de c�digo realmente adicionam valor, ou est�o deixando seu c�digo pior? Ficou curioso de como seus coment�rios podem piorar seus c�digos? Ent�o acompanhe o post que preparamos hoje! Nomear coisas � dif�cil Sobre a nossa profiss�o, Phil Kalton disse [https://martinfowler.com/bliki/TwoHardThings.html]: S� existem duas coisas dif�ceis em Ci�ncia da Computa��o: invalida��o de cache e escolher nomes das coisas.Como supostamente temos c�rebros anal�ticos e gostamos de problemas complexos, focamos sempre na primeira dificuldade. Mas clareza na comunica��o nunca � demais quando trabalhamos em bases de c�digo grandes com outros desenvolvedores. Dar nomes claros e objetivos para fun��es, par�metros e vari�veis � dif�cil. Tal falta de clareza, em alguns casos, � contornada com a utiliza��o de documenta��o � na forma de coment�rios inline. Por�m nem sempre mais documenta��o � melhor. �s vezes essa documenta��o � redundante, sintoma de problemas de clareza no seu c�digo, ou at� uma desculpa para n�o melhorar o c�digo. Hoje em dia v�rias comunidades de desenvolvedores consideram que o antigo objetivo de comentar o m�ximo poss�vel � uma pr�tica obsoleta e at� danosa. Por exemplo, um dos mais populares guias de estilo de Ruby postula que: O bom c�digo � sua pr�pria melhor documenta��o. Quando voc�s estiver prestes a adicionar um comentrio, se pergunte, "Como eu posso melhorar o c�digo para que o este coment�rio n�o seja necess�rio?" Melhore o c�digo e ent�o o documente para torna-lo ainda mais claro.Steve McConnellUm exemplo Veja a fun��o abaixo, que era utilizada internamente em nosso produto. /* Function to hide element stop -> Minimum height for hiding el -> Target element to be hidden Info: The class 'hidden' is used to hide the element */ function hideElement(stop, el) { if (window.pageYOffset > stop) { el.className.add("hidden"); } else { el.classList.remove("hidden"); } } Esses coment�rios aparentemente inofensivos s�o sintomas de problemas maiores com o nome das fun��es e seus par�metros. Vamos ver quais s�o estes problemas? 1. Redund�ncia no nome da fun��o // Function to hide element Perceba que a linha acima n�o faz nada mais do que repetir o a primeira linha de c�digo da fun��o, de forma quase literal: function hideElement(stop, el) { J� essa linha de c�digo n�o cont�m nenhuma ambiguidade quanto a seu objetivo. Sendo assim, � poss�vel remover o trecho de coment�rio sem nenhum preju�zo para a documenta��o.Existe um segundo problema com o nome desta fun��o, mas falaremos dele mais tarde. 2. Nomes de par�metro pouco descritivos stop -> Minimum height for hiding el -> Target element to be hidden Nesse caso, o nome dos par�metros � bastante vago. O que � el? E esse stop? � um verbo no imperativo, ou um substantivo? Esse tipo de ambiguidade atrapalha a utiliza��o da fun��o, e �s vezes exige que o programador leia seu c�digo inteiro antes de utiliz�-la. Lendo os coment�rios podemos observar que � bem f�cil resolver isso, j� que eles pr�prios indicam nomes melhores. O par�metros stop poderia ser minHeight. J� o par�metros el poderia se chamar targetElement. Essas duas pequenas mudan�as n�o ajudariam apenas a remover os coment�rios redundantes, como melhoraram a leitura da parte interna da fun��o. 3. Necessidade de informa��o adicional Info: The class 'hidden' is used to hide the element Essa pequena informa��o � um sintoma de outros dois problemas. Primeiramente, por repetir uma informa��o que j� existe dentro da fun��o � o que quebra o princ�pio DRY. A string hidden aparece duas vezes dentro do nosso c�digo. O segundo problema � que essa string � similar a um n�mero m�gico [https://pt.wikipedia.org/wiki/N%C3%BAmero_m%C3%A1gico_(inform%C3%A1tica)], e aparece no nosso c�digo e no coment�rio sem um contexto e sem um nome auto-explicativo. Como j� estamos utilizando ES6, a solu��o mais pr�tica foi refatorar esta fun��o e utilizar par�metros opcionais. Isso permitiu tanto que a fun��o se tornasse auto-document�vel, quanto trouxe esta flexibiliza��o. Veja como ficou: function hideElement(minHeight, targetElement, hidingClass = "hidden") { if (window.pageYOffset > minHeight) { el.className = hidingClass; } else { el.classList.remove(hidingClass); } } 4. Omiss�es na documenta��o Acredite, existe um problema ainda mais grave aqui! O nome da fun��o n�o � fiel a seu comportamento. Ao ler o c�digo, � poss�vel ver que ela n�o est� simplesmente "ocultando o elemento" � como o nome indica. Ela apenas aplica a classe "hidden" quando o offset y da p�gina � maior que o valor stop, e o soltando quando o valor � igual ou menor. A �nica maneira de obter-se esta informa��o � lendo o corpo da fun��o e se deparando com a linha com a condi��o window.pageYOffset > minHeight. A solu��o para o problema � dar um nome mais descritivo, que realmente captura a funcionalidade. No fim das contas, nosso c�digo ficou assim: function hideElementAfterHeight(minHeight, targetElement, hidingClass = "hidden") { if (window.pageYOffset > minHeight) { el.className.add(hidingClass); } else { el.classList.remove(hidingClass); } } O que aprendemos? O objetivo deste artigo foi demonstrar o lado nocivo dos coment�rios de c�digo. Come�amos o artigo com uma fun��o simples, por�m com nomes que dificultavam sua usabilidade, e a transformamos em um trecho de c�digo que dispensa a documenta��o adicional. Qual � a �moral da hist�ria�? O bom c�digo n�o deve focar apenas na performance de execu��o, mas tamb�m em sua simplicidade, legibilidade e facilidade de manuten��o por outros programadores. E o objetivo dos coment�rios de c�digo n�o deve ser simplesmente repetir o que j� estamos dizendo no c�digo, ou mascarar problemas de legibilidade do mesmo. E a�, este conte�do te ajudou? Acha que pode ajudar mais algu�m? Ent�o compartilhe nas suas redes sociais! feature_image: https://s3.amazonaws.com/chorus-static-files-production20180703025311327900000004/a0132077a97542be94567c41b6641e9b/2018/09/4290373eede1124b7c4752104caff8aa.jpg-X-Amz-Algorithm-AWS4-HMAC-SHA256-X-Amz-Credential-AKIAJ3BVJGGW4RD4RJDA-2F20180918-2Fus-east-1-2Fs3-2Faws4_request-X-Amz-Date-20180918T192002Z-X-Amz-Expires-900-X-Amz-SignedHeaders-host-X-Amz-Signature-276e0bda88e3f2d19a4c3dc39d7d853a10646980061d9ee7d512cf2a30c97427.jpg featured: 0 page: 0 status: published locale: NULL visibility: public meta_title: NULL meta_description: NULL author_id: 1 created_at: 2018-09-18 19:20:09 created_by: rockstudio-author updated_at: 2018-09-18 19:20:09 updated_by: rockstudio-author published_at: 2018-09-18 19:20:09 published_by: rockstudio-author custom_excerpt: NULL codeinjection_head: NULL codeinjection_foot: NULL og_image: NULL og_title: NULL og_description: NULL twitter_image: NULL twitter_title: NULL twitter_description: NULL custom_template: NULL