This program gets over than 30 main parameters of a furnace such as number of passes, furnace geometry, mass flow rate, number of shield tubes, ... and as result calculates pressure loss, number of tubes rows, wall mean temperature, total duty heat capacity. For more information see the following well commented M-File
I want to know much more.
I had to look at this "hot" function, as the author claimed it to be well commented. Is this a valid claim?
Yes, there are many internal comments. This is good. And compared to some of the wholly uncommented codes that are submitted, it is vastly better. But there are many parameters that one must deal with in this code. Look at a few lines of the code:
%################ Input Parameters################
Note that ti and to are left without any definition, except that they are apparently temperatures. The user is left to guess what they refer to. Perhaps you can guess. Input and output temperature? The same is true of many of the parameters. A truly well commented code would be more explicit.
Further on, we see more examples of incomplete comments. These lines below tell me the apparent size of the furnace. (A big one it seems.) But nowhere is it explicitly stated the assumed shape or configuration of the furnace. When I first saw this file, I did not know if it described the design of something designed to heat a home or a small city.
fw=20; %Furnace Wide in Foot
fl=40; %Furnace Length in Foot
fh=25; %Furnace Height in Foot
Next, return to the first few lines of code I showed above. Not that there is absolutely no help in the file. What does the input parameter xx refer to? No help at all there. It returns a variable called fff. What information does it return that a user will find of value? Again, no hints.
Other aspects of good code that a user would look for are
- There is no H1 line.
- There are no error checks on the validity of the parameters.
- There are no references. Many blocks of code use spline fits to curve data stored internally. Where did those curves come from? No documentation is provided.
So I'll heartily disagree with the claim that this code is well commented. The most I'll concede is that parts of it are NOT BADLY documented. I've given this a 3 rating only because the author has clearly put a significant of work into it and because I'd like to encourage an author who has made a serious effort. This is really a higher rating than it probably deserves.
A dozen or so additional lines of comments in front would have caused me to raise my rating at least a notch. If you are willing to spend the time working through all of the implicit, unstated assumptions in the code, some users might find it useful.