Python Logic Lab: do Código à Qualidadertigo

1 INTRODUÇÃO

A lógica de programação constitui uma base importante para a formação de estudantes em computação, pois permite representar problemas por meio de dados, regras, decisões e sequências de instruções. Entretanto, aprender apenas a sintaxe de uma linguagem não garante a compreensão do fluxo de execução. Iniciantes frequentemente apresentam dificuldades para acompanhar mudanças de estado, interpretar estruturas de controle e relacionar um comando ao comportamento produzido pelo programa (ROBINS; ROUNTREE; ROUNTREE, 2003; LAHTINEN; ALA-MUTKA; JÄRVINEN, 2005).

Nesse contexto, foi desenvolvido o Python Logic Lab, um repositório educacional criado inicialmente para um desafio da DIO relacionado ao uso de recursos do GitHub em projetos open source. A proposta evoluiu de uma coleção de exercícios para um ambiente compacto, executável e verificável, integrando aprendizagem progressiva, testes automatizados, documentação, análise estática e integração contínua.

A organização do projeto procura reduzir a distância entre ler um código e compreender seu comportamento. Para isso, os conteúdos foram distribuídos em uma trilha progressiva:

 text
01 Variáveis
 ↓
02 Condicionais
 ↓
03 Repetições
 ↓
04 Funções
 ↓
05 Listas
 ↓
06 Aplicações testadas

Essa progressão busca controlar a complexidade apresentada ao estudante, evitando a introdução simultânea de muitos elementos novos. A organização em etapas também se relaciona aos princípios da carga cognitiva, segundo os quais a forma como um problema é apresentado influencia os recursos mentais exigidos durante sua resolução (SWELLER, 1988).

2 DESENVOLVIMENTO DO PROJETO

O repositório foi estruturado em módulos de desafios, exemplos, testes, documentação e páginas da Wiki. A trilha inicia com variáveis, tipos de dados e operadores, avança para estruturas condicionais e de repetição e, posteriormente, aborda funções, listas e aplicações executadas pelo terminal.

Uma das principais decisões arquiteturais foi separar a lógica de negócio da interação com o usuário. Em vez de concentrar `input()`, processamento e `print()` em um único bloco, as regras foram organizadas em funções importáveis.

```python

def calcular(a: float, operacao: str, b: float) -> float:

"""Executa uma operação validada e devolve o resultado."""
...

Ao receber os valores diretamente e devolver um resultado, a função pode ser testada sem depender do teclado ou da captura da saída do terminal. Essa separação melhora a reutilização, facilita a identificação de erros e permite que a mesma regra seja futuramente utilizada por uma API, uma interface gráfica ou outro tipo de aplicação.

Os exemplos incluem validação de entradas e tratamento de situações como divisão por zero, valores fora dos intervalos permitidos e identificadores inexistentes. Os casos de fronteira receberam atenção especial, pois muitos erros surgem exatamente nos pontos em que uma regra muda de comportamento. Assim, uma classificação de notas, por exemplo, não deve ser testada apenas com valores intermediários, mas também imediatamente antes, no limite e logo depois de cada transição.

A documentação foi desenvolvida em português brasileiro e inglês. O README principal apresenta o projeto internacionalmente, enquanto a versão em português mantém o conteúdo acessível ao público da DIO. A Wiki oficial foi estruturada como uma trilha visual e didática, com objetivos de aprendizagem, exemplos comentados, diagramas, tabelas de rastreamento, exercícios guiados, desafios independentes e referências científicas.

O fluxo open source foi aplicado de forma prática, com utilização de Issues, branches, Pull Requests, commits organizados, licença MIT, templates de contribuição e Código de Conduta. Dessa forma, o projeto demonstra não apenas conhecimentos sobre Python, mas também práticas de documentação, colaboração, revisão e rastreabilidade no GitHub.

3 QUALIDADE E VERIFICAÇÃO

A qualidade técnica do projeto é verificada por uma esteira automatizada composta por diferentes ferramentas:

```text
código
 ├── compileall
 ├── Ruff
 ├── mypy
 ├── pytest
 ├── pytest-cov
 └── GitHub Actions

A compilação com `compileall` verifica a sintaxe e a importação dos arquivos. O Ruff é utilizado para lint, organização de imports e formatação consistente. O mypy realiza análise estática dos tipos declarados. O pytest executa os testes automatizados, enquanto o pytest-cov mede a cobertura de linhas e ramificações.

