3 ms·

So long as the "cleverness" is well-documented it's not a problem. Authors should explain why it is written the way it is. Problem solved. I've seen some weird

So long as the "cleverness" is well-documented it's not a problem. Authors should explain why it is written the way it is. Problem solved. I've seen some weird-ass calculations in code with no comments. If the author has gone through so much effort to come up with the clever solution why not add some commentary so the next guy can read it quickly. That's why every language has support for comments..

yoklov 10y ago
OTOH comments easily become outdated, and it's painfully easy to make a change that subtly invalidates a comment in another file. They're like lines of code that is never tested or run. For calculations, I'm not really sure I agree either. I used to work in games, specifically on physics and collision, and there's a point at which you have to assume that the person maintaining it has a reasonable level of familiarity with the subject matter, or else you'd need to write a comment that contains all of a linear algebra course.
- bigger_cheese 10y ago
  I do not see this as an issue if the comment immediately Precedes the "Clever" section of code. Calculations are the most important part of the code to comment I'm an Engineer most of the guys I work with have never been formally taught any programming often I see a bunch of code written in Fortran with notoriously short variable names if it wasn't for comment very easy to get lost. So long as there is a comment saying something like "Ergun's Equation - Calculates Pressure Drop" You don't need to follow all the fluid dynamics to know what the code does - at minimum someone reviewing it can google "Ergun's Equation" You don't need to comment linear Alegbra but at least comment what the code does "//Solve using LU factorization" or similar is sufficient and it beats seeing segments of code like this with no explanation: r[i] = 1/(pb[i]+t[i]-fr1[i-1]-gr2[i-2]); u[i] = a[i]-r1[i-1]u[i-1]-r2[i-2]u[i-2]; f = pc[i]+t1[i]-h*r1[i-1]; Edit: It stripped chunks of the above code but you get the idea.
  - wangchow 10y ago
    True--sometimes when translating from a mathematical context to programming causes some readability pains! Especially if it's something that takes advantage of multiprocessing to solve the problem.
- wangchow 10y ago
  It's really a balancing act. Gotta have the right amount of comments. In general I prefer code that is written such that comments are not necessary, but in the context here the "clever" tricks should always be commented. And to that end, the code should be peer-reviewed and determined by other individuals whether it's confusing or not. While comments can certainly become stale, we're talking about portions of code that will most likely not change frequently. If there's a clever solution it better need to be clever otherwise it's just bad style.

yoklov 10y ago

OTOH comments easily become outdated, and it's painfully easy to make a change that subtly invalidates a comment in another file. They're like lines of code that is never tested or run. For calculations, I'm not really sure I agree either. I used to work in games, specifically on physics and collision, and there's a point at which you have to assume that the person maintaining it has a reasonable level of familiarity with the subject matter, or else you'd need to write a comment that contains all of a linear algebra course.

bigger_cheese 10y ago
I do not see this as an issue if the comment immediately Precedes the "Clever" section of code. Calculations are the most important part of the code to comment I'm an Engineer most of the guys I work with have never been formally taught any programming often I see a bunch of code written in Fortran with notoriously short variable names if it wasn't for comment very easy to get lost. So long as there is a comment saying something like "Ergun's Equation - Calculates Pressure Drop" You don't need to follow all the fluid dynamics to know what the code does - at minimum someone reviewing it can google "Ergun's Equation" You don't need to comment linear Alegbra but at least comment what the code does "//Solve using LU factorization" or similar is sufficient and it beats seeing segments of code like this with no explanation: r[i] = 1/(pb[i]+t[i]-fr1[i-1]-gr2[i-2]); u[i] = a[i]-r1[i-1]u[i-1]-r2[i-2]u[i-2]; f = pc[i]+t1[i]-h*r1[i-1]; Edit: It stripped chunks of the above code but you get the idea.
- wangchow 10y ago
  True--sometimes when translating from a mathematical context to programming causes some readability pains! Especially if it's something that takes advantage of multiprocessing to solve the problem.
wangchow 10y ago
It's really a balancing act. Gotta have the right amount of comments. In general I prefer code that is written such that comments are not necessary, but in the context here the "clever" tricks should always be commented. And to that end, the code should be peer-reviewed and determined by other individuals whether it's confusing or not. While comments can certainly become stale, we're talking about portions of code that will most likely not change frequently. If there's a clever solution it better need to be clever otherwise it's just bad style.