Que beijinho mais gostoso o Luigi e os Esquilos natalinos.

 Feliz Natal do pequeno Luigi para a famiglia Bellacosa. O pequenino Luigi aprontando arte, brincando com os Esquilinhos dançantes. Na época para ele era uma loucura ouvir esses esquilinhos, ele adorava brincar, agarrar, abraçar, apertar as musiquinhas sempre fazendo bagunca com eles.

📜 COBOL é Autoexplicativo? Problemas na documentação do legado.

  

📜 COBOL é Autoexplicativo?

Documentação, Mitos, Boas Práticas e Sobrevivência no Mainframe Real

“Se o código fosse realmente autoexplicativo, não existiria analista sênior, dump, nem planilha escondida na gaveta.”
— Provérbio não-oficial do Sysprog

---

1️⃣ O mito do COBOL auto-documentado

Desde sua origem, o COBOL foi vendido como uma linguagem:

• legível,

• próxima do inglês,

• acessível a gestores e usuários de negócio.

Na teoria:

IF CUSTOMER-STATUS = 'A'
   PERFORM PROCESS-ACTIVE-CUSTOMER
END-IF

Na prática, sabemos que:

• legível ≠ compreensível

• código não explica regra de negócio

• o “porquê” quase nunca está no fonte

📌 Primeiro choque de realidade
COBOL ajuda a ler a intenção técnica, mas não documenta contexto histórico, exceções fiscais, gambiarra regulatória ou acordo verbal de 1998.

👉 E isso não é culpa da linguagem. É da ausência de documentação.

---

2️⃣ Self-documenting code: sonho bonito, realidade dura

Existe um conceito romântico no mundo de software:

“Código limpo se documenta sozinho”

No mainframe isso vira rapidamente:

“Código limpo ajuda, mas não se explica sozinho”

⚠️ Gotcha clássico

IF WS-FLAG = 'Y'
   MOVE ZERO TO WS-TAX
END-IF

Perguntas que o código não responde:

• Por que zera imposto?

• Qual legislação?

• Em que data isso foi criado?

• Quem autorizou?

• Isso ainda é válido?

📌 Regra de ouro Bellacosa

Código mostra o que o sistema faz.
Documentação explica por que ele faz isso.

---

3️⃣ Onde a documentação realmente mora no COBOL

📂 3.1 No código (sim, mas com juízo)

❌ Comentário inútil

* Move value to variable
MOVE A TO B.

✅ Comentário que salva vidas

* REGRA FISCAL BR-ICMS-2017
* Conforme decreto 12.887, clientes com FLAG = 'Y'
* estao isentos de imposto nesta operacao
IF WS-FLAG = 'Y'
   MOVE ZERO TO WS-TAX
END-IF

📌 Comentário bom envelhece melhor que código bonito.

---

📘 3.2 Cabeçalho de programa (o RG do sistema)

Todo programa COBOL deveria começar com algo assim:

*****************************************************************
* PROGRAMA....: FINC1023
* DESCRICAO...: Calculo de impostos para faturamento
* MODULO......: Financeiro
* AUTOR.......: J. SILVA
* DATA........: 12/03/2017
* ALTERACOES..:
*  - 05/06/2019 - Ajuste ICMS MG (CHG#45871)
*  - 10/08/2022 - Isencao clientes FLAG=Y (LEGAL-889)
*****************************************************************

🧠 Easter Egg #1
Programas sem cabeçalho quase sempre:

• quebram em virada de ano

• explodem em auditoria

• ninguém quer assumir

---

4️⃣ Público-alvo da documentação: quem você está tentando salvar?

Nem toda documentação é para todo mundo.

🎯 Públicos clássicos no mainframe

Público	Precisa de
Desenvolvedor	Comentários técnicos, layout, lógica
Analista de negócio	Regras, exceções, impacto
Suporte/Produção	Fluxo, erros, RC, abends
Auditor	Rastreabilidade, histórico, motivo

📌 Erro comum
Achar que um comentário no código resolve tudo.

👉 Não resolve. Ele ajuda.

---

5️⃣ Padrões: o verdadeiro caminho do “autoexplicativo”

COBOL só fica “auto-documentável” quando existe:

• Naming convention clara

• Layout consistente

• Regras de codificação

• Comentários padronizados

❌ Legado sem padrão

01 A.
   05 B PIC 9(05).

✅ Código legível e sustentável

01 WS-INVOICE-TOTAL        PIC 9(07)V99.
01 WS-INVOICE-TAX          PIC 9(07)V99.

🧠 Easter Egg #2
Quem usa A, B, X1, X2 geralmente:

• herdou código sem documentação

• tem trauma de manutenção

• sabe interpretar dump no olho 😅

---

6️⃣ Documentando o “não documentado” (zona de guerra)

Agora vem a parte crítica.

⚠️ Realidade dura do mainframe

• Sistemas com 30, 40, 50 anos

• Regras que ninguém lembra

• Desenvolvedores se aposentando

• Conhecimento tribal indo embora

📌 O que fazer?

• Usar ferramentas modernas

• Mapear fluxos reais

• Analisar batch, CICS, DB2

• Documentar depois que entende

“Se está funcionando, existe uma regra.
Se ninguém sabe qual é, ela precisa ser documentada.”

---

7️⃣ COBOL, modernização e sobrevivência

Documentação não é nostalgia. É:

• pré-requisito de modernização

• base de DevOps

• segurança contra falha humana

• seguro contra auditoria

Sistemas mission critical não podem falhar.
E eles só sobrevivem porque:

• alguém documentou

• alguém deixou pistas

• alguém pensou no próximo

🧠 Easter Egg #3
O programa mais crítico da empresa:

• roda em batch às 02:13

• ninguém sabe explicar tudo

• mas todo mundo tem medo de mexer

---

8️⃣ Conclusão Bellacosa Mainframe

✔ COBOL não é mágico
✔ Código limpo ajuda, mas não basta
✔ Documentação é responsabilidade técnica
✔ Padrões salvam sistemas
✔ Comentários certos salvam carreiras

Documentar não é escrever mais.
É escrever o que o código nunca vai conseguir explicar.

☕💾

Brincadeiras de criança, memoria do Luigi a enviar beijinhos a Tia Nana...

 Nanazinha com carinho e amor do seu pequeno sobrinho Luigi, um super beijo para começar 2010 com ótimo estilo.

Fim de ano, 2009 terminando e o pequeno Luigi bem animado, brincando com seu pai lelé, mandando muitos beijos e abraços.... Ficando com frio e fazendo careta por causa do cheirinho ruim, ai esse pequeno é um barato, que rapazola fofo... te amo pequenino.

Coral dos Esquilinhos Malucos

O Natal dos Esquilinhos

Foi uma diversao quando comprei os Esquilinhos Cantores e ainda nao tinha ideia que o Luigi voce adorar a brincadeira. Imagine ele do alto dos seus quase 2 anos... iria abraçar, agarrar e brincar com eles.

E aproveitando o espirito natalino, aproveitamos para deixar mensagens de carinho para a familha.