carlos schults / blog

Suas Mensagens de Commit São Um Lixo. Vou Te Ajudar a Melhorar

Tue, 31 Mar 2026 00:00:00 +0000

Suas mensagens de commit são um lixo. Na melhor das hipóteses, elas são inúteis. Mas geralmente, elas são piores do que nada. Eu não digo isso pra ser babaca. Na verdade, é o contrário. Eu quero te ajudar.

Se você sabe que você é exceção pra isso, você pode parar de ler. É sério, fecha a aba e vai pro YouTube. Pronto, te dei alguns minutos de volta, de nada.

Se você ainda tá aqui, então você sabe que tem um problema. Como eu dizia, suas mensagens de commit não servem pra nada. Não fique ofendido. Isso não é culpa só sua. É bem provável que ninguém nunca te ensinou como escrever boas mensagens de commit, ou nem o porquê disso ser importante. E escrever é realmente muito difícil.

A boa notícia é que agora você finalmente tem alguém pra te ajudar. Nesse post, eu vou explicar tudo que você precisa saber sobre mensagens de commit horríveis, e o que fazer pra escrever as que não são horríveis.

Suas Mensagens de Commit São um Lixo Porque…

Por que a maioria das mensagens de commit é tão ruim? Na minha experiência, os motivos se resumem ao que vou falar agora. Vale lembrar que não tem nada de científico ou baseado em dados aqui. É tudo baseado na minha experiência pessoal.

…Você Só Liga pra Código

Se você é como a maioria dos devs, você só — ou quase só — liga pra codar. É onde a diversão mora, e tudo o mais você vê como perda de tempo. Eu sei também que você provavelmente está sob muita pressão pra performar, pra entregar o máximo de valor o mais rápido possível. Então o que você mais quer é terminar o que está fazendo, mergar o PR e então pegar outro ticket do Jira/Azure/Linear pra começar a implementar.

O que acaba acontecendo é que tudo que não é código é tratado como detalhe secundário e não recebe a devida atenção. Isso inclui testes, documentação, preparar uma revisão da feature implementada pra retrospectiva semanal e, claro, escrever mensagens de commit e descrições de PR.

…Às Vezes Você Não Entende o Que Está Fazendo

Boas mensagens de commit — e boa documentação em geral — devem focar no porquê das coisas. Qual é a motivação por trás das suas mudanças? Qual é o problema que você está tentando resolver, por que vale a pena resolvê-lo, de que forma isso ajuda seu time e sua empresa?

Pode parecer loucura que um programador comece a trabalhar numa tarefa que não entende completamente. Mas eu já fiz isso, e aposto que você também. E claro, como você vai explicar o porquê de uma mudança se nem você mesmo entende direito?

…Escrever é Difícil

Como Phil Karlton disse uma vez, só existem duas coisas difíceis em ciência da computação, e dar nome às coisas é uma delas.

Se você parar pra pensar, “dar nome às coisas” é uma forma de escrever. Um subconjunto da escrita, digamos assim. Então sim, escrever mensagens de commit é difícil porque escrever, em geral, é difícil.

…Ninguém Te Ensinou

Acho que a formação de desenvolvedores frequentemente falha em ensinar muita coisa importante que você realmente vai precisar como engenheiro de software. Tratamento de erros de verdade é um exemplo.

Tudo bem, eles vão te ensinar a mecânica de como um try-catch-finally funciona, mas raramente vão te ensinar quando capturar uma exceção, quando não capturar, quando lançar uma exceção, quando logar ou não, e assim por diante.

E escrever mensagens de commit é uma dessas coisas.

…O GitHub Te Ensinou Maus Hábitos

Vamos deixar uma coisa clara: eu uso o GitHub todo dia e gosto muito. O GitHub é o aplicativo matador/killer app do Git, e o Git não teria tido o mesmo nível de adoção sem ele.

Dito isso, acredito que a popularidade do GitHub e dos pull requests fez as pessoas se importarem mais com os PRs do que com os commits individuais. E faz sentido: pull requests suportam discussões que ficam como artefatos históricos do projeto, suportam anexos, texto rico e tudo mais.

Então faz sentido que algumas pessoas não se esforcem muito pra escrever boas mensagens de commit, argumentando que podem escrever descrições ricas no PR.

Claro que o que acaba acontecendo frequentemente é que elas não escrevem as descrições de PR também!

…A Flag `-m` do Git Te Viciou

Acho que a maioria dos programadores nem sabe que mensagens de commit podem ter um corpo com várias linhas. E a culpada aqui é a forma como a maioria das pessoas ensina o comando commit:

git commit -m "Alguma mensagem"

Sem nem mencionar que a flag -m é só uma conveniência pra quando você tem uma mensagem de uma linha, o que deveria ser a exceção, não a regra.

…Você Não Tem Higiene de Commits

Escrever mensagens de commit que não são lixo faz parte de algo mais amplo que algumas pessoas chamam de “higiene de controle de versão.”

É exatamente o que parece: não seja porco na hora de escrever código.

Às vezes você tem dificuldade pra escrever uma mensagem de commit porque trabalha de forma bagunçada. Se suas mudanças são uma salada de correções de bug, refatorações, código morto e ideias de implementação pela metade, claro que você vai ter problema pra escrever uma mensagem descritiva e útil.

Isso costuma ser causado por falta de domínio do Git. Se você não domina ferramentas como stash, reset, rebase interativo e outras, é mais provável que você transforme seu trabalho num caos.

Taxonomia das Mensagens de Commit Ruins

Descobri que mensagens de commit ruins se encaixam em algumas categorias. Vou cobrir algumas delas agora.

A Mensagem de Uma Linha Quase Inútil

Essa é a mensagem de uma linha que dá uma explicação superficial do que foi mudado. Eu chamo de “quase” inútil porque pelo menos o resumo é preciso.

Mas aí ela falha em dar qualquer contexto adicional. Fico com perguntas como:

Qual foi o problema que originou essa mudança?
Por que o autor considerou essa a melhor forma de resolver o problema?
Existe algum issue ou ticket associado a esse trabalho?

Alguns exemplos, com meus comentários:

Added new index to table # que índice? que tabela? com qual propósito?
Enable EF Core execution strategy # o que é essa tal "strategy"? por que você teve que habilitar?
Added Required attribute to model # qual model? isso não é uma breaking change que vai afetar os usuários atuais?

A Mensagem de Uma Linha Inútil

A mensagem de uma linha inútil é… bem, como a quase inútil, mas completamente inútil.

Os exemplos não precisam de mais comentários:

changes
ui
not working
more changes

Quer dizer, no momento em que você escreve “changes” como mensagem de commit, você poderia simplesmente escrever “batata”. Ou contar uma piada. Seria igualmente inútil, mas pelo menos poderia ter graça.

Só a Referência do Sistema de Tickets

É quando as pessoas colocam apenas o id de um issue/ticket/card do sistema de gerenciamento, e nada mais. Alguns exemplos:

JIRA-42
AZ-2234
#125

Acho que essa categoria consegue ser ao mesmo tempo mais útil e mais irritante do que as anteriores. Sim, é mais útil, já que posso sempre ir ao sistema de tickets, procurar o issue, e aprender mais sobre o trabalho. Claro, nada garante que o commit vai conter apenas mudanças relacionadas ao issue em questão, mas isso é conversa pra outro momento.

É mais irritante também porque obriga o leitor a parar e ir a outro lugar pra entender o contexto daquela mudança. Não sei você, mas eu prefiro aprender o motivo por trás de um commit pelo próprio commit, como ~~Deus~~Linus quis.

Além do incômodo, existe um risco maior aqui: a possibilidade de que, um dia, sua empresa migre do sistema de tickets atual e você fique sem aquelas descrições. Todas as empresas em que trabalhei como desenvolvedor fizeram pelo menos uma migração dessas, e tenho certeza que você já passou por pelo menos uma também.

A Mensagem de Uma Linha Enganosa

Às vezes você tem uma mensagem que parece inofensiva, como Add PrintHtmlOutput() method. Aí você vai ver as mudanças e elas também incluem uma breaking change em um endpoint ou alteram a forma como a aplicação interage com o banco de dados.

Você Vai Escrever Boas Mensagens de Commit Quando…

Agora você entende por que escreve mensagens ruins, e como elas são ruins. Pronto pra aprender a melhorar?

…Escrever Suas Mensagens Em Inglês

Um dos posts mais visitados desse blog discute se devemos escrever código em português ou inglês. Eu considero que fiz bons argumentos, mostrando os prós e constras de ambos os lados e deixando meu posicionamento bem claro.

Ainda assim, alguns leitores me acusaram de ficar em cima do muro.

Dessa vez, então, vou falar sem sombra de dúvida: ESCREVA SUAS MENSAGENS DE COMMIT EM INGLÊS. É simplesmente o padrão do mercado, e o quanto antes você se acostumar com isso, melhor.

E é por isso, inclusive, que os exemplos de mensagem de commit deste post estão todos em inglês. Eu escrevi o post originalmente em inglês e agora estou traduzindo para português, mas deixei as mensagens em inglês de propósito mesmo, por causa desse ponto.

…Parar de Escrever Mensagens de Uma Linha

Mensagens de uma linha são ótimas quando o escopo da mudança é pequeno. Se o seu commit só corrige um typo, então Fix typo é uma mensagem de commit válida. Mas na maioria das vezes os commits contêm muito mais mudanças, e nesses casos escrever uma mensagem de uma linha é uma oportunidade perdida de criar uma documentação duradoura.

Então, por favor, pare de usar a flag -m na hora de commitar. Escreva um corpo adequado com mais detalhes na maioria das suas mensagens.

…Começar pelo “O Quê”, Expandir com o “Por Quê” e o “Como”

Agora você sabe que deve escrever um resumo e um corpo na maioria das suas mensagens de commit. O que colocar em cada um?

Simples: comece com o resumo, descrevendo o que você fez. Seja descritivo, mas conciso.

No corpo, descreva qual é o problema que você está tentando resolver, ou o motivo que motivou a mudança. Em seguida, explique como você resolveu, mas de forma macro. Não entre em muito detalhe, porque lembre-se que seu leitor sempre pode ver o diff.

Se necessário, adicione mais informações, como:

trade-offs envolvidos na sua decisão
alternativas que você considerou mas decidiu não usar
links de referência para termos que possam ser desconhecidos (por exemplo, um link para um artigo da Wikipedia, ou para o Catálogo de Refatorações do Martin Fowler)
links de referência para a solução que você aplicou (por exemplo, um link para uma resposta no Stack Overflow)

…Seguir a Regra do 50/72

A regra do 50/72 é o mais próximo que temos de um padrão quando se trata de mensagens de commit. Foi proposta pela primeira vez por Tim Pope e funciona assim:

Comece com um resumo, com a primeira letra maiúscula, com no máximo 50 caracteres
Adicione uma linha em branco
Em seguida, adicione um corpo, quebrando as linhas em no máximo 72 caracteres

Esses limites podem parecer arbitrários, mas existem razões históricas pra eles terem sido escolhidos. Pra resumir, eles funcionam bem com muitas ferramentas diferentes que trabalham com mensagens de commit.

Outro ponto importante: você deve escrever o resumo no modo imperativo. Ou seja, “Implement password hashing” em vez de “Implemented password hashing”, por exemplo. A princípio isso pode parecer estranho, mas é o padrão que o próprio Git usa. Se não acreditar, use git revert pra reverter um commit e vai ver que a mensagem gerada está no modo imperativo:

Revert "Add line of text"

This reverts commit 5ab08c5d3ee7bfdb334406d418d96f76d08962fe.

Viu? “Revert” em vez de “Reverted.”

Adicionalmente, e de forma opcional, você pode adicionar um trailer ao commit. Trailers são metadados que você pode adicionar no final da mensagem de commit, seguindo a sintaxe Nome: valor. Eles servem pra adicionar metadados úteis, como quem aprovou uma mudança, quem co-autorou algo com você, e também pra associar seu commit a um issue ou ticket.

Por exemplo, se você usa GitHub Issues, você pode adicionar um trailer assim:

Closes: #456

E ele vai automaticamente associar o commit ao issue e fechá-lo. Existem outras palavras-chave que você pode usar, como Fixes, Resolves, Resolved, e assim por diante. Você pode aprender mais sobre como fechar issues do GitHub automaticamente aqui.

…Adotar Commits Atômicos

A ideia dos commits atômicos é simples: um commit deve conter apenas mudanças logicamente relacionadas. É o oposto da falta de higiene de controle de versão que mencionei antes.

Digamos que você está trabalhando numa feature. Aí seu chefe te pede pra parar e corrigir um bug. Você vai lá e corrige o bug, e agora tem aquelas mudanças misturadas com as do início da sua implementação de feature.

Não commita tudo junto! Commita apenas as mudanças do bug fix como uma unidade coesa, com uma mensagem descritiva e de qualidade. Aí você volta pra sua feature e commita aquilo.

Fazer isso exige que você domine as ferramentas do Git. Você precisa saber como fazer stage das mudanças e commitar apenas aquelas em vez de tudo. Precisa saber usar o stash. Com frequência, vai precisar saber como commitar coisas e depois editar esse histórico.

Essas habilidades valem a pena ter. Vai atrás delas!

…Commitar Sempre, Polir Depois

Você não precisa esperar estar “pronto” pra commitar. Pelo contrário, você deve commitar o tempo todo. Trabalhe em incrementos pequenos e commite ao longo do caminho.

Assim, se cometer erros e precisar descartar algum trabalho, você vai reverter apenas alguns minutos de trabalho em vez de horas. Você também tem esses checkpoints pra voltar caso a luz caia ou algo do tipo.

Por exemplo, quem pratica TDD (desenvolvimento orientado a testes) frequentemente commita toda vez que chega na fase verde. Ou seja, toda vez que os testes passam.

Também é uma boa ideia manter todos os seus commits limpos. Com isso quero dizer que todos os seus commits, quando aplicados, devem deixar o projeto em um estado onde ele builda com sucesso e todos os testes passam. Isso facilita para você ou outra pessoa usar o git bisect no futuro pra encontrar onde um bug foi introduzido.

Mas se você seguir essa dica, pode acabar com muitos commits pequeninhos que não têm boas mensagens, ou que não representam um conjunto coeso de mudanças. Como resolver isso?

A resposta é: você edita seu histórico pra deixá-lo bonito. Editar o histórico é mal visto — e com razão — quando é uma branch da qual outras pessoas já dependem. Mas se você está trabalhando na sua própria branch isolada e ninguém depende das suas mudanças, você pode fazer o que quiser até aquele ponto. Então commite cedo e com frequência, e depois use amend e rebase até ter um histórico que faça sentido e tenha ótimas mensagens de commit.

Exemplos de Boas Mensagens de Commit

Finalmente chegou a hora de mostrar alguns exemplos de mensagens de commit valiosas que incorporam tudo que cobrimos até aqui.

Por exemplo, em vez de:

Added Required attribute to model

Escreva:

Make PhoneNumber required on /reservations endpoint

The /reservations endpoint originally didn't require a phone number.
The reservations were being accepted but, as data flowed to downstream
systems, the lack of phone number was causing some processes to crash.

We are now adding the [Required] attribute to the PhoneNumber property
on the ReservationRequestModel. This is a breaking change, so that's
why, as part of this changes, we are versioning the endpoint as 2.0

Fixes: AB#456

Veja como fica:

A mensagem começa com um resumo que descreve o que foi feito
O corpo começa com uma descrição do problema, depois explica como a mudança atual o resolve
Por fim, temos um trailer para associar e fechar um ticket no board

Para o segundo exemplo, vamos fazer algo um pouco mais elaborado. Em vez de Enable EF Core execution strategy, você pode usar:

Enable EF Core execution strategy for Azure SQL

After migrating to Azure SQL, save operations started failing
intermittently in production with transient connection errors.
Azure SQL occasionally drops connections during scaling events
and failovers, and Entity Framework does not retry failed
operations by default.

Enabled the built-in SQL Server execution strategy in EF Core,
which automatically retries failed operations using exponential
backoff when a transient error is detected.

An execution strategy is a configurable EF Core component that
intercepts database operations and decides whether to retry
them on failure. The SQL Server provider ships with a strategy
that knows which error codes Azure SQL considers transient.

[1]: https://learn.microsoft.com/en-us/ef/core/miscellaneous/connection-resiliency

Closes: #89

Todas as mensagens precisam ter esse nível de profundidade? Claro que não. Por exemplo, Fix typo é uma ótima mensagem de commit, se tudo que você está fazendo naquele commit é corrigir um typo. O mesmo vale para Remove commented-out code, Remove blank lines, e assim por diante. O tamanho da sua mensagem de commit precisa ser diretamente proporcional ao tamanho e escopo da sua mudança.

A IA Muda Tudo. Ou…Será Que Não?

Eu sei o que você ficou se perguntando durante todo esse tempo. “Mas…mas…mas…e o ChatGPT?”

Minha opinião sincera é que a IA muda pouco, ou nada, do que discutimos até aqui.

Pra começar, com IA ou sem IA, os fundamentos continuam os mesmos:

Boas mensagens de commit ainda devem focar mais no porquê do que no quê e no como.
A regra do 50/72 ainda é uma boa diretriz a seguir.
Usar o modo imperativo nos resumos continua sendo o padrão para muitas ferramentas, incluindo o próprio Git e o GitHub.
Boas mensagens de commit ainda têm imenso valor para leitores futuros, que podem incluir a própria IA.

Mas a IA é ótima pra escrever mensagens de commit. Por que eu deveria me preocupar?

Quando se trata de mensagens de commit, a IA é de fato ótima em uma coisa. E essa coisa é resumir um conjunto de mudanças e escrever, de forma muito bem escrita, gramaticalmente correta, com tom profissional… uma listagem detalhada de todas as mudanças.

Que é exatamente o que você não deveria estar fazendo! Onde a IA falha é exatamente na parte mais importante, que a esta altura você já deve estar cansado de ler: o porquê.

Não estou dizendo que você não deve usar IA pra te ajudar a criar mensagens de commit. Claro que pode. Eu uso bastante. Este é um exemplo de prompt que uso frequentemente com o Claude, com algumas variações:

Write a concise, well-crafted commit message for the diff I'm going to give you.
Make it more high-level, focusing on the why rather than listing all changes in great detail.
Follow these rules:
- Summary
	- Brief description of what was done
	- 50 chars at the most
	- Use imperative mood
	- Do not use conventional commits
- Body
	- Brief description of the "how", but focus more on the reason for the changes
	- Use prose rather than bullet points.
	- Use past tense
	- Lines no longer than 72 chars

Depois eu rodo git diff | clip e colo o resultado junto com esse prompt.

O que eu recebo de volta é sempre uma mensagem muito bem escrita, muito mais detalhada sobre descrever as mudanças do que eu gostaria, e que perde completamente o ponto do porquê estamos fazendo as mudanças. O que não surpreende nada, porque como diabos ela saberia se eu não contei?

O que faço então é explicar os motivos da mudança. E pedir pra tentar de novo, mais alto nível e incluindo a explicação. Às vezes a segunda versão já está boa o suficiente, mas geralmente preciso de pelo menos três até ficar satisfeito.

Entendeu o padrão? Isso é uma colaboração entre a IA e eu. Estamos trabalhando juntos pra criar uma mensagem. Não estou terceirizando 100% pra IA.

Quando uso o Claude Code, essas regras do prompt acima ficam no arquivo Claude.md do projeto. Nesse cenário, ele tende a ir muito melhor em entender o “porquê”, porque tudo começou com um prompt em que eu expliquei o motivo por trás da mudança, e então fizemos uma sessão de planejamento antes de começar a implementar.

Mas mesmo assim, a IA frequentemente ainda precisa de muita orientação até conseguir escrever uma mensagem de commit que realmente foque nos motivos por trás da mudança e que dê informações no nível certo de abstração. Por conta própria, a IA produz mensagens bem escritas que são essencialmente um diff em prosa.

