<?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 Guilherme Alves Felipe on Medium]]></title>
        <description><![CDATA[Stories by Guilherme Alves Felipe on Medium]]></description>
        <link>https://medium.com/@guifelipe?source=rss-35b1722d30ab------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*wa2T1SMzx2nYr9vCEYQzYA.jpeg</url>
            <title>Stories by Guilherme Alves Felipe on Medium</title>
            <link>https://medium.com/@guifelipe?source=rss-35b1722d30ab------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 07:44:55 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@guifelipe/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[A Chegada do Java 22: Melhorias na Linguagem]]></title>
            <link>https://medium.com/luizalabs/a-chegada-do-java-22-melhorias-na-linguagem-f8031bb98c00?source=rss-35b1722d30ab------2</link>
            <guid isPermaLink="false">https://medium.com/p/f8031bb98c00</guid>
            <category><![CDATA[java]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[tech]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Guilherme Alves Felipe]]></dc:creator>
            <pubDate>Mon, 24 Jun 2024 22:32:34 GMT</pubDate>
            <atom:updated>2025-02-28T13:09:42.913Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tLTwYjNdu5kuMLFrg93ruQ.jpeg" /></figure><p>Lançada no dia 19 de Março de 2024, a versão 22 do Java marca a primeira <em>release</em> não-LTS após a versão 21 e trouxe 12 melhorias, incluindo 7 <em>preview features</em> e 1 <em>incubator</em> <em>feature.</em> Essas features cobrem melhorias na linguagem, APIs, performance e nas ferramentas incluídas na JDK.</p><p>Neste artigo, falaremos especificamente sobre as melhorias feitas na linguagem. Mas antes de falar sobre elas, vamos reforçar alguns pontos sobre JEPs, <em>preview features</em> e as <em>incubator features.</em></p><h3>Java Enhancement Proposals (JEPs)</h3><p>Java Enhancement Proposals (ou JEPs) são documentos oficiais que descrevem propostas de melhorias ou novas funcionalidades para a plataforma Java.</p><p>Elas desempenham um papel crucial na evolução da linguagem, servindo como um meio de comunicação detalhada e formal entre desenvolvedores da plataforma e a comunidade de usuários.</p><p>Cada JEP descreve uma alteração específica, como a introdução de uma nova API, melhorias de performance, mudanças na linguagem Java ou atualizações na JVM (Java Virtual Machine).</p><p>O objetivo delas é fornecer uma descrição clara e detalhada para cada mudança proposta, incluindo a justificativa, especificações técnicas, impactos previstos e planos de implementação.</p><h3>Preview Features e Incubator Features</h3><p>Nas <em>releases</em> do Java temos as <em>Preview</em> <em>features </em>e <em>Incubator features, </em>que<em> </em>são usadas para adicionar e coletar feedbacks sobre novos recursos e APIs antes de integrá-los totalmente à JDK. Mas qual a diferença entre elas?</p><h4>Incubator Features</h4><p>As <em>incubator features</em> (features em incubação) tem o objetivo de disponibilizar aos desenvolvedores APIs e ferramentas que estão em um estágio mais “cru” no processo de desenvolvimento.</p><p>Podendo permanecer nesse estado por um período indeterminado, essas features podem sofrer grandes mudanças até o estágio final e são tratadas como features experimentais.</p><h4>Preview Features</h4><p>As <em>preview features</em> (features em prévia) são <em>features</em> que estão totalmente implementadas e especificadas, mas que ainda não foram totalmente integradas a JDK pois precisam de <em>feedback</em> referente ao seu uso em cenários do mundo real.</p><h4>Ponto de Atenção</h4><p>Vale ressaltar que a quantidade de <em>releases</em> que uma <em>feature</em> pode continuar como <em>incubator</em> ou <em>preview</em> depende de diversos fatores, e ainda existe a chance de que ela possa ser removida em uma versão futura. Portanto, tome cuidado ao usá-las em produção.</p><h3>Lista de JEPs Integradas ao Java 22</h3><p>Apesar de falarmos apenas das melhorias na linguagem neste artigo, segue abaixo a lista de todas as JEPs (<em>Java Enhancement Proposal</em>) que foram integradas a versão 22 da JDK:</p><h4><strong>Melhorias na Linguagem</strong></h4><ul><li><a href="https://openjdk.org/jeps/456">JEP-456: Unnamed Variables &amp; Patterns</a></li><li><a href="https://openjdk.org/jeps/447">[Preview] JEP-447: Statements before super (…)</a></li><li><a href="https://openjdk.org/jeps/459">[2nd Preview] JEP-459: String Templates</a></li><li><a href="https://openjdk.org/jeps/463">[2nd Preview] JEP-463: Implicitly Declared Classes and Instance Main Methods</a></li></ul><h4><strong>Bibliotecas</strong></h4><ul><li><a href="https://openjdk.org/jeps/454">JEP-454: Foreign Function &amp; Memory API</a></li><li><a href="https://openjdk.org/jeps/457">[Preview] JEP-457: Class-File API</a></li><li><a href="https://openjdk.org/jeps/461">[Preview] JEP-461: Stream Gatherers</a></li><li><a href="https://openjdk.org/jeps/462">[2nd Preview] JEP-462: Structured Concurrency</a></li><li><a href="https://openjdk.org/jeps/464">[2nd Preview] JEP-464: Scoped Values</a></li><li><a href="https://openjdk.org/jeps/460">[7th Incubator] JEP-460: Vector API</a></li></ul><h4><strong>Performance</strong></h4><ul><li><a href="https://openjdk.org/jeps/423">JEP-423: Regional Pinning for G1</a></li></ul><h4><strong>Ferramentas</strong></h4><ul><li><a href="https://openjdk.org/jeps/458">JEP-458: Launch Multi-File Source-Code Programs</a></li></ul><h3>Melhorias na Linguagem</h3><p>A seguir, uma explicação mais elaborada e com exemplos retirados das JEPs sobre cada uma das melhorias feitas na linguagem, que contam com <strong>uma <em>feature</em> finalizada</strong> e <strong>três <em>features</em> em <em>preview</em></strong>.</p><h4>Observação</h4><p>Para que você consiga executar os exemplos de <em>preview features</em> é necessário compilar e executar o arquivo utilizando a flag — enable-preview ou habilitar as <em>preview features</em> na sua IDE:</p><pre># Compilar com a flag --enable-preview<br>javac --release 22 --enable-preview Main.java<br><br># Executar com a flag --enable-preview<br>java --enable-preview Main</pre><h3>JEP-456: Unnamed Variables &amp; Patterns</h3><p>Com o objetivo de melhorar a legibilidade do código e reduzir a possibilidade de erros, a <strong>JEP-456</strong> permite o uso do sublinhado (_) para declarar variáveis ou padrões não nomeados.</p><p>Esse novo recurso pode ser utilizado de diversas formas diferentes e afeta a definição de variáveis, inicialização de variáveis em <em>loops</em>, parâmetros de <em>lambdas</em>, blocos <em>catch</em> e <em>try-with-resources</em>, <em>switch cases</em> e também a validação de <em>type patterns</em>.</p><h4><strong>Variáveis Não Nomeadas</strong></h4><p>Sempre que uma variável não nomeada for declarada, é obrigatória a sua inicialização, seja ela uma variável local ou uma variável declarada em <em>try-with-resources</em>.</p><p>É importante notar que uma variável não nomeada não adiciona um nome no escopo, então após a sua inicialização,<strong> a variável não pode ser lida ou alterada</strong>.</p><p>Abaixo, alguns exemplos de como variáveis não inicializadas podem ser utilizadas:</p><pre>// Atribuição de Valores de Variáveis<br><br>var _ = order.addProduct(product);<br>// o retorno de addProduct não é utilizado</pre><pre>// Inicialização de Variáveis em Loops<br><br>for (int i = 0, _ = sideEffect(); i &lt; 10; i++) {<br>  // Código onde o retorno de &#39;sideEffect()&#39; não é utilizado<br>}<br><br>for (Order _ : orders) {<br>    // Código onde o valor de &#39;order&#39; não é utilizado<br>}</pre><pre>// Definição de Parâmetros de Lambdas<br><br>map.computeIfAbsent(key, _-&gt; new ArrayList&lt;&gt;());<br>// Código onde o &#39;index&#39; não é utilizado</pre><pre>// Definição de Parâmetros de Blocos Catch<br><br>try {<br>    // Código que pode lançar exceção<br>} catch (SomeException _) {<br>    // Código onde a exceção não é utilizada<br>}</pre><pre>// Atribuição de Recursos em Blocos Try-With-Resources<br><br>try (var _ = ScopedContext.acquire()) {<br>    // Código onde o retorno de &#39;acquire()&#39; não é utilziado<br>}</pre><h4>Variáveis de Padrão Não Nomeadas</h4><p>Variáveis também podem ser declaradas por <em>type patterns</em> (conhecidas como <em>pattern variables</em>), e esses <em>type patterns</em> também podem acabar declarando variáveis que não são utilizadas. Por exemplo:</p><pre>switch (ball) {<br>    case RedBall   red   -&gt; process(ball);<br>    case BlueBall  blue  -&gt; process(ball);<br>    case GreenBall green -&gt; stopProcessing();<br>}<br>// Variáveis &#39;red&#39;, &#39;blue&#39; e &#39;green&#39; não são utilizadas</pre><p>Agora é possível definir <em>type patterns </em>não nomeados para definir padrões contendo variáveis que não serão utilizadas:</p><pre>switch (ball) {<br>    case RedBall _ -&gt; process(ball);<br>    case BlueBall _ -&gt; process(ball);<br>    case GreenBall _ -&gt; stopProcessing();<br>}<br>// Utilizado o caractere &#39;_&#39; para definir as variáveis não nomeadas</pre><p>Além disso, a declaração de vários padrões em apenas um switch case é suportada. Vale notar que, de acordo com a JEP, um switch case com vários padrões declarados é executado se qualquer um dos padrões for verdadeiro:</p><pre>switch (ball) {<br>    case RedBall _, BlueBall _ -&gt; process(ball);<br>    case GreenBall _ -&gt; stopProcessing();<br>}<br>// O primeiro case foi alterado para definir mais de um padrão</pre><h4>Padrões Não Nomeados na Desconstrução de Records</h4><p>Podemos utilizar <em>type patterns</em> não nomeados na desconstrução de records para substituir componentes na verificação de padrões e extrair apenas as propriedades que serão utilizadas:</p><pre>if (point instanceof ColoredPoint(Point(int x, int y), _)) {<br>    // código que usa &#39;x&#39; e &#39;y&#39;<br>}<br><br>// ou<br><br>if (point instanceof ColoredPoint(_, Color color)) {<br>    // código que utiliza &#39;color&#39;<br>}</pre><p>Outro exemplo utilizando a desconstrução de records com <em>type patterns</em> não nomeados e múltiplas condições num switch case:</p><pre>switch (box) {<br>    case Box(RedBall _), Box(BlueBall _) -&gt; processBox(box);<br>    case Box(GreenBall _) -&gt; stopProcessing();<br>    case Box(var _) -&gt; pickAnotherBox();<br>}</pre><h4>Switch Case Guards</h4><p>Outra adição feita nos switch case<em> </em>foi a possibilidade de declarar um guard para torná-lo ainda mais específico. Vale notar que apenas um guard pode ser definido em um case e que guards governam um case como um todo, ou seja, tanto a condição do case quanto o guard devem ser verdadeiros para que o case seja executado:</p><pre>// considere a existência de uma variável &#39;int x&#39;<br>switch (ball) {<br>    case RedBall _, BlueBall _ when x == 42 -&gt; process(ball);<br>    case GreenBall _ -&gt; stopProcessing();<br>}<br>// O primeiro case tem um guard que verifica se x == 42</pre><p>O mesmo também se aplica para o uso de padrões não nomeados na desconstrução de records:</p><pre>switch (box) {<br>    case Box(RedBall _), Box(BlueBall _) when x == 42 -&gt; processBox(box);<br>    case Box(GreenBall _) -&gt; stopProcessing();<br>    case Box(var _) -&gt; pickAnotherBox();<br>}</pre><p>* Exemplos retirados ou baseados nos exemplos e descrição da JEP-456</p><h3>[Preview] JEP-447: Statements before super (…)</h3><p>Trazendo mais liberdade para adicionar lógica nos construtores, a JEP-447 trás a primeira <em>preview</em> da <em>feature</em> que permite que instruções sejam escritas antes de chamadas a super(...) e this(...), facilitando a validação e a preparação de argumentos sem a necessidade de métodos auxiliares.</p><p>Apesar de algo simples, essa <em>feature</em> afeta não só a forma de trabalhar com herança, mas também a forma que podemos implementar a construção de Records e Enums.</p><h4>Herança e Subclasses</h4><p>Para contornar o comportamento padrão referente à chamadas de super(...) no início de construtores de subclasses, se tornou comum a implementação de métodos auxiliares, o uso de <em>static factories</em> com o auxilio de construtores privados ou até mesmo executar as validações após a chamada do super(...):</p><pre>// Exemplo de método auxiliar para executar validações<br><br>public class PositiveBigInteger extends BigInteger {<br><br>    public PositiveBigInteger(long value) {<br>        super(verifyPositive(value)); // Necessidade de validar o valor do parâmetro value<br>    }<br><br>  // Método auxiliar para validar se o valor é positivo<br>    private static String verifyPositive(long value) {<br>        if (value &lt;= 0) {<br>            throw new IllegalArgumentException(&quot;non-positive value&quot;);<br>        }<br>        return String.valueOf(value);<br>    }<br><br>}</pre><pre>// Static Factory em Conjunto com Construtor Privado<br><br>public class PositiveBigInteger extends BigInteger {<br><br>    private PositiveBigInteger(String value) { // Construtor privado<br>        super(value);<br>    }<br><br>  // Construtor estático para executar validações<br>    public static PositiveBigInteger createPositiveBigInteger(long value) {<br>        if (value &lt;= 0) {<br>            throw new IllegalArgumentException(&quot;non-positive value&quot;);<br>        }<br>        return new PositiveBigInteger(String.valueOf(value));<br>    }<br><br>}</pre><h4>Instruções antes do super(…)</h4><p>Com a entrada da JEP-447 os mesmos exemplos mostrados acima podem ser refatorados da seguinte forma:</p><pre>public class PositiveBigInteger extends BigInteger {<br><br>    public PositiveBigInteger(long value) {<br>        if (value &lt;= 0) { // Validação feita diretamente no construtor da subclasse<br>            throw new IllegalArgumentException(&quot;non-positive value&quot;);<br>        }<br>        super(String.valueOf(value));<br>    }<br> <br>}</pre><h4>Records e Enums</h4><p>Apesar de não ter suporte à herança, records e enums também se beneficiam com essa nova <em>feature</em>, já que agora podemos utilizar instruções antes de chamar um construtor alternativo:</p><pre>public record Email(String local, String domain) {<br><br> public Email(String email) {<br>    Objects.requireNonNull(email);<br>    var parts = email.split(&quot;@&quot;);<br>    if (parts.length != 2) {<br>      throw new IllegalArgumentException(&quot;E-mail is not valid&quot;);<br>    }<br><br>    this(parts[0], parts[1]);<br>  }<br><br>}</pre><p>* Exemplos retirados ou baseados nos exemplos e descrição da JEP-447</p><h3>[2nd Preview] JEP-459: String Templates</h3><p>A JEP-459 trás a segunda <em>preview</em> das String Templates, <em>feature</em> que permite fazer interpolações em <em>strings</em> de uma forma mais legível e segura, tornando possível a combinação de textos e expressões para se obter resultados mais especializados.</p><p>O processamento da interpolação de strings pode ser feito pelos novos processadores de templates STR e FMT , através de um processador de template customizado que pode ser criado através da <strong>API de Processadores de Template</strong>.</p><h4>O Processador de Templates STR</h4><p>STR é um processador de template que realiza interpolação de string substituindo cada expressão incorporada no template pelo valor dessa expressão transformado em texto. Esse processador é capaz de executar operações, cálculos e acessar métodos e propriedades:</p><pre>// Interpolação Simples<br><br>String name = &quot;John&quot;;<br>String text = STR.&quot;Hello, \{name}&quot;;<br>// Hello, John</pre><pre>// Execução de Expressões Aritméticas<br><br>int x = 10;<br>int y = 20;<br>String text = STR.&quot;\{x} + \{y} = \{x + y}&quot;;<br>// &quot;10 + 20 = 30&quot;</pre><pre>// Chamada de Métodos e Acesso a Propriedades<br><br>String offerTypeMessage = STR.&quot;You have a \{getOfferType()} waiting for you!&quot;;<br>// &quot;You have a gift waiting for you!&quot;<br><br>String accessMessage = STR.&quot;Access at \{req.date} \{req.time} from \{req.ipAddress}&quot;;<br>// &quot;Access at 2022-03-25 15:34 from 8.8.8.8&quot;</pre><pre>// Expressões Complexas<br><br>String time = STR.&quot;The time is \{<br>    DateTimeFormatter<br>      .ofPattern(&quot;HH:mm:ss&quot;)<br>      .format(LocalTime.now())<br>} right now&quot;;<br>// &quot;The time is 12:34:56 right now&quot;</pre><pre>// Expressões de Múltiplas Linhas<br><br>String name    = &quot;Joan Smith&quot;;<br>String phone   = &quot;555-123-4567&quot;;<br>String address = &quot;1 Maple Drive, Anytown&quot;;<br>String json = STR.&quot;&quot;&quot;<br>    {<br>        &quot;name&quot;:    &quot;\{name}&quot;,<br>        &quot;phone&quot;:   &quot;\{phone}&quot;,<br>        &quot;address&quot;: &quot;\{address}&quot;<br>    }<br>    &quot;&quot;&quot;;<br>//&quot;&quot;&quot;<br>//{<br>//     &quot;name&quot;:    &quot;Joan Smith&quot;,<br>//     &quot;phone&quot;:   &quot;555-123-4567&quot;,<br>//     &quot;address&quot;: &quot;1 Maple Drive, Anytown&quot;<br>// }<br>// &quot;&quot;&quot;</pre><h4>O Processador de Templates FMT</h4><p>Assim como o processador STR, o processador FMT também consegue executar interpolações de string e tem acesso as mesmas funcionalidades. Além disso, ele consegue executar formatações de acordo com o que foi definido em conjunto com as expressões:</p><pre>// Formatação de valores interpolados<br><br>String table = FMT.&quot;&quot;&quot;<br>    Description     Width    Height     Area<br>    %-12s\{zone[0].name}  %7.2f\{zone[0].width}  %7.2f\{zone[0].height}     %7.2f\{zone[0].area()}<br>    %-12s\{zone[1].name}  %7.2f\{zone[1].width}  %7.2f\{zone[1].height}     %7.2f\{zone[1].area()}<br>    %-12s\{zone[2].name}  %7.2f\{zone[2].width}  %7.2f\{zone[2].height}     %7.2f\{zone[2].area()}<br>    \{&quot; &quot;.repeat(28)} Total %7.2f\{zone[0].area() + zone[1].area() + zone[2].area()}<br>    &quot;&quot;&quot;;<br>//  &quot;&quot;&quot;<br>// Description     Width    Height     Area<br>// Alfa            17.80    31.40      558.92<br>// Bravo            9.60    12.40      119.04<br>// Charlie          7.10    11.23       79.73<br>//                              Total  757.69<br>// &quot;&quot;&quot;</pre><h4>API de Processadores de Template</h4><p>Agora também é possível criar processadores de templates customizados com a utilização da API de Processadores de Template. Abaixo, um exemplo de como criar um processador de template que processa a interpolação de uma string e retorna um JSONObject:</p><pre>// Processador de Template com retorno customizado<br><br>var JSON = StringTemplate.Processor.of(<br>  (StringTemplate st) -&gt; new JSONObject(st.interpolate())<br>);<br><br>String name    = &quot;Joan Smith&quot;;<br>String phone   = &quot;555-123-4567&quot;;<br>String address = &quot;1 Maple Drive, Anytown&quot;;<br>JSONObject jsonObject = JSON.&quot;&quot;&quot;<br>{<br>    &quot;name&quot;:    &quot;\{name}&quot;,<br>    &quot;phone&quot;:   &quot;\{phone}&quot;,<br>    &quot;address&quot;: &quot;\{address}&quot;<br>};<br>&quot;&quot;&quot;;</pre><p>* Exemplos retirados ou baseados nos exemplos e descrição da JEP-459</p><h3>[2nd Preview] JEP-463: Implicitly Declared Classes and Instance Main Methods</h3><p>A JEP-463 traz a segunda <em>preview</em> da <em>feature</em> de Classes e Métodos Main Declarados Implicitamente, que tem o objetivo de evoluir a linguagem Java para que estudantes possam criar seus primeiros programas sem a necessidade de entender recursos mais complexos da linguagem.</p><p>Com essa <em>feature</em>, agora se torna possível implementar programas mais básicos de forma simples e introduzir conceitos e recursos mais avançados de forma gradual.</p><h4>Método main() Simplificado</h4><p>Agora, é possível implementar o método main() como um método de instância, sem a necessidade do modificador de visibilidade, de ser estático ou de receber argumentos:</p><pre>class HelloWorld {<br><br>    void main() {<br>        System.out.println(&quot;Hello, World!&quot;);<br>    }<br><br>}</pre><h4>Classe Implicitamente Declarada</h4><p>Para simplificar ainda mais, o compilador agora trata o método main() como parte de uma classe implicitamente declarada, permitindo declará-lo sem a necessidade de especificar uma classe de forma explícita:</p><pre>void main() {<br>    System.out.println(&quot;Hello, World!&quot;);<br>}</pre><p>Métodos e variáveis também podem ser criados dentro da classe implicitamente declarada:</p><pre>String greetingMessage = &quot;Hello, World!&quot;;<br><br>String greetingMethod() { <br>  return &quot;Hello, World!&quot;;<br>}<br><br>void main() {<br>    System.out.println(greetingMessage);<br>    System.out.println(greetingMethod());<br>}</pre><p>* Exemplos retirados ou baseados nos exemplos e descrição da JEP-463</p><h3>Conclusão</h3><p>O Java 22 traz várias melhorias que visam tornar a linguagem ainda mais eficiente, expressiva e acessível.</p><p>As variáveis e padrões não nomeados e os <em>templates</em> de <em>string </em>dão<em> </em>ao código uma maior legibilidade e expressividade. E a possibilidade de declarar métodos e atributos sem a necessidade de ter todo um entendimento sobre orientação a objetos torna a linguagem mais acessível para iniciantes.</p><p>Mas mesmo assim, é importante lembrar que muitas dessas features ainda estão em <em>preview</em> e podem sofrer alterações em versões futuras. Então tome cuidado ao utilizá-las em seus projetos.</p><h3>Referências</h3><p><a href="https://blogs.oracle.com/java/post/the-arrival-of-java-22"></a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f8031bb98c00" width="1" height="1" alt=""><hr><p><a href="https://medium.com/luizalabs/a-chegada-do-java-22-melhorias-na-linguagem-f8031bb98c00">A Chegada do Java 22: Melhorias na Linguagem</a> was originally published in <a href="https://medium.com/luizalabs">luizalabs</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Design Docs: a importância da documentação técnica no desenvolvimento de software]]></title>
            <link>https://medium.com/inside-picpay/design-docs-a-import%C3%A2ncia-da-documenta%C3%A7%C3%A3o-t%C3%A9cnica-no-desenvolvimento-de-software-30f75686ab7e?source=rss-35b1722d30ab------2</link>
            <guid isPermaLink="false">https://medium.com/p/30f75686ab7e</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[tech]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[picpay]]></category>
            <dc:creator><![CDATA[Guilherme Alves Felipe]]></dc:creator>
            <pubDate>Thu, 16 May 2024 18:44:49 GMT</pubDate>
            <atom:updated>2024-05-16T18:44:49.305Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_CnpvXu0CWDo-oonWORVEQ.png" /></figure><p>Já se perguntou sobre quantos projetos você já teve que decifrar e interpretar para tentar entender o que algo faz, quais são as integrações existentes e, o principal, essa foi realmente a melhor alternativa? No pior dos cenários, nem mesmo a própria equipe sabe sobre os detalhes.</p><p>Negligenciar a documentação de features segue sendo um problema comum atualmente, o que gera mal-entendidos, falta de alinhamento entre os membros da equipe e, consequentemente, retrabalho.</p><p>A necessidade de aumentar a visibilidade sobre a implementação de soluções se torna cada vez mais essencial, seja para desenvolvedores, que precisam entender como as soluções se encaixam no quadro geral, ou especialistas em negócio, que precisam ter visão sobre se o que será implementado realmente atende o que foi pedido e a complexidade envolvida.</p><p>O Design Doc existe para auxiliar nessa tarefa. É um documento contendo detalhes sobre o objetivo, motivações, estratégias e trade-offs e outros pontos sobre a implementação de uma solução.</p><p>Para entender melhor sobre como o Design Doc auxilia na tarefa de trazer visibilidade para as pessoas envolvidas, temos que entender como funciona o seu ciclo de vida.</p><h3>Ciclo de Vida de um Design Doc</h3><p>O ciclo de vida de um Design Doc é um processo contínuo e dinâmico, que envolve iteração entre escrita, revisão e ajustes. Esse ciclo só muda após a solução seguir para produção, onde passamos a fazer a manutenção do arquivo sempre que algum ajuste for implementado na solução.</p><h4>Criação e Interação inicial</h4><p>O documento é criado e os tópicos essenciais são preenchidos. É recomendado envolver toda a equipe que trabalhará na solução e as pessoas com conhecimento sobre o tema no início do processo. O ideal é que todos contribuam com dúvidas e sugestões até a conclusão da primeira versão do documento.</p><h4>Revisão e Melhorias</h4><p>O documento criado é compartilhado com os interessados (ou também com pessoas que podem não ter conhecimento sobre o assunto, como outras equipes da mesma tribo, por exemplo). Nessa fase, é encorajado que todas as pessoas cientes sobre a documentação possam dar sugestões, desde que faça sentido, que melhore as explicações dadas no documento ou até mesmo sugerir uma solução diferente.</p><p>O processo de revisão pode envolver várias rodadas e é concluído quando a equipe e os envolvidos entendem que todas as dúvidas foram resolvidas e os detalhes pertinentes foram bem descritos.</p><h4>Implementação e Iteração</h4><p>Com base no objetivo, fluxos, payloads, integrações e no plano de implementação documentados, a equipe pode começar a dividir tarefas, refinar detalhes e dar início a implementação, sempre seguindo o que foi documentado e revisado.</p><p>Como sempre há a possibilidade de mudança de requisitos, detalhes e outros pontos. É recomendável que o documento seja atualizado de acordo com esses novos detalhes e revisado novamente, pelo menos até que a feature ou serviço sejam publicados em produção.</p><h4>Manutenção</h4><p>Com o passar do tempo, correções e melhorias podem na solução podem tornar o documento não condizente com a implementação atual. Portanto, é recomendado que tanto o autor do documento quanto a equipe responsável revisitem e atualizem o conteúdo, se necessário.</p><p>Vale a pena notar que, mesmo que não seja possível manter o documento atualizado, ele ainda é de extrema importância. Isso se deve ao fato de que ele ajuda a entender como a solução foi concebida, levando em conta as motivações e trade-offs no momento de sua criação.</p><h3>O que escrever em um Design Doc</h3><p>Abaixo estão alguns tópicos que podem auxiliar na elaboração de um documento bem estruturado e com detalhes relevantes. Vale ressaltar que, dependendo da solução, nem todos os tópicos são necessários.</p><p><strong>Contexto</strong>: visão geral das motivações para o novo desenvolvimento, o que precisa ser desenvolvido e o impacto resultante do desenvolvimento;</p><p><strong>Fora de escopo</strong>: quais pontos não estão inclusos no escopo da solução, a fim de deixar claro que algo específico não será desenvolvido;</p><p><strong>Solução atual</strong>: fluxogramas da solução existente e descrição dos problemas que devem ser resolvidos com a nova solução;</p><p><strong>Proposta de solução</strong>: sub-tópicos descrevendo com detalhes a proposta de solução para o problema apresentado, como:</p><ul><li><strong>Visão geral</strong>: descrição e desenho da nova solução. É recomendado utilizar alguma ferramenta que possibilite a alterações de forma fácil;</li><li><strong>Novos recursos</strong>: novos recursos a serem criados. Como exemplo, podemos descrever novos serviços, APIs, filas, tópicos. Utilize tabelas contendo o nome, descrição e tecnologias utilizadas nos novos recursos;</li><li><strong>Fluxos e diagramas</strong>: diagramas de sequência, fluxo, ou qualquer outro que ajude a descrever features, integrações e interações. É recomendado utilizar alguma ferramenta que possibilite a alterações de forma fácil, como o <a href="https://mermaid.js.org/">Mermaid</a>;</li><li><strong>Payloads e integrações</strong>: alterações em payloads existentes e criação de novos payloads de API, mensagens, etc. É recomendado utilizar o formato JSON ou até mesmo o mapeamento de classes para facilitar o entendimento;</li><li><strong>Alternativas consideradas</strong>: soluções, fluxos e decisões que foram consideradas e os motivos pelo qual acabaram não entrando na proposta de solução final;</li></ul><p><strong>Monitoramento e alertas</strong>: o que precisa ser monitorado, métricas da aplicação e os alertas a serem criados. Anexar dashboards existentes e canais de comunicação para a notificação de alertas;</p><p><strong>Segurança da Informação</strong>: autenticações, permissões e credenciais necessárias, detalhes sobre mascaramento de dados, e informações referentes a segurança dos dados e integrações;</p><p><strong>Preocupações gerais</strong>: perguntas ou tópicos em aberto que possam impactar o desenvolvimento da solução proposta;</p><p><strong>Plano de implementação</strong>: sugestão de quebra de tarefas de forma sequencial, até o deploy total da solução proposta;</p><p><strong>Equipes envolvidas</strong>: quais equipes estão envolvidas no desenvolvimento da proposta de solução, seja por conta de implementações ou simplesmente por serem impactadas;</p><p><strong>Referências</strong>: páginas, documentos, tarefas e links que serviram de referência para o desenvolvimento do documento;</p><p>Você também pode consultar outros exemplos de Design Docs na biblioteca do designdocs.dev: <a href="https://www.designdocs.dev/library">https://www.designdocs.dev/library</a></p><h3>Quando criar um Design Doc?</h3><p>Nem sempre é necessária a criação de um Design Doc. Tarefas de baixa complexidade ou impacto normalmente não se beneficiam com a criação desse tipo de documento.</p><p>O ideal é que a equipe entenda e defina se a tarefa é complexa o suficiente ou pode trazer um impacto considerável nas soluções existentes para justificar o tempo a ser investido na criação e revisão do documento.</p><p>Além disso, é interessante criar um Design Doc sempre que uma nova feature for implementada (por mais simples que seja), para que exista uma referência sobre as motivações e decisões tomadas para a sua criação.</p><p>Também vale notar que apesar de um Design Doc ter a possibilidade de ser composto de diversos tópicos e detalhes, a criação de uma versão simplificada do documento para soluções mais simples é igualmente útil.</p><h3>Conclusão</h3><p>Ter visibilidade e detalhes sobre o desenvolvimento de soluções é indiscutível necessário, especialmente para empresas que contam com muitos desenvolvedores.</p><p>O Design Doc permite que equipes alinhem suas ideias e estratégias, facilitando a comunicação e colaboração na criação de softwares de qualidade. Além disso, atua como uma fonte de referência crucial para a implementação, monitoramento e manutenção futuros do projeto.</p><p>Apesar de parecer algo burocrático, dedicar tempo e esforço para elaborar um Design Doc detalhado e cuidadoso é um investimento que traz retornos significativos para a qualidade e eficiência das soluções produzidas.</p><h3>Referências</h3><ul><li>Design Docs at Google: <a href="https://www.industrialempathy.com/posts/design-docs-at-google/">https://www.industrialempathy.com/posts/design-docs-at-google/</a></li><li>DesignDocs.dev: <a href="https://www.designdocs.dev/">https://www.designdocs.dev/</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=30f75686ab7e" width="1" height="1" alt=""><hr><p><a href="https://medium.com/inside-picpay/design-docs-a-import%C3%A2ncia-da-documenta%C3%A7%C3%A3o-t%C3%A9cnica-no-desenvolvimento-de-software-30f75686ab7e">Design Docs: a importância da documentação técnica no desenvolvimento de software</a> was originally published in <a href="https://medium.com/inside-picpay">Inside PicPay</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>