Advertisement
Not a member of Pastebin yet?
Sign Up,
it unlocks many cool features!
- *************************** 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
Advertisement
Add Comment
Please, Sign In to add comment
Advertisement