News for hackers. Stuff that matters.
Re:Clarity over brevity in variable and method names by crazygringo on Monday September 10, 2012 @03:05PM (#4501539)
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".

Re:Clarity over brevity in variable and method names by greggman on Monday September 10, 2012 @03:21PM (#4501652)
What do you think about Joel's "Make Wrong Code Look Wrong" (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"
Re:Clarity over brevity in variable and method names by crazygringo on Monday September 10, 2012 @03:51PM (#4501833)
It'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...

Re:Clarity over brevity in variable and method names by columbo on Monday September 10, 2012 @04:34PM (#4502097)
It 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
Re:Clarity over brevity in variable and method names by Silhouette on Tuesday September 11, 2012 @03:01AM (#4504164)
I'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)
Re:Clarity over brevity in variable and method names by Someone on Monday September 10, 2012 @04:20PM (#4502007)
I 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.
Re:Clarity over brevity in variable and method names by fbuilesv on Monday September 10, 2012 @03:58PM (#4501872)
The 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.
Re:Clarity over brevity in variable and method names by mattmanser on Monday September 10, 2012 @04:13PM (#4501974)
Apart 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.
Re:Clarity over brevity in variable and method names by nemetroid on Monday September 10, 2012 @08:36PM (#4503090)
That's not a ruby comment either. It's just pseudocode.