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,547
  • 40
  • 183
  • 216
gkdsp
  • 497
  • 4
  • 11
  • 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 08 '11 at 20:14
  • @Daenyth: Maybe it was bad pseudocode? – FrustratedWithFormsDesigner Jun 08 '11 at 20:15
  • 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 08 '11 at 20:16
  • @Frustrated: I read this as though the developer he's talking with doesn't understand the *concept* of pseudocode. Maybe I'm reading it wrong. – Daenyth Jun 08 '11 at 20:16
  • @Daenyth: Yeah that could be, some first-year student or something. – FrustratedWithFormsDesigner Jun 08 '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. – GEL Jun 08 '11 at 20:18
  • how far down into details are you trying to go? maybe start with documenting what each function does separately and then do an overall picture to give an idea what they are supposed to do together.. – Alex Jun 08 '11 at 20:20
  • 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 08 '11 at 20:38
  • 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 08 '11 at 20:18
  • @Andrea Yup, that's what I meant. That is, is there any recommended software to create such a document explaining program code? Something like, the left-half of the page has the code (color-coded of course, so comments are one color, statements another color, etc), and the right-half of the page comments on it, etc. – gkdsp Jun 08 '11 at 20:41
  • In my experience, developers hate pseudocode. Correctly, because the people writing the pseudocode mostly don't have clue one what a computer program is. – Neil Butterworth Jun 08 '11 at 20:45
  • Appreciate the tip on using Word, lewellen. Neil, what do you prefer if not pseudo code? Thanks everyone for your comments. – gkdsp Jun 08 '11 at 20:50
  • 1
    if it was me I'd want a high level overview of what it does, and the actual matlab code. And possibly a few hours with the matlab developer who actually wrote it, if he's still around. Pseudo code is fine but the problem is that it doesn't execute. With coding the devil's in the details, and in my experience there's always a few key details that are missing. – Kevin Jun 08 '11 at 21:01
  • I think nobody has addressed an important question here, why do you need to translate a perfectly fine Matlab code to some other language? – Lie Ryan Jun 08 '11 at 22:03
  • What will the program do, and in what domain? –  Jun 08 '11 at 22:03
  • @Neil - I agree that developers hate pseudocode - but only when it's written by someone who doesn't write code. I quite often write pseudocode for my own code, often as comments in a source-code file that will be deleted/clarified as the code itself gets filled in. I remember many years ago doing a schoolroom what's-best-and-can-we-mix-and-match comparison of graphical representations of imperative code. Nassi–Shneiderman scored best, but conditionals subdivide the width too much, and boxes all around seemed OTT. We ended up with pseudocode, but with lines highlighting indentation on the left. –  Jun 08 '11 at 22:27
  • `clearly communicate code to a developer` Let him read the code and answer his questions. He will do the rest as he learn the Matlab code, he will be able to read it... never heard about someone asking how to communicate code to a developer... nice! – WarrenFaith Jun 08 '11 at 23:35

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,808
  • 2
  • 84
  • 151
  • 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 08 '11 at 21:02
  • @gkdsp: there probably is, but chances are everyone bidding on the project will have ms-word – Steven A. Lowe Jun 08 '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 08 '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 Jun 08 '11 at 23:08
  • 2
    @btilly: get open office, and stop yer whinin' ;-) – Steven A. Lowe Jun 08 '11 at 23:11
  • @Steven A. Lowe: I have open office. I've also seen how often it isn't quite compatible. And firing up something that big to read what should be plain text is annoying. – btilly Jun 09 '11 at 00:52
  • @Richard DesLonde: I have both philosophical and moral reasons to avoid Microsoft. Among other things their horrible business practices lead to the death of a friend of mine. See http://www.iwethey.org/ed_curry/. Every time I hear about another compromise of US government software in a role that, by law, Microsoft software should never have legally been used in, I get saddened again. – btilly Jun 09 '11 at 00:55
  • I've tried to use OpenOffice, then LibreOffice, and each time had to return to Word to overcome bugs with importing linked images. Even sent in questions to their respective forums, but never got an answer. Word seems to work fine for everything I throw at it. Of course, I'd rather user Oo or LO. – gkdsp Jun 09 '11 at 02:00
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
  • 2
  • 12
  • 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 09 '11 at 04: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 09 '11 at 11:19
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,489
  • 3
  • 22
  • 33
  • 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 08 '11 at 20:53
  • 1
    Oh man. I don't envy you, OR the company that wins the bid. – Kevin Jun 08 '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 James Jun 08 '11 at 21:16
  • Completely agree Ed, thanks. I'm using Illustrator for drawing figures, etc. to explain the algorithms. Just wondering what the best approach is for combining everything. Thanks! – gkdsp Jun 08 '11 at 21:22
  • 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 James Jun 08 '11 at 21:31
  • 1
    whitebord + videorecorder –  Jun 08 '11 at 22:04
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,291
  • 1
  • 30
  • 41
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,861
  • 9
  • 53
  • 96