<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Leisia Medeiros on Medium]]></title>
        <description><![CDATA[Stories by Leisia Medeiros on Medium]]></description>
        <link>https://medium.com/@leisiamedeiros?source=rss-630fee3bdefd------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*V5TujmMk2qUu8ZmOnjpSHw.jpeg</url>
            <title>Stories by Leisia Medeiros on Medium</title>
            <link>https://medium.com/@leisiamedeiros?source=rss-630fee3bdefd------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 04:49:35 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@leisiamedeiros/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[AsyncAPI specification — Using Saunter to generate event documentation]]></title>
            <link>https://medium.com/@leisiamedeiros/asyncapi-specification-utilizando-saunter-para-gera%C3%A7%C3%A3o-da-documenta%C3%A7%C3%A3o-31dbb720f2b0?source=rss-630fee3bdefd------2</link>
            <guid isPermaLink="false">https://medium.com/p/31dbb720f2b0</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[asyncapi]]></category>
            <category><![CDATA[specifications]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[events]]></category>
            <dc:creator><![CDATA[Leisia Medeiros]]></dc:creator>
            <pubDate>Wed, 19 Jan 2022 03:44:40 GMT</pubDate>
            <atom:updated>2023-01-09T16:00:05.096Z</atom:updated>
            <content:encoded><![CDATA[<h3>AsyncAPI specification — Using Saunter to generate event documentation</h3><blockquote><a href="https://www.asyncapi.com/docs/specifications/v2.2.0">AsyncAPI </a>is an open source initiative that seeks to improve the current state of Event Driven Architecture (EDA).</blockquote><p>In this post I will present an implementation of the <a href="https://www.asyncapi.com/docs/specifications/v2.2.0">AsyncAPI Specification</a> (an industry standard for describing asynchronous APIs) using <a href="https://github.com/tehmantra/saunter">Saunter</a> library, which like Swagger, is a tool for generating documentation based on your code.</p><p>The source code you can access in this <a href="https://github.com/leisiamedeiros/asyncapi-masstransit-rabbitmq#async-api-with-masstransit-and-rabbitmq">repository</a>.</p><p><a href="https://github.com/leisiamedeiros/asyncapi-masstransit-rabbitmq">GitHub - leisiamedeiros/asyncapi-masstransit-rabbitmq</a></p><h4>Adding the package</h4><p>The first step is to add the <a href="https://www.nuget.org/packages/Saunter/">package</a> reference to the project, this can be done through the nuget package manager or via command. The package should be added to projects that will make use of the notations mentioned below.</p><pre>dotnet add package Saunter</pre><h4>Setting</h4><p>In this example, a class called AsyncApi was created inside Config folder, and the AddAsyncApiConfig method was created and added in the startup class as shown below;</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/3db3cea32a224efa994e123fe40bf93d/href">https://medium.com/media/3db3cea32a224efa994e123fe40bf93d/href</a></iframe><p>In the example above, the MarkerTypes method returns the types of classes that were ‘marked’ with the AsyncApi notation that we will see later. Don’t forget to call the AddAsyncApiConfig method at project startup.</p><p>Still at startup class we will have to call the middleware responsible for hosting the documentation as you can see bellow;</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/9908d957ad43612203bc8c56926a97e1/href">https://medium.com/media/9908d957ad43612203bc8c56926a97e1/href</a></iframe><h4>Adding attributes</h4><p>For the automatic generation of documentation, Saunter needs that the methods of a class that will publish or subscribe to messages be decorated with <strong>attributes</strong>, as shown in the code below;</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/e27fd2ff53907fdf7f5c14a6c05a4292/href">https://medium.com/media/e27fd2ff53907fdf7f5c14a6c05a4292/href</a></iframe><p>In the class add the attribute [AsyncApi]; in the method add the channel through the attribute Channel and then add the operations, which can be a PublishOperation or SubscribeOperation.</p><p>Finally, just access the configured path and check the result!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*w-Km0o2w-tXrxpmjQEbO5g.png" /></figure><h4>References</h4><ul><li><a href="https://www.asyncapi.com/"></a></li><li><a href="https://www.nuget.org/packages/Saunter/">Saunter 0.9.1</a></li><li><a href="https://github.com/tehmantra/saunter">GitHub - tehmantra/saunter: Saunter is a code-first AsyncAPI documentation generator for dotnet.</a></li></ul><blockquote>Thanks to <a href="https://medium.com/u/8d025f608675">Yan Justino</a> who presented me with the specification!</blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=31dbb720f2b0" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Compilando Clean Code]]></title>
            <link>https://medium.com/xp-inc/compilando-clean-code-6d7d2c5b5bce?source=rss-630fee3bdefd------2</link>
            <guid isPermaLink="false">https://medium.com/p/6d7d2c5b5bce</guid>
            <category><![CDATA[clean-code]]></category>
            <category><![CDATA[software-engineering]]></category>
            <dc:creator><![CDATA[Leisia Medeiros]]></dc:creator>
            <pubDate>Tue, 09 Nov 2021 20:47:30 GMT</pubDate>
            <atom:updated>2021-11-16T19:34:45.369Z</atom:updated>
            <content:encoded><![CDATA[<p>Resolvi fazer um resumo do livro Clean Code do Robert C. Martin (Uncle Bob) e destacar seus principais pontos — na minha opinião — com intuito de relembrar esse tema que fará parte de uma série de artigos que chamo de <em>“Compilando”</em>.</p><p>Espero que seja útil para quem ainda não conseguiu fazer toda a leitura do livro Clean Code, ou quem simplesmente quer revisitar o assunto. O livro apresenta técnicas para desenvolvimento de código limpo e o processo construtivo em busca dos melhores resultados.</p><blockquote>“Masters programmers think of systems as stories to be told rather than programs to be written — Robert C. Martin”</blockquote><h3>Code Sense</h3><p>Segundo o autor <em>“Reconhecer um código ruim não quer dizer que você saiba escrever um bom código”</em> para isso, você precisa adquirir algo que ele chama de code sense quando você se torna capaz de transformar um código ruim em um código limpo, mas isso com certeza requer muita prática.</p><p>Abaixo selecionei algumas das técnicas mencionadas no livro que irá nos ajudar a desenvolver um bom senso de código e como resultado traremos legibilidade, manutenibilidade e uma série de outras qualidades para nosso código.</p><h3>Nomes significativos</h3><blockquote><strong>Utilize nomes que revelam intenções</strong><em><br></em>O nome de uma variável, função ou classe deve responder porque ele existe, o que ele faz e como ele é utilizado.</blockquote><p>Pessoalmente, acredito que essa é uma das dicas mais importante, uma das quais a maioria dos desenvolvedores tem maior dificuldade em acertar. Logo abaixo, vocês notarão que iremos inevitavelmente lembrar desse tópico porque ele está bastante relacionado com outros!</p><h4>Evite Desinformação</h4><blockquote><strong>Informações que possam confundir ou enganar<br></strong>Programadores devem evitar deixar pistas falsas que tornam obscuro o significado do código. Abaixo exemplo retirado do livro que mostra o uso das variáveis l e O que podem ser facilmente confundidas com os números 0 e 1</blockquote><pre>int a = l;<br>if (O == l)<br> a = O1;<br>else<br> l = 01;</pre><h4>Faça distinções significativas</h4><blockquote>De nada adianta dar nomes diferentes se você não é capaz de identificar a distinção entre eles, porque de alguma forma eles possuem o mesmo significado.</blockquote><p>Nesse sentido, um exemplo que achei bem claro é o seguinte; Imagine que você tem uma classe Product que tem as propriedades ProductInfo e ProductData você seria capaz de identificar a distinção entre elas? Ou até mesmo um cenário com Customer e CustomerObject fica difícil distinguir não é?! Você tem apenas nomes diferentes, mas eles possuem significados semelhantes. Outro ponto interessante é sobre não colocar types em nomes de variáveis, por exemplo: nameString carList podem ser simplesmente name ou cars .</p><p>Como já comentei anteriormente, nomear não é tão fácil como imaginamos.</p><h4>Utilize nomes pronunciáveis</h4><p>Basicamente essa dica é para não dar nomes que as pessoas não sejam capaz de pronunciar sem parecer idiota! Por exemplo, tente pronunciar essa classe como se estivesse lendo-a DtaRcrd102 (e não vale mentalmente ler data record cento e dois como acabei de fazer hahaha).</p><h4>Utilize nomes pesquisáveis</h4><blockquote>O tamanho de um nome deve corresponder ao tamanho de seu escopo</blockquote><p>Neste ponto nos preocupamos sobre a rastreabilidade do código, a dica é; Não nomear variáveis ou constantes com apenas uma letra (por exemplo) pois ficará bastante difícil rastreá-las, procure também utilizar constantes para valores que irão se repetir.</p><h4>Evite mapa mental</h4><blockquote>Escreva algo que outros possam entender</blockquote><p>Lembra de nomear as variáveis dependendo do tamanho do escopo? Relaxe, você pode continuar utilizando i, j, k para loops já que o escopo é pequeno (e vamos combinar que é bem tradicional mesmo), mas muito cuidado, moderação é sempre bom!</p><p>O mapa mental trata do uso de nomes que na sua leitura façam sentido mas que na verdade sejam <em>pobres em seu contexto, </em>lembre-se que outras pessoas lerão seu código, e se o contexto fizer sentido apenas para você dificilmente outros entenderão.</p><h4>Nome de Classes</h4><p>Utilize substantivos e evite verbos!</p><h4>Nome de Métodos</h4><p>Ao contrário das classes, utilize verbos!</p><p><em>Para </em><em>accessors, mutators and predicates recomenda-se o prefixo correspondente </em><em>get </em><em>set </em><em>is seguido do nome.</em></p><h4>Utilize uma palavra por conceito</h4><p>Mantenha consistência, se você utiliza get (obter) como nome de método não utilize em outra classe por exemplo retrieve com o mesmo intuito (obter).</p><h4>Utilize Solution and Problem Domain Names</h4><p>Lembre-se que quem irá ler seu código será outros programadores, então não se preocupe em utilizar temos técnicos, um nome como ExportVisitor fará sentido para quem conhece o padrão <a href="https://refactoring.guru/design-patterns/visitor">Visitor</a>.</p><p>Utilize também nomes de problemas de domínio, os programadores que não forem familiarizados podem consultar os experts de domínio sobre seu significado.</p><h3>Funções</h3><p>Neste capítulo existem vários exemplos de métodos que foram refatorados aplicando as técnicas mencionadas, e que nos ajuda a identificar quais erros foram cometidos e como melhorá-los. Abaixo está listada algumas dessas regras que irão nos auxiliar a criar funções de acordo com as boas praticas do clean code;</p><ul><li>Funções devem ser pequenas (dificilmente deveriam ter 20 linhas);</li><li>Evite efeitos colaterais, faça apenas uma coisa, e a faça bem;</li><li>O número ideal de argumentos de uma função deve variar de 0~3, você pode reduzir esse numero passando objetos como parâmetro;</li><li>Evite passar argumentos booleanos para um método, pois da a entender que ele terá mais de uma responsabilidade (case true or false);</li><li>Don’t repeat yourself <strong>(DRY)</strong> elimine código duplicado;</li><li>Uma função deveria ter <strong>somente um ponto de saída</strong>, evite utilizar em pequenas funções break continue ou goto ;</li><li>Não retorne <a href="https://martinfowler.com/eaaCatalog/specialCase.html">nulo</a>, e não passe nulo como parâmetro;</li><li>Se seu método retorna códigos de erro, prefira exceções ao invés e separe os blocos de try catch, veja abaixo o exemplo extraído do livro;</li></ul><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/27d7b287f51d79c10ff97004b2cfec16/href">https://medium.com/media/27d7b287f51d79c10ff97004b2cfec16/href</a></iframe><p>Não espere que você vai escrever o código dos sonhos de primeira, ao criar um método provavelmente o nome vai estar sem muito significado, e o código vai estar funcional mas cheio de responsabilidade. A ideia é que quando testado, voltemos ao código para refinarmos.</p><h3>Comentários</h3><blockquote>Explique-se através de código!</blockquote><p>Em resumo, não utilize comentários quando você pode se expressar através de um bom nome para uma variável ou função. Os comentários muitas vezes podem ser encarados como a necessidade de expressar algo que pode não ter ficado claro no código (o que já sugere que uma falha). O autor menciona também que não existe a preocupação muitas vezes na manutenção do comentário como é feita no código. Portanto, evite comentários desnecessários, ou redundantes.</p><h3>Formatação</h3><blockquote>“Each line represents an expression or a clause, and each group of lines represents a complete thought. Those thoughts should be separated with blank lines.”</blockquote><p>Vamos falar também sobre tamanho de arquivos horizontalmente e verticalmente? Sim, existem pessoas que não se importam em dar scroll lateral ao infinito e além antes de dar uma quebra de linha, e sim amigos… a recomendação e que evitemos ultrapassar os 120 caracteres horizontalmente e não mais do que 500 verticalmente. Lembre-se que o monitor do seu coleguinha pode não ser tão grande quanto o seu!</p><p>Obviamente são sugestões, mas normalmente as rules (regras) de formatação são decididas em conjunto com o time e totalmente configuráveis na IDE ou editor.</p><h3>Testes Unitários</h3><p>Os testes unitários são <strong>indispensáveis </strong>e devem fazer parte da rotina do desenvolvimento, isso já devemos ter em mente! <strong>O mais importante é não deixar de testar seu código e garantir sua cobertura.</strong></p><p>Não esqueça que as boas práticas valem para todo desenvolvimento, inclusive dos testes. Segundo o autor, a <strong>legibilidade </strong>dos testes é um dos principais fatores!</p><p>O que faz um teste ser legível? A mesma coisa que faz um código legível: <em>Claridade, simplicidade e densidade de expressão (diga muito com o mínimo de expressões possíveis)</em>.</p><p>Pensando na legibilidade dos testes, aproveito para indicar a <a href="https://github.com/8T4/gwtdo">biblioteca </a>do colega <a href="https://medium.com/u/8d025f608675">Yan Justino</a> baseado no estilo <a href="https://martinfowler.com/bliki/GivenWhenThen.html">Given-When-Then</a>.</p><p>Não posso deixar de comentar sobre o acrônimo <strong>F.I.R.S.T, </strong>basicamente são 5 regras para clean tests;</p><ul><li><strong>F </strong>(fast) — Testes devem ser rápidos para execução;</li><li><strong>I </strong>(independent) — Testes não podem depender uns dos outros;</li><li><strong>R</strong> (repeatable) — Testes devem ser repetíveis em qualquer ambiente;</li><li><strong>S</strong> (self-validation) — Testes devem ter uma saída booleana, seja sucesso ou falha;</li><li><strong>T</strong> (timely) — Testes devem ser escritos em tempo hábil, antes do código de produção;</li></ul><p>Nos primeiros capítulos do livro o autor descreve sobre o quão difícil é aplicar o código limpo no nosso dia dia de desenvolvimento, e super concordo! Não é atoa que em nossos reviews de código sempre temos algo a sugerir e sempre recebemos sugestões de colegas, mas o trecho que gostaria de destacar do livro sobre esse assunto está logo abaixo, em um resumo que traduzi das partes que achei mais importantes;</p><blockquote>Aprender a escrever código limpo é um trabalho duro, requer muito mais que conhecimento de princípios e padrões. Você precisa praticar e se ver falhando muitas vezes, assim como vai acompanhar a pratica e falha de outras pessoas. Irá vê-los tropeçar e refazer seus passos, assim como vê-los tomando decisões erradas e o preço que irão pagar por elas.</blockquote><p>Por mais que o ego de algumas pessoas discordem disso, devemos sempre ter em mente que não somos perfeitos e sempre temos algo a aprender. Decisões são tomadas muitas vezes baseadas em contextos, e como sempre dizemos em nossa área “<em>não existe bala de prata</em>”, faz parte de nosso aprendizado errarmos e aprendermos com nossos erros.</p><p>Tentei resumir os principais pontos do livro <em>Clean Code</em> nesse artigo, mas se tiver que apontar um ótimo resumo no próprio livro na minha opinião é o capitulo 17 <em>“Smells and Heuristics”</em> onde o autor faz um compilado de vários code smells com explicações e recomendações.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6d7d2c5b5bce" width="1" height="1" alt=""><hr><p><a href="https://medium.com/xp-inc/compilando-clean-code-6d7d2c5b5bce">Compilando Clean Code</a> was originally published in <a href="https://medium.com/xp-inc">Comunidade XP</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>