Well thank god we fixed the naming, that will surely help when someone comes looking to find out why all the amounts don't add up.
Indeed.
Looking forward to the follow-up post, "Choosing good types".
Choosing good names
31–40 of 41 posts
Re: Choosing good names
#32You could provide even more clarity by using meaningful types like Money or TaxPercentage instead of Double. This would allow you to ensure only valid values are passed and would help avoid problematic floating point arithmetic :)
Actually, I think using non standard types increases complexity, despite the more informative naming. I would now have to look up the implementation of Money and TaxPercentage to be sure of what it does, whereas if you move the type names into the variable names like in the following examples: 'double total_money' and 'double tax_percentage' I would immediately understand what's going on. I do see how a TaxPercentage…
Well I disagree, but I doubt I'll convince you if you prefer that style :). You're not really making best use of the type system. Here's some of the reasons I'd prefer modeling this kind of thing with types
How can you find all the uses of money throughout your codebase if they're just doubles? They'll be mixed up with all other uses of doubles.
What happens when you need to add precision because double is no longer good enough? Not only do you need to find them all but then factor them out to different types.
How do you support currencies? How do you know what currency "double total_money" is at the moment? The meaning is lost as soon as you pass it to another function. Even if you are only dealing with USD right now good luck adding currency support in the future if you're using primitives.
Yes, you might have to press a key shortcut to look at the definition to see this information, but duplicating it in the variable name everywhere you use it seems barely better than comments. Furthermore, the variable names can be wrong because they're not enforced by the typesystem. The typechecker can enforce for me that I don't pass a negative value or a value in the wrong currency. Variable names don't do any enforcement
Primitive obsession[0] also tends to lead to lots of duplication of logic. Multiple functions have tests that check what happens when passed an invalid value, logic that would be in one place with a type definition.
[0] http://c2.com/cgi/wiki?PrimitiveObsession
While not really related to the primitive obsession vs domain modelling debate - it's a really bad idea to use floating point numbers for monetary calculations, and from experience I can tell you how hard it is to fix this down the road in an existing codebase processing large amounts of money.
Re: Choosing good names
#33I guess the verbosity of the method's name is actually good in this case? Since it makes the function so much clearer. I am never sure how much to abbreviate a name, but I guess if it's not going to be used much it can be long without problems.
Never abbreviate is my rule of thumb.
I pushed about 6 PRs last week that did nothing but eliminate abbreviations. It was such a minor thing but made me feel so much better. A corollary to your rule is "don't make me think" when reading code. A reader should never have to stop to understand what code is doing, it should be clear. Abbreviations only buy you bytes in the source code at the expense of readability.
Re: Choosing good names
#34thanks for the post. yes taking an extra 10 seconds to name a function in a more clear way could probably save hours of frantic reading and cross referencing for another engineer down the road, especially when fixing urgent bugs/issues
And please make sure the words are spelled correctly in your public API. A library we use at work has a typo in the word "Acknowledge" where it is "Acknowladge". Drives me up the wall every time I see it.
Re: Choosing good names
#35The article makes a clear case for keyword arguments, without mentioning it at all. In Smalltalk you would write something like:
calculateTax: percentage transferValue: value
This has the advantage over the proposed solution that where-ever you CALL such a method, the meaning of the passed-in arguments is clear ALSO in the calling context. Just having meaningful names for FORMAL arguments does not do anything about how the ACTUAL arguments are named, in the (often more than one) places where the method is called. Meaning, it is hard to know whether a given method-call has its arguments in correct order without a) Checking the method-definition for their expected order b) Checking from the calling context the meaning of the variables you pass in to the call. Do they agree? Takes some figuring out.
That requires of course that your language supports keyword arguments. In languages that don't you can simulate them by using a single object as the only argument. That may seem like extra work but it helps, especially when there are many "arguments". It also allows you to have default-arguments without requiring that they are at the end of the argument-list. I think this pattern is called "Argument Object".
Re: Choosing good names
#36Earlier quoted context omitted.
The two examples given in support of short local variables names rely heavily on convention or prior knowledge. I don't think they're strong arguments for making short variable names. Naming the integer counter "i" is convention learned in CS class (initially) that has become common usage. If you have nested for loops then j, k are often conventional for naming the next counter variables, though without an enclosing…
Relying on convention is a good thing, as long as your team (and the larger community for that language) is mature enough to have a strong set of relatively easily discoverable conventions.
Strongly agree. Conventions can produce code that is easier to read and to write. Certainly to the uninitiated, most of the formulas in a math or physics textbook look completely opaque. But by following conventions on meaning of symbols, they are precise and expressive and also easier to write.
Re: Choosing good names
#37Earlier quoted context omitted.
The two examples given in support of short local variables names rely heavily on convention or prior knowledge. I don't think they're strong arguments for making short variable names. Naming the integer counter "i" is convention learned in CS class (initially) that has become common usage. If you have nested for loops then j, k are often conventional for naming the next counter variables, though without an enclosing…
The use of i,j,k, etc is a convention carried over from math to CS. Edit: As are a vast majority of CS knowledge: set theory, calculus, matrix, and so on.
Also in many early programming languages, variables could be only one or two letters. And in Fortran, the variables i, j, k, l, m, n were implicitly integers and others were real (that itself was as you noted, a carryover from mathematical formula conventions).
Re: Choosing good names
#38The article makes a clear case for keyword arguments, without mentioning it at all. In Smalltalk you would write something like: calculateTax: percentage transferValue: value This has the advantage over the proposed solution that where-ever you CALL such a method, the meaning of the passed-in arguments is clear ALSO in the calling context. Just having meaningful names for FORMAL arguments does not do anything about h…
[deleted]
Re: Choosing good names
#39When it comes to code readability, and ultimate reusability, I believe renaming variables is where most time refactoring is best spent. Not only does it encourage better naming, but if the naming or paradigm model is off, it encourages better design.
I'd vote for removing dead/useless code, reducing scope/visibility, making things immutable, and running an auto-formatter. In the case your code is being re-used by outsiders, in an API or something, yeah bad naming ends up being awful.
Re: Choosing good names
#40thanks for the post. yes taking an extra 10 seconds to name a function in a more clear way could probably save hours of frantic reading and cross referencing for another engineer down the road, especially when fixing urgent bugs/issues
And please make sure the words are spelled correctly in your public API. A library we use at work has a typo in the word "Acknowledge" where it is "Acknowladge". Drives me up the wall every time I see it.
ya this drives me nuts. Especially when the "autocorrect" word checker inside the IDE complains about the typo and keeps showing a red squiggly line, for code that is in another library that I am not supposed to change within the project in the IDE. Drives me nuts