views:

328

answers:

3

I'm building a website (in Django) and am confused about the right naming convention to use for my functions. Trivial example: let's say I have a page that lets the user decide whether they want to see image A or image B. Once the user submits the decision, the site displays the image the user requested.

Here are the two functions I would have in my views module:

def function1(request):
    """Returns the page that presents the user with the choice between A and B"""

def function2(request):
    """Takes in the submitted form and returns a page with the image the user requested."""

What is the convention for naming the functions that do this? I see at least two feasible ways:

Option 1: function1: "decide", function2: "view_image"

Option 2: function1: "view_choices", function2: "decide"

The central issue is that each of these functions does 2 things: (1) process and store the data the user submitted, and (2) return the next page, which may or may not be related to the user's input. So should I name my functions after (1) or (2)?

A: 

As long as you have those nice comments in, I suspect it won't ever be an issue for you.

Anyway, it's best to name functions based on what they do so function1 could be "displayImageChoices" and function2 could be "displayImage".

IE, function1 takes some input and displays some choices, function2 takes some input and displays an image.

Neil Trodden
PEP8 (http://www.python.org/dev/peps/pep-0008/) says:"Function names should be lowercase, with words separated by underscores as necessary to improve readability. mixedCase is allowed only in contexts where that's already the prevailing style (e.g. threading.py), to retain backwards compatibility."
andybak
That's a good point, I was focusing on "what the names convey", rather than camelCase/formatting conventions.
Neil Trodden
+5  A: 

Typically the convention is some kind of CRUD (create, retrieve, update, delete). I personally use index, detail, create, update, delete for my actions. However, I don't think this applies to your custom functions.

Really it sounds like your functions should be merged into the same "choose" function. You then either display the form or the result depending on whether the result was a POST or not.

Note: I've heavily coppied this example form the django docs on form handling.

def choose(request):
    """
    Presents the user with an image selection form and displays the result.
    """
    if request.method == 'POST': # If the form has been submitted...
        form = ChoiceForm(request.POST) # A form bound to the POST data
        if form.is_valid(): # All validation rules pass
            # Process the data in form.cleaned_data
            # ...
            return HttpResponseRedirect('/thanks/') # Redirect after POST
    else:
        form = ChoiceForm() # An unbound form

    return render_to_response('choose.html', {
        'form': form,
    })
Soviut
Thanks Soviut! This might be just what I'm looking for. But I'm wondering -- would this "choose" function also contain the code to return the page with the picture, or would that code belong in another function? (I wouldn't be redirecting to '/thanks/' in my case.)
RexE
@RexE: If the form is POSTed (which it should be if it modifies data), then you _should_ redirect after processing the data to a different view that displays the page. Otherwise you expose the user to confusing messages and possibly unintentionally executing the action multiple times if they try to refresh the page.
Carl Meyer
@Carl: In most cases I'd agree, except in situations where you're doing something like returning a search result, but still displaying the search box at the top of the page, in that case redirection is unnecessary. This may be the case with the OP's question.
Soviut
@Soviut: if you're just displaying a search result, then you should be using GET, not POST.
Carl Meyer
A: 

I'd use something similar to the built in views (object_list, object_detail, etc) where applicable. (Always a good idea)

The rest would then follow that notion (item_action) as far as possible.

Marcus Lindblom