13 ms·

1) Vector3 computeNewtonianGravity(float massA, Vector3 positionA, float massB, Vector3 positionB); Which way does the returned force vector point? Towards mas

1) Vector3 computeNewtonianGravity(float massA, Vector3 positionA, float massB, Vector3 positionB); Which way does the returned force vector point? Towards mass A, or towards mass B? 2) Vector3 UnitVectorWithDirection(Vector3 originalVector); What does this function do when the magnitude (length) of originalVector is zero? 3) float ArcTan(float x); What is the allowable range of values for x? ...

dougk16 11y ago
While I don't agree with the general sentiment of vinceguidry (e.g. I think comments answering "why?" are very important), for your specific counterpoints I do tend try solve it in code if possible: 1) Vector3 calcNewtonianGravityToB(float massA, Vector3 positionA, float massB, Vector3 positionB); 2) Vector3 unitVectorWithDirection(Vector3 originalVector_mayBeZero); vs. Vector3 unitVectorWithDirection(Vector3 originalVector_throwsIfZero); (if in a supporting language, throws declaration would also clarify). 3) float ArcTan(float x_throwsIfZero); or float ArcTan(float x_returnsNaNIfNot0to1), etc. This assumes: (a) You're not working in a language or environment that supports range constraints in the first place, cause if you are then that's ideal. (b) You're working on personal code or a small team. If you're writing code for public consumption you have no choice but to add detailed API documentation if you want to be successful, even if it's not DRY.
- deleted 11y ago
  [deleted]
joshvm 11y ago
The sibling comment about renaming is good - particularly with regard to the first function. However I think the other two are better suited to documentation rather than trying to make the function signature explain itself. Sooner or later you'll just remember that it takes a float, not the variable name. Certainly calling things like "x_returnsNaNIfNot0to1" works, but I find it a bit ugly and it gets complicated if you have multiple or more complex constraints. This is where languages with docstrings are nice. In Python all I would do is add a """ comment describing the inputs and the return values. You then have a) a comment describing the code; and b) documentation that's standard so people can pull it up with pydoc or ? in Ipython. When I'm working in Jupyter, I often hit shift-tab to check what a function is expecting.
- JabavuAdams 11y ago
  Was just looking at the Oculus SDK math library, and they have some really neat ideas... For one, handling rotation sign (is positive clockwise or counter-clockwise), left-handed vs. right-handed coordinates, etc. through c++ template parameters.
douche 11y ago
I prefer to put that kind of stuff in the javadocs/xmldocs, but I mostly work in C#/Java, with IDEs that have tooling baked in that make generating that kind of documentation A.) really easy to generate and B.) very useful in auto-complete lists, mouse-over popups, etc. Ideally, you'd have some tests as well that would test those kind of corner-cases and illustrate failure cases and expected outputs.

dougk16 11y ago

While I don't agree with the general sentiment of vinceguidry (e.g. I think comments answering "why?" are very important), for your specific counterpoints I do tend try solve it in code if possible: 1) Vector3 calcNewtonianGravityToB(float massA, Vector3 positionA, float massB, Vector3 positionB); 2) Vector3 unitVectorWithDirection(Vector3 originalVector_mayBeZero); vs. Vector3 unitVectorWithDirection(Vector3 originalVector_throwsIfZero); (if in a supporting language, throws declaration would also clarify). 3) float ArcTan(float x_throwsIfZero); or float ArcTan(float x_returnsNaNIfNot0to1), etc. This assumes: (a) You're not working in a language or environment that supports range constraints in the first place, cause if you are then that's ideal. (b) You're working on personal code or a small team. If you're writing code for public consumption you have no choice but to add detailed API documentation if you want to be successful, even if it's not DRY.

deleted 11y ago
[deleted]

joshvm 11y ago

The sibling comment about renaming is good - particularly with regard to the first function. However I think the other two are better suited to documentation rather than trying to make the function signature explain itself. Sooner or later you'll just remember that it takes a float, not the variable name. Certainly calling things like "x_returnsNaNIfNot0to1" works, but I find it a bit ugly and it gets complicated if you have multiple or more complex constraints. This is where languages with docstrings are nice. In Python all I would do is add a """ comment describing the inputs and the return values. You then have a) a comment describing the code; and b) documentation that's standard so people can pull it up with pydoc or ? in Ipython. When I'm working in Jupyter, I often hit shift-tab to check what a function is expecting.

JabavuAdams 11y ago
Was just looking at the Oculus SDK math library, and they have some really neat ideas... For one, handling rotation sign (is positive clockwise or counter-clockwise), left-handed vs. right-handed coordinates, etc. through c++ template parameters.

douche 11y ago

I prefer to put that kind of stuff in the javadocs/xmldocs, but I mostly work in C#/Java, with IDEs that have tooling baked in that make generating that kind of documentation A.) really easy to generate and B.) very useful in auto-complete lists, mouse-over popups, etc. Ideally, you'd have some tests as well that would test those kind of corner-cases and illustrate failure cases and expected outputs.