Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Lets say you have to write some code to fix a bug that on first glance by another engineer would seem weird or unnecessary.

Would it be good or bad form to put the code in a method named for example "preventWindowFromJumpingWhenKeyboardAppears" or just name it "forceSpecifiedWindowPosition" and then add a comment about why you are doing this when calling the method?

share|improve this question
10  
Does that mean it's acceptable to name functions after your co-workers? –  DaveNay Sep 23 '11 at 23:16
1  
Of course you should try to avoid building a workaround where a more direct solution is possible. As far as names go the ones you suggest sound reasonable. –  Joseph Weissman Sep 23 '11 at 23:36
2  
I don't understand why you aren't just fixing the defect and making the fix a separate method. –  Thomas Owens Sep 23 '11 at 23:47
1  
The defect is in the operating system, would love to fix it if I could. –  satur9nine Sep 24 '11 at 0:05
add comment

5 Answers

up vote 8 down vote accepted

I think it's better to name methods based on what you are trying to accomplish rather than how, as part of the whole public interface / private implementation thing. So, all else being equal, I would call it "preventWindowFromJumpingWhenKeyboardAppears".

However, all else might not be equal. Will the parameters make sense equally with both names? If you have to pass the window position to "forceSpecifiedWindowPosition" it makes sense, but not so much for "preventWindowFromJumpingWhenKeyboardAppears", which sounds like it would either be passed nothing or a window. Also, if forcing the window position could be considered a side-effect (sounds like no - it's the effect you want) then "preventWindowFromJumpingWhenKeyboardAppears" would have results that might be unexpected from the name, so I wouldn't name it that.

share|improve this answer
add comment

assuming this is completely unavoidable:

of the options, i'd use preventWindowFromJumpingWhenKeyboardAppears; also detailing the issue in the method's documentation (what versions it is known to appear, how to repro, or a case #).

if you are introducing something awkward, it's best to make that obvious, to detail the motivation/issue, and to quarantine the workaround. otherwise, people read it and get confused (or omit its use if they have not spent a lot of time with your interfaces). then they may remove it in the future because they are not sure why it exists ("... but it tested fine on the latest OS."). for really bad cases, i'll use even more syntactic stigma because the method name you have chosen does not stand out when scanned.

if you can keep it entirely within private implementation, even better.

finally, preventWindowFromJumpingWhenKeyboardAppears makes it pretty obvious at the call site that there is a legitimate bug as well as the context it pertains to, rather than some haphazard implementation. forceSpecifiedWindowPosition makes little sense in comparison.

share|improve this answer
3  
+1 for "if you are introducing something awkward, it's best to make that obvious" –  Dean Harding Sep 24 '11 at 8:51
add comment

Don't worry about pride -- yours or anyone else's. Don't worry about good form. There is only one thing you should worry about when naming a method: What reads best in the calling code?

What is someone else going to see, when they come back to this code later? Will they see a method which positions a window that was just created, or will they see something that appears to do nothing (thus tempting them to remove it)?

Imagine yourself as a future newbie reading the calling method. You don't want to click through to the method implementation to find anything out, nor do you want to have to go to version control or bug-tracking to find out why something was added, you're just trying to read the flow of that method.

Put exactly as much information in the method name as you would want to read in the calling method and no more.

share|improve this answer
add comment

I tend to think that naming methods should be concise and general with comments filling in the specific details. So I would think your second name is better. But that is just me.

share|improve this answer
add comment

Here's some arbitrary rules for you to follow:

  1. Don't write too smart or weird or unnecessary code
  2. Long function names are not very good
  3. ForceSpecifiedWindowPosition is too long
  4. Don't do workarounds. Do real fixes.
  5. Naming classes and functions is important activity. Use enough time for it.
share|improve this answer
4  
I disagree with point number 3 and partially disagree with point number 2. If you think that ForceSpecifiedWindowPosition is too long a name for a method then you are probably sacrificing good method names for short method names. There is no good reason to make a method name short if it loses meaning. Your other points are fairly obvious, I do completely agree with your point number 5. –  satur9nine Sep 24 '11 at 0:28
1  
One should never make or follow arbitrary rules. –  Caleb Sep 24 '11 at 11:30
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.