11

I suppose this question is going to be immediately flagged as subjective, but which do you think is better:

double volume(double pressure, double n_moles, double temperature) {
  return n_moles * BOLTZMANN_CONSTANT * temperature / pressure;
}

or

double volume(double P, double n, double T) {
  return n*R*T/P;
}

In other words, should functions that implement some equation follow that equation's notation, or should they use more verbose names?

|improve this question
  • 3
    Do you also sometimes spend more time thinking about how to name a variable than you spend on the coding itself? ;-) – Tomas Aug 12 '11 at 21:34
  • 1
    I think the second alternative is OK. I would explain the variables in a comment though. – Giorgio Aug 12 '11 at 21:38
  • It looks like someone saw fit to go through and down-vote everyone's answers. Would this person care to share his reason for doing so? The answers seemed perfectly reasonable to me. – Seth Aug 12 '11 at 21:48
  • Technically, this has nothing to do with 'mathematical' notation and everything to do with what a physicist would think. There's nothing more than arithmetic going on here. – duffymo Aug 13 '11 at 2:01
  • 2
    I can see all the Americans passing temperature in Fahrenheit. I would definitely not be using double as the type for temperature. Same probably goes for pressure. I think I would be more interested in getting the types secure than the names. – Martin York Aug 15 '11 at 6:06

10 Answers 10

14

Depends on who is reading it. If you can guarantee that for all eternity, the next programmer who reads your code is also familiar with thermodynamics, then yes, go for the truncated version.

My personal style is to use such variables (whose abbreviations are commonly known in the field), but include their description in comments.

/* P : Pressure
   V : Volume
   n : Number of moles
   R : Boltzmann constant
   T : Temperature (in K)
*/
double compute_V(double P, double n, double T) {
  return n*R*T/P;
}
|improve this answer
  • 5
    What's the point? Someone who doesn't grok thermodynamics has no chance of successfully maintaining the code no matter what the variable names are. – dsimcha Aug 12 '11 at 21:37
  • This is certainly better than not including the information, but at this point, it seems like it would be easier to just use those names in the function. I'm not seeing a lot of utility in using the letters... – Patrick87 Aug 12 '11 at 21:48
  • @dsmicha: Yes, PV = nRT is a very basic example. In the real world, more complicated functions exist which are not commonly known and tend to be long and convoluted. So even if the person is trained in the field, there's a good chance s/he will come across a function which is totally alien. – Jacob Aug 12 '11 at 21:50
  • 4
    @Patrick87: I prefer the letters because I can quickly check the veracity of the expression by looking at the paper it's from (or from memory) since it's much closer to the original form. – Jacob Aug 12 '11 at 21:53
  • 2
    +1. This is the best way to do it. Even fairly elementary physics equations may use greek letters, roots, partial derivatives, operators (Laplace, Hamilton), vectors, tensors, etc. so that generally it's not possible to represent the equation legibly in comments. Sticking to as-standard-as-possible variable names / abbreviations (e.g. GAS_CONSTANT is not a standard variable name; every textbook I know of uses R for that) and explaining them briefly in comments is the best thing that can be done. – Joonas Pulakka Aug 15 '11 at 7:11
7

Just throwing it out there, you have another option:

Volume ComputeVolume(Pressure p, Moles m, Temperature t) { ... }

This is somewhat similar to what F# does with units of measure, and has the benefit of avoiding issues like replacing inadvertently a pressure by a temperature. It's difficult to eyeball what arguments should go where when the signature is like (double, double, double)

|improve this answer
  • Just to make clear, are there languages out there that can do that sort of dimensional analysis? I.e. that know that for instance that the product between a Pressure and a Volume can be assigned to a unit of Energy? – lindelof Aug 12 '11 at 21:56
  • Yes, F# does this, with Units of Measure. msdn.microsoft.com/en-us/library/dd233243.aspx – Mathias Aug 12 '11 at 21:57
  • Even without support for automatic conversion between units, it may be beneficial to define dedicated types for certain units, like a Money class. It limits inadvertent variable assignment and conversion mistakes, and helps with refactoring. – Mathias Aug 13 '11 at 17:42
  • This can be done very robustly with C++ templates. – kevin cline Aug 15 '11 at 5:51
  • @lindelof: You can achieve some of this functionality with C++ typedef – Jacob Sep 1 '11 at 20:53
7

I prefer this:

/* This function calculates volume using the following formula:
 *
 *     n * R * T
 * v = ---------
 *         P
 */
double volume(double pressure, double n_moles, double temperature) {
    return n_moles * BOLTZMANN_CONSTANT * temperature / pressure;
}

