Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question

closed as primarily opinion-based by gnat, MichaelT, Dynamic, Yusubov, Jimmy Hoffa Jul 17 '13 at 18:26

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise.If this question can be reworded to fit the rules in the help center, please edit the question.

1  
I wonder if this question is just worded poorly or I'm misunderstanding. How could a developer not understand what pseudocode is? Are you talking about high-level docs for how the program works? –  Daenyth Jun 8 '11 at 20:14
4  
Why give the developer pseudocode? Why not give them that Matlab code and let them convert it themsevles? A decent developer should be able to learn Matlab and figure out how the program works. –  FrustratedWithFormsDesigner Jun 8 '11 at 20:16
1  
I think he's describing a developer who knows nothing about MatLAB, which is even understandable as the former is a very niche programming language. What I suspect the OP is asking is something along the lines of "Do you know any proven system/process/procedure which will make transition easier for someone totally unaware of MATLAB to get to grips with it and translate the code into another programming language?" But then, it's just me, I might be wrong! –  Andrea Raimondi Jun 8 '11 at 20:18
1  
Word should be suitable. There are two approaches you could take. Orienting the page in landscape mode and presenting your MATLAB code on the left hand side and your annotations on the right hand side. Or portrait and switch back and forth between code and exposition. –  lewellen Jun 8 '11 at 20:18
1  
If I were the developer I'd want to know that % starts a comment, and then I'd want explanatory comments added to the Matlab code. And let me come back with questions about things that didn't make sense to me. That would be easiest all around. –  btilly Jun 8 '11 at 20:38

5 Answers 5

up vote 4 down vote accepted

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

share|improve this answer
    
Thanks Steven, this is the type of answer I was hoping to see. I thought about doing this actually, but hoped there'd be some alternative method dedicated to such a task for programmers (not really being one myself). Thanks –  gkdsp Jun 8 '11 at 21:02
    
@gkdsp: there probably is, but chances are everyone bidding on the project will have ms-word –  Steven A. Lowe Jun 8 '11 at 21:11
4  
@Stephen A. Lowe: As a Linux/Mac guy, I hate it when people assume that I have ms-word. –  btilly Jun 8 '11 at 22:50
    
@btilly: Most people do. Unless you have a philosophical or moral reason not to, you should as well. Otherwise you are just needlessly causing problems for yourself and (potentially) others. –  Richard DesLonde Jun 8 '11 at 23:08
2  
@btilly: get open office, and stop yer whinin' ;-) –  Steven A. Lowe Jun 8 '11 at 23:11

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 :-)

share|improve this answer
2  
+1: if the developer you have isn't willing to learn Matlab, find a better developer. Besides, if he isn't willing to learn Matlab, how well can he do in the translation? –  kevin cline Jun 9 '11 at 4:55
    
I definitely think it'd be much easier finding someone who already knows Matlab and get them to learn the 2nd language, rather than vice versa. (Unless the 2nd language is something even more obscure and difficult to learn! LOL) –  TrojanName Jun 9 '11 at 11:19

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.

share|improve this answer

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.

share|improve this answer

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.

share|improve this answer
    
I agree Ed. One Matlab line of code could be a heck of a lot more in another language. That's why I don't think it's sufficient to simply supply the Matlab program. Regarding whiteboarding, that requires you to be in the same city/state/country, which isn't typically possible. Also, I'm generating documents for companies to bid on the project. I need to explain what I want them to do before deciding on the team or individual that will do it. –  gkdsp Jun 8 '11 at 20:53
1  
Oh man. I don't envy you, OR the company that wins the bid. –  Kevin Jun 8 '11 at 21:03
    
Ah, you didn't note the lack of physical proximity in the question so I'm sorry this isn't a brilliant fit. I've had the job of working with MATLAB on numerous occasions and as far as I'm concerned the source code would be effectively useless unless you're both well versed in MATLAB to start with and also well versed in what the code actually does. I would definitely try to go with some sort of pictorial method of getting the message across, like flowcharts or something. Perhaps a bunch of (I can't believe I'm suggesting this) UML activity diagrams might be appropriate? –  Ed Woodcock Jun 8 '11 at 21:16
1  
To be honest, if I was going to have a bunch of formatted code, text and images interspersed I'd probably choose LaTeX and export it to a PDF. The big benefit of LaTeX over word is that it can actually handle code nicely (which I have never managed to get Word to do properly). –  Ed Woodcock Jun 8 '11 at 21:31
1  
whitebord + videorecorder –  user1249 Jun 8 '11 at 22:04

Not the answer you're looking for? Browse other questions tagged or ask your own question.