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"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...
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 somethingThe 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) var allAccessesRevoked = items.All( areRevoked);
if( allAccessesRevoked)
person.makeOutsiedSubscriber;
but sometimes, the programmer hasn't discovered a good refactoring. 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.
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:
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".