Executando verificação de segurança...
3
correiatec
1 min de leitura ·

[Opinião] Documentação (ou a falta dela)

Em quase todos lugares que trabalhei e até no que trabalho agora, sempre me deparei com a falta de documentação dos projetos.
Uns até tinham ex: WordPress, Magento
Mas outros não tinham absolutamente nada.
Nem sequer comentários no código (Até sei que isso não é documentação), mas ajuda muito a entender o que aquele método/função faz.
Sei que o programador é preguiçoso, está super atarefado ou sobrecarregado, mas é tão difícil assim documentar minimamente?
Código não é documentação, já vi muita "macarronada" por aí que não dá pra entender nada, ou deixou de um modo que só ele faz manutenção, mas um dia ele é demitido e aí forma-se o caos.
Como anda a documentação onde você trabalha?
Você documenta o que faz?

Carregando publicação patrocinada...
3
clacerda

Aqui na firma a gente faz avião, e para cada linha de código alterada precisamos atulizar pelo menos 33 documentos. É o inferno, mas é por isso que aviões não caem do céu. A sua documentação reflete a qualidade do seu software não a sua implementação!!

1
Oletros

Meus 2 cents:

Certa vez um parceiro de trabalho comentou comigo exatamente isso: "o que faz um aviao voar nao eh combustivel, eh papel..."

Este parceiro participa de escola de aviacao e oficina de manutencao de aeronaves - quando vejo a dor de cabeca que ele tem com a papelada realmente me espanta.

A burocracia do ramo aeronautico nunca deixa de me surpreender - faz algum tempo (2021) que comecei a ver a questao do LOG BOOK via API do diario de bordo disponibilizado pela ANAC (blockchain) - mas desde 2023 nao tem mais movimento na lista de discussao especifica e nao ouvi falar mais nada sobre o assunto.

3
abrhaao

Documentar é uma arte, amigo.
A maioria dos programadores nem é capaz de fazê-lo com qualidade.
Comentar o código é a coisa mais prática, e a documentação acaba ficando mais pra setups ou pontos de configuração mais específicos.

2
RodrigoSchio

eu faço documentação em um outro nivel

otopatamá

eu mantenho um site (no ghPages) explicando timtim por timtim em portugues claro
o codigo fonte e as 'escolhas em codeTime'
dos projetos que mantenho

2
flipcruz182

Percebi isso logo no início dos meus bate papo com os devs parceiros que tocam nossos projetos, a minha pergunta super leiga é, existe um modelo / padrão de documentação ou isso depende muito da categoria e / ou pessoas ?

1
caioken

Documentação de código é postura de Dev Senior. É ser profissional. É ser responsável.

Dev é preguiçoso para documentação. Muitos são, eu NUNCA !

Sempre tive pra mim que documentação faz parte de QUALQUER entrega. QUALQUER.

Desde apenas comentários no código até outros artefatos desenvolvidos.

Já tive que documentar coisas que "herdei" de outros devs e confesso que é estressante mas ao mesmo tempo, tenho certeza que contribui para que outros peguem uma situação melhor do que a que veio para mim.

Então não seja um dev preguiçoso, irresposável, que só quer de implementar e aperta o f* para a documentação. A pessoa que faz isso está criando uma bomba relógio que explodirá no colo de alguém no futuro.

Além disso a documentação serve para daqui 3, 6 meses, 1 ano, quando você tem que voltar a dar manutenção eu algo, ela vai te poupar tempo de análise.

Enfim, documentação é postura de um dev senior, alguém que entende que a documentação é tão importante quanto o código e deveria sempre existir em qualquer entrega.

1
correiatec
Autor
Autor

Eu tinha pensado em uma base de conhecimento.
Ao invés de você ficar perguntando, tem isso, tem aquilo.
Ou pior sair desenvolvendo novamente algo que já existe.
Seria bem mais prático, pesquisar nessa base e pronto tá lá, só usar.
Mas é claro que a cada método/função nova essa base deveria ser populada.