Conclusão

A essa altura, você provavelmente percebeu que este é um post bem opinionado. Algumas das coisas cobertas aqui estão muito perto de ser um padrão, como a regra do 50/72 e a ideia de escrever resumos no modo imperativo.

Porém, algumas coisas que discuti são preferências pessoais. Por exemplo, eu normalmente não uso Conventional Commits. Os motivos pra isso estão além do escopo deste post, mas existem. São motivos bastante pessoais, então não vou te julgar se você gosta de usar Conventional Commits.

A principal lição que quero que você leve deste post é: coloque trabalho nas suas mensagens de commit. Não escreva qualquer coisa; elabore suas mensagens. Trabalhe nelas, aperfeiçoe-as, até não conseguir mais melhorar.

Sim, é difícil. Pode ser frustrante. Pode parecer uma perda de tempo ficar 10, 15 ou até 20 minutos elaborando uma mensagem que o seu LLM favorito teria gerado em segundos.

Mas eu garanto: anos depois, quando você estiver investigando um incidente crítico em produção e se deparar com ótimas mensagens de commit que oferecem insights valiosos sobre o porquê de algumas mudanças terem sido feitas… você vai ficar feliz por ter feito isso.

Obrigado por ler.

Implementando o git em Go do Zero: Unindo o Útil ao...Agradável?

Mon, 09 Mar 2026 00:00:00 +0000

Recentemente comecei a trabalhar no meu projeto mais novo: construir o git em Go, do zero. Qual é o sentido disso?, você pode estar se perguntando.

Tipo, é um projeto bastante inútil no sentido de que, você sabe, o git existe há 20 anos. (Obrigado, Linus.) Meu objetivo com esse projeto é duplo:

aprender a linguagem Go
aprofundar meu conhecimento sobre os internos do git

Escopo do Projeto

Não pretendo implementar 100% do git. Isso seria muito difícil. O que vou fazer é implementar um subconjunto pequeno de comandos do git, apenas em suas variações mais básicas. Esta é a lista atual do que pretendo implementar:

git init
git add
git status
git commit
git log

Essa lista não é estática. Posso decidir implementar mais comandos, ou menos. Tudo depende de eu decidir que aprendi o suficiente. Vamos ver como isso vai.

Fluxo de Trabalho do Projeto (eu realmente não sabia como chamar essa seção)

Como vou fazer tudo isso, na prática? Já estou fazendo, já que comecei há cerca de uma semana. Então, a forma como estou conduzindo isso é basicamente percorrer essa lista de comandos, implementando um por um, e documentando meus aprendizados neste blog.

Ainda não tenho certeza sobre a cadência das postagens. Sinto que atualizações semanais são demais; já que tenho apenas cerca de 30 a 50 minutos por dia para trabalhar nisso, não quero perder muito tempo escrevendo as atualizações em si.

Então acho que vou começar escrevendo os posts sempre que sentir que acumulei atualizações interessantes o suficiente para compartilhar, e aí compartilho. Pode ser que depois eu estabeleça em uma cadência regular, mas também pode ser que não.

Sobre o Uso de LLMs

Impus algumas regras a mim mesmo para este projeto. A mais importante é que zero linhas de código serão escritas por IA/LLMs. Isso derrotaria o propósito, já que o objetivo é realmente aprender a linguagem.

Isso não significa que não estou usando IA. Estou usando o Claude para me ajudar a planejar o roteiro, por assim dizer. Ele tem me ajudado a decidir a ordem dos comandos que faz mais sentido, quais são os conceitos de Go necessários para construir isso e quais posso pular, e assim por diante.

Para o meu aprendizado de Go em si, estou usando a documentação do Go e a boa e velha busca na web. Como nos velhos tempos.

Construindo o git em Go: A Primeira Atualização

Então, o que fiz até agora? Comecei este projeto na segunda-feira, 2026-03-02. Uma semana atrás no momento em que escrevo. Durante os primeiros três dias, segui o Go Tour para relembrar as poucas coisas que eu sabia sobre a linguagem e aprender mais dos fundamentos.

Na quinta-feira, terminei o tour. Passei pelos conteúdos sobre generics bem rapidamente e pulei completamente os de concorrência. Nesse dia, criei o repositório e escrevi um “Hello World.”

Por algum motivo, não mexi no projeto na sexta-feira. Sábado foi o dia em que implementei de fato meu primeiro comando, e o único implementado até agora: ggt init.

Ah sim, a propósito: meu executável se chamará ggt, porque o próprio projeto se chama go-gitter. Isso é um trocadilho idiota com a expressão em inglês “go-getter”, que se refere a uma pessoa que está sempre em ação, realizando muitas coisas e tal.

Implementar o init foi muito fácil e tenho certeza de que só vai ficar mais difícil a partir de agora. Criar um repositório git é surpreendentemente simples, e é algo que você pode fazer manualmente, sem usar o git em si. Duvida? Ok, vou te ensinar.

Vá a algum lugar no seu computador e crie uma pasta. Entre nessa pasta e crie uma nova chamada .git. Exatamente assim.

Agora, entre em .git e crie um arquivo de texto chamado HEAD. Exatamente assim, sem extensão. Dentro desse arquivo, coloque o seguinte texto e salve:

ref: refs/heads/main

Próximo passo: crie duas novas pastas, objects e refs. Dentro de objects, crie mais duas pastas vazias: info e pack. Dentro de refs, crie heads e tags.

Agora, usando o terminal, vá ao mesmo nível onde a pasta .git está e execute git status. Você verá um resultado assim:

On branch main

No commits yet

nothing to commit (create/copy files and use "git add" to track)

Parabéns! Você acabou de criar um repositório git manualmente. Isso é exatamente o que meu código Go está fazendo.

Acompanhe as Atualizações

As atualizações deste progresso serão rastreadas pela tag go-gitter, então você pode salvar essa página nos favoritos, se quiser. Já vinculei ao repositório, mas aqui está novamente, caso você tenha perdido: go-gitter.

Obrigado pela leitura. Até a próxima atualização.

O Que São Breaking Changes?

Fri, 26 Sep 2025 00:00:00 +0000

Foto por Denis Oliveira no Unsplash

Estou começando uma série de artigos onde vou definir alguns conceitos ou termos que são comuns no desenvolvimento de software, e estou começando com Breaking Changes. Afinal, por que começar com A como uma pessoa normal?

Beleza, mas… por que escrever uma série assim?

Principalmente porque quero criar os recursos que gostaria de ter tido quando estava começando.

Naquela época, me deixava louco quando as pessoas falavam de coisas como se eu já soubesse o que elas significavam.

Olha, eu sou um desenvolvedor ~~velho~~ experiente, o que significa que na minha época eu não tinha um amiguinho de IA pra simplesmente perguntar essas coisas. Sim, o Google já existia, também não sou tão ~~velho~~ experiente assim né, porra.

O problema é que muitas vezes as explicações que você encontrava no Google não eram lá essas coisas. Frequentemente o Stack Overflow ajudava, mas nem sempre. Hoje em dia, claro, você pode perguntar pro seu LLM favorito pra explicar as coisas pra você, se você não se importar com o tom genérico, desprovido de qualquer voz humana autêntica ou anedotas.

Então, estou escrevendo esses artigos pra ajudar os iniciantes por aí a entender um pouco melhor alguns conceitos chave do desenvolvimento de software, um de cada vez, de forma simples e interessante, espero. Tudo cortesia do seu amigo aqui. Vamos começar?

O que é um breaking change?

“Breaking change” significa qualquer mudança que você faz no seu software que pode fazer o código dos seus usuários quebrar, depois que eles fizerem o upgrade. Breaking changes só fazem sentido quando você pensa em software que você cria e de alguma forma distribui para usuários terceiros.

Pense em coisas como:

APIs
bibliotecas/pacotes
frameworks
ferramentas CLI

Vamos ver um exemplo. Enquanto desenvolvia uma aplicação pra sua empresa, você extraiu algumas funcionalidades comuns como uma biblioteca e decidiu publicar isso como um pacote open-source hospedado no https://www.nuget.org.

Depois de um tempo, você publica uma nova versão onde muda o nome de um dos métodos mais importantes e usados dentro do pacote. Os usuários fazem upgrade pra sua versão mais nova e agora o código deles não compila mais, porque ainda se refere ao método usando o nome original. Isso é um breaking change!

ℹ️ NOTA

Importante: pra algo ser um breaking change, não é necessário que 100% dos usuários quebrem quando fazem upgrade. No nosso exemplo, é possível que nem todos os usuários estivessem realmente usando aquele método específico no código deles, o que significa que o código deles não teria quebrado. Mas a mudança ainda é um breaking change, porque o potencial de quebrar está lá.

Exemplos de Breaking Changes

Na prática, que tipos de mudanças são breaking changes?

Eu diria que a mais comum, ou pelo menos o que a maioria das pessoas pensaria como breaking change, seria excluir ou renomear coisas.

Se você renomeia um endpoint de API, uma classe pública ou método do seu pacote, ou um comando do seu CLI, código que usa essas coisas não vai mais funcionar. E, pra todos os efeitos práticos, renomear é a mesma coisa que excluir, porque aquela versão antiga não existe mais.

Cadê o método que estava aqui?

Existem outros tipos de breaking changes, então vamos revisar alguns deles.

Novos Parâmetros Obrigatórios

Se você adiciona novos parâmetros a um método, e eles são obrigatórios, então todo código existente que chama o método vai falhar na compilação. A solução aqui seria adicionar novos parâmetros como opcionais, ou até criar um novo método.

Parâmetros opcionais removidos ou tornados obrigatórios

Essa é uma continuação lógica da anterior. Se você remove um parâmetro opcional, código que chama aquele método passando o parâmetro vai quebrar. Por outro lado, se você torna um parâmetro opcional obrigatório, acontece o oposto: agora todos os lugares que não passam o parâmetro vão quebrar.

Novos Membros Adicionados a Uma Interface

Aqui estou falando especificamente de linguagens estaticamente tipadas que têm o conceito de interface onde você define comportamentos que classes cliente precisam implementar.

Adicionar um novo membro a uma interface é um breaking change porque agora todas as classes que a implementam não teriam implementado o novo membro.

Recentemente, o time do C# resolveu esse problema de uma forma que gerou alguma controvérsia: adicionando a possibilidade de implementar métodos nas próprias interfaces!

Mudou o Tipo de um Parâmetro de Método

Se você muda o tipo de um parâmetro de, digamos, string para int, você está garantindo que muito código cliente vai quebrar.

Mudou o tipo de retorno de um método ou função

Novamente, dependendo dos tipos antigo e novo, isso pode nem quebrar, mas ainda é um breaking change em geral.

Mudou a ordem dos parâmetros

Esse é interessante porque pode quebrar de uma forma diferente dos outros. Para a maioria dos exemplos que eu tenho dado até agora, “quebrar” significa que o código que consome seu código vai falhar na compilação.

Com este, você pode fazer de uma forma que o código ainda compile, mas falhe em funcionar corretamente.

Por exemplo, veja esse código:

public async Task<IReadOnlyList<Product>> GetProductsByCategory(int categoryId, int companyId)
{
// implementação
}

Se você invertesse a ordem entre categoryId e companyId, o código ainda compilaria mas não funcionaria corretamente. Ainda seria um breaking change, mas um que falha de forma mais sutil.

Claro que se os dois parâmetros são de tipos diferentes, então falharia no sentido de falhar na compilação. E é por isso que muita gente argumenta que você não deveria usar primitivos pra coisas como ids, mas criar seus próprios tiny types pra isso.

Comportamento de tratamento de erro modificado (lançando exceções diferentes)

Se o seu método costumava lançar um certo tipo de exceção e agora lança uma diferente, isso é um breaking change, porque código que foi escrito pra capturar aquela primeira exceção específica não vai funcionar pra nova, a menos que ela herde da primeira.

Tornou métodos ou propriedades públicas privadas

Na prática, do pontos de vista do cliente, isso é o mesmo que excluir algo, então é um breaking change óbvio.

Adicionou requisitos de autenticação onde não existiam

Até agora, todos os exemplos foram pra bibliotecas ou pacotes. Agora vamos ver alguns exemplos pra APIs web. O primeiro tem a ver com autenticação: se um endpoint não requeria autenticação mas agora requer, isso é um breaking change, porque código existente que costumava chamar isso agora vai receber um erro 401 Unauthorized.

Adicionou novas propriedades obrigatórias a um payload

Isso é similar a adicionar novas propriedades obrigatórias a um método público, certo? Se seu endpoint agora espera um payload diferente do que esperava antes, código existente vai quebrar, provavelmente recebendo um erro 400 Bad Request.

Renomear ou deletar um endpoint

Esse é auto-explicativo.

O que fazer sobre breaking changes?

Isso deveria ser óbvio agora, mas vamos deixar claro: breaking changes são Uma Coisa Ruim™. Tente ao máximo evitá-las.

Se você distribui qualquer código ou software publicamente e existem pessoas que dependem dele, você não vai querer ficar quebrando os workflows delas frequentemente, ou elas vão ficar bravas com você, e com razão.

Às vezes não tem jeito. Você simplesmente precisa fazer um breaking change, seja removendo um método ou classe que se tornou obsoleta, ou mudando a assinatura de uma função.

Quando você tem que fazer algo assim, algumas coisas são aconselhadas.

Depreciação Gradual

Adicionar um breaking change é algo que você não deveria levar de forma leviana porque pode dramaticamente interromper o workflow dos seus usuários. Além disso, não faça isso de repente, do nada, e de uma vez.

Antes de remover classes/métodos/etc obsoletos, primeiro anuncie publicamente que você está fazendo isso, várias versões antes. Então, você marca aquele artefato como deprecated de alguma forma, mas ainda não remove. Por exemplo, em C# você pode usar o atributo Obsolete.

Então, depois de algumas versões, você finalmente faz seu breaking change.

Adicione Instruções às Suas Release Notes

Se você está publicando software publicamente pra uso de terceiros, você provavelmente tem algum tipo de release notes onde comunica quais foram as mudanças nesta nova versão. Aproveite isso.

Quando for hora de realmente publicar uma versão com breaking change, use suas release notes pra descrever, em detalhes, qual é a mudança e como vai afetar seus usuários.

Geralmente, quando um breaking change consiste em aposentar um método/classe/endpoint, vem acompanhado de uma nova forma de fazer a mesma coisa. Afinal, você não estaria aposentando a forma antiga só porque sim.

Nesses casos, também use suas release notes pra explicar em detalhes como os usuários podem adaptar seu código pra migrar da forma antiga pra nova de fazer a tarefa.

Use Semantic Versioning

Finalmente, use Semantic Versioning e use o número da versão pra comunicar que isso é um breaking change, lançando uma versão major.

Semantic Versioning (ou SemVer pra abreviar) é um padrão de versionamento onde você usa um número de versão neste formato: major.minor.patch.

Quando sua nova versão só contém correções de bugs, e elas não adicionam breaking changes, você incrementa o componente patch.

Por exemplo:

2.0.0 -> 2.0.1

Se a versão contém nova funcionalidade que não quebra compatibilidade, então você incrementa o componente minor e zera o componente patch:

2.0.1 -> 2.1.0

Agora vem a parte mais importante. Quando sua versão contém breaking changes, seja por nova funcionalidade, correções de bugs, ou ambos, você incrementa o número major e zera os outros dois:

2.1.0 -> 3.0.0

Dessa forma, você comunica claramente aos seus usuários a presença ou ausência de breaking changes na sua release mais recente.

Conclusão

Neste post, expliquei o conceito de breaking change, por que geralmente é ruim, e o que fazer sobre isso. Resumo rápido:

Breaking changes são mudanças que quebram o código dos seus usuários, no contexto de software que é distribuído para usuários terceiros.
Evite adicionar breaking changes ao seu software, porque prejudicam a experiência dos seus clientes.
Às vezes você não pode evitar adicionar um breaking change. Nesses casos, use depreciação gradual, comunique claramente o que mudou e como se adaptar, e use semantic versioning.

Acho que é isso. Obrigado por ler, espero que tenha sido útil e nos vemos novamente no próximo episódio desta série, onde provavelmente vou voltar pra letra A, porque sou esquisito assim mesmo.

Como Melhorar a Experiência do Desenvolvedor: 7 Coisas Para Mudar

Tue, 08 Jul 2025 00:00:00 +0000

ℹ️ NOTA

Escrevi este post originalmente para a Nimbus. Você pode ler o original no site deles, em inglês.

O Que é Experiência do Desenvolvedor? Por Que Você Deveria Se Importar?

No desenvolvimento de software, falamos muito sobre experiência do usuário, e com razão. Como é o usuário final que se beneficia diretamente do software que a gente escreve, faz sentido que ele esteja sempre no centro de todos os nossos esforços. Mas recentemente, outro termo começou a ganhar força no contexto de melhorar a qualidade do software: experiência do desenvolvedor, ou developer experience no original em inglês.

É sobre isso que este post trata — experiência do desenvolvedor. Vamos começar explicando o que é experiência do desenvolvedor e por que todas as organizações de software deveriam se importar com isso. A partir daí, vamos partir para a parte prática, apresentando uma lista de sugestões que você pode adotar imediatamente para melhorar a experiência do desenvolvedor na sua equipe ou empresa.

Aqui está minha definição de experiência do desenvolvedor: quão confortável e “desenrolado” é o processo de desenvolvimento de software para uma determinada equipe ou organização.

Por que a experiência do desenvolvedor é tão importante? Por que as pessoas começaram a falar tanto sobre isso recentemente?

Não é difícil de entender. Software é tremendamente valioso, então as pessoas que criam software também são tremendamente valiosas. É do interesse de qualquer empresa que cria software manter seus desenvolvedores felizes e produtivos, especialmente num mercado aquecido onde desenvolvedores recebem oportunidades o tempo todo.

Se você melhorar a experiência do desenvolvedor na sua empresa, é mais provável que você atraia ótimos desenvolvedores e mantenha os que já tem. A produtividade provavelmente vai aumentar, assim como a qualidade do trabalho.

Experiência do Desenvolvedor: Melhore com Essas 7 Dicas

Chega de enrolação, vamos ver sete sugestões práticas que você pode adotar hoje para melhorar a experiência do desenvolvedor na sua empresa ou equipe.

1. Minimize as Interrupções

De forma geral, desenvolvedores de software odeiam interrupções. Não é porque somos uns bichos do mato que não podem ser incomodados com reuniões ou atividades que podem ser descritas como “sociais” (ok, eu admito, alguns são).

O problema com interrupções é que o desenvolvimento de software é uma atividade que requer longos períodos de foco intenso. Como qualquer profissional cuja área exige esse nível de concentração vai dizer, alcançar esse estado demora tempo e esforço. No entanto, perdê-lo é fácil: basta o João da contabilidade ou seu gerente aparecer na sua mesa ou te mandar uma mensagem no Slack para fazer esse foco desaparecer no ar.

Para melhorar a experiência do desenvolvedor, minimize as interrupções. Em termos mais práticos, faça o seguinte:

Use comunicação assíncrona o máximo possível. Tente usar newsletter interno, artigos na wiki e atualizações por e-mail em vez de reuniões e chamadas.
Adote um dia livre de reuniões. Escolha um dia da semana, ou pelo menos meio dia, em que a agenda de todos fica bloqueada e não pode ser reservada. Isso vai dar a todos a chance de ter tempo dedicado para concentração profunda.
Otimize o horário e duração das reuniões. Reuniões são inevitáveis às vezes. Quando esse for o caso, escolha um horário e duração que facilite para as pessoas se concentrarem. Por exemplo, se o horário de trabalho da sua empresa termina às 18h, não agende uma reunião que termina às 17h30. Esses últimos trinta minutos provavelmente serão perdidos, já que não são suficientes para os desenvolvedores alcançarem o foco profundo que precisam.

