Keep files and write documentation to be well-organised

This is a request for some suggestions/good practices rather than a technical MATLAB question. I have been doing some tests recently which have produced many data (by data I mean variables in a workspace). These data are produced by both twitching some parameters in functions and by using slightly different versions of the same function. At the moment the functions are not commented, but I'd like to spend some time writing a documntation, since most likely I will forget som details as soon as I stop working with them for a few weeks.

The question is: is there a standard "good" way to do this? And also to save the data fils so that I don't go crazy? At the moment if I have, say, parameters I just save the data as "a=a_0_b=b_0_c=c_0.mat" where are some particular values. But this isfast becoming quite unfeasible, s i'd like to know how it's supposed to be done.

[Stephen23]

Why not just save the variables a, b, c, etc inside the Mat file?

Answer 1

[Rik]

My advice would be to start writing the comments before you write the code.

Each idea/thing should be described with a comment. You can still do that with your completed code. The benefit of writing it that way is that you are forced to think about your steps in advance. It also makes sure you write your code in short sections. Each section could potentially be separated into a stand-alone function if it becomes too large.

For functions you should make sure that you have a description of the input and the outputs, along with a few examples with valid syntax and expected output. Once your project becomes more serious, those could be added to a test suite.

As to saving data, I would recommend storing this kind of metadata in a struct. You could even have a main lookup table, where you use a struct array to store the parameters and a file name. The file name could either be a hash of the parameters, or what you already did here.

You should make sure your functions have a stable interface. You should not change them for only two reasons: to add functionality or to fix a bug. Any other change means that you have a parameter you are hard-coding. Change that into an input parameter instead.