Documentação do código-fonte externalizada com hiperlink [fechada]

Por que ainda incorporamos descrições em linguagem natural do código-fonte (ou seja, a razão pela qual uma linha de código foi escrita) dentro do código-fonte, e não como um documento separado?

Dado o amplo espaço imobiliário oferecido aos ambientes de desenvolvimento modernos (monitores de alta resolução, monitores duplos, etc.), um IDE poderia fornecer painéis de semi-bloqueio em que o código-fonte é visualmente separado - mas intrinsecamente ligado a - seus comentários correspondentes. Por exemplo, os desenvolvedores poderiam escrever comentários sobre o código-fonte em uma linguagem de marcação hiperligada (vinculando-se a requisitos adicionais de software), o que impediria simultaneamente a documentação de sobrecarregar o código-fonte.

Quais deficiências inibiriam esse mecanismo de desenvolvimento de software?

Uma maquete para ajudar a esclarecer a pergunta:

Quando o cursor está em uma linha específica no código-fonte (mostrado com um plano de fundo azul acima), a documentação que corresponde à linha no cursor é destacada (ou seja, diferenciada dos outros detalhes). Conforme observado na pergunta, a documentação permaneceria na etapa de bloqueio com o código-fonte, à medida que o cursor salta pelo código-fonte. Uma tecla de atalho pode alternar entre "modo de documentação" e "modo de desenvolvimento".

As vantagens potenciais incluem:

• Mais código fonte e mais documentação na (s) tela (s) de uma só vez
• Capacidade de editar a documentação independentemente do código-fonte (independentemente do idioma?)
• Escreva documentação e código fonte em paralelo, sem conflitos de mesclagem
• Documentação com hiperlink em tempo real com formatação de texto superior
• Tradução automática em tempo quase real para diferentes idiomas naturais
• Cada linha de código pode ser claramente vinculada a uma tarefa, requisito comercial, etc.
• A documentação pode registrar o carimbo de data / hora automaticamente quando cada linha de código é gravada (métricas)
• Inclusão dinâmica de diagramas de arquitetura, imagens para explicar relações, etc.
• Documentação de fonte única (por exemplo, trechos de código de tag para inclusão no manual do usuário).

Nota:

• A janela da documentação pode ser recolhida
• O fluxo de trabalho para visualizar ou comparar arquivos de origem não seria afetado
• Como a implementação acontece é um detalhe; a documentação pode ser:
  • mantido no final do arquivo de origem;
  • dividido em dois arquivos por convenção ( filename.c, filename.c.doc); ou
  • totalmente orientado a banco de dados
• Por documentação com hiperlink, refiro-me à vinculação a fontes externas (como StackOverflow ou Wikipedia) e documentos internos (ou seja, um wiki em um subdomínio que poderia fazer referência cruzada da documentação de requisitos de negócios) e outros arquivos de origem (semelhantes aos JavaDocs).

Tópico relacionado: O que há com a aversão à documentação no setor?

Esse problema me incomoda o tempo todo, e eu tive uma idéia da direção que deveríamos tentar resolver (foi assim que encontrei essa pergunta).

Acho que o problema da documentação vinculada foi considerado errado quando decidimos incluir a documentação do usuário no código-fonte. Como a docco faz.

Antes de tudo, vamos diferenciar os comentários do código da documentação do usuário.

Os comentários de código normalmente são melhores quando são curtos, super curtos, de fato, para que eu possa realmente ler o código que faz as coisas sem precisar ver alguma poesia de por que e como funciona.

Os comentários do usuário são destinados a pessoas que tentam usar sua biblioteca / API e podem incluir exemplos de uso, explicação de por que foi implementada dessa maneira ou instruções sobre como estender a biblioteca. Esse tipo de comentário costuma ser bem detalhado.

Eu concordo com o fato de que a documentação deve ser escrita em texto sem formatação, para que não seja fixado pelo fornecedor e seja fácil adicionar um VCS. Mas acho que manter a documentação do usuário no arquivo de origem foi um grande erro por pelo menos duas razões:

• Código mais difícil de ler
• Documentação insuficiente (suponha que eu precise de duas páginas de documentação usando o mesmo código de exemplo ou de uma página de documentação que precise intercalar o código de dois arquivos de origem diferentes).

Então, por que queremos tê-lo no mesmo arquivo? Bem, ninguém quer ter suas documentações fora de sincronia a partir do código. Mas fazemos de qualquer maneira, e especialmente nos dias de hoje com o grande sucesso do Markdown. Que eu acho que está no caminho certo, mas se ficar aquém, muito aquém.

Quando intercalamos comentários de código com comentários de usuários, temos uma ligação bidirecional. Isso nos permite ver facilmente qual comentário corresponde a qual parte do código. Também podemos ver se algum código não está documentado. O que ele não oferece, é uma maneira de verificar se o comentário está atualizado ou não, e isso acontece muito quando seu código é difícil de ler (porque a documentação o tornou feio).

E se, em vez de termos uma ligação de duas vias, tivermos uma maneira? Documentação apontando para o código. Poderíamos ter código de remarcação com comandos especiais como:

Some documentation right here that explains the following code:
   @include_file <path/to/some/file>:<line_start>-<line_end>
or
   @include_file <path/to/some/file>
     @starts_with "some regexp or literal text to search"
     @ends_with "another regexp"
or
   @include_file <path/to/some/file>
     @class MyClass
     @method foo
or any combination or way of linking you could imagine