2. Invista em Excelência Técnica

A maioria dos desenvolvedores quer saber que seu trabalho importa. Eles querem saber que estão trabalhando numa equipe que cria software com os mais altos padrões, usando as melhores práticas disponíveis e encantando usuários com ótimas funcionalidades entregues rapidamente.

Portanto, investir em excelência técnica é uma ótima forma de melhorar a experiência dos desenvolvedores. A lista do que você pode fazer inclui o seguinte:

Adotar testes automatizados e, opcionalmente, TDD (desenvolvimento guiado por testes)
Usar integração contínua (CI) e entrega e deployment contínuos (CD).
Ter um processo de revisão de código ou, em vez, programação em par.
Usar analisadores estáticos e linters para detectar problemas comuns no código.
Coletar e acompanhar métricas de qualidade.

Essas são apenas algumas sugestões sobre o que você pode fazer para fomentar uma cultura de excelência técnica na qual os desenvolvedores sentem orgulho do seu trabalho e sentem que seu trabalho tem propósito.

3. Dê Autonomia aos Desenvolvedores

Autonomia é um grande motivador de produtividade e felicidade no trabalho. Para se sentirem realizadas, as pessoas precisam ter pelo menos algum grau de autonomia sobre a forma como fazem seus trabalhos.

De forma geral, desenvolvedores deveriam receber um alto grau de autonomia sobre como fazem seu trabalho. Permita que as equipes decidam o seguinte:

Qual workflow de branching melhor atende suas necessidades
Se eles estimam usando pontos, tamanhos de camiseta, Fibonacci, horas ou algo completamente diferente
Quão rigorosamente eles querem aderir às cerimônias do seu sabor preferido de agile (por exemplo, se devem ou não ter um daily scrum)

No nível individual, permita que desenvolvedores escolham se querem trabalhar remotamente, no escritório ou de forma híbrida. Dê ao colaborador flexibilidade para montar um pacote de benefícios que faça sentido para ele (algumas pessoas têm filhos, outras não, então benefícios que atendem apenas pessoas casadas com filhos certamente vão alienar uma parte considerável da sua força de trabalho).

4. Remova o Atrito ao Criar Ambientes de Desenvolvimento

Uma coisa que quase todo desenvolvedor odeia é um processo manual, tedioso e propenso a erros ao criar um novo ambiente de desenvolvimento. Esses processos fazem com que desenvolvedores demorem muito tempo até conseguirem contribuir com código para a equipe. Pior ainda, os processos frequentemente não são facilmente reproduzíveis, o que significa que diferenças entre ambientes podem ser introduzidas.

Como consequência, o ambiente de desenvolvimento se afasta do staging e produção, tornando bugs mais prováveis e criando a famosa desculpa “funciona na minha máquina”.

Para melhorar a experiência do desenvolvedor, invista em formas de facilitar a criação de ambientes consistentes e reproduzíveis. Soluções de container como Docker são uma ótima forma de alcançar isso. Alternativamente, você pode aproveitar soluções que oferecem a criação de ambientes de desenvolvimento na nuvem.

5. Invista na Educação dos Desenvolvedores

Debs também têm uma ótima experiência quando sentem que dominam as ferramentas do seu trabalho. A sensação de estar no controle é muito boa. Isso não só leva a um resultado de maior qualidade, mas também é mais prazeroso.

Então, uma forma certeira de melhorar a experiência do desenvolvedor é investir na educação deles. Há várias formas de fazer isso:

Oferecer aos desenvolvedores uma verba mensal ou anual que eles podem usar livremente para investir em cursos, livros ou certificações.
Dar aos desenvolvedores tempo (tempo remunerado da empresa, sim!) durante o qual eles podem estudar e praticar
Oferecer recursos de aprendizado pagos pela empresa, como uma biblioteca da empresa ou serviços como Udemy ou Pluralsight

6. Não Seja Pão-Duro com Ferramentas

Se você quer que seus desenvolvedores façam um ótimo trabalho, você deve dar a eles as ferramentas para fazê-lo. Se seus desenvolvedores não conseguem entregar um ótimo trabalho devido a um computador lento ou falta de licença de software, a culpa é sua.

Seus programadores deveriam ter ótimo hardware, como laptop fornecido pela empresa, monitor, teclado e por aí vai (e até complementos de escritório como uma ótima cadeira).

Você também deveria fornecer o software necessário. Isso inclui licenças de IDE, assinaturas de serviços, plugins e o que mais for preciso. Não importa o que seus desenvolvedores precisam para realizar seu trabalho, a empresa deveria, dentro do razoável, fornecer.

7. Ouça o Feedback dos Desenvolvedores (e Aja Baseado Nele)

Por último, mas não menos importante, aqui está o item final da nossa lista: ouça seus desenvolvedores!

Entende o seguinte: desenvolvedores de software geralmente são pessoas inteligentes que se importam com o que fazem. As chances são de que eles tenham ideias muito boas sobre como melhorar não apenas sua própria experiência, mas a de suas equipes e organizações como um todo.

Ouça seus desenvolvedores. Quando fizer sentido, coloque suas sugestões em prática. Além do benefício criado pela sugestão em si, isso terá o benefício adicional de melhorar o moral da equipe. Seus desenvolvedores vão se sentir valorizados e como parte essencial da equipe. O que, é claro, eles são.

Melhore a Experiência do Desenvolvedor, Melhore Sua Empresa

Se sua organização é uma organização de tecnologia, então desenvolvedores de software são indiscutivelmente seus ativos mais preciosos. Então, melhorar a experiência do desenvolvedor, além de ser uma coisa decente e humana a se fazer, também é um ótimo investimento. É do seu interesse manter seus desenvolvedores felizes e produtivos, e como você viu neste post, isso é algo que você pode alcançar relativamente facilmente.

As sugestões neste post são simplesmente sugestões. Seus resultados podem variar (por exemplo, se você trabalha numa indústria altamente regulamentada, dar aos desenvolvedores um alto grau de autonomia pode não se aplicar). Como sempre, use seu julgamento. Considere a lista neste post como um ponto de partida. Ajuste conforme necessário, corte e adicione a ela. O que importa é que você melhore a experiência do desenvolvedor na sua empresa pelo bem dos seus desenvolvedores, seus usuários finais e a empresa como um todo.

Obrigado pela leitura!

Git Switch Branch: Tudo o Que Você Precisa Saber

Tue, 15 Apr 2025 00:00:00 +0000

ℹ️ NOTA

Escrevi este post originalmente para a Cloudbees. Você pode ler o original, em inglês, no site deles.

Repositórios no Git funcionam de uma maneira fundamentalmente diferente da maioria das outras ferramentas. Um dos exemplos mais marcantes dessas diferenças é o branching. Na maioria das outras ferramentas de controle de versão, criar um branch é uma cerimônia elaborada. Eles fazem um grande alarde sobre isso, e os desenvolvedores acabam desistindo, preferindo fluxos de trabalho que não dependem de muitos branches.

No Git, o oposto é frequentemente verdadeiro: criar branches é tão barato que a maioria das pessoas faz isso muito. As pessoas frequentemente ficam confusas ao tentar gerenciar seus branches. Este post tenta esclarecer parte dessa confusão, oferecendo um guia sobre como fazer o git switch branch de maneira fácil e segura. Antes de chegarmos lá, no entanto, começamos com alguns fundamentos, explicando o que realmente são branches no Git, como funcionam e como você as cria.

Antes de concluir, compartilhamos uma dica bônus, abordando como fazer checkout de branches remotas. Vamos começar!

Como Funcionam os Branches no Git?

Como funcionam os branches no Git? A primeira coisa que você precisa saber é que um repositório no Git é composto por objetos e referências. Os principais tipos de objetos em um repositório Git são commits. Referências apontam para outras referências ou para objetos. Os principais tipos de referências são—você adivinhou—branches.

Objetos no Git são imutáveis. Você não pode alterar um commit de forma alguma ou mover sua posição no histórico. Existem comandos que parecem mudar as coisas, mas na verdade eles criam novos commits. Referências, por outro lado, mudam bastante. Por exemplo, quando você cria um novo commit, a referência do branch atual é atualizada para apontar para ele.

Quando você cria um novo branch, tudo o que acontece é que uma nova referência é criada apontando para um commit. É por isso que criar branches no Git é tão barato e rápido. Falando nisso…

Como Crio um Novo Branch?

Nós já temos um post completo explicando como você pode criar um branch no Git, cobrindo as quatro principais maneiras de fazer isso.

Aqui, vamos apenas cobrir a maneira mais fácil de criar um branch no Git, que é simplesmente usar o comando branch a partir do branch atual. Vejamos um exemplo:

mkdir git-switch-demo
cd git-switch-demo
git init
touch file1.txt
git add .
git commit -m "Create first file"
touch file2.txt
git add .
git commit -m "Create second file"
touch file3.txt
git add .
git commit -m "Create third file"

No exemplo acima, criamos um novo repositório e adicionamos três commits a ele, criando um novo arquivo por commit. Aqui está uma representação visual do estado atual do nosso repositório:

Para criar um novo branch a partir do ponto atual, só precisamos executar:

git branch example

Criamos um branch, mas ainda não mudamos para ele. É assim que nosso repositório se parece agora:

E se adicionássemos um novo commit enquanto ainda estamos no branch master? Isso afetaria o branch example? A resposta é não. Execute os seguintes comandos:

echo "Another file" > file4.txt
git add .
git commit -m "Create fourth file"

Na próxima seção, mostraremos como você pode fazer git switch branch e, em seguida, poderá ver por si mesmo como esse novo branch não contém o quarto commit. Por enquanto, dê uma olhada na representação visual do estado atual do nosso repositório:

Como Você Muda de Branch?

Durante a maior parte da história do Git, o comando checkout era usado para isso. Embora você ainda possa usá-lo, a versão 2.23 do Git adicionou o comando switch (bem como o comando restore) em uma tentativa de ter comandos mais específicos para algumas das muitas tarefas para as quais o comando checkout é usado.

Como Uso o Git Checkout?

A maneira mais antiga e mais conhecida de mudar de branch no Git é usando o comando checkout. Seguindo nosso exemplo, se quiséssemos mudar para o branch “example”, só teríamos que executar:

git checkout example

Após executar o comando, você deverá ver uma mensagem dizendo que mudou com sucesso para o branch example:

Agora você está no novo branch, isso significa que pode adicionar quantos commits quiser, sabendo que o branch master não será afetado. O comando checkout, seguido por um nome de branch, atualiza a árvore de trabalho e o índice, e atualiza a referência HEAD, apontando-a para o branch que você acabou de fazer checkout. E se você tivesse alterações não commitadas no momento da mudança? Essas seriam mantidas para permitir que você as commitasse no novo branch.

O Git permite que você use o comando checkout de diferentes maneiras. Por exemplo, um cenário incrivelmente comum é criar um branch e imediatamente mudar para ele. Na verdade, eu diria que criar um branch e não mudar para ele na hora é a exceção, e não a regra. Então, o Git nos oferece um atalho. Em vez de criar um branch e depois fazer checkout dele, você pode fazer isso em uma única etapa usando o comando checkout com o parâmetro -b.

Então, fazer isso:

git checkout -b new

é equivalente a isso:

git branch new
git checkout new

Checkout não funciona apenas com branches, no entanto. Você também pode fazer checkout de commits diretamente. Por que você gostaria de fazer isso?

Bem, dar uma olhada em como o projeto estava há algum tempo atrás é frequentemente útil, particularmente para fins de teste. Mas há mais. Fazer checkout de um commit coloca seu repositório em um estado chamado “detached HEAD” que permite criar alterações experimentais, adicionando commits que você pode então escolher manter ou descartar.

O Que é Git Switch?

Durante a maior parte da vida do Git, o comando checkout era o único que você usaria para mudar de branch. O problema é que esse comando também faz outras coisas, o que pode levar à confusão, especialmente entre novos usuários.

A versão 2.23.0 do Git resolve isso adicionando dois novos comandos: switch e restore. O comando restore não é relevante para nós hoje. O comando switch, por outro lado, é uma nova maneira de mudar para branches.

A página do manual para o comando lista todas as suas muitas opções. Em sua forma mais básica, você o usa da mesma maneira que o git checkout, apenas trocando o nome do comando:

git switch example

Se você quiser voltar ao branch anterior, pode usar um atalho em vez do nome completo:

git switch -

E se você quiser criar um novo branch e imediatamente mudar para ele? Com checkout, poderíamos usar este atalho:

git checkout -b <nome-do-branch>

O novo comando também oferece um atalho, mas neste caso, usamos a letra “c”:

git switch -c <nome-do-branch>

Vale a pena usar o novo comando? Bem, eu provavelmente continuarei usando o git checkout, desde que eles não o mudem, principalmente por causa da memória muscular. Mas ao ensinar Git para iniciantes? Então eu definitivamente usarei o comando switch. Ele tem um nome que está mais relacionado à tarefa que executa e, portanto, é mais memorável.

Como Faço para Mudar para um Branch Remoto?

Antes de concluir, compartilhamos uma dica final: como mudar para branches remotas?

Para este exemplo, vamos usar um projeto de código aberto chamado Noda Time, que é uma API alternativa de data e hora para .NET. Comece clonando o repositório:

git clone https://github.com/nodatime/nodatime.git

Se tudo funcionou bem, você deve ter uma pasta “nodatime” agora. Entre na pasta e execute o seguinte comando:

git branch -a

O comando branch lista os branches em seu repositório. A opção “-a” significa que você quer ver todos os branches, não apenas os locais. O resultado deve ser parecido com isto:

Como você pode ver, temos apenas um branch local, que é o branch master. Você pode ver, em vermelho, todos os branches remotos. Então, digamos que você queira fazer checkout do branch chamado “slow-test”. Como você faria isso?

Bem, tecnicamente falando, o Git não permite que você trabalhe nos branches de outras pessoas. E é isso que são os branches remotos. O que você realmente faz é criar uma “cópia” local do branch de outra pessoa para trabalhar. Então, vamos ver como fazer isso.

Quando você cria um branch, pode passar um commit ou nome de branch como parâmetro. Então, para criar um branch local a partir do branch remoto “slow-test”, eu só teria que fazer:

git branch slow-test origin/slow-test

No exemplo, estou usando “slow-test” como o nome para o meu branch local, mas eu poderia realmente ter usado qualquer outro nome válido.

Alternativamente, eu poderia ter usado o comando checkout com a opção -b ou o comando switch com a opção -c. Então, as duas linhas a seguir são equivalentes à linha acima:

git checkout -b slow-test origin/slow-test
git switch -c slow-test origin/slow-test

Finalmente, há uma maneira ainda mais fácil. Eu poderia ter simplesmente usado:

git checkout slow-test

e o resultado teria sido o mesmo. Isso funciona porque quando você tenta fazer checkout de um branch e o Git não encontra um branch com esse nome, ele tenta corresponder a um branch remoto de um de seus remotes. Se ele conseguir corresponder com sucesso, as coisas simplesmente funcionam.

Branches do Git: Use com Moderação

Neste post, mostramos como mudar de branch no Git. Mas fomos além disso: explicamos o que são branches e como funcionam. Esperamos que, a esta altura, você esteja mais confortável criando e usando branches no Git.

Antes de irmos, uma ressalva final: só porque você pode fazer algo, não significa que deva. Às vezes, as pessoas ficam tão entusiasmadas com a facilidade de criar branches no Git que acabam usando fluxos de trabalho que dependem de vários branches de longa duração, o que torna seu processo de desenvolvimento muito complexo e propenso a erros, além de atrasar a integração.

Obrigado por ler e até a próxima!

C# Type Safe: Como a IA Generativa Torna os Tiny-Types Viáveis

Tue, 10 Dec 2024 00:00:00 +0000

É estranho como nossa memória funciona, não é? Não consigo lembrar exatamente o que jantei há duas noites, ou o motivo pelo qual deixei de ir à academia em alguns dias da semana passada. Mas me lembro vividamente de um bug específico que corrigi no meu primeiro emprego como programador depois de me formar na faculdade.

Havia este método que não estava funcionando corretamente, e sua assinatura era algo assim:

void ProcessOrder(int orderId, int customerId)

Eu revisei o código e não consegui encontrar nada de errado. Mas quando comecei a debugar, percebi que o local da chamada estava passando os argumentos na ordem errada — ou seja, customerId primeiro e depois orderId.

Erros como este são fáceis de cometer e difíceis de detectar mesmo em revisões de código. Até mesmo os testes podem deixar passar, já que você pode ter o azar de fornecer valores que acidentalmente fazem o código funcionar sem explodir tudo.

Como acontece, existe uma ótima maneira de prevenir problemas como o que acabei de descrever. O problema? A maioria dos desenvolvedores acharia que é trabalho demais para se preocupar.

Tiny Types: A Melhor Técnica de Design de Software Que Ninguém Usa

Eu sei, eu sei. Vou ser o primeiro a admitir que este título é exagerado. “Uma Técnica Interessante de Design de Software Que Muitas Pessoas Não Usam” simplesmente não tem o mesmo impacto, foi mal.

Então, o que é essa coisa de “tiny types”? É uma solução radical para o code smell de obsessão primitiva. Essencialmente, em vez de usar tipos primitivos para conceitos de domínio — por exemplo, usar um int para representar um identificador único — você envolve todos eles usando um objeto de valor extremamente simples.

Usando tiny types, poderíamos reescrever a assinatura do método anterior assim:

void ProcessOrder(OrderId orderId, CustomerId customerId)

Implementando um Tiny Type

Como seria o tipo OrderId?

Para começar, já que OrderId deve envolver um int, ele deve receber um int como parâmetro e armazená-lo em algum lugar. Vejamos:

public class OrderId
{
    private readonly int _value;
    public OrderId(int value)
    {
        if (value <= 0)
        {
            throw new ArgumentOutOfRangeException(
                nameof(value),
                 "Value must be a positive integer!");
        }
        _value = value;
    }
}

Acho que o exemplo acima é um bom começo, você não concorda? Recebemos um int como parâmetro, validamos e lançamos uma exceção em caso de valores zero ou negativos, e então o atribuímos a um campo privado readonly, o que é apropriado, já que OrderId, como um objeto de valor, deve ser imutável.

Você sabe do que mais os objetos de valor — e, por consequência, os tiny types — precisam? Igualdade estrutural. Ou seja, ao compará-los, devemos considerar apenas seus valores, não se suas referências apontam para o mesmo objeto.

Então, vamos começar sobrescrevendo Equals:

public override bool Equals(object? obj)
{
    var other = obj as OrderId;
    if (other == null)
    {
        return false;
    }
    return other._value == _value;
}

