TRAVELING SALESMAN PROBLEM USING CONVHULL

Very simple m-file that produce solution comparable with other TSP toolbox in the matlab exchange.

Description

You can find the description at:

http://www.advancedmcode.org/traveling-salesman-problem-using-convhull.html

• MATLAB release: MATLAB 7.5 (R2007b)
• Other requirements: Shoul works on all platforms
• Other Files: license.txt, ; TSPconvhull.m

[John D'Errico]

The website administrator has removed the author's self ratings. Good. Now, I'll spend some time on a review.

This code has no effective help. Look at the functions that you will find in MATLAB itself. Those functions have a block of comments, the VERY first contiguous block. This is what help returns when you call it on your function. If you use help on this code, all you get is:

Author: Giaccari Luigi
Last update: 10/11/2008

This is all you get. The limit of how we know how to use this software. There is no hint of what it does, or how to use it. Good software helps the user. This software tells you only the author's name.

Next, there is a function called lookfor in MATLAB. This function helps a user to find code they know must exist in matlab, but they do not recall the name. The idea is to use lookfor to search for keywords, placed in the very first line of the help. For example, if you want to do an interpolation in matlab, but you have no idea what function might do this, type

lookfor interpolation

A list of functions will appear, including interp1, interp2, etc. All of this is mediated by the inclusion of a single line of help - the very first line of help. It should contain a simple description of your function, including the likely keywords that might be searched.

This code has none of these useful things. Yes, if you look inside the code, you will find some help. But how will anybody ever know to even look there? There is no H1 line, so lookfor fails. Forcing a user to edit your code just to learn how to use it is bad form.

How about the help itself? I mean, if you do edit the code, what does it tell you? Even there, it tells you very little. There is no simple description of what the arguments are, of what they mean. What shape should they be? Does this code only work on doubles? Or will it work on uint8 variables? Must the arguments be vectors? Row vectors, column vectors? Sorry, no hints to be found.

There is error checking. Good there. But, the author has never told his users what will be checked for. So what good is it?

I did find internal comments in the code, explaining some of what is done internally. This is good, since it will help the author or another user to debug later problems.

How about the code itself? Mlint finds 3 minor flags. There are a couple of variables created that are never used. Minor deadwood there. I found some plots, with the comment that to suppress output, just comment the plot out. Sorry, but good code is a bit more friendly.

Overall, with readable, usable help and an H1 line, I'd probably rate this as a 4. With more comments in the code to explain how it is working, I'd push that rating to a 5. Without the useful help, this just "Needs Improvement". No code that lacks useful help can be considered good. Your job as a programmer does not stop when you finish writing code. You must have written the help too. (My own style is to write the help before I ever write a line of code.)

[Luigi Giaccari]

Last Update:
Added distance matrix, more comments, and fixed the missing % in hep lines.