We can even have semantic in the directives:
   @explain_code <path/and/same/of/above>
   @example_code <path/and/same/of/above>
   @performance_notice <path/and/same/of/above>

Which would do basically the same, but it adds the intention of why
do we want to add this code in the first place, which could be 
used different by an IDE. 

Isso tem o benefício de ser marcado com algumas adições e, com as ferramentas adequadas, podemos agregar mais valor a ela.

Imagine essa ligação unidirecional com ferramentas como o grunhido (mesmo com a tarefa de assistir). Você pode detectar quando um arquivo de origem é alterado, ver quais arquivos de documentação dependem dele e avisar o usuário (ou marcar em algum lugar) se o código que foi comentado foi alterado.

404 Página Não Encontrada

Ao trabalhar com código, você não deseja que seus comentários se percam e é isso que acontecerá quando você separar códigos e comentários em documentos separados.

Além disso, manter o controle de versão entre o documento de comentário e o documento de código causará mais sofrimento e ganho.

Algumas das sugestões que você faz são de que eu realmente gosto, mas que podem ser implementadas facilmente, além de ter código e comentários em um arquivo.

Possíveis desvantagens que vejo:

• Você precisa de um editor especial que implemente esse recurso

• O código não é mais apenas texto simples, fácil de manipular e confirmar com o VCS-es

• Você precisa de duas vezes mais largura de tela para trabalhar com o código

Quanto aos seus argumentos:

Mais código fonte e mais documentação na (s) tela (s) de uma só vez

Mas pode ser inconveniente se você deseja visualizar dois arquivos lado a lado.

Capacidade de editar a documentação independentemente do código-fonte (independentemente do idioma?)

Eu diria que é realmente uma desvantagem. Eu, pessoalmente, tento manter a documentação o mais próxima possível do código, para que não fique desatualizada.

Escreva documentação e código fonte em paralelo, sem conflitos de mesclagem

Mais uma vez, possivelmente uma desvantagem. Se seus documentos estão profundamente intercalados com o código, como você pode editá-los independentemente?

Documentação com hiperlink em tempo real com formatação de texto superior

Se estiver no código, já é em tempo real;) Quanto aos hiperlinks, o salto para a definição já está implementado na maioria dos IDEs.

Tradução automática em tempo quase real para diferentes idiomas naturais

Não vejo por que você não pode fazer isso com comentários / docstrings regulares.

Cada linha de código pode ser claramente vinculada a uma tarefa, requisito comercial, etc.

Eu não tenho certeza sobre isso ... Não pode ser alcançado com comentários regulares?

A documentação pode registrar o carimbo de data / hora automaticamente quando cada linha de código é gravada (métricas)

Os VCS-es já não fornecem esse tipo de informação?

Dito isto, gosto bastante do layout em si - mas não vejo a necessidade de alterar o formato do arquivo, não é tão difícil gerá-lo a partir de comentários regulares. Há vários geradores de documentação que fazem isso, por exemplo, a Docco e seus sucessores, como Pycco ou Marginalia .

Em primeiro lugar, os comentários do documento precisam seguir o código - movê-los para outro lugar apenas torna as coisas incrivelmente difíceis de manipular para obter praticamente zero ganho. Então, por que se preocupar!

O que poderia ser feito, porém, é pegar esses comentários incorporados e ocultá-los no editor, mostrando-os em um balão ou dica de ferramenta ou outros itens necessários. Eu espero que essa abordagem encoraje as pessoas a escrever muito mais documentação no código - por exemplo, uma descrição de uma classe poderia ser usada com a classe, e não em um documento de design externo.

No momento, é possível incorporar hiperlinks nos comentários do código e gerar documentos a partir do código usando ferramentas como Doxygen ou Sphinx. Eu acho que seria preciso alguma extensão sofisticada para o editor de código para suportar melhor essas ferramentas.

Eu não vincularia nenhuma linha de código a um rastreador de erros ou a uma ferramenta de requisitos, esse é um trabalho melhor para o seu SCM. Em seguida, você pode ver as edições de código por confirmação vinculadas a uma tarefa. Também não integraria a documentação armazenada no código ao rastreador de bugs - você seria ferrado se quisesse migrar para um novo (hmm, posso ver esse recurso sendo adicionado ao TFS agora) ou se você perdeu seu histórico de consolidação (o que acontece)

Além do que o @Bogdan já declara, eu acrescentaria alguns:

• Eu configurei meu IDE para ter sempre 2 arquivos de uma só vez. Com o recurso que você está sugerindo, eu precisaria basicamente de 2 monitores para ver a mesma quantidade de informações e 3 para fazer o que estou fazendo agora com 2.
• Ao navegar por um arquivo, você não vê os comentários imediatamente e, se não sabe exatamente o que está procurando, é muito difícil encontrá-lo.
• Ao pesquisar em um arquivo, não consigo pesquisar comentários diretamente (ou com a mesma facilidade).
• Às vezes, preciso fazer vários testes / escrever pequenos trechos de código no servidor ativo , por meio do ssh . Embora a funcionalidade que você está dizendo possa ser integrada ao VIM ou a outros editores de linha de comando - provavelmente haverá grandes problemas

• A maioria dos IDEs suporta códigos / comentários em colapso , com os resultados finais sendo os seguintes:

  Em vez do normal:

  

Torne o código mais legível, caso você não precise dos comentários.

Código-fonte e documentação da maneira que deve ser feita.

http://jasmine.github.io/2.3/introduction.html