What is the purpose of writing functions and methods? When should you make a snippet of code into a function or method?

Question

I have a philosophical disagreement with one of my co-workers, and I'm trying to get back to basics here. What is the purpose of a method?

In this question, consider this example. I was criticized for writing the following two methods. I would like to give the caveat that this is a boiled down baby-example, that there were other places in my code that were more complicated but similar.

The baby example

class UI:
    def __init___(self):
        self.thingsCheckBox = # checkbox widget
        self.moreThingsCheckBox = # checkbox widget

def wantShowThings(self):
    return self.thingsCheckBox.checkState()

def wantShowMoreThings(self):
    return self.moreThingsCheckBox.checkState()

So, my co-worker questioned me about writing those two methods. Ultimately, I was forced to remove those two methods (as they did not pass his code review). And this ultimately meant...

My version

if ui.wantShowThings():
    # do stuff...

if ui.wantShowMoreThings():
    # do more stuff...

His version (that ultimately won)

 if ui.thingsCheckBox.checkState():
     # ...

 if ui.moreThingsCheckBox.checkState():
    # ...

What is the purpose of writing those methods?

• reuse: I think we all agree about reusability. If a bit of code is being copy and pasted multiple times, it should be put into a function or method so that if the code ever changes, you only have to change it in one place. My co worker argues that reusability is the only reason to write something into a function. My co-worker said that if a function isn't called more than once, I should "inline" the logic (write it in the place its used) and write a comment. "Short" methods are "useless" and serve to increase the "spaghetti code". "Stop making me jump around to figure out the logic".

I believe that writing functions serves other purposes:

• encapsulation: Hide the implementation of your class. This brings your thinking into a higher level and abstracts away the concrete parts of your code. In my above example, it doesn't matter with wantShowThings() whether or not the underlying implementation is a checkbox, radio button, or even a server call. We're thinking more abstractly than a checkbox. We're thinking "if we want to show things".

• documentation: I think code itself can serve as documentation. I know there are pretty radical people that think that comments are completely useless. While I'm not quite as extreme, I sympathize with the philosophy. Why write a comment when you can refactor it into a method with a meaningful name? In my example, I don't need a comment # This returns true if we want to show things, it's in the method name.

I believe that I have a multitude of literature that supports my thinking. "Clean Code", CodingHorror. I took a class with Stanford's David Cheriton that certainly stood on my side as well.

Answer 1

The main purpose of a method (besides reuse) is

Building a useful abstraction by introducing a carefully chosen, meaningful name.

(You called that "encapsulation" and "documentation", both not wrong, but not fully the term which fits IMHO best to it).

Maybe you can convince you coworker by telling him that his version clearly violates the "Law of Demeter". Or maybe just tell him I think his version is mediocre, yours is definitely better (as long as the function name really does make the purpose clearer) ;-)

Answer 2

My co-worker said that if a function isn't called more than once, I should "inline" the logic (write it in the place its used) and write a comment. "Short" methods are "useless" and serve to increase the "spaghetti code". "Stop making me jump around to figure out the logic".

And on the other hand:

I believe that writing functions serves other purposes:

Encapsulation...

Documentation...

And in the end, you are both right. Your coworker is right that making a method that just obscures a line of code called once can be obfuscating, and provides no value. You are right that a well made function can clarify what is going on as well as create an abstraction so that implementation details can be changed freely.

Which is better falls squarely into "it depends" territory. Not just on what is being abstracted, but how it is used, how it will be used, the skill of your programmers, the obscureness of the domain... dozens of things. You weigh the benefits/disadvantages of one option versus the other and make your best guess based on the knowledge available to you.

Sometimes you will guess wrong, and you get to refactor. That is part and parcel of the art of programming.

Answer 3

I think you already answered your question. I had the same thinking while I was beginning to develop for Android. I had this member variable in my CheatActivity class

public static final String EXTRA_ANSWER_SHOWN = "com.sabernova.geoquiz.answer_shown";

...and this method as well:

public static boolean wasAnswerShown(Intent data) {
    return data.getBooleanExtra(EXTRA_ANSWER_SHOWN, false);
}

The data object was received in the QuizActivity class which is also the launcher for my app and I didn't understand why the author wanted to include a method and the string tag for the Boolean extra in the second activity. Why not directly access it?

There were two things:

1. The Boolean extra is created and thus belongs within CheatActivity and hence, it's tag should also reside within CheatActivity -- encapsulating data.
2. Say I used the statement just once. Doesn't mean it will always be like that. I will expand my app in the future and that means I might use it more than once. Or say I change the string tag in the CheatActivity class. Now, I have to go ahead and change all the sightings of the string inside QuizActivity as well. This will be hectic in the long run and could've been solved by putting the right statement inside a well-named function -- Reuse.

So, in a nutshell, creating the right functions means that any change in the actual code would not break up the entire system and cause a lot of rewriting code since the function serves as the interface through which, we can execute code and get the needed stuff.