(Para um estilo C# mais moderno, poderíamos ter usado pattern matching, mas acho que a abordagem acima é mais clara.)

Agora recebo um aviso do compilador porque meu tipo sobrescreve Equals mas não GetHashCode, então vamos corrigir isso:

public override int GetHashCode()
{
    return _value.GetHashCode();
}

Como OrderId é um tipo simples representando valores únicos e imutáveis, ele deveria realmente ser uma struct em vez de uma classe, de acordo com as Diretrizes de Design de Tipos da Microsoft:

Structs são o caso geral de tipos de valor e devem ser reservadas para tipos pequenos e simples, semelhantes aos primitivos da linguagem.

Mas as diretrizes de design também dizem que todas as structs devem implementar a interface IEquatable<T>, então vamos fazer isso. Aliás, já que estamos aqui, vamos também implementar IComparable<T> e dar overload nos operadores de comparação:

public struct OrderId : IEquatable<OrderId>, IComparable<OrderId>
{
    private readonly int _value;
    public OrderId(int value)
    {
        if (value <= 0)
        {
            throw new ArgumentOutOfRangeException(
                nameof(value),
                 "Value must be a positive integer!");
        }
        _value = value;
    }

    public override bool Equals(object? obj)
    {
        if (obj is OrderId other)
        {
            return _value == other._value;
        }
        return false;
    }

    public bool Equals(OrderId other) => _value == other._value;

    public override int GetHashCode()
    {
        return _value.GetHashCode();
    }

    public int CompareTo(OrderId other) => _value.CompareTo(other._value);

    public static bool operator ==(OrderId left, OrderId right) => left.Equals(right);
    public static bool operator !=(OrderId left, OrderId right) => !(left == right);
    public static bool operator <(OrderId left, OrderId right) => left.CompareTo(right) < 0;
    public static bool operator >(OrderId left, OrderId right) => left.CompareTo(right) > 0;
    public static bool operator <=(OrderId left, OrderId right) => left.CompareTo(right) <= 0;
    public static bool operator >=(OrderId left, OrderId right) => left.CompareTo(right) >= 0;
    
    public override string ToString() => _value.ToString();
}

Existem mais coisas que poderíamos adicionar, como conversões implícitas/explícitas, mas nosso tipo já é funcional como está. Para aqueles que usam C# moderno, poderíamos alcançar o mesmo com uma sintaxe mais concisa:

public readonly record struct OrderId : IComparable<OrderId>
{
    private readonly int _value;

    public OrderId(int value)
    {
        if (value <= 0)
        {
            throw new ArgumentOutOfRangeException(
                nameof(value),
                "O valor deve ser um inteiro positivo!");
        }
        _value = value;
    }

    public int CompareTo(OrderId other) => _value.CompareTo(other._value);

    public static bool operator <(OrderId left, OrderId right) => left.CompareTo(right) < 0;
    public static bool operator >(OrderId left, OrderId right) => left.CompareTo(right) > 0;
    public static bool operator <=(OrderId left, OrderId right) => left.CompareTo(right) <= 0;
    public static bool operator >=(OrderId left, OrderId right) => left.CompareTo(right) >= 0;
    
    public override string ToString() => _value.ToString();
}

Tiny Types São Muito Caros

Meu pequeno tipo OrderId ali ocupa 42 linhas no meu Visual Studio. Sim, existem algumas escolhas estilísticas envolvidas — por exemplo, eu não gosto quando as linhas têm mais de 80 caracteres de comprimento — mas mesmo assim, é bastante trabalho.

A versão mais concisa, que aproveita o recurso record do C# moderno, é mais curta, mas ainda requer uma quantidade razoável de código.

Agora imagine fazer isso para todos os ids em sua aplicação! E não apenas ids, claro. Imagine fazer isso para mais tipos que exigem validação/análise mais complexa:

CEPs
Placas de carro
Números de telefone.

E assim por diante.

Essa é a principal razão pela qual desenvolvedores que conhecem esta técnica não a usam. Mesmo quando gostam da ideia e entendem como ela poderia ser benéfica, eles acham que fazer tudo isso não vale o trabalho.

LLMs ao Resgate

Já se passaram dois anos desde que a OpenAI apresentou o ChatGPT ao mundo, e tenho experimentado com LLMs desde então. Minha opinião atual sobre eles é que sua proposta de valor para desenvolvedores experientes é dupla:

Eles atuam como um substituto do Google ao aprender algo novo
Eles atuam como um gerador de código para coisas mundanas que eu preferiria não fazer.

Há alguns meses, tornei-me um assinante pago do Claude. Tenho usado principalmente como auxílio em um projeto hobby no qual estou trabalhando, e devo dizer que estou muito satisfeito com os resultados que obtenho, já que o Claude é muito melhor que o ChatGPT para tarefas de programação.

Fui ao Claude com o seguinte prompt:

Gere um tipo chamado OrderId. Deve ser um wrapper sobre um int. Não permita valores zero ou negativos. Implemente igualdade, hash code, sobrecarga de operadores de comparação e igualdade.

Não adicione conversões explícitas ou implícitas.

E este é o resultado que obtive:

public readonly struct OrderId : IEquatable<OrderId>, IComparable<OrderId>
{
    private readonly int value;

    public OrderId(int value)
    {
        if (value <= 0)
        {
            throw new ArgumentException("Order ID must be greater than zero", nameof(value));
        }
        this.value = value;
    }

    public override bool Equals(object? obj)
    {
        return obj is OrderId other && Equals(other);
    }

    public bool Equals(OrderId other)
    {
        return value == other.value;
    }

    public override int GetHashCode()
    {
        return value.GetHashCode();
    }

    public int CompareTo(OrderId other)
    {
        return value.CompareTo(other.value);
    }

    public static bool operator ==(OrderId left, OrderId right)
    {
        return left.Equals(right);
    }

    public static bool operator !=(OrderId left, OrderId right)
    {
        return !(left == right);
    }

    public static bool operator <(OrderId left, OrderId right)
    {
        return left.CompareTo(right) < 0;
    }

    public static bool operator <=(OrderId left, OrderId right)
    {
        return left.CompareTo(right) <= 0;
    }

    public static bool operator >(OrderId left, OrderId right)
    {
        return left.CompareTo(right) > 0;
    }

    public static bool operator >=(OrderId left, OrderId right)
    {
        return left.CompareTo(right) >= 0;
    }

    public override string ToString()
    {
        return value.ToString();
    }
}

É um bom começo, mas ainda não estou completamente satisfeito:

Pode torná-lo um record para que a implementação seja mais concisa? Além disso, use métodos com corpo de expressão para as linhas únicas.

E agora o Claude me deu isso:

public readonly record struct OrderId : IComparable<OrderId>
{
    private readonly int value;

    public OrderId(int value)
    {
        if (value <= 0)
             throw new ArgumentException("Order ID must be greater than zero", nameof(value));
        this.value = value;
    }

    public int CompareTo(OrderId other) => value.CompareTo(other.value);

    public static bool operator <(OrderId left, OrderId right) => left.CompareTo(right) < 0;
    public static bool operator <=(OrderId left, OrderId right) => left.CompareTo(right) <= 0;
    public static bool operator >(OrderId left, OrderId right) => left.CompareTo(right) > 0;
    public static bool operator >=(OrderId left, OrderId right) => left.CompareTo(right) >= 0;

    public override string ToString() => value.ToString();
}

Finalmente, fui ao Claude e perguntei isto:

Imagine que existe uma classe Order que precisa ser salva no banco de dados. Usamos Entity Framework. Como garantir que tudo funcione já que este modelo usa o tipo OrderId?

E esta é minha resposta, completa com o modelo e a configuração necessária do EF para lidar com nosso tipo personalizado:

.HasConversion<OrderIdValueConverter>()
                .ValueGeneratedOnAdd(); // Usar auto-incremento do banco de dados
            
            builder.Property(o => o.CustomerName)
                .IsRequired()
                .HasMaxLength(200);

            builder.Property(o => o.TotalAmount)
                .HasPrecision(18, 2);
        });
    }
}

Conclusão

Este post tinha dois objetivos. Primeiro, apresentar o conceito de tiny types para aqueles de vocês que nunca ouviram falar dele. Espero que concordem que, apesar de ser uma ideia simples, o padrão tiny types é algo que pode ajudar você a escrever código mais robusto.

Segundo, e de forma mais ampla, demonstrar como os LLMs podem desempenhar um papel interessante no fomento de um melhor design de software. No passado, muitas técnicas de design de software podem ter sido descartadas por serem consideradas trabalho demais para valer a pena. Agora, com a ajuda do Claude, ChatGPT ou assistentes de código como o Copilot, podemos agilizar a escrita de código “chato”, o que faz com que a economia das técnicas de design, como a que apresentei neste post, faça mais sentido.

Erros de Aprendizado Para Se Evitar Como Desenvolvedor de Software

Tue, 22 Oct 2024 00:00:00 +0000

Foto de Francisco De Legarreta C. na Unsplash

ℹ️ Info

Agradeço ao amigo André Gonçalves da Silva por ler e revisar esboços deste post, e sugerir melhorias.

Se você trabalha com desenvolvimento de software, com certeza já ouviu frases do tipo “Nunca pare de estudar”, “Tem que se atualizar sempre”, “A nossa área muda muito rápido”, e assim por diante.

Claro, todas essas frases estão certas, em algum nível. Mas sair por aí repetindo como um papagaio “nunca pare de estudar” não é a coisa mais útil do mundo no sentido de fornecer um direcionamento para o seu aprendizado.

O que acaba acontecendo na prática é que muita gente, por não ter aprendido a aprender da forma correta, comete muitos erros de aprendizado que comprometem seu desenvolvimento profissional. Esses erros podem levar a um progresso lento, frustração e até mesmo estagnação na carreira - algo que ninguém está a fim de passar.

Por isso, nesse post, resolvi trazer um compilado do que acredito serem os erros mais comuns de aprendizado que devs em geral cometem. Essa lista é fruto de anos de experiência pessoal, observação de colegas desenvolvedores e muitas conversas com gente da área. Eu sei na prática do que estou falando porque muitos desses erros são coisas que eu já cometi.

(Sendo sincero, alguns eu ainda cometo e tô sempre precisando me policiar para parar, mas não conta pra ninguém. ;))

Identificar e entender esses erros é o primeiro passo para superá-los. Ao evitá-los, você pode otimizar seu processo de aprendizado, acelerar seu crescimento profissional e se manter relevante em um campo que está sempre evoluindo.

Então, sem mais delongas, aqui vai a lista dos erros de aprendizado para você evitar. Para cada erro, você vai ver:

a explicação do erro
o problema que ele causa
como remediá-lo

Bora lá?

Índice

Achar Que Apenas Consumo de Conteúdo == Aprendizado
Não Aplicar o Conteúdo dos Recursos de Aprendizado
Falta de Foco
Falta de Consistência
Subestimar a Importância das Bases
Viver Embaixo de Uma Pedra (Não se antenar com o que está acontecendo)
Conclusão

Achar Que Apenas Consumo de Conteúdo == Aprendizado

Comecei a lista com esse que acredito ser o erro de aprendizado mais comum atualmente, pelo simples fato de que a gente vive em uma época onde se produz conteúdo pra caramba.

Por que caímos nessa armadilha?

Consumir conteúdo é fácil, conveniente e(potencialmente) divertido. Vamos entender o porquê:

Fácil: É algo passivo, você não tem que pensar muito ou tomar decisões, e o ser humano tende a procurar o caminho do menor esforço.
Conveniente: Você pode geralmente consumir o conteúdo enquanto faz outras coisas:
- Ouvir um podcast enquanto se exercita ou lava a louça
- Assistir um vídeo enquanto almoça
- Ler posts no Reddit enquanto espera na fila do banco
Divertido: Muitos criadores percebem que, pra engajar o público, precisam adicionar um toque de entretenimento e transformar o conteúdo numa performance que segure a atenção.

Pronto, a armadilha está montada. Aí você vai lá, bola uma estratégia para preencher cada momento livre do dia com o consumo de podcasts, vídeos no Youtube, blog posts, Reddit, e sei lá o que mais.

As consequências desse erro

No fim, você vai ter:

Consumido seu tempo com informações superficiais
Retido quase nada do que consumiu
Um vago sentimento de que “aprendeu” alguma coisa

Mas e na hora de aplicar isso de maneira significativa no seu dia-a-dia? É aí que a conta não fecha.

A longo prazo, as consequências podem ser ainda mais sérias:

Estagnação profissional, pois você não está realmente desenvolvendo novas habilidades
Frustração ao perceber que não está progredindo como esperava
Possível burnout ao tentar constantemente “ficar por dentro” de tudo

Pra deixar bem claro: o erro aqui não é “consumir conteúdo.” E sim achar que apenas o consumo desenfreado de conteúdo é o suficiente para você evoluir como profissional.

Como remediar esse erro

A solução é simples em teoria, o que não necessariamente significa que é fácil. Aqui vai:

Diminua a parcela do seu tempo de aprendizado que você gasta com consumo passivo de conteúdos, e aumenta a parcela gasta com aprendizado prático, principalmente projetos pessoais.

As sugestões aqui são:

Crie ou contribua com um projeto open-source
Faça um site ou aplicativo para uma ONG, entidade assistencial, ou sua igreja
Solucione algum problema que você ou algum familiar tem criando uma automação simples
Reinvente a roda: Implemente uma tecnologia ou ferramenta conhecida (exemplos: git, Docker, um servidor HTTP) simplesmente com o objetivo de aprender.

A lista acima não é exaustiva, mas serve apenas pra começar a te inspirar. Cinco minutos de Google ou de conversa com o Chat GTP vai render muitas ideias de projetos legais para fazer.

Não Aplicar o Conteúdo dos Recursos de Aprendizado

Se você comprar um livro e não o ler, você joga dinheiro fora. Se você comprar o livro, ler, e o aprendizado daquilo não impactar a maneira como você faz seu trabalho, então você desperdiça o seu dinheiro e o seu tempo!

O mesmo se aplica a cursos, tutoriais, e outros recursos de aprendizado. Ser desenvolvedor de software é uma profissão prática; como você espera se beneficiar do que aprendeu, se não o colocar em prática?

Antes que alguém reclame: sim, é claro que existem livros, vídeos, etc., cujo conteúdo não tem uma aplicação prática direta. Talvez você tenha lido O Mítico Homem-Mês pra pegar alguns insights e aprender sobre a história do desenvolvimento de software, mas isso não muda necessariamente como você escreve código. E tá tudo bem, esses casos existem – use seu bom senso.

Como o erro #2 difere do anterior?

A gente pode resumir o primeiro erro como “gastar 100% do seu tempo de aprendizado com o consumo de conteúdo.” Ou seja, você não faz mais nada além de consumir coisas.

Este erro aqui é na linha de “não aplicar o que você aprende com o conteúdo assistido.”

Ou seja, é possível cometer o segundo erro sem cometer o primeiro. Por exemplo, você pode dedicar 60% do seu tempo de aprendizado à criação de projetos pessoais e 40% ao consumo de conteúdo. Mas se ainda sim você não aplicar de nenhuma forma o conteúdo que você aprendeu nesses 40% do tempo, você vai ter cometido o erro #2. Ficou claro?

Motivo Desse Erro

Por que tanta gente (este que vos fala incluso) comete esse erro? Provavelmente o que rola aqui é uma certa pressão psicológica que muitos sentimos, no sentido de atingir números. Quantas pessoas você conhece que criam umas metas assim?

Ler x livros técnicos por ano
Fazer y cursos até o segundo semestre
etc…

Se você se sente realmente a fim de atingir esse tipo de meta, não tem jeito: precisa “gastar” o menor tempo possível com cada conteúdo. Do contrário, a conta não fecha.

Problemas Causados Por Este Erro

Uma consequência grave que você pode sofrer com este erro é a falta de motivação. Você leu todos os livros famosos da área que te indicaram, concluiu todos os cursos no seu PDI, e parece que nada mudou. Assim fica difícil ter a motivação pra insistir no aprendizado, quando a sensação é de que nada disso gera impacto real na maneira como você trabalha.

É essa a tal da frustração com a falta de evolução na carreira, que a gente citou no erro anterior. Outra consequência séria desse erro é o próprio desperdício de tempo, dinheiro e energia: o aprendizado é um investimento que precisa ter um retorno para ser justificado.

Qual a solução?

O remédio para este erro tem dois passos:

Priorizar qualidade ao invés de quantidade
Aplique constantemente o que aprendeu

Então, aqui fica a minha sugestão prática:: só inicie outro curso/livro/etc após ter aplicado o aprendizado do anterior.

Por exemplo, digamos que você está fazendo um curso na Udemy. Após cada aula ou seção, pare e crie um pequeno projeto no qual você exercita o que você acabou de aprender. Não precisa ser um projeto grande, nem mesmo útil. De preferência, jogue fora depois de terminar: o importante é a prática.

Aqui estão mais alguns exemplos:

Após assistir um tutorial de programação, dedique tempo para replicar o projeto por conta própria, sem olhar o vídeo
Leu um artigo sobre uma nova técnica de refatoração? Aplique-a em um projeto pessoal ou no trabalho
Ouviu um podcast sobre boas práticas de código? Revise um projeto antigo e veja onde você pode aplicar essas práticas

Com relação à leitura de livros técnicos, recentemente eu criei uma regra pra mim: quando eu termino um livro, eu só posso começar outro depois que eu tiver aplicado o conteúdo do livro que acabei de ler. Essa aplicação pode ter diferentes formas:

fazer os exercícios do livro, caso tenha
criar um ou mais projetos para exercitar aquele conteúdo
propor/implementar uma nova prática no meu trabalho baseado no que aprendi

No fim das contas, é isso que importa: que você dê um jeito de aplicar o conteúdo aprendido pra melhorar a sua vida profissional. Uma pilha de livros cujo conteúdo não te impactou só serve pra juntar poeira ou de suporte para monitor.

Falta de Foco

Existem muito mais coisas “aprendíveis” do que você tem tempo ou energia para aprender. Você nunca vai saber tudo, e nunca vai zerar a sua fila de coisas para aprender. Isso é um fato e você precisa aceitar e abraçar esse fato, a não ser que você esteja muito a fim de um burnout.

Infelizmente, a gente sente a pressão de “estar sempre estudando”, mesmo que essa frase em si não tenha nenhuma utilidade—não oferece nenhuma ajuda sobre o quê estudar, ou que estratégias usar.

É comum que essa pressão venha das nossas próprias empresas:

Leia o livro x!
Faça esse curso!
Conclua essa trilha!

E essas pessoas são bem intencionadas, mas isso não muda o fato de que você tem uma quantidade limitada de tempo no seu dia e, mais importante, uma quantidade limitada de energia no tempo que você tem disponível

Mas aí você cede à pressão e acaba cometendo o erro desse item: ficar pulando de curso em curso, livro em livro, tutorial em tutorial, sem nunca concluir nada, ou pelo menos atingir algum progresso significativo.

Um Disclaimer

Olha só: eu sei que no dia-a-dia do trabalho, é muito comum a gente se deparar com um número enorme de problemas diferentes que precisam ser resolvidos, e o prazo é sempre pra ontem. Nestas situações, muitas vezes a coisa correta é sim aprender somente o superficial de um assunto para conseguir dar conta da demanda e gerar valor para o usuário o mais rápido possível.

A habilidade de distinguir quando é a hora de investir em um certo item de maneira mais aprofundada e quando um conhecimento superficial basta é algo que é extremamente valioso para a carreira de qualquer profissional, e a única maneira de aperfeiçoar essa habilidade é com a prática.

O erro que eu aponto neste item é uma situação diferente do cenário acima. Mais especificamente, o erro é sobre tentar aprender muitas coisas ao mesmo tempo, de maneira aprofundada, com recursos densos.

Problemas Causados Por Este Erro

O principal problema causado pela falta de foco é que você nunca se aprofunda em nada. Você fica com uma vaga impressão de conhecimento em um milhão de coisas, mas quando rola uma situação crítica no qual o conhecimento aprofundado faria falta, você não tem o que mostrar.

Como eu já disse antes, é impossível se aprofundar em tudo. Mas você deveria, sim, se aprofundar nas coisas que mais importam, aquelas que geram maior valor para sua carreira. Me refiro aos tais dos fundamentos que muita gente fala, mas vou falar mais a respeito disso em outro tópico.

Como Remediar

Este erro talvez seja o mais difícil de remediar, porque a solução envolve uma dose alta de autoconhecimento e um senso muito forte de priorização.

No geral, a dica é: defina UM ponto de evolução para sua carreira, e foque nele por um tempo considerável, até avaliar que fez progresso.

Alguns exemplos de pontos de melhoria:

Melhorar meus conhecimentos de paralelismo, concorrência, e performance
Aprender os principais design patterns e saber aplicá-los em projetos reais
Adquirir habilidades avançadas em SQL
Aprender uma nova linguagem e chegar em um nível produtivo

Não é fácil identificar este ponto de melhoria, mas aqui vão algumas dicas:

