{"id":351,"date":"2023-10-03T11:45:00","date_gmt":"2023-10-03T14:45:00","guid":{"rendered":"http:\/\/suspensao.blog.br\/descrenca\/?p=351"},"modified":"2023-10-03T20:51:40","modified_gmt":"2023-10-03T23:51:40","slug":"sem-comentarios-e-agora","status":"publish","type":"post","link":"https:\/\/suspensao.blog.br\/descrenca\/sem-comentarios-e-agora\/","title":{"rendered":"Sem Coment\u00e1rios. E agora?"},"content":{"rendered":"\n

Tradicionalmente, considera-se uma boa pr\u00e1tica comentar o c\u00f3digo. H\u00e1 algum tempo, tem-se revisto este conceito. Na Liferay<\/a>, por exemplo, seguimos uma pol\u00edtica de n\u00e3o comentar c\u00f3digo. Pessoalmente, sou um entusiasta desta filosofia. Mas n\u00e3o quero apresentar ou defender esta estrat\u00e9gia: h\u00e1 muito material<\/a> bom sobre isto<\/a>. Quero discutir uma quest\u00e3o em aberto.<\/p>\n\n\n\n

Quem comenta quer transmitir alguma informa\u00e7\u00e3o importante. Que informa\u00e7\u00e3o \u00e9 essa? E, mais importante ainda, onde podemos registr\u00e1-la? Vejamos algumas alternativas.<\/p>\n\n\n\n

O que essas linhas fazem?<\/h2>\n\n\n\n

Os nomes de fun\u00e7\u00f5es<\/em> s\u00e3o excelentes para explicar o que<\/em> o c\u00f3digo faz. Se um bloco de c\u00f3digo precisa de um coment\u00e1rio, considere extra\u00ed-lo para uma fun\u00e7\u00e3o ou classe. O nome da entidade j\u00e1 esclarecer\u00e1 seu prop\u00f3sito.<\/p>\n\n\n\n

Observe, por exemplo, as linhas abaixo, retiradas desta classe de testes<\/a>:<\/p>\n\n\n

Assert<\/span>.assertNotNull<\/span>(recurrence<\/span>);\nAssert<\/span>.assertNull<\/span>(recurrence<\/span>.getUntilJCalendar<\/span>());\nAssert<\/span>.assertEquals<\/span>(0, recurrence<\/span>.getCount<\/span>());<\/code><\/span>Code language:<\/span> CSS<\/span> (<\/span>css<\/span>)<\/span><\/small><\/pre>\n\n\n
Os conceitos s\u00e3o complexos; eu mesmo me confundiria ao reler estes asserts<\/em>. Um coment\u00e1rio poderia explic\u00e1-los. Mas este commit<\/a> j\u00e1 esclareceu tudo ao mover essas linhas para um m\u00e9todo e invoc\u00e1-lo: <\/p>\n\n\n
assertRepeatsForever(recurrence);<\/code><\/span><\/pre>\n\n\n
Aquelas asser\u00e7\u00f5es verificavam se o evento se repete eternamente! Nenhum coment\u00e1rio foi necess\u00e1rio \u2014 felizmente, pois estes asserts<\/em> estavam em v\u00e1rios testes.<\/p>\n\n\n\n
O que est\u00e1 acontecendo?<\/h2>\n\n\n\n
Se o coment\u00e1rio iria explicar algo relevante em tempo de execu\u00e7\u00e3o, considere transform\u00e1-lo em uma mensagem de log! Note o exempo abaixo.<\/p>\n\n\n
if<\/span> (Validator.isBlank(serviceAccountKey)) {\n\t\/\/ If no credentials are set for GCS Store, the library will<\/span>\n\t\/\/ use Application Default Credentials.<\/span>\n\t_googleCredentials =\n\t\tServiceAccountCredentials.getApplicationDefault();\n}\nelse<\/span> {\n\t_googleCredentials = ServiceAccountCredentials.fromStream(\n\t\tnew<\/span> ByteArrayInputStream(serviceAccountKey.getBytes()));\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
if<\/span> (Validator.isBlank(serviceAccountKey)) {\n\tif<\/span> (_log.isInfoEnabled()) {\n\t\t_log.info(\n\t\t\t\"No credentials set for GCS Store. Library will use \"<\/span> +\n\t\t\t\t\"Application Default Credentials.\"<\/span>);\n\t}\n\n\t_googleCredentials =\n\t\tServiceAccountCredentials.getApplicationDefault();\n}\nelse<\/span> {\n\t_googleCredentials = ServiceAccountCredentials.fromStream(\n\t\tnew<\/span> ByteArrayInputStream(serviceAccountKey.getBytes()));\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Por que este c\u00f3digo est\u00e1 aqui?<\/h2>\n\n\n\n
Coment\u00e1rios para explicar por que<\/em> algumas linhas est\u00e3o ali tamb\u00e9m s\u00e3o comuns. Um local melhor para compartilhar essas informa\u00e7\u00f5es s\u00e3o as mensagens de commits<\/em>.<\/p>\n\n\n\n
Estes dias, por exemplo, me pediram para ajudar com um c\u00f3digo em que trabalhei anos atr\u00e1s. Lendo uma JSP \u2014 lembre-se, anos atr\u00e1s \u2014 eu encontrei essas linhas<\/a>:<\/p>\n\n\n
<liferay-portlet:renderURL<\/span> portletName<\/span>=\"<%= KaleoDesignerPortletKeys.KALEO_DESIGNER %>\"<\/span> var<\/span>=\"viewURL\"<\/span>><\/span>\n\t<portlet:param<\/span> name<\/span>=\"mvcPath\"<\/span> value<\/span>=\"\/designer\/view_kaleo_definition_version.jsp\"<\/span> \/><\/span>\n\t<portlet:param<\/span> name<\/span>=\"redirect\"<\/span> value<\/span>=\"<%= currentURL %>\"<\/span> \/><\/span>\n\t<portlet:param<\/span> name<\/span>=\"name\"<\/span> value<\/span>=\"<%= kaleoDefinitionVersion.getName() %>\"<\/span> \/><\/span>\n\t<portlet:param<\/span> name<\/span>=\"draftVersion\"<\/span> value<\/span>=\"<%= kaleoDefinitionVersion.getVersion() %>\"<\/span> \/><\/span>\n<\/liferay-portlet:renderURL<\/span>><\/span><\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
Esta tag<\/em> est\u00e1 gerando uma URL para ser utilizada em outro lugar. Mas meus olhos treinados acharam estranho aquele par\u00e2metro portletName<\/code>. Este valor costumar ser definido automaticamente.<\/p>\n\n\n\n
\n
LPS-74977 \/ LPS-73731 By making the render URL explicitly use the Kaleo Designer name, it will be valid when rendered in another portlet.<\/p>\n<\/blockquote>\n\n\n\n
Entendi! Este c\u00f3digo provavelmente vai ser invocado por algum outro portlet. Neste caso, o valor seria automaticamente setado pela outra aplica\u00e7\u00e3o, e por alguma raz\u00e3o queremos evitar isso.<\/p>\n\n\n\n
(Por esta raz\u00e3o, ali\u00e1s, prefiro  commits<\/em> pequenos: eles facilitam descobrir a raz\u00e3o de trechos de c\u00f3digo bem espec\u00edficos. \u00c9 como se todas<\/em> as linhas de c\u00f3digo tivessem um coment\u00e1rio! N\u00e3o \u00e9 uma posi\u00e7\u00e3o un\u00e2nime, por\u00e9m: h\u00e1 quem prefira commits<\/em> maiores.)<\/p>\n\n\n\n
A raz\u00e3o da linha foi esclarecida. Mas por que ela pode ser invocada de outra aplica\u00e7\u00e3o? Isto n\u00e3o \u00e9 usual…<\/p>\n\n\n\n
Por que esta mudan\u00e7a foi feita?<\/h2>\n\n\n\n
Um c\u00f3digo bem escrito explica como<\/em> algo foi implementado. A mensagem de commit<\/em> esclarece o porqu\u00ea<\/em>, mas em um contexto local. Como explicar a motiva\u00e7\u00e3o mais ampla por tr\u00e1s de um c\u00f3digo sem recorrer a coment\u00e1rios?<\/p>\n\n\n\n
Os t\u00edquetes do issue tracker<\/em> s\u00e3o excelentes para isto. Normalmente escritos para guiar o desenvolvimento, esses documentos ajudam demais na interpreta\u00e7\u00e3o do c\u00f3digo. Se adicionarmos a chave do t\u00edquete \u00e0 mensagem de commit<\/em>, podemos rastrear as raz\u00f5es.<\/p>\n\n\n\n
Voltando ao exemplo acima. Descobrimos que uma linha permite usar o mesmo c\u00f3digo em v\u00e1rios portlets. Mas isso raramente \u00e9 necess\u00e1rio. Por que precisamos reutilizar o c\u00f3digo neste caso? Por sorte, a mensagem menciona dois t\u00edquetes. Fui verificar o mais antigo; cheguei a LPSA-64324<\/a>:<\/p>\n\n\n\n
\n
[Information Architecture] EE – As a portal admin, I would like to access all workflow portlets from the control panel section under the same tab.<\/p>\n<\/blockquote>\n\n\n\n
O t\u00edtulo j\u00e1 ajuda, e o texto esclarece de vez. Por raz\u00f5es de usabilidade, tr\u00eas aplica\u00e7\u00f5es diferentes passaram a aparecer em abas de um mesmo portlet. Faz todo sentido!<\/p>\n\n\n\n
Os coment\u00e1rios que a gente gosta<\/h2>\n\n\n\n
\u00c9 importante destacar que tentamos evitar coment\u00e1rios desorganizados, que se entrela\u00e7am no c\u00f3digo e tentam explicar trechos dif\u00edceis de entender. H\u00e1 v\u00e1rios coment\u00e1rios, frequentemente com formatos padronizados, que n\u00e3o atrapalham a leitura. Um exemplo \u00f3bvio s\u00e3o os cabe\u00e7alhos de copyright<\/em>.<\/p>\n\n\n\n
Outra maneira de usar coment\u00e1rios efetivamente \u00e9 a programa\u00e7\u00e3o letrada<\/a>. Neste estilo de programa\u00e7\u00e3o, os coment\u00e1rios s\u00e3o a estrela do show: o c\u00f3digo-fonte contem mais prosa do que c\u00f3digo execut\u00e1vel. Isto \u00e9 \u00fatil quando explicar o algoritmo \u00e9 mais importante do que l\u00ea-lo, como em pesquisas acad\u00eamicas e an\u00e1lise de dados. N\u00e3o por acaso, \u00e9 o paradigma de ferramentas populares como Jupyter Notebook<\/a> e Quarto<\/a>.<\/p>\n\n\n\n
Mais relevante ainda, ferramentas como Javadoc<\/a>, JSDoc<\/a>, Doxygen<\/a> etc. leem coment\u00e1rios em um formato espec\u00edfico para gerar documenta\u00e7\u00e3o. Estes coment\u00e1rios n\u00e3o afetam a legibilidade. Pelo contr\u00e1rio: javadocs s\u00e3o \u00f3timos para explicar como usar<\/em> estas entidades. Combinados com ferramentas como meu querido Doctest<\/a>, temos at\u00e9 garantias de acur\u00e1cia e atualidade!<\/p>\n\n\n\n
Um mundo de possibilidades<\/h2>\n\n\n\n
Esses s\u00e3o apenas alguns exemplos de alternativas aos coment\u00e1rios. H\u00e1 muitas outras op\u00e7\u00f5es, como wikis, blogs. J\u00e1 encontrei a explica\u00e7\u00e3o para um c\u00f3digo que escrevi no Stack Overflow! Podemos pensar em ainda mais solu\u00e7\u00f5es para atender a diferentes necessidades. O ponto principal \u00e9 que, tendo estas ferramentas \u00e0 nossa disposi\u00e7\u00e3o, adicionar coment\u00e1rios diretamente ao c\u00f3digo torna-se desnecess\u00e1rio.<\/p>\n\n\n\n
Naturalmente, evitar coment\u00e1rios \u00e9 apenas uma das formas para se escrever c\u00f3digo leg\u00edvel. Coment\u00e1rios n\u00e3o s\u00e3o proibidos; de fato, h\u00e1 estrat\u00e9gias que podem torn\u00e1-los eficazes. No entanto, na minha experi\u00eancia, comentar indisciplinadamente leva a piores resultados, e essas t\u00e9cnicas ajudam a documentar informa\u00e7\u00f5es importantes que n\u00e3o cabem diretamente no c\u00f3digo.<\/p>\n\n\n\n
Voc\u00ea \u00e9 um adepto da estrat\u00e9gia “sem coment\u00e1rios”? Se sim, que outros meios voc\u00ea usa para transmitir infirma\u00e7\u00f5es? Se n\u00e3o, como voc\u00ea faz para ter coment\u00e1rios efetivos? Que tipo de coment\u00e1rio voc\u00ea n\u00e3o v\u00ea sendo substitu\u00eddo por essas abordagens? Adoraria escutar suas opini\u00f5es.<\/p>\n","protected":false},"excerpt":{"rendered":"
Tradicionalmente, considera-se uma boa pr\u00e1tica comentar o c\u00f3digo. H\u00e1 algum tempo, tem-se revisto este conceito. Na Liferay, por exemplo, seguimos uma pol\u00edtica de n\u00e3o comentar c\u00f3digo. Pessoalmente, sou um entusiasta desta filosofia. Mas n\u00e3o quero apresentar ou defender esta estrat\u00e9gia: h\u00e1 muito material bom sobre isto. Quero discutir uma quest\u00e3o em aberto. Quem comenta quer […]<\/p>\n","protected":false},"author":2,"featured_media":548,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2}},"categories":[12,1],"tags":[167,168,166],"class_list":["post-351","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-programacao","category-uncategorized","tag-comentario","tag-comentario-de-codigo","tag-comentarios"],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"https:\/\/i0.wp.com\/suspensao.blog.br\/descrenca\/wp-content\/uploads\/2023\/10\/1920px-Mona_Lisa_margin_scribble.jpg?fit=1920%2C576&ssl=1","jetpack_shortlink":"https:\/\/wp.me\/p23QLV-5F","jetpack_sharing_enabled":true,"jetpack_likes_enabled":true,"jetpack-related-posts":[],"_links":{"self":[{"href":"https:\/\/suspensao.blog.br\/descrenca\/wp-json\/wp\/v2\/posts\/351","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/suspensao.blog.br\/descrenca\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/suspensao.blog.br\/descrenca\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/suspensao.blog.br\/descrenca\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/suspensao.blog.br\/descrenca\/wp-json\/wp\/v2\/comments?post=351"}],"version-history":[{"count":24,"href":"https:\/\/suspensao.blog.br\/descrenca\/wp-json\/wp\/v2\/posts\/351\/revisions"}],"predecessor-version":[{"id":558,"href":"https:\/\/suspensao.blog.br\/descrenca\/wp-json\/wp\/v2\/posts\/351\/revisions\/558"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/suspensao.blog.br\/descrenca\/wp-json\/wp\/v2\/media\/548"}],"wp:attachment":[{"href":"https:\/\/suspensao.blog.br\/descrenca\/wp-json\/wp\/v2\/media?parent=351"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/suspensao.blog.br\/descrenca\/wp-json\/wp\/v2\/categories?post=351"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/suspensao.blog.br\/descrenca\/wp-json\/wp\/v2\/tags?post=351"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
Um git blame<\/code> esclareceu tudo, quando encontrei este commit<\/a>. A mensagem \u00e9 clara:<\/p>\n\n\n\n
Este coment\u00e1rio pode ser relevante para quem l\u00ea o c\u00f3digo. Contudo, seria crucial<\/em> para algu\u00e9m investigando um problema de autentica\u00e7\u00e3o. Por isso, na pr\u00e1tica, escolhi logar uma mensagem<\/a>:<\/p>\n\n\n
Essas linhas verificam se a RRule<\/a> de um evento tem certas propriedades: ela deve existir, ter um “until<\/em>” Calendar<\/code><\/a> nulo e uma contagem de zero.<\/p>\n\n\n\n