app...app...app...app..
by joe

Posted on 2018-10-02



Computer programming consists of naming things and subroutines.
Joe, ca. 1983


Naming Things

Through the years we have run across (and participated in) quite a few programming conflicts: Do we indent two spaces or four? Curly braces on separate lines? Include type info with variable names? Long names or short names? Underscores or dashes? CamelCase or camelCase?

Industry practice has settled on answers to each of these questions and many more like them - then reversed. Then reversed again. Not fads exactly, but changes in style from time to time. Developers of new tools or languages often set the tone for their customers and followers.

With respect to issues around naming variables, or classes, or functions, etc., we have forsworn conflict, giving ourself over to common practice in whatever realm we are working at the time. Our most recent pickup is Python. PEP 8 lays out "common practice" for Python programming, and for the most part we're OK with it - at least with respect to naming conventions.

Naming Dependencies

Python is blessed with a surfeit of tools and packages, and we lighted on Flask pretty early in the game. Flask offers a framework that is human-scaled. It neatly takes care of a huge chunk of the nitty gritty details that come with HTTP-based applications. We are a fan and an inveterate user. The Flask guys are great - benefactors to the community. If you have not ever explored the Werkzeug and Flask source code, you should. It is gorgeous.

Now the but ...

But we found many of the attempts at teaching or explaining Flask to be confusing because of one simple issue: lack of clarity in exposing the necessary (or assumed) naming dependencies among the different elements of the project or application. (See the Project/Application sidebar.)

Let us illustrate with a simple example. Immediately below is the directory and file setup that mimics common Flask tutorials or examples.


/home/joe
    |
    |-- /app        (project directory)
        |
        | -- /app   (application directory)
        .    |
        .    | -- /static  (css, js, etc.)
        .    | -- /templates  (html files)
        .    |
        .    | -- __init__.py
        .    | -- views.py
        .    | :
        .    | :
        |
        | -- config.py
        | -- app.py
        | :
        | :

The directory structure and file names shown above illustrate a common setup for a Flask tutorial or example - common when we first started using Flask, and still all too common today. Both the project directory and the application directory are named "app." Is that a requirement for Flask? If you see this same setup in every post, you could be forgiven for thinking so. That dependency seems even more likely when you see the __init__.py file:


from flask import Flask

app = Flask(__name__)


@app.route('/')
def index():
    return b'Hello, World!'

Two more "apps." How are they related to the names for the project directory and the application directory? Are they related to each other? But wait, there's more. Three more "apps" in the actual running Python program, named "app.py" no less.


from app import app

if __name__ == 'main':
    app.run()

app...app...app...app..

So, eight "apps" in this example. Can you spot the dependencies? Are there any dependencies? We find some answers in the modified example below:


/home/joe
    |
    |-- /alex       (project directory)
        |
        | -- /paa   (application directory)
        .    |
        .    | -- /static  (css, js, etc.)
        .    | -- /templates  (html files)
        .    |
        .    | -- __init__.py
        .    | -- views.py
        .    | :
        .    | :
        |
        | -- config.py
        | -- run_me.py
        | :
        | :

The project directory is named "alex." No requirement that the application directory or the "run_me.py" program share the same name as the application directory ("paa").


from flask import Flask

ned = Flask(__name__)


@ned.route('/')
def slash():
    return b'Howdy doodly, Neighbor!'

The Flask application object is named "ned" - no required tie to either the project directory name or the application directory name. The name of the decorator "@ned.route()" does depend on the name of the Flask application. Finally, everything is much clearer when you inspect the "run_me.py" program:


from paa import ned

if __name__ == 'main':
    ned.run()

It turns out that the name of the project directory is arbitrary. The name "alex" means nothing. It is never used elsewhere in the file and directory structure or in the application code.

The name of the application directory is a different matter. That is the Python package name - the anchor name for imports within the application.

Re-using the same application directory name for either the Flask project directory or the Flask application object confuses the student learning Flask unnecessarily because the "same-naming" signals dependencies where none exist.

Looking back, we see that those eight apps become four neds, and we can understand the naming dependencies much more readily.

Real World Naming

To be clear, we are not suggesting that names should never carry internal meaning. In a real project/application, it makes perfect sense to use the same name for both. But in the context of a tutorial or other extended example it is confusing. Give distinct elements of the example distinct names.

Again, to be clear, this post is directed at tutorial-type explanations.

If you are writing a business application and you need a variable to represent a customer's account balance, by all means, name it "account_balance" or "customer_account_balance." If your function returns a multi-valued object, we endorse the name "construct_multi_framistan."

Coming up with names is exhausting. Further, signaling connections with coordinated names can add cohesiveness to a project. It's perfectly sensible to use the same name for a Flask project directory and its application directory when everyone on the project knows the ins and outs of making Flask applications.

BUT when you are trying to explain something to newbies, especially experienced programmers who are new to your subject, don't rely on - or signal - implicit dependencies.

Remember: Explicit is better than implicit.

Project / Application Naming
It is useful to have distinct nomenclature to distinguish clearly the Flask "project directory" and the Flask "application directory."

Flask is freely configurable, so it is possible to have multiple "application" directories inside a single "project" directory. Further, it is possible to have those multiple applications share resources such as a single "static" directory (which makes sense) or even a single "templates" directory (which probably doesn't make sense).
ned = Flask(__name__)
The parameter used for the Flask() object call is actually used by Flask for locating internal objects, directories, files, etc.

Check the Flask docs on the subject here.

You are almost always safe with the standard Flask(__name__), though.
Distinct Names - Explicit Dependencies
Many of the succeeding blog posts, cast in the form of short tutorials or examples, are meant to be instructive for those who may not be very familiar with Flask.

Our intention is to make dependencies clear by using distinct names or by explicitly highlighting dependencies. Please let us know when we fail to live up to these standards.

Comments

It will be some time yet before we get a comments section working here. In the meantime feel free to send comments via email. On this site our name is Joe Python. The email address is our first name at joepython.com.

Edited: 2019-01-30 20:55:12(utc) Generated: 2019-06-10 17:29:58(utc)