*************************** 9. row ***************************
id: 5ba14fe9cd4b330001500cde
uuid: 04687a0d-66da-4715-aedf-459cca0f8b44
title: Ser� que seus coment�rios est�o deixando seu c�digo pior?
slug: sera-que-seus-comentarios-estao-deixando-seu-codigo-pior
mobiledoc: {"version":"0.3.1","markups":[],"atoms":[],"cards":[["card-markdown",{"cardName":"card-markdown","markdown":"<p>Programador, voc� tem o costume de comentar seu c�digo de forma meticulosa e detalhada?�</p><p>Como a maioria das pessoas, voc� respondeu (ou ao menos gostaria de responder) SIM!</p><p>Mas ser� que seus coment�rios de c�digo realmente adicionam valor, ou est�o deixando seu c�digo pior?</p><p>Ficou curioso de como seus coment�rios podem piorar seus c�digos? Ent�o acompanhe o post que preparamos hoje!</p><h2>Nomear coisas � dif�cil</h2><p>Sobre a nossa profiss�o,<a href=\"https://martinfowler.com/bliki/TwoHardThings.html\"> Phil Kalton disse</a>:�</p><blockquote>S� existem duas coisas dif�ceis em Ci�ncia da Computa��o: invalida��o de cache e escolher nomes das coisas.�</blockquote><p>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.</p><p><strong>Dar nomes claros e objetivos para fun��es, par�metros e vari�veis � dif�cil.</strong></p><p>Tal falta de clareza, em alguns casos, � contornada com a utiliza��o de documenta��o � na forma de coment�rios <em>inline</em>. 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.</p><p>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<a href=\"https://github.com/bbatsov/ruby-style-guide#comments\"> dos mais populares guias de estilo de Ruby</a> postula que:</p><blockquote>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</blockquote><h3>Um exemplo</h3><p>Veja a fun��o abaixo, que era utilizada internamente em nosso produto.</p><h2><pre>/*\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}</pre></h2><p>Esses coment�rios aparentemente inofensivos s�o sintomas de problemas maiores com o nome das fun��es e seus par�metros.�</p><p>Vamos ver quais s�o estes problemas?</p><h3>1. Redund�ncia no nome da fun��o</h3><h2><pre>// Function to hide element</pre></h2><p>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:</p><h2><pre>function hideElement(stop, el) {</pre></h2><p>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.</p><h3>2. Nomes de par�metro pouco descritivos</h3><h2><pre>stop -> Minimum height for hiding\nel -> Target element to be hidden</pre></h2><p>Nesse caso, o nome dos par�metros � bastante vago. O que � <strong><em>el</em></strong>? E esse <strong><em>stop</em></strong>? � um verbo no imperativo, ou um substantivo?�</p><p>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.</p><p>Lendo os coment�rios podemos observar que � bem f�cil resolver isso, j� que eles pr�prios indicam nomes melhores.�</p><p>O par�metros <strong><em>stop</em></strong> poderia ser <strong><em>minHeight</em></strong>.�</p><p>J� o par�metros <strong><em>el</em></strong> poderia se chamar <strong><em>targetElement</em></strong>.</p><p>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.</p><h3><strong>3. Necessidade de informa��o adicional</strong></h3><h2><pre>Info: The class 'hidden' is used to hide the element</pre></h2><p>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.</p><p>A string <em>hidden </em>aparece duas vezes dentro do nosso c�digo. O segundo problema � que essa string � similar a um<a href=\"https://pt.wikipedia.org/wiki/N%C3%BAmero_m%C3%A1gico_(inform%C3%A1tica)\"> n�mero m�gico</a>, e aparece no nosso c�digo e no coment�rio sem um contexto e sem um nome auto-explicativo.</p><p>Como j� estamos utilizando ES6, a solu��o mais pr�tica foi refatorar esta fun��o e utilizar par�metros opcionais.�</p><p>Isso permitiu tanto que a fun��o se tornasse auto-document�vel, quanto trouxe esta flexibiliza��o. Veja como ficou:</p><h2><pre>function hideElement(minHeight, targetElement, hidingClass = \"hidden\") {\n if (window.pageYOffset > minHeight) {\n el.className = hidingClass;\n } else {\n el.classList.remove(hidingClass);\n }\n}</pre></h2><h3><strong>4. Omiss�es na documenta��o</strong></h3><p>Acredite, existe um problema ainda mais grave aqui! O nome da fun��o n�o � fiel a seu comportamento.</p><p>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 <em>offset y</em> da p�gina � maior que o valor <em>stop</em>, e o soltando quando o valor � igual ou menor.</p><p>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 <em>window.pageYOffset > minHeight</em>.</p><p>A solu��o para o problema � dar um nome mais descritivo, que realmente captura a funcionalidade.</p><p>No fim das contas, nosso c�digo ficou assim:</p><h2><pre>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}</pre></h2><h3>O que aprendemos?</h3><p>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�?</p><p>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.</p><p>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.</p><p>E a�, este conte�do te ajudou? Acha que pode ajudar mais algu�m? Ent�o compartilhe nas suas redes sociais!</p><p></p>"}]],"sections":[[10,0]]}
html: <p>Programador, voc� tem o costume de comentar seu c�digo de forma meticulosa e detalhada?�</p><p>Como a maioria das pessoas, voc� respondeu (ou ao menos gostaria de responder) SIM!</p><p>Mas ser� que seus coment�rios de c�digo realmente adicionam valor, ou est�o deixando seu c�digo pior?</p><p>Ficou curioso de como seus coment�rios podem piorar seus c�digos? Ent�o acompanhe o post que preparamos hoje!</p><h2>Nomear coisas � dif�cil</h2><p>Sobre a nossa profiss�o,<a href="https://martinfowler.com/bliki/TwoHardThings.html"> Phil Kalton disse</a>:�</p><blockquote>S� existem duas coisas dif�ceis em Ci�ncia da Computa��o: invalida��o de cache e escolher nomes das coisas.�</blockquote><p>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.</p><p><strong>Dar nomes claros e objetivos para fun��es, par�metros e vari�veis � dif�cil.</strong></p><p>Tal falta de clareza, em alguns casos, � contornada com a utiliza��o de documenta��o � na forma de coment�rios <em>inline</em>. 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.</p><p>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<a href="https://github.com/bbatsov/ruby-style-guide#comments"> dos mais populares guias de estilo de Ruby</a> postula que:</p><blockquote>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</blockquote><h3>Um exemplo</h3><p>Veja a fun��o abaixo, que era utilizada internamente em nosso produto.</p><h2><pre>/*
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");
}
}</pre></h2><p>Esses coment�rios aparentemente inofensivos s�o sintomas de problemas maiores com o nome das fun��es e seus par�metros.�</p><p>Vamos ver quais s�o estes problemas?</p><h3>1. Redund�ncia no nome da fun��o</h3><h2><pre>// Function to hide element</pre></h2><p>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:</p><h2><pre>function hideElement(stop, el) {</pre></h2><p>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.</p><h3>2. Nomes de par�metro pouco descritivos</h3><h2><pre>stop -> Minimum height for hiding
el -> Target element to be hidden</pre></h2><p>Nesse caso, o nome dos par�metros � bastante vago. O que � <strong><em>el</em></strong>? E esse <strong><em>stop</em></strong>? � um verbo no imperativo, ou um substantivo?�</p><p>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.</p><p>Lendo os coment�rios podemos observar que � bem f�cil resolver isso, j� que eles pr�prios indicam nomes melhores.�</p><p>O par�metros <strong><em>stop</em></strong> poderia ser <strong><em>minHeight</em></strong>.�</p><p>J� o par�metros <strong><em>el</em></strong> poderia se chamar <strong><em>targetElement</em></strong>.</p><p>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.</p><h3><strong>3. Necessidade de informa��o adicional</strong></h3><h2><pre>Info: The class 'hidden' is used to hide the element</pre></h2><p>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.</p><p>A string <em>hidden </em>aparece duas vezes dentro do nosso c�digo. O segundo problema � que essa string � similar a um<a href="https://pt.wikipedia.org/wiki/N%C3%BAmero_m%C3%A1gico_(inform%C3%A1tica)"> n�mero m�gico</a>, e aparece no nosso c�digo e no coment�rio sem um contexto e sem um nome auto-explicativo.</p><p>Como j� estamos utilizando ES6, a solu��o mais pr�tica foi refatorar esta fun��o e utilizar par�metros opcionais.�</p><p>Isso permitiu tanto que a fun��o se tornasse auto-document�vel, quanto trouxe esta flexibiliza��o. Veja como ficou:</p><h2><pre>function hideElement(minHeight, targetElement, hidingClass = "hidden") {
if (window.pageYOffset > minHeight) {
el.className = hidingClass;
} else {
el.classList.remove(hidingClass);
}
}</pre></h2><h3><strong>4. Omiss�es na documenta��o</strong></h3><p>Acredite, existe um problema ainda mais grave aqui! O nome da fun��o n�o � fiel a seu comportamento.</p><p>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 <em>offset y</em> da p�gina � maior que o valor <em>stop</em>, e o soltando quando o valor � igual ou menor.</p><p>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 <em>window.pageYOffset > minHeight</em>.</p><p>A solu��o para o problema � dar um nome mais descritivo, que realmente captura a funcionalidade.</p><p>No fim das contas, nosso c�digo ficou assim:</p><h2><pre>function hideElementAfterHeight(minHeight, targetElement, hidingClass = "hidden") {
if (window.pageYOffset > minHeight) {
el.className.add(hidingClass);
} else {
el.classList.remove(hidingClass);
}
}</pre></h2><h3>O que aprendemos?</h3><p>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�?</p><p>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.</p><p>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.</p><p>E a�, este conte�do te ajudou? Acha que pode ajudar mais algu�m? Ent�o compartilhe nas suas redes sociais!</p><p></p>
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
Comments