🚀 Código Comentado

Aprender Programação Ensinando Programação

Um repositório colaborativo onde cada conceito de programação é explicado através do próprio código.

Aqui, o código não é apenas escrito: ele é comentado, explicado e contextualizado para ensinar o que é, como funciona e, principalmente, por que existe.

---

---

📑 Índice

• Comece por aqui
• O problema que queremos resolver
• Objetivos
• Trilhas de Aprendizado
• Roadmaps
• Regra de Ouro do Projeto
• Estrutura do Projeto
• Padrão dos Conteúdos
• Como contribuir
• Documentação
• Manifesto

---

🚀 Comece por aqui

Novo no projeto? Siga este caminho:

README
  ↓
GETTING_STARTED
  ↓
Trilha de Aprendizado
  ↓
Roadmap da Linguagem
  ↓
Código Comentado
  ↓
Prática e Contribuição

📌 Guia inicial: GETTING_STARTED.md

---

💡 O problema que queremos resolver

Existem milhares de repositórios com códigos de estudo no GitHub.

A maioria mostra	Poucos explicam
O que fazer	Por que fazer
Como fazer	Quando usar
—	Quais problemas aquela solução resolve

Exemplo

this.nome = nome;

Qualquer pessoa consegue aprender a escrever essa linha. Poucas entendem:

• Por que o this existe
• Qual problema ele resolve
• Quando ele realmente é necessário O Código Comentado nasce para preencher essa lacuna:

Transformar cada arquivo de código em um pequeno capítulo de aprendizado.

---

🎯 Objetivos

Ao participar do projeto, o colaborador pratica:

• 🧠 Lógica de programação
• 🗂️ Estruturas de dados
• 🧩 Programação Orientada a Objetos
• ⚙️ Frameworks
• 🔀 Git e GitHub em fluxo real
• ✍️ Escrita técnica
• 📚 Documentação
• 🔍 Code Review
• 🤝 Trabalho colaborativo Tudo dentro de um único projeto com padrão e propósito definidos.

---

🎓 Trilhas de Aprendizado

As trilhas mostram o caminho recomendado para aprender cada linguagem, desde os fundamentos até conceitos profissionais.

Linguagem	Trilha
☕ Java	TRILHA-JAVA.md
🐍 Python	TRILHA-PYTHON.md

---

Futuras linguagens

Seguirão o mesmo padrão:

• JavaScript
• C#
• Kotlin
• Go
• Entre outras

---

🗺️ Roadmaps

Os roadmaps apresentam todos os conceitos disponíveis em cada linguagem, funcionando como uma referência completa de assuntos.

Linguagem	Roadmap
☕ Java	ROADMAP-JAVA.md
🐍 Python	ROADMAP-PYTHON.md

---

Fluxo de estudo

Trilha
  ↓
Roadmap
  ↓
Conceito
  ↓
Código Comentado
  ↓
Exercício

---

🥇 Regra de Ouro do Projeto

Todo Pull Request deve agregar conhecimento, não apenas código.

O objetivo de um PR não é apenas adicionar uma funcionalidade ou exemplo, mas tornar o repositório mais útil para quem está aprendendo.

---

Checklist antes de aprovar um Pull Request

• O código funciona corretamente?
• A explicação está tecnicamente correta?
• O autor explicou por que tomou aquela decisão?
• Existem exemplos práticos?
• Existe uma analogia para facilitar o entendimento?
• Foram destacados erros comuns?
• Um iniciante conseguiria aprender aquele conceito? Um Pull Request só está completo quando ensina algo novo para a próxima pessoa que o ler.

---

📂 Estrutura do Projeto

codigo-comentado/
 
├── README.md
├── CONTRIBUTING.md
 
├── docs/
│   ├── trilhas/
│   ├── roadmaps/
│   └── guides/
 
├── java/
│   ├── c03_programacao_orientada_a_objetos/
│   ├── collections/
│   ├── exceptions/
│   ├── streams/
│   └── spring/
 
├── python/
│   ├── fundamentos/
│   ├── c03_programacao_orientada_a_objetos/
│   ├── collections/
│   └── frameworks/
 
└── javascript/

A organização foi pensada para permitir o crescimento do projeto sem perder padronização.

---

Padrão de organização por linguagem

linguagem/
    ↓
tema/
    ↓
conceito
    ↓
código comentado

---

📚 Padrão dos Conteúdos

Cada arquivo segue uma estrutura obrigatória:

#	Seção
1	O que é?
2	Como funciona?
3	Por que existe?
4	Quando usar?
5	Quando evitar?
6	Vantagens
7	Desvantagens
8	Erros comuns
9	Boas práticas
10	Analogia
11	Exemplo prático
12	Exercício
13	Resumo

O objetivo não é apenas mostrar código funcionando — é explicar o raciocínio por trás dele.

---

🤝 Como contribuir

O Código Comentado é um projeto colaborativo. Antes de contribuir, consulte:

📄 CONTRIBUTING.md

O documento explica:

• Criação de branches
• Padrão de commits
• Pull Requests
• Code Review
• Organização dos conteúdos

---

Acompanhamento de tarefas

Feito através do GitHub Projects:

🔗 https://github.com/orgs/Codigo-Comentado/projects/16

---

📚 Documentação

Documentos importantes:

• Trilhas de aprendizado
• Roadmaps
• Guia de contribuição
• Padrão de conteúdos
• Organização do projeto Local:

docs/
├── trilhas/
├── roadmaps/
└── guides/

---

📜 Licenciamento

O Código Comentado utiliza diferentes licenças de acordo com o tipo de material:

• 📚 Conteúdo educacional: CC BY-SA 4.0
• 💻 Código educacional: GPL-3.0
• 🎨 Nome, logo, Codee e identidade oficial: não incluídos automaticamente nas licenças abertas

Consulte o arquivo LICENSE.md para detalhes.

---

📜 Manifesto

Acreditamos que conhecimento compartilhado vale mais do que conhecimento guardado.

Este repositório não existe apenas para armazenar código. Ele existe para registrar:

• A lógica
• As decisões
• Os fundamentos
• O aprendizado por trás de cada conceito Queremos criar o material que gostaríamos de ter encontrado quando começamos a estudar programação.

---

Nosso compromisso

• ✅ Cada linha de código deve ensinar algo
• ✅ Cada comentário deve reduzir uma dúvida
• ✅ Cada Pull Request deve tornar o projeto melhor

"A melhor forma de aprender é ensinar. E a melhor forma de ensinar é explicar o porquê."