Peça feedback dos gestores e colegas.
Converse com algum mentor técnico em quem você confia.
Se você está ativamente participando de processos seletivos para vagas e tem falhado, analise os pontos nos quais foi mal nas entrevistas para identificar onde melhorar.
Se não está ativamente procurando, finja que está. Peça para algum amigo ou mentor fazer uma mock interview com você, e depois peça feedback honesto.

Falta de Consistência

O que é melhor, dedicar 30 minutos por dia pra aprender, todos os dias, ou 5 horas no final de semana, uma vez a cada três meses? A resposta é óbvia.

A nossa profissão é prática, é necessária prática deliberada e consistente para que você internalize as coisas que aprende a saiba usar quando chegar a hora.

Consequências

As consequências aqui são bem óbvias, né? Simplesmente não tem como fazer progresso se você não se esforça com consistência. Isso na verdade se aplica em praticamente qualquer coisa na vida: atividade física, aprendizado de idiomas, tocar um instrumento, e por aí vai.

Se você investe, por exemplo, 1 hora por semana para aprender algo, isso dá um total de cerca de 51 horas no ano. Agora, se você aprender 15 minutos todos os dias, isso dá um total de 5475 minutos no ano, o que dá mais de 91 horas!

Estudar só uma vez por semana tem outra desvantagem. Se surgir algum imprevisto e você precisar faltar, quando voltar já terão se passado duas semanas. Assim, fica complicado manter o ritmo; você precisa lembrar de onde parou 14 dias atrás, e retomar o contexto perdido não é nada fácil.

Como Remediar

Solucionar esse erro requer pensar em estratégias para que o aprendizado se torne uma parte natural da sua rotina diária.

Para começar, defina o tempo **que você vai dedicar diariamente, de forma realista. Não adianta se comprometer com 2 horas de aprendizado diário se a sua rotina simplesmente não permite isso.

Outra coisa essencial é escolher o horário do seu tempo de aprendizado. Pra fixar bem o hábito, o ideal seria que fosse no mesmo horário todos os dias. Ao escolher esse horário, leve em consideração como seus níveis de energia mudam durante o dia. Você é uma pessoa matinal? Coloque seu tempo de aprendizado na parte da manhã. Do contrário, à noite.

Vou dar o exemplo do que funciona pra mim. Eu sei que se for deixar meu tempo de aprendizado para depois do trabalho, vou estar muito cansado e provavelmente não vou fazer. Então, para mim, o melhor é reservar cerca de 50 minutos antes do trabalho para o aprendizado.

Pra fazer do aprendizado um hábito, a chave é integrar na rotina e diminuir o atrito. Sabe aquela galera que dorme de roupa de academia? Mesma ideia pro estudo. Deixe o PC ligado com o VS Code aberto no seu projeto, ou configure o navegador pra abrir direto no curso da Udemy. Quanto mais fácil começar, melhor.

Também é interessante que a hora de decidir o que aprender e a hora de aprender sejam momentos distintos. Se você tem 50 minutos por dia para o aprendizado, mas gasta 20 desses minutos todos os dias decidindo o que vai ler/praticar/assistir, você está desperdiçando 40% do seu tempo.

Então vai a dica: no sábado, você vai definir a sua rotina de aprendizado para a semana seguinte. Você criar uma planilha definindo os dias e o que você vai fazer, ou criar um board no Trello, ou mesmo usar papel e caneta, não importa. O importante é você já ter isso definido de antemão. Aí, nos dias da semana, você simplesmente confere e segue o planejamento feito.

Finalmente, algo que funciona para muitas pessoas é fazer algum tipo de compromisso público. Você declara, publicamente—por exemplo, no seu Linkedin—que vai estudar sem faltar durante x dias. O simples fato de ter feito esse compromisso frequentemente ajuda as pessoas a manterem a rotina sem faltar.

Uma iniciativa legal nesse sentido é o 100 Dias de Código, que incentiva pessoas a codarem durante 100 dias seguidos, sem falta, interagindo com outros participantes no processo.

Subestimar a Importância das Bases

Muita gente subestima a importância de se aprender os fundamentos da computação. Sim, estou falando daquelas coisas chatas que você não gostava de estudar na faculdade: algoritmos e estruturas de dados, teoria da computação, complexidade de algoritmos, e por aí vai.

Esse pessoal argumenta que você não precisa saber dessas coisas todas pra fazer o seu código funcionar. Sim, isso pode ser verdade boa parte do tempo, mas não sempre.

A gente pode pensar na computação como várias camadas que abstraem a camada anterior. Quando você está trabalhando em uma camada, você geralmente não precisa se preocupar com as outras. Isso é uma coisa boa, e é literalmente o motivo pelo qual a gente usa abstrações: “esconder” coisas que não são essenciais, diminuindo a complexidade do que você precisa lidar.

Consequências

Infelizmente, as abstrações não são perfeitas. Como já nos advertiu Joel Spolsky mais de 20 anos atrás, as abstrações em algum momento vazam.

Em outras palavras: só porque você usa um ORM não significa que você não tem que saber SQL. Mesmo quem usa uma linguagem gerenciada como C# ou Java pode se beneficiar de ter um entendimento sobre gerenciamento de memória: no mínimo, você vai ser capaz de escrever código que usa lifetimes de maneira correta, não cria alocações desnecessárias e coloca pressão no garbage collector.

Falta de entendimento de complexidade de algoritmos pode derrubar um sistema. Você testa localmente seu código com algumas poucas centenas de valores, mas quando aquilo vai ao ar e tem que lidar com milhões de itens, ele simplesmente não dá conta.

Em resumo: você consegue fazer algo que “funciona” sem conhecimento de fundamentos. Porém, funciona em parte dos cenários, parte do tempo, com desempenho inaceitável, e sem levar em conta edge cases.

Além dos problemas que a falta de uma base sólida pode causar nos sistemas em que você trabalha, este erro pode trazer outra consequência bem séria para sua carreira.

Sim, estou falando de você não ser capaz de passar nos processos seletivos das empresas. É muito comum que empresas, principalmente as de fora do país, utilizem desafios técnicos que requerem um bom conhecimento em tópicos como algoritmos, estrutura de dados, complexidade, concorrência e paralelismo, o modelo de memória da sua linguagem preferida, entre outros.

Não ter esse conhecimento significa ser reprovado sumariamente nos processos.

Solução

Se você não tem faculdade, recomendo fortemente que estude Ciência da Computação. Caso já tenha terminado a faculdade mas esqueceu todos aqueles tópicos, procure relembrar/reforçar esses conceitos.

Na internet você pode achar de sobra conteúdo sobre Ciência da Computação. Por exemplo, o projeto Teach Yourself Computer Science tem um roadmap de tópicos para aprender, com bibliografia e vídeos de aulas de universidades renomadas.

O NeetCode é um site que traz um roadmap de estudo de algoritmos e estruturas de dados. Também oferece cursos e a funcionalidade de praticar questões reais usadas em entrevistas de emprego.

Viver Embaixo de Uma Pedra (Não se antenar com o que está acontecendo)

Achei que seria interessante que o último erro fosse exatamente o oposto do primeiro. Enquanto o erro que abre a lista era “apenas consumir conteúdo e achar que está aprendendo”, esse aqui é “nunca consumir conteúdo nenhum.”

Por Que Isso é Um Problema?

Nós trabalhamos em uma área que muda constantemente, e cada vez mais rápido. Não se manter atualizado pode levar a:

Obsolescência das suas habilidades
Perda de oportunidades de carreira
Dificuldade em resolver problemas usando abordagens mais eficientes
Falta de inspiração para inovação no seu trabalho diário

Em outras palavras: falta de atualização prejudica seu desempenho no seu trabalho atual, e ao mesmo tempo diminui suas chances de conseguir um potencial novo emprego. Não é isso que você quer, né?

Encontrando o equilíbrio

Por um lado, utilizar cada segundo livre para consumir cada podcast/artigo/vídeo que seja possível não é uma boa estratégia. É como comer muita porcaria que não é nutritiva: você vai se sentir cheio, mas aquela comida não vai trazer os benefícios que seu corpo precisa.

Mas por outro lado, não consumir conteúdo nenhum é igualmente ruim. Como desenvolvedor, é importantíssimo que você tenha pelo menos uma noção do que está acontecendo no mundo do desenvolvimento de software.

O que manter no radar

Aqui vai uma pequena lista de coisas que seria interessante manter no seu radar:

Lançamento de livros técnicos sobre temas que você se interessa, ou de autores que você já acompanha
Novas funcionalidades da versão mais recente da sua linguagem ou framework principais
Ferramentas ou técnicas que podem facilitar a sua vida
Tendências emergentes na indústria (por exemplo, IA.)

Onde encontrar conteúdo relevante

Existem muitas fontes de informação valiosas para desenvolvedores. Aqui estão algumas sugestões:

Reddit:
- r/programming para um apanhado geral
- Subreddits específicas como r/csharp, r/java, r/golang, etc.
Hacker News: Excelente para notícias e discussões sobre tecnologia em geral
YouTube:
- Pesquise por canais relacionados aos seus interesses específicos
- Assista a palestras de conferências de tecnologia
Blogs técnicos:
- De empresas de tecnologia (por exemplo, blog de engenharia do Netflix, Spotify, etc.)
- De desenvolvedores influentes na sua área
Podcasts de tecnologia: Ótimos para consumir informação enquanto faz outras atividades

Conclusão

Chegamos ao fim da lista. Espero que o compilado de erros de aprendizado que você acabou de ler seja útil para sua carreira. Com essa lista eu cobri o que não fazer, mas o que você deve fazer então?

Talvez no futuro eu escreva um post apenas sobre isso: como aprender da maneira correta, e no que focar. Deixa aí nos comentários caso você se interesse em algo assim.

Mas, por enquanto, para saber o que fazer, basta imaginar uma estratégia de aprendizado que seja o contrário dos erros acima:

Aprenda com consistência, de preferência um pouco todos os dias;
Tenha foco: privilegia um ponto principal de melhoria por vez;
Prefira um aprendizado baseado em projetos, suplementado em partes por consumo de conteúdo
Ao consumir conteúdo, sempre aplique o que aprendeu de alguma forma prática
Aprender sobre ferramentas é importante, mas ter fundamentos sólidos é mais importante

Agora vem a dica mais importante que eu posso deixar.

Feito é melhor que perfeito.

Pulou um dia de aprendizado? Não tem importância, continue no próximo. Dedicou 30 minutos ao seu projeto ao invés dos 50 que tinha planejado? Ainda é infinitamente melhor do que não ter feito nada.

Tendências são mais importantes do que data points. Estar indo na direção certa é mais significativo do que metas arbitrárias do tipo “vou ler 6 livros técnicos em 2024”.

É difícil lidar com a pressão de desenvolvimento constante que a gente sente nessa área, eu sei bem disso. Na medida do possível, tente relaxar. Não se martirize demais. Você está indo na direção certa.

Só o fato de ter lido até o final um post de quase 4 mil palavras demonstra que você é muito mais interessado(a) em seu desenvolvimento que a maioria. Por isso, eu lhe agradeço muito. Se precisar de ajuda, não hesite em entrar em contato.

Erro 'Git Detached Head': O Que Significa e Como Resolver

Mon, 16 Sep 2024 00:00:00 +0000

ℹ️ Info

Nota editorial: Eu originalmente escrevi este post para o blog da Cloudbees. Você pode ler o original, em inglês, no site deles.

Índice

Introdução
Reproduzindo o “Problema”
O que é um HEAD no Git?
- Você está no estado ‘detached HEAD’?
Benefícios de um HEAD Desanexado
Como Corrigir um HEAD Desanexado no Git?
Removendo a Mensagem “Git Detached HEAD”
Conclusão

Introdução

Iniciantes no Git frequentemente ficam confusos com algumas das mensagens que esta ferramenta de controle de versão apresenta. A mensagem “You are in ‘detached HEAD’ state” (Você está no estado ‘HEAD desanexado’) é certamente uma das mais estranhas. Após se deparar com essa mensagem, a maioria das pessoas começa a pesquisar freneticamente no Google por termos como “git detached HEAD”, “git detached HEAD fix”, ou similares, buscando qualquer coisa que possa ajudar. Se esse é o seu caso, você veio ao lugar certo.

Aqui está a primeira coisa que você deve saber: você não fez nada de errado. Seu repositório não está quebrado nem nada parecido. A expressão “Detached HEAD” pode soar um tanto bizarra, mas é um estado perfeitamente válido em um repositório Git. Claro, não é o estado normal, que seria - você adivinhou! - quando o HEAD está anexado. A segunda coisa que você precisa saber é que voltar ao normal é super fácil. Se você só quer fazer isso e seguir com o seu dia, vá para a seção “Como corrigir um HEAD desanexado no Git?” deste post para ver como é feito.

Mas se você quer saber mais - e eu acho que quer - fique por aqui e nós vamos te ajudar. O que significa HEAD no Git? O que significa estar anexado ou desanexado? Essas são o tipo de perguntas que responderemos neste post. Ao final dele, você terá uma melhor compreensão dos fundamentos do Git, e HEADs desanexados nunca mais te incomodarão. Bora começar?

Git Detached HEAD: Reproduzindo o “Problema”

Vamos começar com uma rápida demonstração de como chegar ao estado de HEAD desanexado. Criaremos um repositório e adicionaremos alguns commits a ele:

mkdir git-head-demo
cd git-head-demo 
git init
touch file.txt
git add .
git commit -m "Create file"
echo "Hello World!" > file.txt
git commit -a -m "Add line to the file"
echo "Second file" > file2.txt
git add .
git commit -m "Create second file"

Com os comandos acima, criamos uma nova pasta com um novo repositório dentro dela. Em seguida, criamos um novo arquivo vazio e fizemos o commit com a mensagem “Criar arquivo”. Depois, adicionamos uma linha a esse arquivo e fizemos o commit da alteração, com a mensagem “Adicionar linha ao arquivo”. Por fim, criamos outro arquivo com uma linha de texto e também fizemos o commit. Se você usar o comando git log –oneline, verá algo como isto:

Digamos que, para fins de teste, precisamos ver como as coisas estavam no momento do segundo commit. Como faríamos isso? Na verdade, podemos fazer checkout de um commit da mesma forma que faríamos checkout de branches. Lembre-se, branches são apenas nomes para commits. Então, com base no exemplo de saída acima, executaríamos git checkout 87ec91d. Tenha em mente que, se você estiver seguindo junto e executando esses comandos em seu próprio sistema, o hash para seus commits será diferente dos exemplos. Use o comando log para encontrá-lo.

Após executar o comando, recebemos a mensagem “You are in ‘detached HEAD’ state[…]”. Antes de continuarmos, certifique-se de manter isso em mente: você chega ao estado de HEAD desanexado fazendo checkout diretamente de um commit.

O que é um HEAD no Git?

O que significa HEAD no Git? Para entender isso, precisamos dar um passo atrás e falar sobre os fundamentos.

Um repositório Git é uma coleção de objetos e referências. Os objetos têm relações entre si, e as referências apontam para objetos e para outras referências. Os principais objetos em um repositório Git são commits, mas outros objetos incluem blobs e trees. As referências mais importantes no Git são as branches, que você pode pensar como rótulos que você coloca em um commit.

HEAD é outro tipo importante de referência. O propósito do HEAD é manter o controle do ponto atual em um repositório Git. Em outras palavras, HEAD responde à pergunta: “Onde eu estou agora?”

Por exemplo, quando você usa o comando log, como o Git sabe de qual commit ele deve começar a exibir os resultados? HEAD fornece a resposta. Quando você cria um novo commit, seu pai é indicado pelo local para onde o HEAD está apontando atualmente.

Você está no estado ‘detached HEAD’?

Você acabou de ver que HEAD no Git é apenas o nome de uma referência que indica o ponto atual em um repositório. Então, o que significa estar anexado ou desanexado?

Na maioria das vezes, HEAD aponta para um nome de branch. Quando você adiciona um novo commit, a referência do seu branch é atualizada para apontar para ele, mas o HEAD permanece o mesmo. Quando você muda de branch, o HEAD é atualizado para apontar para o branch para o qual você mudou. Tudo isso significa que, nesses cenários, HEAD é sinônimo de “o último commit no branch atual”. Este é o estado normal, no qual HEAD está anexado a um branch.

Uma representação visual do nosso repositório de demonstração seria assim:

Como você pode ver, HEAD aponta para o branch master, que aponta para o último commit. Tudo parece perfeito. Após executar git checkout 87ec91d, o repositório fica assim:

Este é o estado de HEAD desanexado; HEAD está apontando diretamente para um commit em vez de um branch.

Benefícios de um HEAD Desanexado

Existem boas razões para você estar no estado de HEAD desanexado? Com certeza!

Como você viu, você desanexa o HEAD fazendo checkout de um commit. Isso já é útil por si só, pois permite que você volte a um ponto anterior na história do projeto. Digamos que você queira verificar se um determinado bug já existia na terça-feira passada. Você pode usar o comando log, filtrando por data, para encontrar o hash do commit relevante. Em seguida, você pode fazer checkout do commit e testar a aplicação, seja manualmente ou executando sua suíte de testes automatizados.

E se você pudesse não apenas olhar para o passado, mas também mudá-lo? É isso que um HEAD desanexado permite que você faça. Vamos revisar como a mensagem de desanexação começa:

Você está no estado 'detached HEAD'.
Você pode olhar ao redor, fazer mudanças experimentais e fazer commits delas,
e você pode descartar quaisquer commits que fizer neste estado sem
impactar nenhum branch, simplesmente mudando de volta para um branch.

Neste estado, você pode fazer mudanças experimentais, efetivamente criando uma história alternativa. Então, vamos criar alguns commits adicionais no estado de HEAD desanexado e ver como nosso repositório fica depois:

echo "Welcome to the alternate timeline, Morty!" > new-file.txt
git add .
git commit -m "Create new file"
echo "Another line" >> new-file.txt
git commit -a -m "Add a new line to the file"

Agora temos dois commits adicionais que descendem do nosso segundo commit. Vamos executar git log –oneline e ver o resultado:

Assim é como o diagrama fica agora:

O que você deve fazer se quiser manter essas mudanças? E o que deve fazer se quiser descartá-las? É isso que veremos a seguir.

Como corrigir um HEAD desanexado no Git?

Você não pode corrigir o que não está quebrado. Como eu disse antes, um HEAD desanexado é um estado válido no Git. Não é um problema. Mas você ainda pode querer saber como voltar ao normal, e isso depende do motivo pelo qual você está nessa situação em primeiro lugar.

Cenário #1: Estou aqui por acidente

Se você chegou ao estado de HEAD desanexado por acidente - ou seja, você não tinha a intenção de fazer checkout de um commit - voltar é fácil. Basta fazer checkout do branch em que você estava antes:

git checkout <nome-do-branch>

Se você está usando o Git 2.23.0 ou mais recente, você também pode usar switch em vez de checkout:

git switch <nome-do-branch>

Cenário #2: Fiz mudanças experimentais e quero descartá-las

Você entrou no estado de HEAD desanexado e fez alguns commits. O experimento não levou a lugar nenhum, e você não vai mais trabalhar nele. O que você faz? Você faz o mesmo que no cenário anterior: volta para o seu branch original. As mudanças que você fez enquanto estava na linha do tempo alternativa não terão nenhum impacto no seu branch atual.

Cenário #3: Fiz mudanças experimentais e quero mantê-las

Se você quer manter as mudanças feitas com um HEAD desanexado, basta criar um novo branch e mudar para ele. Você pode criá-lo logo após chegar a um HEAD desanexado ou após criar um ou mais commits. O resultado é o mesmo. A única restrição é que você deve fazê-lo antes de retornar ao seu branch normal.

Vamos fazer isso em nosso repositório de demonstração:

git branch alt-history
git checkout alt-history

Observe como o resultado de git log –oneline é exatamente o mesmo de antes (a única diferença sendo o nome do branch indicado no último commit):

