8

I'm a scientific person needing to document complex Matlab code to hand to a developer for him/her to understand and program in a different language. In the past, I've used MS Word (explaining each program step as a new row in a table), and then Excel, but didn't find either particularly well suited to displaying my Matlab code and entering comments in a clear and concise way to document it.

I'm wondering if there's any better technique to communicate pseudo-code to a developer. Any existing software (free?) or other platform (e.g. TextWrangler) particularly suited to providing code and some method for explaining it? Hoping to learn from others' experiences doing the same thing. Thanks in advance.

After reading some comments, let me try to explain more... I assume all developers know pseudo-code, but I don't assume many know Matlab code. Thus, if I write in pseudo-code, I can ignore the Matlab code (or provide it for reference, etc.). But my question is really simpler... is there any software or platform people have used in the past to clearly communicate code to a developer? Something that enables the person creating the document to easily describe the code? For example, you can embed code that the software color codes (one color for comments, another for reserved words (if, then, else, for, etc.), etc.), and along one side there's room for me to enter explanations and references, etc. I tried do this using MS products, but thought since there's an industry of people needing to do the same thing, maybe someone has developed a system to make this easier.

yannis
  • 39,647
gkdsp
  • 497

5 Answers5

4

put the MATLAB code into ms-word; change the font to courier (monospace) if it helps

highlight each line and use Insert Comment (under the Review tab in word 2010) to enter your explanation

the developer can do the same; word will make different comment boxes for each of you

Steven A. Lowe
  • 33,828
2

I'd hire a coder who is already familiar with Matlab. Less pain all round for everyone. There are plenty of us ex-mathematicians working in software development :-)

TrojanName
  • 373
1

Whiteboard!

MATLAB's syntax is pretty far out there compared to a "normal" procedural language (~= for not equals!!!!?), so documenting every line of code is probably not going to be too helpful (a one-line matrix transformation in MATLAB will oftentimes translate to a few hundred lines of C code, for example).

Why not spend some time going through the gist of the functionality of the program with the developer in front of a whiteboard with a laptop with (or printout of) the code at hand. That way you can get stuck into the difficult to understand bits of the program itself, not the MATLAB syntax.

If you really are just expecting them to translate it into a different language you don't want them to have to know the ins and outs of how MATLAB does its processing anyway, it probably won't translate very well into other languages, MATLAB is very specialised for working with matrices. Really you just need them to know that you need to multiply matrix A by product B and do X with the output.

Ed James
  • 3,499
  • 3
  • 24
  • 34
1

How about using code review tools like Rietveld or ReviewBoard

You can add comments and discussions that aren't part of the Matlab code itself.

Lie Ryan
  • 12,496
0

I'm a scientific person needing to document complex Matlab code to hand to a developer for him/her to understand and program in a different language. In the past, I've used MS Word (explaining each program step as a new row in a table), and then Excel, but didn't find either particularly well suited to displaying my Matlab code and entering comments in a clear and concise way to document it.

Well, Word could work ... I guess. You define different styles for different parts of code (comments in green, code in ...). Not sure though how much is this practical in reality. What's wrong with just exporting it as HTML and serving the developer in question that. He can always use the online help, if there is a problem, if he/she do not already have MATLAB installed.

After reading some comments, let me try to explain more... I assume all developers know pseudo-code, but I don't assume many know Matlab code. Thus, if I write in pseudo-code, I can ignore the Matlab code (or provide it for reference, etc.).

Since you're translating MATLAB code, and you say you're a scientific person, can one assume that mathematical equations could be one viable alternative.

Note of caution though ... sometimes MATLAB functions used are NOT the ones described in the help. Test your new code throughourly along the way.

Rook
  • 19,947