O repositório apresenta uma linha de base de 76 testes automatizados aprovados e 100% de cobertura combinada de linhas e branches, com cobertura mínima obrigatória configurada em 90%. Uma cobertura elevada não significa, isoladamente, que todos os testes possuem qualidade. Entretanto, ela oferece uma medida objetiva e verificável sobre os caminhos do código que foram exercitados.

A reprodução da cobertura pode ser realizada com o comando:

```bash
python -m pytest --cov=exemplos --cov=desafios --cov-branch

O GitHub Actions executa a esteira de qualidade e uma matriz de testes nas versões Python 3.11, 3.12, 3.13 e 3.14. Isso permite identificar incompatibilidades entre versões e reduz a dependência do ambiente local do desenvolvedor. As aplicações utilizam somente a biblioteca padrão do Python em tempo de execução, enquanto as ferramentas de desenvolvimento são mantidas separadamente.

4 RESULTADOS E APRENDIZADOS

O principal resultado foi a transformação de um exercício educacional em um repositório reproduzível, documentado e auditável. Cada conceito pode ser estudado, executado, modificado e verificado por meio de testes.

Durante o desenvolvimento, tornou-se evidente que validar entradas é tão importante quanto produzir uma saída correta. Um programa pode executar sem erros de sintaxe e ainda fornecer uma resposta semanticamente inadequada. Por isso, valores inválidos são rejeitados explicitamente, em vez de serem silenciosamente classificados como situações comuns.

A integração contínua também demonstrou sua relevância. Cada alteração pode ser avaliada automaticamente, reduzindo a possibilidade de que uma modificação aparentemente simples comprometa comportamentos já implementados. O uso de branches e Pull Requests tornou o histórico mais compreensível e permitiu relacionar problemas, soluções, testes e documentação.

A documentação bilíngue ampliou a apresentação do projeto para públicos distintos, enquanto a Wiki possibilitou uma progressão mais didática do que um README isolado. A experiência também proporcionou aprendizagem prática sobre versionamento, licenciamento, padrões de contribuição, revisão de código e publicação de documentação.

O projeto foi desenvolvido como uma iniciativa orientada por evidências. A literatura científica contribuiu para decisões relacionadas à progressão dos conteúdos, à clareza dos exemplos e à redução da sobrecarga cognitiva. Entretanto, o repositório não realizou um experimento controlado com estudantes e, portanto, não afirma eficácia pedagógica comprovada. As evidências produzidas diretamente pelo projeto são técnicas: execução do código, resultados dos testes, cobertura e verificações automatizadas.

5 CONSIDERAÇÕES FINAIS

O Python Logic Lab demonstra como conteúdos introdutórios de lógica de programação podem ser organizados em um projeto educacional associado a práticas reais de engenharia de software.

Sua contribuição não está apenas nos exemplos de Python, mas na integração entre aprendizagem, testes, cobertura, análise estática, documentação e desenvolvimento open source. O repositório pode ser clonado, executado, testado, analisado e auditado por qualquer pessoa interessada em compreender sua estrutura.

A experiência permitiu transformar um desafio da DIO em um projeto mais completo, no qual o código não é apresentado de forma isolada, mas como parte de um processo que envolve planejamento, validação, documentação e melhoria contínua.

Repositório do projeto:

https://github.com/matheusflorindo32/dio-estudos-logica-python

REFERÊNCIAS

LAHTINEN, Essi; ALA-MUTKA, Kirsti; JÄRVINEN, Hannu-Matti. A study of the difficulties of novice programmers. ACM SIGCSE Bulletin, v. 37, n. 3, p. 14-18, 2005. DOI: https://doi.org/10.1145/1151954.1067453.

ROBINS, Anthony; ROUNTREE, Janet; ROUNTREE, Nathan. Learning and teaching programming: a review and discussion. Computer Science Education, v. 13, n. 2, p. 137-172, 2003. DOI: https://doi.org/10.1076/csed.13.2.137.14200.

SWELLER, John. Cognitive load during problem solving: effects on learning. Cognitive Science, v. 12, n. 2, p. 257-285, 1988. DOI: https://doi.org/10.1207/s15516709cog1202_4.