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

📜 COBOL é Autoexplicativo? Problemas na documentação do legado. Documentação, Mitos, Boas Práticas e Sobrevivência no Mainframe Real

 

COBOL Documentação

📜 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.

☕💾