<\> Casa do Dev
Notícias abrir
Ferramentas abrir
Vagas abrir
Aprender abrir
Comunidade abrir
Guia de Compras abrir

Estruturar pastas de projeto: o que ninguém ensina e todo iniciante precisa

DA

12 min

Estruturar pastas de projeto: o que ninguém ensina e todo iniciante precisa

Saber programar não inclui saber organizar; o guia prático de estrutura de pastas que destrava o primeiro projeto do zero.

Neste artigo

Existe uma pergunta que aparece com regularidade assustadora nos fóruns de quem está aprendendo a programar, e ela quase nunca está em nenhum programa de curso. Uma das versões mais citadas da temporada apareceu no r/programacao em a discussão sobre como realmente estudar programação: o autor relata cerca de um ano e meio de estudo, com Python, projetos que integravam front e back e banco de dados, e o bloqueio declarado é outro do que se esperaria de alguém com esse histórico. Ele não sabe por onde começar um projeto do zero, e o item que nomeia explicitamente é a estrutura de pastas: onde colocar cada coisa, por onde startar. Um ano e meio escrevendo código sem nunca ter precisado decidir onde ele mora.

Este tutorial assume que a dúvida não é defeito seu, é buraco do formato de curso. A proposta aqui é ensinar o raciocínio, não a receita: separação por responsabilidade como princípio, o que muda conforme o projeto cresce, as convenções que o mercado reconhece e a resposta honesta de quando o "só funciona" é aceitável. No fim, um layout comentado de projeto pequeno para usar de molde e a regra que governa tudo: a estrutura evolui junto com o projeto, nunca antes dele existir.

Por que ninguém ensina a organizar

Curso, aula e tutorial têm uma economia própria: o tempo da aula é curto e o professor quer chegar à parte interessante, então entrega o esqueleto pronto. Você abre o projeto e as pastas já estão lá, nomeadas, com o arquivo no lugar certo. Isso não é preguiça do professor, é uma decisão didática que cobra preço escondido: ao pular a organização, o curso também pula as perguntas que ela responde. Quem sempre recebeu o esqueleto pronto nunca praticou a decisão de criar uma pasta, e decisão não se aprende assistindo, se aprende errando.

O resultado é o padrão do relato: meses de estudo, código sendo escrito, e a estrutura permanece um mistério porque nunca foi exercício. A boa notícia é que o raciocínio inteiro cabe num princípio só, e ele é mais simples que qualquer diagrama de arquitetura. O resto deste tutorial é esse princípio aplicado a situações que vão do arquivo único ao projeto com testes.

O princípio: separar por responsabilidade

Organizar um projeto é responder uma pergunta repetida: qual é o trabalho de cada parte? A estrutura de pastas é a resposta visual dessa pergunta. Cada pasta deve ter um trabalho claro, que você consegue dizer em uma frase sem conjunção. Uma pasta que guarda "o que conversa com o usuário" tem responsabilidade clara. Uma pasta chamada "diversos" ou "geral" não tem responsabilidade nenhuma, é o armário da bagunça, e todo projeto tem um se ninguém decidir contra.

O teste prático para cada pasta que você cria é o seguinte: explique em voz alta o que vai nela. Se a explicação precisa de um "e também" para cobrir coisas sem relação entre si, você está misturando duas responsabilidades, e a pasta pede para ser dividida. Se a explicação é uma frase só e você consegue adivinhar o que tem dentro antes de abrir, a pasta está certa. Note que o princípio não menciona nenhuma tecnologia, nenhum nome de framework e nenhuma regra de negócio: separar por responsabilidade funciona igual em JavaScript, Python, Java ou no shell script de dez linhas, porque o que está sendo organizado é o seu raciocínio, não o código em si.

💡 Dica: escolha nomes que você mesmo entenderá daqui a seis meses, e prefira sempre o nome que descreve o trabalho ao nome que soa sofisticado. Uma pasta chamada "pagamento" diz mais que uma chamada "core", e um nome honesto hoje economiza uma sessão de arqueologia no futuro.

Do script solto à aplicação: o que muda conforme cresce

A segunda parte do raciocínio é entender que estrutura não é um tamanho único: ela acompanha o estágio do projeto. Cobrar arquitetura de um script de estudo é peso morto, e negligenciar estrutura numa aplicação que cresce é convite ao caos. A tabela abaixo mostra a progressão:

Estágio do projetoEstrutura adequada
Script único de estudo ou tarefa de uma vezUm arquivo só, com um nome que diga o que ele faz
Poucos arquivos relacionados que se conversamUma pasta única com nomes claros, um por arquivo
Aplicação com entrada, regras e saída de dadosPasta do código dividida por responsabilidade, mais arquivo de apresentação
Projeto que outra pessoa pode usar ou manterCódigo separado, verificação separada, documentação separada e instruções de uso na raiz

A regra que atravessa a tabela é econômica: cada nível de estrutura existe para resolver uma dor específica. A pasta única resolve a dor de dez arquivos espalhados pela área de trabalho. A divisão por responsabilidade resolve a dor de procurar onde uma coisa está. A separação de testes e documentação resolve a dor do visitante, que quase sempre é você mesmo daqui a três meses. Estrutura sem dor para resolver é enfeite, e enfeite cobra manutenção.

As convenções que o mercado reconhece

Com o princípio claro, a segunda camada é a convenção: nomes e formatos que a comunidade de desenvolvimento usa em praticamente todo projeto sério, independente de linguagem. Convenção não é frescura, é comunicação: quando você abre qualquer repositório maduro e encontra as mesmas peças nos mesmos lugares, você está colhendo o benefício de décadas de acordo coletivo. As quatro peças básicas:

  • src: a casa do código do programa. O nome vem de fonte, e a promessa implícita é que tudo ali é o produto, sem mistura com anotação, dado de teste ou rascunho.
  • tests: a casa da verificação do código. Espelha a organização interna de src, para que cada parte testada tenha seu teste correspondente no mesmo lugar relativo.
  • docs: a casa da documentação que não cabe no arquivo de apresentação, decisões de projeto, instruções mais longas e anotações de arquitetura.
  • README, na raiz: a porta de entrada. O que o projeto faz, como rodar e o que ainda não funciona, em poucas linhas que qualquer visitante entende.

Seguir convenção tem um benefício que os iniciantes subestimam: projeto organizado do jeito que o mercado reconhece fala por você. Quem abre o seu repositório, seja um colega, seja um avaliador de vaga, lê a estrutura como sinal de cuidado antes de ler uma linha de código. Para escolher o que construir primeiro e dar a esse repositório um propósito, o guia de como escolher a stack para o seu primeiro projeto cobre a decisão que vem antes da pasta: o que o projeto vai ser feito.

Quando o só funciona é aceitável

Agora a parte que os tutoriais de boas práticas raramente dizem: existe situação em que tudo em um arquivo só é a escolha certa. O script pessoal que converte um arquivo de planilha uma única vez, o experimento de estudo que vai ser apagado no fim da semana, a automação doméstica de dez linhas que ninguém além de você vai ler. Nesses casos, a estrutura é custo sem retorno: a dor que ela resolve, encontrar as coisas e receber visitante, simplesmente não existe no projeto. Organizar demais um projeto descartável é a mesma armadilha de decorar demais antes de praticar, perfeição no lugar errado.

O sinal de que o "só funciona" venceu o prazo é comportamental e é fácil de observar: você reluta em mexer no próprio código. Quando editar um arquivo vira risco porque você não sabe mais o que depende do quê, quando procurar uma função leva mais tempo que escrevê-la de novo, quando a ideia de mostrar o projeto a alguém te constrange pela bagunça e não pela qualidade, o projeto pediu estrutura. Esse é o momento de separar. Antes dele, tudo bem deixar simples. Para quem ainda está escolhendo o primeiro projeto para aplicar tudo isso, a guia de como escolher o seu primeiro projeto de programação ajuda a calibrar o tamanho da primeira aposta.

⚠️ Atenção: copiar a estrutura de um projeto grande de empresa para o seu projeto de estudo não é boas práticas, é transplante de órgão em paciente pequeno. Pastas em camadas profundas, criadas para times de dezenas de pessoas, viram burocracia vazia em projeto de uma. Comece pelo molde simples e deixe a necessidade puxar cada camada nova.

Um layout comentado para projeto pequeno

