API specs

[contolini]

We should standardize our function signatures. Right now we're all over the place. Here are some rules I just made up. Feel free to add your own.

• Methods should receive a single object argument.
  • e.g. cashFlow({income: 100000, expenses: 50000}) and not cashFlow(100000, 50000)
• Percent values should be represented as integers.
  • e.g. 20% is 20 and not .2
• Output should be as verbose as possible
  • e.g. interest returns an object with both the interest amount, and the total amount. The user could easily add their principal to the interest to get the total themselves, but it's nice to do it for them.

[ascott1]

+1

[cfarm]

yes

[mistergone]

Percent values should be represented as integers.

I actually prefer percents represented as decimals - I know integers are more readable, and possibly make more immediate sense to people, but mathematically, they aren't proper numeric representations, they would always have to be divided by 100 to do any math, and then multiplied by 100 when returned, and that just seems like something that is more appropriate to the front-end.

For instance, cfpb/student-debt-calc takes a lot of "rates" (which would textually be written as percentages, like "7.55%") but it takes them in as decimals (like .0755). Setting aside entirely that "7.55%" can't technically be represented as an integer, I think it's less confusing to take as an input the mathematical value that the code is going to use anyway. I also think it's a little silly to take in a 20 when you know your code needs a .2 to actually do its work.

The front-end of cfpb/college-costs takes user input of rates in the "percentage" format ("7.55%") and divides them by 100 to pass them to decimals to the calculator package. It takes what the calculator returns and multiples it by 100 to display the output. That makes more sense to me than the package taking in numbers it doesn't really want.

Since we're talking about packages doing math, not front-ends displaying values, I think decimals just make more sense.

[mistergone]

Methods should receive a single object argument.
Output should be as verbose as possible

These two rules I totally 👍 🎆 😋

[contolini]

I think decimals just make more sense.

Fine by me.