4 ms·
Of course, naming is one of the "Two Hard Things". It's absolutely an art, not a science. But it shouldn't go to either extreme -- names that are too short (va
by crazygringo 14y ago
Of course, naming is one of the "Two Hard Things".
It's absolutely an art, not a science. But it shouldn't go to either extreme -- names that are too short (var xi_a) are too confusing for clarity, but names that are too long provide too much visual noise to be clear.
In my opinion, "make_person_an_outside_subscriber_if_all_accesses_revoked" just takes too long to read. Much better would be something like this:
// If all accesses have been revoked, then make the person an outside subscriber
def updateOutsideSubscriber
...
end
The function name is short and gets straight to the point of what it does. Someone coming across the code for the first time can instantly figure out roughly what the function is, and then decide if it's worth their time to read further, or if they should just skip over it.
Then, a comment explains in further detail what it is for, and why it is used. You only need to read it if it seems important to your task at hand.
Good variable naming strategy goes hand-in-hand with good commenting strategy.
The end goal should always be maximum clarity, but remember that too much information, or too much information presented upfront, can reduce clarity.
37signals says "clarity over brevity". I'd say "clarity over extremes".
- greggman 14y agoWhat do you think about Joel's "Make Wrong Code Look Wrong" (http://www.joelonsoftware.com/articles/Wrong.html http://www.joelonsoftware.com/articles/Wrong.html)? In it he makes the argument that it's a good goal to make each line of code understandable with as little other context as possible. Your `makeOutsideSubscriber` is fine when your in that module. But when someone else is using the module. import subcribe ... def SomeFunction subscribe.makeOutsideSubscriber(...) And then 3 months later someone comes and reads the code above using your module it sure would be nice if they didn't have to go dig through the source of your module and read the comments to figure out that it really means "make person an outside subscriber if all accesses revoked"
- crazygringo 14y agoIt's a good point. (And BTW I edited my comment to be "updateOutsideSubscriber" when I realized that was what it was really doing.) It seems to me that "make_person_an_outside_subscriber_if_all_accesses_revoked" just sounds like an internal module function. If something outside the module is calling it, it just smells like the whole thing is organized wrong. But sure, if the function is being used in a "global" way like that, then the full, long version is probably better...
- fbuilesv 14y agoThe problem with this is that although your solution might be better while reading the file where `updateOutsideSubscriber` is defined, once you see that method call somewhere else you'll have to go to that other file to read the comment. With the longer method name you don't need to read the method definition to see what's going on.
- mattmanser 14y agoApart from you're using camel case in ruby. def update_outside_subscriber ... end Surely? I hope I'm not being pedantic, it just looks really odd to me. It sticks out like a sore thumb in an otherwise excellent point.
- nemetroid 14y agoThat's not a ruby comment either. It's just pseudocode.
- Someone 14y agoI disagree. In my opinion, "make_person_an_outside_subscriber_if_all_accesses_revoked" is an ugly name for an ugly function. The label matches the content, and that is the primary goal of naming functions. Of course, it would be better if things were refactored into var allAccessesRevoked = items.All( areRevoked); if( allAccessesRevoked) person.makeOutsiedSubscriber; but sometimes, the programmer hasn't discovered a good refactoring.
- columbo 14y agoIt doesn't bother me that make_person_an_outside_subscriber_if_all_accesses_revoked is long, it bothers me that it seems too specific to be a method. Part of the condition is in the method name (if_all..), that's something that really seems odd to me. What if new requirements dictate that if the same thing should happen given a different condition (if all access is revoked or if the user is set to be disabled), would the method name then become make_person_an_outside_subscribe_if_all_access_revoked_or_user_is_set_to_disabled ? The function as described means that the only time this method is to ever be used is if all access is revoked... if that's the case why even make it into a function? Or to put it another way: //make_person_an_outside_subscriber_if_all_accesses_revoked function revokeAccess(user) { user.clearSubscriptions(); user.addSubscription(new OutsideSubscription()); //other revoky stuff goes here... } //shift_records_upward_starting_at function shiftRecords(startPosition, amount) { //up or down. to go down supply a negative amount } ...or something
- Silhouette 14y agoI'm not sure updateOutsideSubscriber is a good substitute for the original. It reads like you're updating an existing outside subscriber, ignoring the creation/conversion aspect. The original function appears to have two responsibilities: it performs a test on the accesses, and then it also converts the person in some cases. The long name follows from that complexity. Unless there was a good reason not to, I would prefer to separate those responsibilities into their own functions with one job each, and then the naming problem takes care of itself: if all_accesses_revoked(john): convert_to_outside_subscriber(john)