Juntando princípio, estágio e convenção, este é um molde honesto para o primeiro projeto de verdade, com a justificativa de cada peça:

  • README na raiz: três seções curtas, o que o projeto faz em uma frase, como rodar do zero e o estado atual, incluindo o que está quebrado. É a primeira coisa que qualquer pessoa lê, e a pessoa mais frequente é você.
  • src, a pasta do código: dentro dela, uma subpasta por responsabilidade. Um projeto pequeno típico se contenta com três: a parte que conversa com o usuário, a parte que guarda as regras do problema e a parte que salva e recupera dados. Três subpastas resolvem a imensa maioria dos projetos de estudo.
  • tests, a pasta da verificação: mesma divisão interna de src, para que encontrar o teste de uma parte seja intuitivo. Se você ainda não escreve testes, crie a pasta assim mesmo e coloque dentro uma nota dizendo o que pretende verificar; o caminho preparado é convite.
  • docs, a pasta das decisões: por que você escolheu o caminho A e descartou o B, quais limitações o projeto tem hoje e como ele se conecta a ideias futuras. Documento de decisão vale mais que documento de sonho.
  • dados ou exemplos: arquivos de amostra que o projeto usa para demonstrar funcionamento, guardados fora do código para que ninguém confunda dado de demonstração com regra do programa.

Note o que esse molde não tem: nenhuma camada de arquitetura com nome estrangeiro, nenhuma hierarquia de cinco níveis, nenhuma pasta vazia esperando o futuro. É o mínimo que responde às perguntas reais de um projeto pequeno, e nada mais. Quando um projeto desses for para o portfólio, a escada de exercícios do guia com dez projetos simples para treinar programação oferece escopos que cabem exatamente nesse tamanho de estrutura.

Evolua a estrutura junto com o projeto, nunca antes

A última regra amarra todas as anteriores, e ela é o conselho que mais evita abandono de projeto: não desenhe a estrutura do projeto que você imagina ser, desenhe a do projeto que existe hoje. Estrutura antecipada é aposta sem informação, e quase sempre aposta errada, porque você ainda não sabe quais partes do sistema vão crescer. A estrutura certa nasce da dor real: a segunda subpasta de src aparece no dia em que a primeira fica cheia demais, a pasta de docs aparece quando a segunda decisão importante precisa de registro, a pasta de dados aparece quando o primeiro arquivo de exemplo se perde no meio do código.

Mover pastas depois é barato, não caro, e o controle de versão existe justamente para isso: reorganizar o projeto com histórico preservado faz parte da rotina de quem mantém software. O medo de errar a estrutura é, no fim, mais um disfarce do medo de começar, e o antídoto é o mesmo: comece simples, corretamente simples, e deixe que o projeto, com as dores reais dele, seja quem pede cada acréscimo. Estrutura boa é a que você consegue explicar em um minuto e que nenhuma pasta está ali por moda. Se a sua passa nesse teste, ela está certa para o tamanho que o seu projeto tem hoje, e é isso que estrutura de pasta precisa ser. O passo seguinte natural, quando o projeto sair do estudo e virar ideia de verdade, está no guia de como transformar uma ideia de software em projeto real, que cobre exatamente a transição deste tutorial para o mundo.

Perguntas frequentes

Preciso separar pastas desde o primeiro arquivo?

Não. O primeiro arquivo pode ficar solto, e a primeira pasta aparece quando existe mais de uma responsabilidade convivendo. O que vale desde o início é a intenção: cada pasta criada deve ter um trabalho que você sabe dizer em uma frase.

Existe uma estrutura ideal de pastas?

Não existe estrutura ideal em absoluto, existe estrutura adequada ao estágio. As convenções de código separado, verificação e documentação cobrem quase todos os casos de projeto pequeno, e qualquer coisa além disso deve ser puxada por uma dor real do projeto, nunca por imitação de projeto maior.

Onde entra o código de teste que ainda não escrevo?

Crie a pasta de testes desde o começo e mantenha a divisão interna espelhada com a do código, mesmo que ela fique vazia por um tempo. O caminho preparado reduz a barreira de começar, e quem adia a pasta costuma adiar a prática junto.

E se eu errar a estrutura e o projeto crescer errado?

Reorganizar é parte normal do ciclo de vida de qualquer projeto e o controle de versão torna a mudança segura. O sinal de reorganização é comportamental: quando mexer no código começa a dar medo e encontrar as coisas passa a custar mais que escrevê-las, é hora de repartir, e não de recomeçar tudo do zero.

Produtos relacionados

Este conteúdo tem links de afiliado: se você comprar por eles, podemos receber uma comissão sem custo extra para você. A escolha dos produtos segue critérios próprios e não é influenciada por comissão.

O que você achou deste artigo?

Responda a Pergunta do Dia Teste seu conhecimento e mantenha sua streak. Crie seu Dev Card público Perfil dev compartilhável em um único link.

Depois dessa formação...

Veja vagas em tecnologia →

Vagas relacionadas

Ver todas as vagas →
DA

Escrito por

Dagmar

Publicado em

Ver perfil do autor

COMPARTILHAR