É normal / aceitável anotar notas, pensamentos, algoritmos, decisões durante a codificação e manutenção? [fechadas]

Algumas pessoas têm esse problema que não conseguem pensar sem palavras. E anotar seus pensamentos e decisões é a maneira mais eficaz de proceder.

Então - é normal e aceitável anotar meus pensamentos e decisões em algum arquivo do Notepad ++ durante a codificação?

Às vezes, deve ser aceitável, por exemplo, ao recriar documentação técnica ou raciocinar sobre algoritmos mais complexos, mas às vezes pode ser estranho, por exemplo, quando estou pensando em opções de design e tentando julgar.

O impacto dessa prática na produtividade não é claro. Por um lado, o raciocínio com palavras interiores pode ser mais rápido do que com as palavras escritas. Do outro lado - problemas mais complexos requerem escrita. Além disso, se alguém está preso a mais opções de design, o sentimento é melhor quando a decisão é escrita, aumentando a moral.

Não é apenas normal, é uma boa ideia.

Há uma citação famosa

"Dê-me seis horas para cortar uma árvore e passarei os quatro primeiros afiando o machado".

Dedique um tempo para organizar seus pensamentos e planejar seu trabalho antes que a codificação seja um tempo bem gasto. Colocar esses pensamentos no papel dará a você tempo para refletir sobre seus planos, criticá-los e organizá-los de maneiras que seriam muito difíceis se feitas apenas "em sua cabeça".

Sim, isso é perfeitamente aceitável e normal.

Documentar seu processo de tomada de decisão é frequentemente valioso ao revisitar o código, para ajudar a determinar por que o código foi escrito de uma certa maneira.

Essas notas podem ser incluídas diretamente no código como comentários, se forem curtas o suficiente. Comentários estendidos geralmente são mantidos como parte de um documento de design técnico externo.

É uma ideia muito boa. Até que se torne uma maneira de procrastinar.

A chave é o equilíbrio. Acho que sou mais produtivo se não me encaixar, mas capturar idéias à medida que elas surgirem.

Se eu estiver trabalhando em um nível baixo e surgir uma idéia de alto nível, basta anotá-la e voltar mais tarde.

Planejar o trabalho é uma boa idéia, mas, a menos que você precise se comunicar ou apresentar diante do público, as melhores ferramentas são caneta e guardanapo. Capture a ideia. Não perca tempo fazendo bonito.

Em qualquer situação profissional, não é apenas "normal e aceitável", é obrigatório. O ciclo de desenvolvimento típico consiste em duas fases da documentação antes que qualquer codificação comece:

1. Documento de Requisitos Funcionais: normalmente escrito por analistas de negócios, especificando a funcionalidade a ser implementada.

2. Documento de projeto detalhado: que é basicamente o que você está falando, apenas mais formal, especificando a decomposição funcional (fatoração) do sistema, algoritmos, etc. Alguns dos meus (muito) antigos estão online, por exemplo, isso .

Para documentação menos formal, eu 110% concorda com as observações anteriores sobre comentários embutidos. Esse é o único caminho a percorrer; de um jeito ou de outro, tudo o mais acaba se perdendo. Mas comentar em linha, puro e atencioso, é uma habilidade de codificação separada, desenvolvida através do esforço e da prática como qualquer outra habilidade. Você pode ver algumas das minhas coisas (muito) antigas em, por exemplo, isso . Esse estilo pode ou não apelar para você. Eu recomendo encontrar primeiro um código bem comentado com o estilo que você gosta e emular esse código no seu próprio código. Depois de um tempo, adapte-o como achar melhor.

Um ótimo lugar para colocar esse tipo de informação está diretamente na mensagem de confirmação do seu sistema de controle de versão (SVN, git, etc). Dessa forma, você pode ver as alterações e o raciocínio delas no mesmo local.

Além das outras boas respostas, acrescentarei que muitas vezes escrevo meus pensamentos sobre o que estou tentando fazer.

Ser muito explícito sobre a articulação do que estou tentando fazer me ajuda a perceber pressupostos, suposições e / ou requisitos que não necessariamente se aplicam.

Isso então sugere alternativas, as quais eu posso refletir melhor cada uma delas; essa escrita ajudando a salvar meu lugar se eu pensar em outra coisa.

Faço anotações rápidas para explorar a respiração e a profundidade, para que funcione recursivamente, ajudando-me a elaborar, navegar e avaliar uma árvore de soluções, fazendo backup, explorando, descobrindo, percebendo e decidindo.

Anotar tudo o que pode economizar tempo para você / (novos) membros da equipe é um tempo bem gasto. Apenas certifique-se de que é algo que alguém possa precisar mais tarde e não pense demais, a menos que seja um projeto de longo prazo.

Também não deve demorar algum tempo. Se você passa um tempo pensando, pode escrever seus pensamentos de 1 para 1 (contanto que eles sejam úteis para alguém).

O verdadeiro problema pode estar exagerando no que você escreve. Só porque você está escrevendo não significa que você precisa aderir a algum formato já existente ou precisa fazer todo o caminho para criar uma documentação completa.

Se você optar por não escrever nada e apenas escrever notas não-formais em um bloco de notas, basta escrever notas não-formais.

Você diz: "Algumas pessoas têm esse problema que não conseguem pensar sem palavras. E escrever seus pensamentos e decisões é a maneira mais eficaz de proceder".

Se anotar seus pensamentos e decisões é a maneira mais eficaz de proceder, por que não seria normal e aceitável proceder da maneira mais eficaz? Você faz o que funciona melhor para você. Pode não ser o que funciona melhor para outra pessoa. Nesse caso, você não deixa que outra pessoa lhe diga o que é melhor para você e não diz o que é melhor para ela. Todo mundo faz o que é melhor para eles.

Os humanos só podem segurar cerca de sete "coisas" na cabeça de uma só vez. Essa é a razão dos números de telefone de sete dígitos. Para que os programadores trabalhem com eficiência, eles precisam encontrar algum tipo de sistema para descarregar as coisas da memória e recuperá-las rapidamente mais tarde, conforme necessário. Suas anotações são uma maneira óbvia e direta, mas todos que trabalham em algo moderadamente complexo precisam fazê-lo de alguma forma . Quando você emparelha um programa com alguém, procure um método.

Uma maneira comum é o desenvolvimento orientado a testes. Nesta metodologia, você escreve um teste com falha, escreve apenas o código suficiente para obter a aprovação do teste e refatora o código para torná-lo mais agradável, mantendo todos os testes existentes aprovados. Essa metodologia mantém todas as suas "notas" codificadas dentro dos testes. As pessoas podem trabalhar muito rapidamente dessa maneira sem parecer fazer anotações, porque estão focadas apenas no próximo teste.

Outra maneira comum é simplesmente escrever suas anotações em seu código como comentários ou stubs de pseudocódigo e substituí-lo gradualmente pela coisa real. É assim que eu costumo escrever algoritmos. Meu primeiro rascunho é apenas uma função principal do pseudocódigo e, gradualmente, ele se preenche em níveis cada vez mais profundos de abstração.

Não se sinta mal ao usar qualquer método que funcione para você, mas tente perceber quais métodos seus colegas "eficientes" estão usando. Eles têm as mesmas limitações humanas que você.