Poderíamos apenas executar git branch alt-history, e estaríamos prontos. Essa é a nova - e final - versão do nosso diagrama:

Removendo a mensagem “Git Detached HEAD”

Antes de concluir, vamos compartilhar uma última dica rápida. Agora que você entende tudo sobre HEAD desanexado no Git e sabe que não é tão grave assim, ver essa mensagem toda vez que fizer checkout de um commit pode se tornar cansativo. Felizmente, há uma maneira de não ver mais o aviso. Basta executar o seguinte comando:

git config advice.detached head false

Fácil, não é? Você também pode usar o modificador –global se quiser que a mudança se aplique a todos os repositórios e não apenas ao atual.

Git Detached HEAD: Menos assustador do que parece

Uma mensagem falando sobre cabeças não estarem anexadas não soa como uma mensagem de erro de software rotineira, certo? Bem, não é uma mensagem de erro.

Como você viu neste post, um HEAD desanexado não significa que algo está errado com seu repositório. Detached HEAD é apenas um estado menos usual em que seu repositório pode estar. Além de não ser um erro, pode ser bastante útil, permitindo que você execute experimentos que depois pode escolher manter ou descartar.

Gostaria de aprender mais sobre Git? Confira alguns dos seguintes posts:

Obrigado por ler!

[Tradução] Tudo o que você precisa saber sobre configuração e gerenciamento de segredos em .NET

Tue, 23 Jul 2024 00:00:00 +0000

ℹ️ NOTA

Este post é uma tradução, cuja publicação foi autorizada pelo autor. Caso tenha interesse, leia o artigo original, em inglês..

Eu decidi não traduzir as imagens, pois achei que seria muito trabalhoso. Portanto, as figuras que você verá são as mesmas do artigo original, com as informações nelas em inglês.

Em respeito ao autor, procurei deixar o artigo o mais próximo possível do original: mantive call to actions que o autor faz para suas palestras e conteúdos, e também mantive um pedido de contribução financeira ao final do artigo.

A partir do índice, inicia-se o artigo de autoria de Sander ten Brinke. Após a conclusão do artigo, eu volto com algumas palavras antes de finalizar. Boa leitura!

Índice

Introdução
Configuração no .NET
options pattern
Gerenciamento de segredos durante o desenvolvimento
Meu modelo para gerenciamento de configuração
Usando o Azure para armazenar a configuração
Finalizando
- Links para a demo
- Links para a documentação oficial
Carlos de volta

ℹ️ Info

Este post é um complemento da minha palestra Keep it secret, keep it safe with .NET! Se você não puder assistir a uma sessão dessa palestra, poderá ler este post em vez disso! Dessa forma, o maior número possível de pessoas poderá aprender sobre o sistema de configuração do .NET e como manter os segredos em segurança!

Minha palestra oferece algumas informações mais detalhadas, portanto, se quiser saber mais, dê uma olhada na minha página Speaking para ver quando e onde darei essa palestra novamente! Você também pode entrar em contato se quiser que eu dê essa palestra em seu evento!

Introdução

Se você já escreve código há algum tempo, provavelmente já usou configuração de alguma forma. Pense em feature flags, configurações de log, configurações de autenticação etc. Talvez você tenha usado um arquivo de configuração com algumas configurações para o seu aplicativo ou talvez tenha usado variáveis de ambiente. Talvez você tenha usado ambos!

Também é provável que você tenha interagido com segredos, que também considero parte de um sistema de configuração. Pense em strings de conexão e chaves de API. Elas devem ser sempre seguras!

A configuração no .NET mudou radicalmente desde a introdução do .NET Core. Já se foi o tempo em que se usavam vários arquivos Web.config e agora temos um sistema muito mais flexível. No entanto, um sistema flexível também pode ser um sistema complexo. É por isso que eu quis criar uma palestra e uma publicação no blog em que você aprenderá como funciona o sistema de configuração do .NET e como usá-lo de forma otimizada. Você também aprenderá a manter seus segredos seguros, tanto localmente quanto em produção, usando o poder da nuvem do Azure!

ℹ️ Info

Este post contém tudo que você precisa saber sobre configuração e gerenciamento de segredos no .NET. Ela não aborda todos os detalhes, mas abrange tudo o que acredito que um desenvolvedor .NET tem que saber. Considere-o um guia de bolso útil que você pode usar ou enviar a outras pessoas quando elas tiverem dúvidas sobre configuração e gerenciamento de segredos no .NET.

Acho que esta post é muito útil porque são necessárias múltiplas horas para encontrar e ler completamente a documentação da Microsoft sobre esses tópicos. Se quiser saber mais, você encontrará links para a documentação oficial no final do post.

Vamos começar!

Configuração no .NET

O sistema de configuração do .NET é muito flexível! Você pode usar vários provedores de configuração, sendo que cada um deles pode ter um formato de configuração diferente:

Uma visão geral do sistema de configuração do .NET.
Extraído da documentação oficial

Outras fontes podem ser arquivos como .xml, .ini e muito mais. Você pode até mesmo conectar seu sistema de configuração à nuvem, o que faremos mais adiante!

O Básico

Como você pode ver, toda a sua configuração pode ser acessada usando a interface IConfiguration. Com isso, você pode recuperar seus valores de uma maneira fortemente tipada. Um exemplo:

public IConfiguration Configuration { get; set; }

public string GetApiKey()
{
    // GetValue<> permite que você passe o tipo de retorno
    string method1 = Configuration.GetValue<string>(“ApiKey”); 

    // A variante do indexador sempre retorna uma string
    string method2 = Configuration[“ApiKey”]; 

    return method1;
}

Você perceberá que não estamos especificando qual provedor deve ser usado para recuperar a ApiKey. Isso ocorre porque isso não deveria importar; a IConfiguration esconde toda essa complexidade de nós e, portanto, cria flexibilidade. O sistema de configuração decide qual provedor usar com base na ordem dos provedores. Falaremos mais sobre isso mais tarde!

Acesso a dados estruturados

Um recurso muito avançado do sistema de configuração do .NET é o fato de ele oferecer suporte a dados estruturados. Isso é muito útil porque permite que você agrupe valores de configuração relacionados. Todos os provedores oferecem suporte a dados estruturados, mas se você já trabalhou com um projeto ASP.NET Core, provavelmente reconhecerá o mais comum, que é appsettings.json. O JSON a seguir é um exemplo de um arquivo desse tipo:

{
  “Logging": {
    “LogLevel": {
      “Default” (Padrão): “Informações”,
      “Microsoft.AspNetCore": “Warning”
    }
  },
  “AllowedHosts": “*”,

  “ConnectionStrings": {
    “Banco de dados": “CONNECTIONSTRING_HERE”
  },

  “Features” (Recursos): {
    “EnableNewUI": false
  }
}

Você pode imaginar o objeto raiz e as seções Logging, ConnectionStrings e Features como “dados estruturados”.

Para interagir com essas seções no .NET, você pode usar o código a seguir.

⚠️ Aviso

O código a seguir não é a melhor maneira de interagir com dados estruturados! Falaremos sobre maneiras melhores (usando o padrão Options) mais adiante.

public IConfiguration Configuration { get; set; }

// ...

public IConfigurationSection GetFeaturesSection()
{
    // GetSection retorna nulo quando a seção não pode ser encontrada
    var method1 = Configuration.GetSection(“Features”);

    // GetRequiredSection dispara uma exceção quando a seção não pode ser encontrada.
    // SEMPRE prefira esse método ao GetSection para evitar bugs desagradáveis!
    var method2 = Configuration.GetRequiredSection(“Features”);

    return method2;
}

public bool GetEnableNewUI()
{
    return Configuration.GetValue<bool>(“Features:EnableNewUI”);
}

A IConfigurationSection fornece a mesma API que a IConfiguration, portanto, você pode chamar featuresSection.GetValue<bool>(“EnableNewUI”) para obter o valor dessa seção. Também é possível acessar diretamente um valor de configuração que existe dentro de uma seção usando um :, que pode ser visto em uso no método GetEnableNewUI.

ℹ️ Info

Os dados estruturados não se limitam aos arquivos JSON. Todos os provedores são compatíveis com eles, embora a sintaxe para especificar uma seção possa ser diferente. Por exemplo, para fornecer um valor para EnableNewUI usando uma variável de ambiente, você terá que criar uma chamada Features__EnableNewUI.

Como tudo isso funciona?

Estamos usando IConfiguration em alguns exemplos. Você deve estar se perguntando como tudo isso funciona nos bastidores; como criar uma instância de IConfiguration e como configurá-la? Vamos dar uma olhada!

Para criar uma instância de IConfiguration, você precisará usar a classe ConfigurationBuilder (ou outra classe que implemente IConfigurationBuilder). Essa classe usa o padrão Builder para que você possa adicionar vários provedores. No final, você chama Build() e acaba com um IConfigurationRoot. É a mesma coisa que IConfiguration, mas também tem uma lista de todos os provedores que você adicionou. Você nunca deve usar o IConfigurationRoot diretamente, pois não deve acessar os provedores por baixo do pano. Um exemplo:

var builder = new ConfigurationBuilder();

builder.AddJsonFile(“sharedsettings.json”);
builder.AddJsonFile(“appsettings.json”);
builder.AddEnvironmentVariables();
// E assim por diante...

IConfigurationRoot configuration = builder.Build();

A ordem desses provedores é muito importante porque se trata de um sistema em camadas. Dê uma olhada na imagem a seguir:

Uma visão geral da importância da ordem dos provedores de configuração.
ASP.NET Core in Action, Second Edition (Permissão concedida pelo autor Andrew Lock)

Imagine que sharedsettings.json tenha um valor para todos os valores de configuração usados pelo aplicativo. O appsettings.json e as Variáveis de ambiente contêm um subconjunto desses valores. Como o provedor para as variáveis de ambiente foi adicionado por último, ele tem a prioridade mais alta. Portanto, se você quiser recuperar um valor de configuração chamado ApiKey, o sistema examinará primeiro as variáveis de ambiente. Se ele existir, será retornado, mesmo que outros provedores também contenham um valor para ApiKey. No entanto, se as variáveis de ambiente não contiverem um valor para ApiKey, ele passará para o provedor que foi adicionado antes dele e pesquisará lá, e assim por diante.

Os valores default

Talvez você esteja um pouco confuso neste ponto. Eu certamente estava quando aprendi sobre o IConfigurationBuilder e a importância dessas camadas. Por quê? Bem, percebi que estava usando o IConfiguration em muitos projetos, mas nunca tinha ouvido falar do IConfigurationBuilder antes. Então, como eu poderia estar usando o IConfiguration?

Isso funciona porque, se você trabalhar em um aplicativo .NET que usa um Host, ele definirá todo um sistema de configuração para você por padrão! Por exemplo, projetos ASP.NET Core e workers services usam um Host, portanto, na maioria dos projetos, isso será feito para você! Agora vamos dar uma olhada em como isso funciona.

Em um aplicativo ASP.NET Core padrão, o seguinte é configurado para você.

Provedor	Exemplo	Notas
appsettings.json	{ “Key”: “default value” }
appsettings.{ENVIRONMENT}.json	{ “Key”: “development value” }
user secrets (desenvolvimento)	dotnet user-secrets set “key” “development value”	Também pode ser definido em IDEs. Mais sobre isso posteriormente.
Variáveis de ambiente	Powershell: setx key “valor do ambiente” Bash: export key=‘valor do ambiente’	Também pode ser definido em IDEs. Muito popular em implantações do Docker/Kubernetes.
Argumentos da linha de comando	dotnet run –key “important value”	Também pode ser definido nos IDEs.

O item no topo tem a prioridade mais baixa. Portanto, se você chamar Configuration[“key”], obterá como resultado important value, mesmo que o User Secrets também forneça um valor.

ℹ️ Info

O provedor User secrets só é adicionado quando o Environment é definido como Development. Os ambientes serão tratados a seguir. Os user secrets são tratados em profundidade mais adiante.

O Visual Studio (e outros IDEs, como o JetBrains Rider) oferecem suporte à configuração de variáveis de ambiente/argumentos de linha de comando em seu IDE quando você acessa as propriedades do projeto. No entanto, aconselho contra o uso disso durante o desenvolvimento. Eu nunca uso variáveis de ambiente ou argumentos de linha de comando durante o desenvolvimento porque é mais difícil editá-los do que simplesmente abrir um arquivo. Armazená-los em appsettings.Development.json (que será abordado a seguir) é mais conveniente para você e seus colegas.

Configuração e Ambientes

O provedor appsettings.{ENVIRONMENT}.json é um pouco diferente dos outros provedores. Isso ocorre porque ele depende do ambiente do aplicativo. O ambiente atual do aplicativo é lido a partir do valor da variável de ambiente DOTNET_ENVIRONMENT ou ASPNETCORE_ENVIRONMENT. Se o seu projeto não for um projeto ASP.NET Core, o aplicativo verificará apenas DOTNET_ENVIRONMENT. Os projetos ASP.NET Core retornam para DOTNET_ENVIRONMENT quando ASPNETCORE_ENVIRONMENT não existe.

O ambiente será considerado como Production quando essas variáveis de ambiente não existirem.

Quando você cria um projeto ASP.NET Core, um arquivo chamado launchSettings.json será criado na pasta Properties. Aqui, você pode ver que a variável de ambiente ASPNETCORE_ENVIRONMENT está definida como Development:

{
  // Muitos outros detalhes foram removidos desse arquivo para fins de brevidade
  “$schema": “https://json.schemastore.org/launchsettings.json”,
  “profiles": {
    “MY_PROJECT": {
      “commandName": “MY_PROJECT”,
      “applicationUrl": “https://localhost:7237;http://localhost:5292”,
      “environmentVariables": {
        “ASPNETCORE_ENVIRONMENT": “Development”
      }
    }
  }
}

O resultado do sistema de configuração trabalhando em conjunto com o ambiente do aplicativo resulta em um recurso muito poderoso, pois permite que você crie arquivos de configuração diferentes para cada ambiente.

Você pode armazenar valores padrão em appsettings.json e substituí-los em appsettings.Development.json, appsettings.Test.json, appsettings.Staging.json e appsettings.Production.json.

Por exemplo, digamos que você tenha terminado o novo design de uma página de checkout de uma loja virtual. Ele ainda precisa ser testado e revisado por outras pessoas em um ambiente de teste, mas ainda não deve entrar em produção. Esse parece ser um caso de uso perfeito para feature flags! Você poderia criar um feature flag chamado EnableNewCheckoutUI e defini-lo como false em appsettings.json como o valor padrão. Em seguida, você pode substituir esses valores em appsettings.Development.json e appsettings.Test.json para que eles sejam ativados somente lá:

// appsettings.json
{
  “FeatureFlags": {
    “EnableNewCheckoutUI": false
  }
}

// appsettings.Development.json e appsettings.Test.json
{
  “FeatureFlags": {
    “EnableNewCheckoutUI": true
  }
}

Você não está limitado aos nomes de ambiente mencionados acima; eles são apenas os padrões que o .NET usa. Se quiser usar um nome diferente, configure a variável de ambiente ASPNETCORE_ENVIRONMENT com o nome de sua escolha e crie um arquivo appsettings.ENV_NAME.json correspondente. A única outra coisa que você precisa fazer é garantir que o ambiente em que você executa seu aplicativo tenha ASPNETCORE_ENVIRONMENT ou DOTNET_ENVIRONMENT definido com o valor correto.

Tratando a Configuração Como Código

Anteriormente, elogiei o sistema de configuração do .NET e o IConfiguration por serem flexíveis e ricos em recursos. Falei sobre seu suporte a dados estruturados e sobre a recuperação de valores de uma hierarquia de configuração mais profunda. Mas você sabia que pode fazer muito mais com dados estruturados?

Digamos que nosso aplicativo se comunique com uma API externa usando HTTP. Para isso, precisamos de um ApiUrl, ApiKey e talvez queiramos configurar um TimeoutInMilliseconds. Do ponto de vista do código, talvez queiramos armazenar esses valores em uma classe (ou record) porque eles pertencem um ao outro:

public class ExternalApiSettings
{
    public string ApiUrl { get; set; }
    public string ApiKey { get; set; }
    public int TimeoutInMilliseconds { get; set; }
}

Em seguida, teríamos uma classe ExternalApiClient que usa a configuração e a classe que acabamos de criar:

public class ExternalApiClient
{
    private readonly IConfiguration _configuration;

    public Foo(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    public void CallExternalApi()
    {
        IConfigurationSection externalApiSettingsSection = _configuration.GetRequiredSection(“ExternalApiSettings”);
        
        // Método 1 (Get<TType>() obtém os valores dessa seção e os mapeia em uma nova instância da classe fornecida)
        ExternalApiSettings settings1 = externalApiSettingsSection.Get<ExternalApiSettings>(); 

        // Método 2 (Bind() espera uma instância existente de um tipo e mapeará os valores para essa instância existente)
        ExternalApiSettings settings2 = new();
        _configuration.GetRequiredSection(“ExternalApiSettings”).Bind(settings2);

        // Faça algo com essas configurações aqui...
    }
}

Isso parece bem legal, certo? Em vez de realizar 3 chamadas para obter cada propriedade de configuração relacionada à API individualmente, podemos mapeá-las em um objeto fortemente tipado. Agora podemos tratar nossa configuração como código! Poderíamos até criar métodos em nossa classe ExternalApiSettings para torná-la ainda mais poderosa!

No entanto, há algumas desvantagens importantes nessa abordagem.

Desvantagens

A primeira desvantagem é que o nosso ExternalApiClient requer uma instância de IConfiguration para funcionar. Essa é uma dependência muito grande e um grande desperdício, considerando que ele usa apenas 3 valores de configuração! Além disso, essa classe agora pode acessar outros valores de configuração, como uma string de conexão a um banco de dados, configurações de registro, feature flags etc., mesmo que não precise dessas informações.
A segunda desvantagem é que essa classe está violando o princípio da responsabilidade única. Ela não é responsável apenas por chamar a API externa, mas também por interagir com o sistema de configuração para poder chamar essa API externa.
Como essa classe interage diretamente com o sistema de configuração, ela depende de sua estrutura e, portanto, está fortemente acoplada. Qualquer alteração na seção de configuração ExternalApiSettings (como o nome ou os nomes de seus filhos) causaria problemas em tempo de execução.

Então, o que podemos fazer em relação a isso? Reescrevê-la em Rust 🦀? Não, podemos usar o options pattern!

Options Pattern

O options pattern (“padrão de opções”) permite que você faça um uso ainda melhor do sistema de configuração do .NET 🚀! Ele permite a você desacoplar seu aplicativo do sistema de configuração e adiciona muitos recursos poderosos a esse sistema, como:

Injeção de dependência
Validação
Diferentes tempos de vida de configuração
E muito mais!

Para começar a usar o options pattern de forma eficaz, é necessário criar classes/records das suas seções de configuração. Já fizemos isso no exemplo anterior, portanto, vamos continuar com ele:

public class ExternalApiSettings
{
    public string ApiUrl { get; set; }
    public string ApiKey { get; set; }
    public int TimeoutInMilliseconds { get; set; }
}

Injeção de dependência

O options pattern funciona muito bem com a injeção de dependência! Para isso, basta registrar sua classe/record de opções na coleção de serviços. Dependendo do seu projeto, o ponto de entrada para isso pode ser o método Startup.cs -> ConfigureServices(IServiceCollection services) ou em algum lugar em seu Program.cs.

services.Configure<ExternalApiSettings>(configuration); // Passe em uma instância existente de IConfiguration

Isso adicionará uma instância de IOptions<ExternalApiSettings> ao seu contêiner de injeção de dependência. Para ver os benefícios dessa abordagem, vamos dar uma olhada em como poderíamos melhorar nosso ExternalApiClient de antes:

public class ExternalApiClient
{
    private readonly ExternalApiSettings _externalApiSettings;