In other words, explain the meaning of the code in the comment in English (and mathematics; it's comments, you can expand on it as much as necessary), but use descriptive variable names so that anyone reading the only code still is able to comprehend it easily - especially with larger functions. Another reason why I'd use real words as variable names is that the interface is much clearer if you need to copy the function declaration to a header file.

|improve this answer
  • 2
    Additionally, would be nice in the comment to include a link to somewhere on the internet that talks about the formula (eg: en.wikipedia.org/wiki/Ideal_gas_law). – Chris Shaffer Aug 12 '11 at 21:39
  • This is a very nice approach, but a little messy. I might prefer just to see a link to e.g. Wikipedia describing (in this case) the ideal gas law. – Patrick87 Aug 12 '11 at 21:46
3

IMHO it's always better to use the established notation of the problem domain you're working in if the function is very domain-specific. Someone who doesn't understand the problem domain has no chance of successfully maintaining your code anyhow, and for someone who is familiar with the domain, the long names will just be noise, as well as more typing for you.

OTHO, I will say that I wish conventional mathematical notation were more verbose and descriptive at times, but regardless I think mathematical code should stick to mathematical convention.

Edit: This answer applies only if there is a very strong convention on notation when writing the formula mathematically. If there isn't one, and you'd have to explain what the variables represent in a comment even assuming that the reader is familiar with the domain, then it's best to err on the side of a more descriptive convention.

|improve this answer
2

Pure opinion, but always use the words over the single-letter symbols. If you use words, everybody will understand; if you use symbols, only subject-matter experts are guaranteed to follow. Even then, some people use different symbols for the same physical quantities. You have nothing to lose by using the longer names.

|improve this answer
2

Your concern should be clarity then correctness (incorrect but clear code is easily corrected) therefore your function should be written for maintainability by a generic coder as far as possible. The function header comments should explain the formula and its usage and describe in/out parameters. Thereafter how the function body is layed-out shouldn't matter too much as long as it's consistent with the header comments.

(I know this is not a discussion but - my personal preference would be to give explicit names to the varaibles although in this case a one-liner could suffice as it's a 'pure' function; a call with the same parameters would yield the same result always so there should be no state-related complexity requiring explanation)

  • Re other languages supporting dimensional analysis, this can be implemented e.g. in C++ with templates, the Boost Units library uses this approach I believe.
|improve this answer
1

Depends on how "far away" from the business layer the code is... The furthur back in the stack the code is, the more targeted it is towards the abstract mathematical function is implements, the more I would try to emulate the generally accepted matehmatical notation and naming conventions.. The closer to the front end or to the business layer, the more I would conform to the conventions established in the problem domain.

|improve this answer
1

I like to think of it this way - Mathematicians got it wrong with short variables and physicists followed suit. Why repeat their mistake? We now know that longer names are more descriptive and produce less confusion, so stick with improvement. On a lighter note, I sometimes try to sneak it longer variables into my maths, at which everyone is appalled.

|improve this answer
  • You're gonna love this... – user1372 Oct 13 '11 at 14:12
0

The correct format for a programming equation is one that you still understand after not having seen it for six months.

If you come back to:

n*R*T/P;

And you recognize what's going on, then it's probably fine. Typically for advanced formulas I wont remember what each part was unless I'm actively using it. For me:

n_moles * BOLTZMANN_CONSTANT * temperature / pressure;

is a much better equation format specifically because I can easily understand each part, even if I don't necessarily know why the equation is written as it is.

|improve this answer
  • You think energy_in_joules = mass_in_kilograms * pow(speed_of_light_in_vacumm_in_metres-per_second,2) is easier than E=mc^2 – Martin Beckett Aug 15 '11 at 12:51
  • @Martin Beckett, did you actually read what I posted? "Typically for advanced formlas I wont remember what each part was unless I'm actively using it." I didn't say I would forget the equations that have managed to push themselves into public knowledge. In cases like E=m*(c^2) I will understand it in six months. – zzzzBov Aug 15 '11 at 13:23
  • for well known classical equations it's better to use the normal notation so people can spot it. Even to the extent of naming variables theta or phi if that's whats used in the domain – Martin Beckett Aug 15 '11 at 15:04
-1

Toss the coin.

Do you also sometimes spend more time thinking about how to name a variable than you spend on the coding itself?

|improve this answer
  • 6
    Yes, I typically spend more time designing my code than coding it, and it begins with understanding the problem and naming things properly. – Mathias Aug 12 '11 at 21:47

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