naming convention for different types of functions (use prefixes or suffixes?)

Does anyone have suggestions for naming conventions for different types of functions, particularly wrapper functions that need to connect to and disconnect from the database vs. wrapper functions that are passed a db link and don’t need to connect and disconnect?

The project on which I am working has these types of functions (among other types):

wrapper functions that need to connect to the database, then call other functions, then disconnect
wrapper functions that are passed a db link and call other functions (these functions don’t need to connect to the db, that has already been done)

Has anyone worked in a similar environment? Did you follow any naming conventions to distinguish between these wrapper functions that need to connect vs. being passed a db link, such as using a particular prefix or suffix?

If you are using an OO language that has polymorphism, it should already be apparent from the method signatures which method you need to call:

bool SaveCustomer(Customer cust)
{
    var conn = new DatabaseConnection(connectionString);
    SaveCustomer(conn, cust);
}

bool SaveCustomer(DatabaseConnection conn, Customer cust)
{
    // Save the customer
}

Fix the Blueprint, Not the Walls

Feeling a need to have these markers seems like a code smell. It doesn’t appear to me to be a matter of naming convention but of architectural (and behavioral) design. Though obviously having a good naming convention will be important in making that design usable.

Solutions

There are various approaches, but here are 2 possibles options.

1 Class per DB Usage Approach ^{(easy to do, but not recommended)}

Have 2 separate classes to deal with both scenarios, thus effectively taking the distinction one level higher up the chain. For instance, something like (in no particular language):

class CustomerDirectDAO {

  save() {}

}

class CustomerIndirectDAO {

  save(Connection c) {}

}

As mentioned, this would allow you to take the issue of selecting the right problem one level up your design chain. However, you can obviously the it looks tedious, and that you still need a distinction for each approach. Also, the first class probably does in essence what the second class does with just the extra step of creating the connection and invoking it.

This isn’t so great.

1 Data Class, and 1 DB Connection Supplier/Factory

It would be better to have a class that always requires to be passed a connection object and another class constructing and supplying them. That’d seem a better way, and would allow to swap in place implementations of the connection objects that could originate from different suppliers.

A wrapper Connection object could also be supplied only once to the constructor, where the wrapper will check for the connection’s status and recreate one if necessary.

For instance (in no particular language):

class Customer {

  save(ConnectionWrapper c) {}

  // (or pass the wrapper object only once to the constructor,
  // as the wrapper would automatically check to reconnect the
  // connection if invalid)

}

class ConnectionWrapper<T extends Connection> {

  T get() {}; // gets the wrapped connection or returns a newly created one

}

class ConnectionFactory<T extends Connection> {

  ConnectionWrapper<T> create() {}

}

There are dozens of ways to achieve this, and you may pick whichever seems more applicable to you.

The approach above uses a single data-representation class allowing to switch classes used for storage. But another approach is to take the problem from the reverse angle, for instnace with this DAO pattern, where you can see a similar approach to allow for swappable implementations of the backend without using method prefixes, but require 2 concrete implementations of your data object:

More on the topic with approaches for DAO on Wikipedia and DAO for JEE applications.

Using pre-or suffixes in method names can in a few cases be used meaningful to express design intentions directly in code. I wouldn’t recommend to use it though, since ideally there should be an extra document where among other things (e.g. different architectural views) design decisions are documented. One exception are widely accepted naming patterns, for example using +Factory for classes involved in Factory pattern.

In your case with the wrapper functions, you have in the first case actually two responsibilities in one method, namely establishing connection and saving customer. Why not naming the method accordingly bool ConnectDBandSaveCustomer(Customer cust). This is expressive for what the method actually does and you already see that it must be a wrapper method since you can derive the two responsibilities directly from the method name.

Sure it can lead to long method names and therefore to some kind of bloated code, but who cares if you are able to understand foreign code by a magnitude faster. Additionally, it makes you more productive in using other code for example in IDEs with autocompletion, because you won’t have to look as often in the method definition as you would have to with poorly chosen method names!

This is actually quite subjective and it really boils down to what the individual prefers. It also depends on the size of the project as well.

In bigger project that involves a group of people it is always good to standardise a coding standard for everyone within the group to follow (bug the tech director for it if you need to).

There are quite a number of astablished standards out there. One of the better known ones is the Hungarian Notation that adds a prefix to everything.

Wiki: Hungarian_notation

Examples:

boolean bDone;
double * pdbPointerDouble;

You can also create a whole new variety yourself (which i personally prefer) I personally just makes use of the camelCase and some self declared standards. Like a HeadedCamel notation for functions and headlessCamel for variables. of cos you can add prefix or suffixes as well. but the main point of doing this is to keep it simple and easy to understand.

Wiki: CamelCase

Examples:

boolean isTriggered;
void TriggerFunction()
{
    // code here
}

Find a notation that suits you (and your team mates) and you should be good to go.

Hope this helps

P.S. more info: http://en.wikipedia.org/wiki/Naming_convention_(programming)

I like to use SOV order, it’s the most common in human languages. Subject – Object – Verb. Now the name of the subject/object themselves could be reoriented like iteratorRefs vs refsIterator. I believe iteratorRefs is better because the final s indicates a plural. But this depends on the language semantics.

The SOV order works naturally in alot of OO languages too:

this.object.add();

As you can see, this is the subject, the object is the object, and add is the verb.

However in some cases, the function name itself has to consist of hte entire SOV, therefore subjectObjectVerb.

Also this means I prefer objectVerb over verbObject.

And advantage of this means you can do prefix search easily, you can search for everything involving a subject, or a subject and object., and finally the verb.

This changes if you are programming generically. In functional languages, functions are not always methods attached to an object. Therefore functions are more “first class”, in such cases the function is often generic, and the name and type signature should reflect this (such as in Haskell).

See this for more information: http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom-of-nouns.html and

Filed under: softwareengineering - @ 04:33

Thẻ: naming, naming-standards

Thiết kế website giá rẻ

Danh mục

naming convention for different types of functions (use prefixes or suffixes?)

Fix the Blueprint, Not the Walls

Solutions

1 Class per DB Usage Approach ^{(easy to do, but not recommended)}

1 Data Class, and 1 DB Connection Supplier/Factory

Danh mục

Fix the Blueprint, Not the Walls

Solutions

1 Class per DB Usage Approach (easy to do, but not recommended)

1 Data Class, and 1 DB Connection Supplier/Factory

1 Class per DB Usage Approach ^{(easy to do, but not recommended)}