Qual é a melhor plataforma para explicar o pseudo-código a um desenvolvedor que não sabe nada sobre isso? [fechadas]

8

Sou uma pessoa científica que precisa documentar códigos complexos do Matlab para entregar a um desenvolvedor para que ele entenda e programe em um idioma diferente. No passado, eu usei o MS Word (explicando cada etapa do programa como uma nova linha em uma tabela) e depois o Excel, mas não achei particularmente adequado para exibir meu código Matlab e inserir comentários de forma clara e concisa. maneira de documentá-lo.

Gostaria de saber se existe alguma técnica melhor para comunicar pseudo-código a um desenvolvedor. Algum software existente (gratuito?) Ou outra plataforma (por exemplo, TextWrangler) particularmente adequado para fornecer código e algum método para explicá-lo? Na esperança de aprender com as experiências dos outros, fazendo a mesma coisa. Desde já, obrigado.

Depois de ler alguns comentários, deixe-me tentar explicar mais ... Presumo que todos os desenvolvedores conhecem pseudo-código, mas não presumo que muitos conheçam o código Matlab. Portanto, se eu escrever em pseudo-código, posso ignorar o código do Matlab (ou fornecê-lo para referência, etc.). Mas minha pergunta é realmente mais simples ... existe algum software ou plataforma que as pessoas usaram no passado para comunicar claramente o código a um desenvolvedor? Algo que permite que a pessoa que cria o documento descreva facilmente o código? Por exemplo, você pode incorporar códigos que os códigos de cores do software (uma cor para comentários, outra para palavras reservadas (se, então, outra coisa para, etc.), etc.) e, ao longo de um lado, há espaço para eu inserir explicações e referências, etc. Tentei fazer isso usando produtos MS, mas pensei que há uma indústria de pessoas que precisa fazer a mesma coisa,

pseudocode gkdsp
fonte
1
Gostaria de saber se esta pergunta é apenas mal formulada ou estou mal entendido. Como um desenvolvedor pode não entender o que é pseudocódigo? Você está falando de documentos de alto nível sobre como o programa funciona?
Daenyth
4
Por que dar ao desenvolvedor pseudocódigo? Por que não dar a eles esse código do Matlab e deixá-los convertê-los em si? Um desenvolvedor decente deve ser capaz de aprender Matlab e descobrir como o programa funciona.
FrustratedWithFormsDesigner
1
Acho que ele está descrevendo um desenvolvedor que não sabe nada sobre o MatLAB, o que é até compreensível, pois o primeiro é uma linguagem de programação muito específica. O que eu suspeito que o OP está perguntando é algo como "Você conhece algum sistema / processo / procedimento comprovado que tornará a transição mais fácil para alguém totalmente inconsciente do MATLAB se familiarizar com ele e traduzir o código para outra linguagem de programação?" " Mas então, sou só eu, posso estar errado!
Andrea Raimondi
1
O Word deve ser adequado. Existem duas abordagens que você pode adotar. Orientando a página no modo paisagem e apresentando seu código MATLAB no lado esquerdo e suas anotações no lado direito. Ou retrato e alterne entre código e exposição.
GEL
1
Se eu fosse o desenvolvedor, gostaria de saber que %inicia um comentário e, em seguida, gostaria de adicionar comentários explicativos ao código do Matlab. E deixe-me voltar com perguntas sobre coisas que não faziam sentido para mim. Isso seria mais fácil por toda parte.
btilly

Respostas:

4

coloque o código MATLAB em ms-word; altere a fonte para courier (monospace) se isso ajudar

destaque cada linha e use Inserir comentário (na guia Revisão na palavra 2010) para inserir sua explicação

o desenvolvedor pode fazer o mesmo; word criará caixas de comentários diferentes para cada um de vocês

Steven A. Lowe
fonte
Obrigado Steven, este é o tipo de resposta que eu esperava ver. Pensei em fazer isso, na verdade, mas esperava que houvesse algum método alternativo dedicado a essa tarefa para programadores (não sendo eu mesmo). Obrigado
gkdsp
@gkdsp: provavelmente existe, mas as chances são todos de licitação do projeto terá ms-word
Steven A. Lowe
4
@ Stephen A. Lowe: Como um cara de Linux / Mac, eu odeio quando as pessoas assumem que eu tenho ms-word.
btilly
@ btilly: A maioria das pessoas faz. A menos que você tenha uma razão filosófica ou moral para não, você também deve. Caso contrário, você estará causando problemas desnecessariamente para si e para os outros (potencialmente).
Richard
2
@btilly: get escritório aberto, e parar yer whinin' ;-)
Steven A. Lowe
2

Eu contrataria um programador que já esteja familiarizado com o Matlab. Menos dor o tempo todo para todos. Muitos de nós, ex-matemáticos, trabalhamos no desenvolvimento de software :-)