    public ExternalApiClient(IOptions<ExternalApiSettings> options)
    {
        // Importante: o padrão Options é “preguiçoso”. Isso significa que as opções são mapeadas somente quando você as solicita chamando .Value!
        // Isso é feito apenas uma vez, portanto, você não precisa se preocupar com o desempenho.
        _externalApiSettings = options.Value;
    }

    public void CallExternalApi()
    {
        // Faz algo com essas configurações aqui...
    }
}

Isso eliminou todas as desvantagens de antes! Nosso ExternalApiClient não tem mais uma dependência do IConfiguration e não está mais acoplado ao sistema de configuração. Ele também não precisa mais se preocupar com a estrutura do sistema de configuração.

Você pode argumentar que temos uma dependência indireta do sistema de configuração por causa da chamada .Configure<>(configuration) de antes, mas você não é obrigado a usar esse método para configurar suas opções. Você pode criar uma instância de IOptions<T> usando Microsoft.Extensions.Options.Options.Create() se precisar criar uma instância manualmente, e pode passar quaisquer dados que desejar. Você pode até mesmo criar opções com base em outras dependências usando o método Configure<TDep1,...>() do OptionsBuilder, que será discutido a seguir.

ℹ️ Info

Talvez você se pergunte por que precisamos envolver nossa classe de configurações com uma interface IOptions<>. Isso ocorre porque ela permite que você use alguns recursos mais avançados sobre os quais falaremos a seguir.

Validação

Meu recurso favorito do sistema de configuração do .NET é a facilidade com que é possível validar sua configuração! Acredito que essa seja uma das partes mais importantes de qualquer aplicativo, e não vejo que ela seja usada com frequência. O motivo pelo qual acredito que a configuração é uma das partes mais importantes de qualquer aplicativo é porque ela abriga definições muito importantes do seu aplicativo.

Um aplicativo configurado incorretamente pode ter resultados desastrosos. Na pior das hipóteses, imagine que o seu ambiente de teste esteja se conectando acidentalmente aos recursos do ambiente de produção. Agora imagine que você testaria uma função de exclusão em massa e acidentalmente excluiria todos os seus dados de produção. Isso seria um desastre!

É por isso que queremos validar nossa configuração. Se o nosso aplicativo for iniciado com um sistema de configuração incorreto, queremos sair imediatamente.

Então, como configuramos isso? É mais fácil do que você imagina. Eu gosto de usar Data Annotations para minhas validações de opções quando não preciso de regras de validação complexas, portanto, vamos modificar nosso ExternalApiSettings desta forma:

public class ExternalApiSettings
{
    [Required] // Se o ApiUrl não estiver definido, a configuração é inválida
    public string ApiUrl { get; set; }

    [Required] // Se a ApiKey não for definida, a configuração será inválida
    public string ApiKey { get; set; }

    [Range(1, 1_000_00)] // Se o TimeoutInMilliseconds não for definido (o padrão é 0) ou for maior que 100000, a configuração será inválida
    public int TimeoutInMilliseconds { get; set; }
}

Agora, vamos alterar a forma como registramos essas opções no contêiner de injeção de dependência:

services
    .AddOptions<ExternalApiSettings>()
    .BindConfiguration(“ExternalApiSettings”)
    .ValidateDataAnnotations() // Lança uma OptionsValidationException se a configuração for inválida
    .ValidateOnStart(); // Altamente recomendado!

Em vez de usar Configure<TType>(configuration), agora usamos AddOptions<TType>(). Isso retorna um OptionsBuilder e nos permite usar alguns métodos poderosos.

O primeiro que usamos é o BindConfiguration(). Esse método recupera o IConfiguration do contêiner de injeção de dependência e vincula a seção que passamos. Isso é útil porque não precisamos mais passar manualmente nossa configuração.
Em seguida, chamamos ValidateDataAnnotations(). Isso validará nossa seção de configuração com base nos atributos que definimos nas propriedades.
1. Observação: você precisa instalar o pacote nuget Microsoft.Extensions.Options.DataAnnotations se não tiver esse método disponível.
Por fim, chamamos ValidateOnStart(). Essa etapa é muito importante! Por padrão, suas opções só serão validadas quando você chamar .Value nelas em algum lugar, como em uma classe onde elas são injetadas. Isso significa que seu aplicativo NÃO lançaria um erro e sairia na inicialização quando sua configuração fosse inválida! O ValidateOnStart() validará sua configuração depois que o aplicativo terminar de se inicializar.

Você também pode validar seu código de muitas outras maneiras. Você pode usar a interface IValidatableOptions<> para implementar uma lógica de validação complexa ou pode chamar Validate(Func<TOptions, bool> validation) para escrever uma lógica de validação personalizada como parte do construtor de opções. Você pode até mesmo integrá-lo ao FluentValidation!

Tempos de vida da configuração

Por fim, gostaria de falar sobre o tempo de vida do padrão Options. O IOptions<T> é um singleton. Isso significa que, se um de seus provedores de configuração for atualizado em tempo de execução, as opções não serão atualizadas. Isso ocorre porque as opções são mapeadas apenas uma vez quando você chama .Value sobre elas.

Isso pode ser considerado positivo, pois significa que seu aplicativo não mudará repentinamente de comportamento quando a configuração for alterada. No entanto, você também pode dizer que isso é ruim porque talvez não queira ter que fazer deploy ou reiniciar o aplicativo quando alterar a configuração. Nesse caso, é melhor usar IOptionsSnapshot<T> ou IOptionsMonitor<T>.

Visão geral dos recursos de IOptions, IOptionsSnapshot e IOptionsMonitor

IOptionsSnapshot

Em vez de injetar IOptions<T> em uma de suas classes, você pode injetar IOptionsSnapshot<T>. Isso recarregará esse tipo específico de opções a cada scope. Um escopo no .NET é um termo abstrato. Um escopo pode ser uma solicitação HTTP, por exemplo. Portanto, para cada solicitação HTTP, ele recarregaria as opções e elas permaneceriam consistentes para toda a solicitação. Isso significa que, se você alterar sua configuração, ela só será atualizada em uma nova solicitação.

⚠️ Aviso

Usar IOptionsSnapshot<T> pode causar desempenho ruim.

IOptionsMonitor

O IOptionsMonitor<T> não funciona com escopos. Em vez disso, você precisa chamar .CurrentValue (em vez de .Value) para recuperar a versão atual. No entanto, é preciso ter cuidado com a forma como você acessa a sua configuração! Imagine um cenário em que sua configuração é alterada no meio de uma solicitação HTTP. Chamar .CurrentValue no início e no final de uma solicitação resultaria em valores diferentes, o que cria um risco de sincronização. Você pode registrar uma chamada de retorno usando OnChange() para ser notificado sobre esses eventos.

Essa interface é mais útil em um cenário de trabalho em segundo plano que é instanciado apenas uma vez, mas que se beneficiaria da capacidade de lidar com alterações de configuração.

Gerenciamento de segredos durante o desenvolvimento

Se você vai tirar alguma conclusão dEste post, que seja a seguinte:

❌ Importante

Nunca armazene segredos em seu repositório git! Considere o uso de uma ferramenta de verificação de código como GitHub Advanced Security, GitHub Advanced Security for Azure DevOps ou GitGuardian para evitar que segredos sejam vazados.

Se você armazenar segredos em seu repositório git e o repositório for comprometido, seus segredos também serão comprometidos. Acho que não preciso explicar por que isso é ruim. Então, como podemos evitar que isso aconteça com o .NET?

Usando o provedor de configuração de user secrets (segredos de usuário).

O provedor de configuração de user secrets

Mencionei o provedor de configuração de user secrets anteriormente. Esse provedor de configuração foi criado para desenvolvimento local somente. Ele permite que você armazene segredos em seu computador local sem precisar se preocupar com o risco de eles serem versionados no repositório git, pois são armazenados em um local diferente:

Windows: %APPDATA%\Microsoft\UserSecrets\<user_secrets_id>\secrets.json
Mac e Linux: ~/.microsoft/usersecrets/<user_secrets_id>/secrets.json

Esse arquivo é muito semelhante ao provedor appsettings.json. Basta inserir JSON nele e você poderá acessá-lo com o sistema de configuração do .NET. Quando seu aplicativo for iniciado e sua variável de ambiente ASPNETCORE_ENVIRONMENT ou DOTNET_ENVIRONMENT estiver definida como Development, ele carregará automaticamente o provedor de configuração de user secrets desde que seu projeto esteja configurado para usar esse provedor.

⚠️ Aviso

Mesmo que esse provedor tenha o nome “secret”, esteja avisado! O conteúdo do arquivo secrets.json não é criptografado. Se você trabalha em um ambiente em que armazenar segredos na própria máquina é arriscado, considere usar um armazenamento de segredos externo como o Azure KeyVault durante o desenvolvimento.

Esse provedor de configuração pode ser acessado usando a CLI ou seu IDE favorito. Talvez seja necessário instalar o pacote Microsoft.Extensions.Configuration.UserSecrets caso você não use um Host ou tenha uma configuração personalizada.

Usando User Secrets

CLI

Você pode usar o dotnet cli para interagir com user-secrets abrindo um terminal no diretório em que reside o *.csproj do seu projeto.

# Necessário apenas quando as user-secrets ainda não foram inicializadas
dotnet user-secrets init

# Você pode usar dados estruturados usando dois pontos (:) para separar as chaves
dotnet user-secrets set “ConnectionStrings:Database” “Data Source=...”
dotnet user-secrets set “AdminPassword” “hunter2”
# Outros comandos como “list”, “remove” e “clear” também estão disponíveis

Visual Studio

Clique com o botão direito do mouse em um projeto no Solution Explorer e selecione Manage User Secrets. Um arquivo secrets.json será aberto, no qual você poderá inserir seus segredos.

Visual Studio Code

Instale a extensão .NET Core User Secrets Visual Studio Code. Em seguida, você pode clicar com o botão direito do mouse em um arquivo *.csproj e selecionar Manage User Secrets. Um arquivo secrets.json será aberto, no qual você poderá inserir seus segredos.

JetBrains Rider

Clique com o botão direito do mouse em um projeto no Solution Explorer e selecione Tools > Manage User Secrets. Um arquivo secrets.json será aberto, no qual você poderá inserir seus segredos.

Configurando um projeto que usa user-secrets

Uma desvantagem de usar segredos de usuário durante o desenvolvimento é que, se o seu projeto exigir alguns segredos para ser executado, será necessário executar algumas etapas de configuração após a clonagem do projeto. Tenho duas recomendações para lidar com isso:

Você pode criar um script que recupere os segredos do seu local de armazenamento de segredos e, em seguida, armazene-os em user-secrets, canalizando esses valores para dotnet user-secrets set. Agora você só precisa executar esse script uma vez após clonar o projeto e pronto!
Como alternativa, recomendo atualizar seu README.MD incluindo instruções de configuração que informem ao usuário quais user-secrets devem ser definidos e de onde obter esses valores. Sinta-se à vontade para criar um link para Este post se quiser explicar o que são user-secrets 😉.

Meu modelo para gerenciamento de configuração

Agora que abordamos os conceitos básicos e o uso avançado do sistema de configuração do .NET e como incorporar o gerenciamento de segredos locais, gostaria de mostrar minha “configuração” para o gerenciamento de configuração em um projeto .NET. Quando crio um novo projeto .NET, uso a seguinte configuração:

appsettings.json

O sistema de configuração do .NET permite que você seja muito flexível com todos os diferentes provedores. Isso é ótimo, mas também pode causar confusão quando seu aplicativo estiver usando valores de configuração que você não esperava ou quando não conseguir descobrir de onde vem um valor de configuração específico.

💡 Dica

Use o método IConfigurationRoot.GetDebugView() quando estiver tendo problemas com os valores de configuração. Para fazer isso, obtenha uma instância IConfiguration, converta-a em IConfigurationRoot e inspecione o resultado de GetDebugView().

Para obter mais informações, consulte o fantástico post de Andrew Lock sobre isso.

Eu uso appsettings.json para armazenar um modelo de todos os valores de configuração que meu projeto usa e de onde os valores são recuperados. Esse arquivo também pode conter valores reais quando o arquivo appsettings.json é o único provedor para esse valor de configuração. Gosto muito dessa configuração porque ela me permite ver todos os valores de configuração que meu projeto usa em um só lugar.

{
  “Logging": {
    “LogLevel": {
      “Default” (Padrão): “Informações”,
      “Microsoft.AspNetCore": “Warning”
    }
  },

  “ConnectionStrings": {
    “Database”: “<from-azure-keyvault>” // O Azure Key Vault será discutido na próxima seção
  },

  “ExternalApiSettings": {
    “ApiUrl": “<from-environment-variables>”,
    “ApiKey": “<from-azure-keyvault>”,
    “TimeoutInMilliseconds": 5000
  }
}

appsettings.Development.json

A seguir, temos o arquivo appsettings.Development.json. Esse arquivo pode conter valores de configuração que substituem os valores do appsettings.json, como configurações de registro. Além disso, esse arquivo nunca deve conter segredos! Em vez disso, ele faz referência ao provedor de configuração de user secrets. Isso torna menos provável que as pessoas insiram segredos nesse arquivo, pois elas são levadas a usar o provedor de configuração de user secrets.

{
  “Logging": {
    “LogLevel": {
      “Default”: “Debug”, // As configurações de log são 100% de preferência pessoal, fique à vontade para usar o que quiser
      “Microsoft.AspNetCore": “Warning”
    }
  },

  “ConnectionStrings": {
    “Database”: “<from-user-secrets>” // Cada desenvolvedor pode usar sua própria string de conexão de banco de dados local
  },

  “ExternalApiSettings": {
    “ApiUrl": “dev.externalapi.example.com”,
    “ApiKey": “<from-user-secrets>”
    // Não forneço um valor para TimeoutInMilliseconds porque não tenho problemas com o valor de appsettings.json
  }
}

User Secrets

Por fim, uso o provedor de configuração user secrets para armazenar segredos locais e substituir a configuração não secreta que não quero enviar para o repositório git, como alterar as configurações de log no caso de precisar me aprofundar em um bug. Se eu alterasse esses valores de configuração no arquivo appsettings.Development.json, teria que me lembrar de reverter essas alterações antes de fazer o commit do meu código. Ao usar o provedor de configuração de user secrets, não preciso me preocupar com isso.

{
  “Logging": {
    “LogLevel": {
      “Microsoft.AspNetCore": “Information”
    }
  },

  “ConnectionStrings": {
    “Database”: “Data Source=...”
  },

  “ExternalApiSettings": {
    “ApiKey": “abc123def456ghi7”
  }
}

❓ Pergunta

Como é a sua configuração? O que você acha da minha? Deixe sua opinião nos comentários abaixo!

Usando o Azure para armazenar a configuração

Agora que sabemos como armazenar a configuração e os segredos localmente, é hora de falar sobre a execução de seus aplicativos em ambientes reais. Há muitas maneiras diferentes de configurar a configuração e o gerenciamento de segredos para ambientes não locais, portanto, tudo se resume a conhecer as vantagens e desvantagens dessas abordagens e escolher o que funciona melhor para você. Neste post, você aprenderá a usar o Azure para armazenar sua configuração e seus segredos com segurança.

ℹ️ Info

Embora esta seção seja sobre o Azure, os conceitos também se aplicam a outros provedores de nuvem. O equivalente do Azure App Configuration no AWS é chamado de AWS Systems Manager Parameter Store. O Azure Key Vault tem um equivalente no AWS chamado AWS Secrets Manager e o equivalente do Google é chamado Google Secret Manager.

Se quiser hospedar seu gerenciamento de segredos por conta própria, dê uma olhada em Hashicorp Vault.

Armazenamento de segredos no Azure Key Vault

Como dissemos anteriormente, não é possível usar o provedor de configuração User Secrets em ambientes não locais. Portanto, temos que encontrar uma maneira diferente de armazenar nossos segredos quando estivermos implantando nossos aplicativos. O Azure Key Vault é um ótimo serviço para armazenar segredos, chaves e certificados de forma barata, fácil e segura.

No início deste post, mencionei que é possível conectar o sistema de configuração do .NET à nuvem, o que é possível com o Key Vault. Essa é uma ótima abordagem para o gerenciamento de segredos porque você pode simplesmente tratar o Key Vault como um provedor de configuração e não precisa mais fazer coisas complicadas no pipeline de lançamento.

Para adicioná-lo como um provedor de configuração, instale os pacotes Azure.Extensions.AspNetCore.Configuration.Secrets e Azure.Identity. Em seguida, você só precisará adicionar algumas linhas de código ao seu Program.cs quando criar uma API mínima, por exemplo:

using Azure.Identity;

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((context, config) =>
{
    if (!context.HostingEnvironment.IsDevelopment())
    {
        var keyVaultUrl = new Uri(context.Configuration.GetValue<string>(“KeyVaultUrl”));
        config.AddAzureKeyVault(keyVaultUrl, new ManagedIdentityCredential()); // Há outras opções de credenciais disponíveis. As Managed Identities serão abordadas em breve!
    }
});

O Key Vault agora é adicionado como o provedor final e, portanto, tem a prioridade mais alta. Portanto, mesmo que outros provedores tenham um valor configurado para um segredo, o Key Vault será usado em seu lugar!

ℹ️ Info

Os segredos estruturados devem ser armazenados no Key Vault com 2 traços (--) em vez de 2 sublinhados ou dois pontos devido a limitações de nomenclatura. Por exemplo, ExternalApiSettings--ApiKey em vez de ExternalApiSettings:ApiKey ou ExternalApiSettings__ApiKey.

Usando o Key Vault durante o desenvolvimento local

Anteriormente neste post, mencionei brevemente que você pode estar em um cenário em que não é possível armazenar segredos em seu computador por motivos de segurança, por exemplo. Nesse caso, usar o Key Vault durante o desenvolvimento local resolveria esse problema. Você pode pegar o exemplo de código da seção anterior e modificá-lo da seguinte forma:

using Azure.Identity;

var builder = WebApplication.CreateBuilder(args);

builder.Host.ConfigureAppConfiguration((context, config) =>
{
    var keyVaultUrl = new Uri(context.Configuration.GetValue<string>(“KeyVaultUrl”));
    config.AddAzureKeyVault(keyVaultUrl, new DefaultAzureCredential()); // Esses tipos de credenciais serão abordados a seguir!
});

Agora, seu aplicativo sempre se conectará ao Key Vault, mesmo durante o desenvolvimento. O resultado é que você não precisa mais armazenar segredos em seu computador, pois eles são sempre recuperados do Key Vault. Uma desvantagem dessa abordagem é que você sempre precisa de uma conexão com a Internet para se conectar à nuvem!

ℹ️ Info

Devido aos benefícios que essa solução traz, considere o uso dessa abordagem mesmo em cenários em que o armazenamento de segredos localmente seria aceitável. Um grande benefício dessa abordagem é que você pode simplesmente clonar um projeto e, desde que tenha as permissões corretas, pode executá-lo sem precisar configurar nenhum segredo em sua máquina, pois eles são simplesmente recuperados da nuvem!

Conectando-se ao Azure com identidades gerenciadas

Nos exemplos de código anteriores, você viu alguns tipos estranhos de credenciais: ManagedIdentityCredential e DefaultAzureCredential. Antes de discutirmos isso, considere o seguinte:

Queremos nos conectar a um provedor de armazenamento seguro de segredos para obter segredos com os quais executar nosso aplicativo. Para nos conectarmos a esse provedor, precisaremos passar algumas credenciais para que o provedor possa autorizar nossa solicitação. Mas essas credenciais também são segredos, então onde as armazenamos? Poderíamos armazená-las em outro provedor de configuração, mas isso não anula todo o propósito de ter um provedor secreto? Se essas credenciais vazassem, alguém poderia acessar nossos segredos de qualquer forma! Para resumir, estamos lidando com um problema de galinha e ovo.