TrojanName
fonte
2
+1: se o desenvolvedor que você possui não estiver disposto a aprender Matlab, encontre um desenvolvedor melhor. Além disso, se ele não estiver disposto a aprender Matlab, como ele pode se sair na tradução?
Kevin cline
Definitivamente, acho que seria muito mais fácil encontrar alguém que já conheça o Matlab e levá-lo a aprender a segunda língua, em vez de vice-versa. (A menos que o segundo idioma é algo ainda mais obscuro e difícil de aprender LOL!)
TrojanName
1

Whiteboard!

A sintaxe do MATLAB está bastante distante em comparação com uma linguagem processual "normal" (~ = para não é igual !!!!?), Portanto, documentar cada linha de código provavelmente não será muito útil (uma transformação de matriz de uma linha em O MATLAB muitas vezes se traduz em algumas centenas de linhas de código C, por exemplo).

Por que não gastar algum tempo analisando a essência da funcionalidade do programa com o desenvolvedor na frente de um quadro branco com um laptop com (ou impresso) o código em mãos. Dessa forma, você pode ficar preso nos bits difíceis de entender do próprio programa, não na sintaxe do MATLAB.

Se você realmente espera que eles o traduzam para um idioma diferente, você não quer que eles conheçam os meandros de como o MATLAB processa seu processo de qualquer maneira, provavelmente não se traduzirá muito bem em outros idiomas, o MATLAB é muito especializado para trabalhar com matrizes. Realmente, você só precisa que eles saibam que você precisa multiplicar a matriz A pelo produto B e fazer X com a saída.

Ed James
fonte
Eu concordo Ed. Uma linha de código do Matlab pode ser muito mais em outro idioma. É por isso que acho que não basta fornecer o programa Matlab. Em relação ao quadro branco, isso exige que você esteja na mesma cidade / estado / país, o que normalmente não é possível. Além disso, estou gerando documentos para as empresas licitarem no projeto. Preciso explicar o que quero que eles façam antes de decidir sobre a equipe ou o indivíduo que fará isso.
Gkdsp
1
Oh cara. Não invejo você, OU a empresa que vence a licitação.
Kevin
Ah, você não notou a falta de proximidade física na pergunta, então lamento que não seja um ajuste brilhante. Eu tive o trabalho de trabalhar com o MATLAB em várias ocasiões e, no que me diz respeito, o código fonte seria efetivamente inútil, a menos que você seja versado no MATLAB para começar e também versado no que o código realmente faz . Definitivamente, tentaria usar algum tipo de método pictórico para transmitir a mensagem, como fluxogramas ou algo assim. Talvez um monte de (não acredito que estou sugerindo isso) diagramas de atividades UML possa ser apropriado?
Ed James
1
Para ser honesto, se eu tivesse um monte de código formatado, texto e imagens intercalados, provavelmente escolheria o LaTeX e o exportaria para um PDF. O grande benefício do LaTeX sobre o Word é que ele pode realmente lidar bem com o código (o que eu nunca consegui fazer com que o Word fizesse corretamente).
Ed James
1
whitebord + videorecorder
1

Que tal usar ferramentas de revisão de código como Rietveld ou ReviewBoard

Você pode adicionar comentários e discussões que não fazem parte do próprio código do Matlab.

Lie Ryan
fonte
0

Sou uma pessoa científica que precisa documentar códigos complexos do Matlab para entregar a um desenvolvedor para que ele entenda e programe em um idioma diferente. No passado, eu usei o MS Word (explicando cada etapa do programa como uma nova linha em uma tabela) e depois o Excel, mas não achei particularmente adequado para exibir meu código Matlab e inserir comentários de forma clara e concisa. maneira de documentá-lo.

Bem, o Word pode funcionar ... eu acho. Você define estilos diferentes para diferentes partes do código (comentários em verde, código em ...). Não tenho certeza de quanto isso é prático na realidade. O que há de errado em apenas exportá-lo como HTML e atender ao desenvolvedor em questão. Ele sempre pode usar a ajuda on-line, se houver um problema, se ele / ela ainda não tiver o MATLAB instalado.

Depois de ler alguns comentários, deixe-me tentar explicar mais ... Presumo que todos os desenvolvedores conhecem pseudo-código, mas não presumo que muitos conheçam o código Matlab. Portanto, se eu escrever em pseudo-código, posso ignorar o código do Matlab (ou fornecê-lo para referência, etc.).

Como você está traduzindo o código MATLAB e diz que é uma pessoa científica, pode-se supor que as equações matemáticas podem ser uma alternativa viável.

Nota de cautela ... algumas vezes, as funções do MATLAB usadas NÃO são as descritas na ajuda. Teste seu novo código durante todo o processo.

Torre
fonte