Felizmente, algumas pessoas inteligentes da Microsoft descobriram isso! Para o desenvolvimento local, você pode usar o DefaultAzureCredential para se comunicar com os serviços do Azure. Esse tipo de credencial tentará se autenticar usando vários métodos, como a conta da Microsoft com a qual você está conectado ao seu IDE, suas credenciais da CLI do Azure (az) e muito mais.

A Identidade do Azure usa vários métodos para autenticar a conta do Azure de um desenvolvedor.

Para ambientes de produção, a Microsoft recomenda Managed Identities para autenticar com recursos do Azure. As identidades gerenciadas são um recurso do Microsoft Entra (anteriormente conhecido como Azure Active Directory) que permite criar uma identidade para seu aplicativo no Microsoft Entra. Essa identidade pode ser usada para autenticação em outros serviços do Azure, como o Key Vault. A vantagem dessa abordagem é que você não precisa mais armazenar nenhuma credencial no aplicativo, pois a identidade é gerenciada pelo Azure AD.

ℹ️ Info

As Managed Identities podem ser bastante difíceis de entender em um primeiro momento. Dê uma olhada na parte inferior do post para ver alguns links com mais informações sobre Managed Identities.

Armazenamento da configuração na Configuração de Aplicativo do Azure

Por último, mas não menos importante, quero falar sobre a oferta de nuvem do Azure para gerenciamento de configuração. Enquanto o Azure Key Vault abrange o gerenciamento de segredos, o Azure App configuration é uma oferta de SaaS que o ajudará a gerenciar sua configuração. Esses dois serviços funcionam muito bem juntos quando você vincula o Azure App Configuration ao Azure Key Vault. Se optar por usar esse serviço, você só precisará adicionar o Azure App Configuration como um provedor de configuração e, em seguida, poderá usar o sistema de configuração do .NET para acessar todas as suas configurações E segredos da nuvem!

Ele também tem muitos outros recursos, portanto, vale a pena dar uma olhada!

ℹ️ Info

Considere a possibilidade de usar identidades gerenciadas para acessar a Configuração de Aplicativos para aumentar a segurança!

Finalizando

Você chegou até o fim! Este post levou muito tempo para ser escrito, e estou feliz por finalmente ter sido concluído! Abaixo, você encontrará mais informações se quiser saber mais sobre os conceitos que abordei neste post. Se você tiver alguma dúvida, fique à vontade para deixar um comentário abaixo. Se quiser saber quando e onde darei a versão de palestra deste post, confira minha página Speaking.

Links para a demo

Mencionei que o post é um complemento de uma de minhas sessões. Essa sessão contém várias demonstrações que mostram os conceitos discutidos nEste post. Você pode encontrar as demonstrações aqui.

Links para a documentação oficial

Você gostou deste post?

Carlos de volta

Carlos Schults de volta aqui. Espero que tenham gostado bastante do post, e sugiro que o coloquem nos favoritos para ser um recurso útil de consulta toda vez que surgir alguma dúvida referente ao gerenciamento de secrets e configuração.

Agradeço a Sander ten Brinke, autor do artigo original, que gentilmente me autorizou a traduzí-lo. O blog dele é fantástico, tem muitos artigos extremamente bem escritos sobre diversos tópicos relacionados a .NET. Para quem sabe inglês, recomendo fortemente a visita.

Gostaria de agradecer também a Andrew Lock, o autor do livro ASP.NET Core in Action, por ter concedido autorização para reproduzir uma imagem de seu livro.

A você que leu o artigo - todo ou apenas uma parte — deixo também um agradecimento e um pedido: me dê seu feedback. É extremamente importante saber se as pessoas gostam desse tipo de conteúdo, pois me motiva a continuar produzindo.

Até a próxima!

C# Regex: Como Expressões Regulares Funcionam em C#, Com Exemplos

Tue, 07 May 2024 00:00:00 +0000

NOTA: Eu originalmente escrevi esse post para o blog da empresa Stackify. Você pode ler o artigo original, em inglês, no site deles.

A manipulação de texto é uma das tarefas mais comuns na programação, sendo que praticamente todas as principais linguagens de programação oferecem suporte a regex (expressão regular) por meio de suas bibliotecas padrão. O C# não é exceção, portanto, hoje trazemos a você um guia de regex do C#.

Você aprenderá o que são expressões regulares, por que você deseja usá-las e como começar de uma maneira abrangente e acessível. Dessa forma, você poderá começar a usar expressões regulares para resolver problemas reais o mais rápido possível.

Prepare-se para sua jornada de aprendizado de regex, que começa agora!

O Que é Regex?

Uma expressão regular (também chamadas de regex, abreviação para regular expression) é uma expressão que contém um ou vários caracteres que expressam um determinado padrão no texto. Se isso parecer um pouco vago, um exemplo vai ajudar. Considere uma data no seguinte formato:

28-JUL-2023

Usando um regex, podemos expressar esse formato da seguinte forma:

[0-9]{2}-[A-Z]{3}-[0-9]{4}

Observe que a expressão regular acima expressa um padrão com:

dois dígitos numéricos seguidos de um hífen
três letras maiúsculas seguidas de um hífen
mais quatro números

Você saberá mais sobre o significado de cada parte de uma regex em um minuto. Por enquanto, lembre-se de que a regex acima não sabe nada sobre datas. Acontece que conseguimos criar uma expressão regular que corresponde ao padrão ou ao formato da data. Todos os itens a seguir correspondem a essa regex, mesmo que não sejam datas válidas:

32-ABC-7894
30-FEV-1978
00-AAA-9999

Existe Regex no C#?

Sim, é claro. Mas isso não vem da própria linguagem. Em vez disso, o suporte a regex vem da .NET’s BCL (Base Class Library), que é essencialmente a biblioteca padrão do C#.

Por Que Usar Regex em C#?

Como você viu, regex é algo a ser usado para expressar um padrão que pode corresponder a um determinado texto.

Na prática, todos os usos de regex em C# ou em outras linguagens se resumem a três motivos: validação, manipulação e extração.

Validação

Um caso de uso incrivelmente comum para regex é a validação de dados. Por exemplo, digamos que você tenha um formulário da Web e queira garantir que um determinado campo só aceite entradas em um formato específico. Como resolver isso? O Regex vem em seu socorro.

Manipulação

Às vezes, você precisa alterar informações dentro do texto. Vamos voltar ao exemplo anterior. Imagine que, por motivos de compliance, você precise remover todos os números de telefone desse corpo de texto e substituí-los pela palavra “REDACTED”. Novamente, as expressões regulares seriam perfeitas para essa situação.

É interessante notar que as linguagens de programação não são as únicas a usar expressões regulares para resolver problemas. Até mesmo os editores de texto, como o Notepad++, oferecem recursos de localizar e substituir com o auxílio de expressões regulares.

Extração

Digamos que você tenha uma quantidade considerável de texto. Esse texto contém números de telefone que você precisa extrair. Você conhece o formato desses números e o fato de que eles estão dentro do texto, mas esse é o limite do seu conhecimento.

Como você faria para extrair essas informações? Um regex C# bem feito certamente seria útil nessa situação.

Como usar o Regex em C#: Primeiros passos na prática

O C# é uma linguagem orientada a objetos, portanto, não é de surpreender que você use uma classe para trabalhar com regex no C#. Mais especificamente, a classe de que estou falando é apropriadamente chamada de Regex e reside no namespace System.Text.RegularExpressions.

C# Regex: Um exemplo de validação

Vamos começar com um exemplo simples de validação sobre como usar regex para validar se várias cadeias de caracteres correspondem a um determinado padrão. A primeira etapa é adicionar a seguinte instrução using ao seu código:

using System.Text.RegularExpressions;

Agora, vamos criar um array de strings e preenchê-la com alguns valores:

var candidates = new[]
{
    "28-JUL-2023",
    "whatever",
    "89-ABC-1234",
    "11-JUN-2022",
    "11-JUN-2022, uma data e outras coisas",
    "Isso certamente não é uma data"
};

Por fim, percorreremos os valores e usaremos o método estático IsMatch da classe Regex para verificar qual das cadeias de caracteres corresponde ao padrão desejado:

var pattern = "[0-9]{2}-[A-Z]{3}-[0-9]{4}";
foreach (var c in candidates)
{
    if (Regex.IsMatch(c, pattern))
    {
        Console.WriteLine($"A string '{c}' corresponde ao padrão '{pattern}'");
    }
}

Antes de prosseguir, vamos detalhar o padrão parte por parte:

[0-9]{2}: A primeira parte significa “Corresponde exatamente a dois caracteres, que devem ser dígitos de 0 a 9”.
-: Esse caractere corresponde exatamente a um hífen.
[A-Z]{3}: Aqui, a expressão diz: “Vamos corresponder exatamente a três caracteres, que podem ser qualquer uma das letras de A a Z.”
-: Isso corresponde a outro hífen
[0-9]{4}: Isso já deve ser fácil de entender, certo? Exatamente quatro números.

Agora, vamos executar o código e ver o que obtemos:

A string '28-JUL-2023' corresponde ao padrão '[0-9]{2}-[A-Z]{3}-[0-9]{4}'
A string '89-ABC-1234' corresponde ao padrão '[0-9]{2}-[A-Z]{3}-[0-9]{4}'
A cadeia de caracteres '11-JUN-2022' corresponde ao padrão '[0-9]{2}-[A-Z]{3}-[0-9]{4}'
A cadeia de caracteres '11-JUN-2022, a date plus other stuff' corresponde ao padrão '[0-9]{2}-[A-Z]{3}-[0-9]{4}'

Os três primeiros resultados provavelmente não o surpreenderam. Eu até incluí algo que não é uma data, mas que corresponde ao padrão que estamos usando para realmente enfatizar que as expressões regulares tratam de padrões e formas e não de qualquer semântica dos dados que estamos procurando.

Entretanto, o quarto resultado pode tê-lo surpreendido. O texto de fato começa com dados que correspondem ao padrão que estamos procurando, mas depois tem algum texto adicional. E mesmo assim, essa string correspondeu!

A explicação para esse comportamento é simples e está explicada para nós no summary do método IsMatch:

Indica se a expressão regular especificada encontra uma correspondência na cadeia de caracteres de entrada especificada.

A expressão regular de fato encontrou uma correspondência na string de entrada especificada (“11-JUN-2022, a date plus other stuff”), e é por isso que foi considerada uma correspondência.

Mas e se quiséssemos uma correspondência exata? Nesse caso, seria necessário alterar o padrão, adicionando um acento circunflexo (“^”) ao início do padrão e um cifrão (“$”) ao seu final. Em outras palavras, veja como o padrão deve ficar agora:

var pattern = "^[0-9]{2}-[A-Z]{3}-[0-9]{4}$";

Se executarmos o código agora, ele exibirá apenas as cadeias de caracteres que são uma correspondência exata com o padrão:

A string '28-JUL-2023' corresponde ao padrão '^[0-9]{2}-[A-Z]{3}-[0-9]{4}

C# Regex: Um exemplo de manipulação

Considere que você tem um texto que contém dados sensíveis do usuário. Devido a questões de privacidade/compliance, você deseja excluir esses dados. Felizmente para você, é muito fácil usar uma regex para isso.

Vamos começar criando uma matriz contendo nomes e números de telefone de pessoas fictícias:

var contacts = new[] {
    "Emily Johnson,(555) 123-4567",
    "Benjamin Williams,(555) 987-6543",
    "Olivia Davis,(555) 222-3333",
    "Alexander Smith,(555) 444-5555",
    "Sophia Brown,(555) 777-8888",
    "William Anderson,(555) 111-2222",
    "Ava Martinez,(555) 666-7777",
    "James Thompson,(555) 888-9999",
    "Isabella Wilson,(555) 333-4444",
    "Michael Taylor,(555) 777-1111"
};

Em seguida, vamos criar o padrão para corresponder aos números de telefone:

var pattern = @"\([0-9]{3}\)\s[0-9]{3}-[0-9]{4}";

O padrão acima é um pouco mais complexo do que os que usamos anteriormente, mas ainda é simples. No entanto, há alguns elementos novos:

A barra invertida (\): Precisamos dela aqui para escapar dos parênteses de abertura e fechamento, que é um caractere com significado em uma expressão regular. Nesse caso, queremos de fato corresponder a um caractere “(“, portanto, precisamos escapar dele.
O caractere \s: corresponde a um único espaço.

Por fim, vamos percorrer essa matriz e, para cada item, usar o método Regex.Replace para gerar uma nova string na qual o número de telefone é substituído por todos os zeros:

foreach (var contact in contacts)
{
    Console.WriteLine(
        Regex.Replace(contact, pattern, "(000) 000-0000"));
}

Usar o método estático Replace é fácil. Embora ele tenha várias sobrecargas, a que usamos recebe apenas três argumentos:

a string de entrada
o padrão que você deseja corresponder
a string de substituição

Depois de executar o código, eis o resultado que obtemos:

Emily Johnson,(000) 000-0000
Benjamin Williams,(000) 000-0000
Olivia Davis,(000) 000-0000
Alexander Smith,(000) 000-0000
Sophia Brown,(000) 000-0000
William Anderson,(000) 000-0000
Ava Martinez,(000) 000-0000
James Thompson,(000) 000-0000
Isabella Wilson,(000) 000-0000
Michael Taylor,(000) 000-0000

C# Regex: Um exemplo de extração

Para o nosso último exemplo, vamos extrair dados de uma string usando uma expressão regular. Vamos começar convertendo o array do exemplo anterior em uma única string:

var contacts =
    "Emily Johnson+(555) 123-4567" +
    "\nBenjamin Williams+(555) 987-6543" +
    "\nOlivia Davis+(555) 222-3333" +
    "\nAlexander Smith+(555) 444-5555" +
    "\nSophia Brown+(555) 777-8888" +
    "\nWilliam Anderson+(555) 111-2222" +
    "\nAva Martinez+(555) 666-7777" +
    "\nJames Thompson+(555) 888-9999" +
    "\nIsabella Wilson+(555) 333-4444" +
    "\nMichael Taylor+(555) 777-1111";

Em seguida, definimos o padrão novamente (o mesmo) e usamos o método estático Matches para obter todas as correspondências da string:

var pattern = @"\([0-9]{3}\)\s[0-9]{3}-[0-9]{4}";
MatchCollection matches = Regex.Matches(contacts, pattern);

A classe MatchCollection contém todas as cadeias de caracteres que corresponderam ao padrão que fornecemos ao método. Esse objeto é enumerável, portanto, podemos fazer um loop sobre ele com um foreach:

Console.WriteLine("Aqui estão os números de telefone extraídos:");
foreach (Match match in matches)
{
    Console.WriteLine(match.Value);
}

E, finalmente, nossos resultados:

Aqui estão os números de telefone extraídos:
(555) 123-4567
(555) 987-6543
(555) 222-3333
(555) 444-5555
(555) 777-8888
(555) 111-2222
(555) 666-7777
(555) 888-9999
(555) 333-4444
(555) 777-1111

C# Regex: Uma Ferramenta Indispensável

Como dissemos na introdução, a manipulação de texto é um elemento básico da programação, e as expressões regulares facilitam essa tarefa. Neste guia de regex em C#, você aprendeu o que são expressões regulares, seus cenários de uso mais comuns e como começar a usar expressões regulares em C#.

Antes de ir embora, algumas dicas:

Faça mais experimentos com a classe Regex. Ela oferece muitos recursos, e os métodos que usamos hoje têm muitas sobrecargas com recursos úteis.
Saiba mais e pratique a escrita de expressões regulares. Aqui está um ótimo site que você pode usar.
Informe-se sobre as considerações de desempenho do C# regex. Por exemplo, leia este artigo da Microsoft sobre a compilação e a reutilização de expressões regulares.

Por fim, se quiser saber mais sobre o C# em geral, o blog da Stackify está repleto de recursos úteis. Como sugestão, dê uma olhada em os prós e contras dos 3 principais frameworks de teste de unidade para C#, como capturar exceções e localizar erros de aplicativos em C# e como funciona a reflexão em C#.

Obrigado pela leitura!

carlos schults / blog

Suas Mensagens de Commit São Um Lixo. Vou Te Ajudar a Melhorar

Suas Mensagens de Commit São um Lixo Porque…

…Você Só Liga pra Código

…Às Vezes Você Não Entende o Que Está Fazendo

…Escrever é Difícil

…Ninguém Te Ensinou

…O GitHub Te Ensinou Maus Hábitos

…A Flag -m do Git Te Viciou

…Você Não Tem Higiene de Commits

Taxonomia das Mensagens de Commit Ruins

A Mensagem de Uma Linha Quase Inútil

A Mensagem de Uma Linha Inútil

Só a Referência do Sistema de Tickets

A Mensagem de Uma Linha Enganosa

Você Vai Escrever Boas Mensagens de Commit Quando…

…Escrever Suas Mensagens Em Inglês

…Parar de Escrever Mensagens de Uma Linha

…Começar pelo “O Quê”, Expandir com o “Por Quê” e o “Como”

…Seguir a Regra do 50/72

…Adotar Commits Atômicos

…Commitar Sempre, Polir Depois

Exemplos de Boas Mensagens de Commit

A IA Muda Tudo. Ou…Será Que Não?

Conclusão

Implementando o git em Go do Zero: Unindo o Útil ao...Agradável?

Escopo do Projeto

Fluxo de Trabalho do Projeto (eu realmente não sabia como chamar essa seção)

Sobre o Uso de LLMs

Construindo o git em Go: A Primeira Atualização

Acompanhe as Atualizações

O Que São Breaking Changes?

O que é um breaking change?

Exemplos de Breaking Changes

Novos Parâmetros Obrigatórios

Parâmetros opcionais removidos ou tornados obrigatórios

Novos Membros Adicionados a Uma Interface

Mudou o Tipo de um Parâmetro de Método

Mudou o tipo de retorno de um método ou função

Mudou a ordem dos parâmetros

Comportamento de tratamento de erro modificado (lançando exceções diferentes)

Tornou métodos ou propriedades públicas privadas

Adicionou requisitos de autenticação onde não existiam

Adicionou novas propriedades obrigatórias a um payload

Renomear ou deletar um endpoint

O que fazer sobre breaking changes?

Depreciação Gradual

Adicione Instruções às Suas Release Notes

Use Semantic Versioning

Conclusão

Como Melhorar a Experiência do Desenvolvedor: 7 Coisas Para Mudar

O Que é Experiência do Desenvolvedor? Por Que Você Deveria Se Importar?

Experiência do Desenvolvedor: Melhore com Essas 7 Dicas

1. Minimize as Interrupções

2. Invista em Excelência Técnica

3. Dê Autonomia aos Desenvolvedores

4. Remova o Atrito ao Criar Ambientes de Desenvolvimento

5. Invista na Educação dos Desenvolvedores

6. Não Seja Pão-Duro com Ferramentas

7. Ouça o Feedback dos Desenvolvedores (e Aja Baseado Nele)

Melhore a Experiência do Desenvolvedor, Melhore Sua Empresa

Git Switch Branch: Tudo o Que Você Precisa Saber

Como Funcionam os Branches no Git?

Como Crio um Novo Branch?

Como Você Muda de Branch?

Como Uso o Git Checkout?

O Que é Git Switch?

Como Faço para Mudar para um Branch Remoto?

Branches do Git: Use com Moderação

C# Type Safe: Como a IA Generativa Torna os Tiny-Types Viáveis

Tiny Types: A Melhor Técnica de Design de Software Que Ninguém Usa

Implementando um Tiny Type

Tiny Types São Muito Caros

LLMs ao Resgate

Conclusão

Erros de Aprendizado Para Se Evitar Como Desenvolvedor de Software

Índice

Achar Que Apenas Consumo de Conteúdo == Aprendizado

Por que caímos nessa armadilha?

As consequências desse erro

…A Flag `-m` do Git Te Viciou