Naming convention should separate semantic relations?!
Naming convention should separate semantic relations.
What do you think about the following guideline for naming convention?
The main idea is separating the few groups of semantic relations in
the c++ language. Each identifier name should be marked to express
which group it belongs to sematically.
* Don't misunderstand, it is not like the old hungarian notation,
which marks the c++ variable type or concept, this system marks the
semantic relations.
Most naming conventions I've seen specify part of these groups, but
not all (not as finely separated).
such as:
- prefix underscore for data members.
- uppercase first letter for types
- lowercase first letter for functions
- prefix "I" for interface classes.
Some add a few more groups.
Some IDEs automatically mark groups with different colors.
My main point is that these are not enough.
the main important groups are:
- instanciable type
- interface class
- traits class
- variable
- function
- parameter
- namespace
but actually my separation is more fine grained:
- instanciable type (class or enum), intances can be created as most
derived type. i.e. public ctors.
- regular
- template
- interface. intended to be inherited, and produce base subobject
intances. i.e. usually protected ctors.
- regular
- template
- traits class. no instances. i.e. no ctor/dtor
- regular
- template
- variable
- local constant (function local that doesn't change)
- local iterator (a non-const function local variable)
- static local
- data member
- static member
- global
- function
- global
- static member
- nonstatic member (with this->func() call syntax)
- virtual member function (see note below)
- parameter
- in parameter
- out parameter. function only write to it.
- in/out parameter. i.e function reads and writes to it.
- namespace
My experience led me to separate all these groups with different
namings, and I feel that it makes code much faster to understand and
handle (and also track some bugs).
The point is that wherever I see an identifier, I know by its marked
name where it is declared, and the most important things about how it
can be used, without need to find the declaration. It makes it obvious
where there is an implicit "this->" or "::". When reading a function,
it points out which are the variables whose usage and values should be
tracked carefully.
It's not very important how each group is marked. If the IDE has
enough different color markings, the actual identifier names can be
oblivious. My IDE has much fewer colorings. I use a different prefix
for each group.
In details.
As there are quite a few groups (all important though), when starting
to use this notation, it takes at least a few hours/days to get used
to it and remember the prefixes matchings. I suppose the notation
really helps only when the prefixes are known by heart. I can tell
that when used regularly, they come very automatic without thought.
* note about virtual functions: When calling a member function on an
object, the user needs to know which parts of its behaviour is
polymorphic (per the function's contract). How the polymorphism is
done is an implementation detail. What I mean is that the user doesn't
want or need to know whether that function itself is virtual. I
consider it an implementation detail. Therefor, all functions used by
the users of the class will be marked as regular member function
"f_...". All virtual functions are private and marked "v_..." and are
implementation details, never referred to by users of the class. Each
virtual function may have a public regular member function that calls
it (but that one is "f_..."). See in the example code v_get_name(),
f_get_name(), v_get_title().
A huge advantage of this, is that when overriding a virtual function,
the same "v_..." identifier is used, and it makes totally clear that
it should be an override even if the keyword virtual is not present.
In any case, such function will never be invoked directly by mistake.
1) add the following prefix to an identifier per its group:
c - instantiable type
ec - instanciable template class
i - interface class
ei - interface template class
z - traits class
ez - traits template class
g - function.
f - non-static member function
v - virtual member function.
b - function local constant
a - function local variable
m - data member
r - in parameter
o - out parameter
ro - in/out parameter
s - static data variable
k - static constant
n - namespace
template parameters will be prefixed by "j":
jc - template type parameter which is expected to be instantiable type
ji - template type parameter which is expected to be an interface
class
jz - template type parameter which is expected to be a traits class
jec, jei, jez - templates of such
jk - template value parameter ("k" becuase it's somewhat like a static
constant)
2) if the identifier is a member of a class, further add "h" prefix:
hc - member instantiable type
hec - member instanciable template class
hi - member interface class
hei - member interface template class
hz - member traits class
hez - member traits template class
hg - member static function
hs - static data member
/*** code example (with prefixed_lowercase_underscored_names and below
with prfxCapitalizedNames) ***/
namespace n_naming_convention_example {
template< typename jz_name_traits >
class ei_person
{
//xtor
public: virtual ~ei_person() {}
protected: ei_person() {}
//methods
public: jz_name_traits::hc_string f_get_name() const { return
v_get_name(); }
private: virtual jz_name_traits::hc_string v_get_name() const = 0;
private: virtual jz_name_traits::hc_string v_get_title() const = 0;
public: jz_name_traits::hc_string f_get_header() const
{
return ( v_get_title() + " " + f_get_name() );
}
};
template< typename jz_name_traits >
class ec_student:
public ei_person< jz_name_traits >
{
//data
private: jz_name_traits::hc_string m_name;
private: jz_name_traits::hc_string m_title;
//xtor
public: ~ec_student() {}
public:
template< typename ri_user_string >
ec_student( ri_user_string const& r_name, ri_user_string const&
r_title )
:
m_name( jz_name_traits::hg_convert_string(r_name) ),
m_title( jz_name_traits::hg_convert_string(r_title) )
{}
//methods
//overriders
private: jz_name_traits::hc_string v_get_name() const
{
return m_name;
}
private: jz_name_traits::hc_string v_get_title() const
{
return m_title;
}
};
class z_user_name_traits
{
public: typedef char hc_character;
public: typedef std::basic_string< hc_character > hc_string;
public:
template< typename ji_user_string >
static hc_string hg_convert_string( ji_user_string const&
r_user_string )
{
//this is bad code, just example for naming convention
size_t const b_size( r_user_string.size() );
hc_string a_target;
for( size_t a_index(0); a_index != b_size; ++a_index ) {
hc_character const
b_current_letter( r_user_string[ a_index ] );
a_target += b_current_letter;
}
return a_target;
}
};
void g_user_code()
{
ec_student< z_user_name_traits > const
b_my_student( std::string( "john smith" ), std::string( "Dr." ) );
ei_person< z_user_name_traits > const* const
b_my_person( &b_my_student );
std::cout << b_my_person->f_get_name() << "\n";
std::cout << b_my_person->f_get_header() << "\n";
};
}
/*** And the same example code with prfxCaptalizedVariableNames ***/
namespace nNamingConventionExample {
template< typename jzNameTraits >
class eiPerson
{
//xtor
public: virtual ~eiPerson() {}
protected: eiPerson() {}
//methods
public: jzNameTraits::hcString fGetName() const { return
vGetName(); }
private: virtual jzNameTraits::hcString vGetName() const = 0;
private: jzNameTraits::hcString fGetTitle() const { return
vGetTitle(); }
private: virtual jzNameTraits::hcString vGetTitle() const = 0;
public: jzNameTraits::hcString fGetHeader() const
{
return ( fGetTitle() + " " + fGetName() );
}
};
template< typename jzNameTraits >
class ecStudent:
public eiPerson< jzNameTraits >
{
//data
private: jzNameTraits::hcString mName;
private: jzNameTraits::hcString mTitle;
//xtor
public: ~ecStudent() {}
public:
template< typename riUserString >
ecStudent( riUserString const& rName, riUserString const& rTitle )
:
mName( jzNameTraits::hgConvertString(rName) ),
mTitle( jzNameTraits::hgConvertString(rTitle) )
{}
//methods
//overrides
private: jzNameTraits::hcString vGetName() const
{
return mName;
}
private: jzNameTraits::hcString vGetTitle() const
{
return mTitle;
}
};
class zUserNameTraits
{
public: typedef char hcCharacter;
public: typedef std::basic_string< hcCharacter > hcString;
public:
template< typename jiUserString >
static hcString hgConvertString( jiUserString const& rUserString )
{
//this is bad code, just example for naming convention
size_t const bSize( rUserString.size() );
hcString aTarget;
for( size_t aIndex(0); aIndex != bSize; ++aIndex ) {
hcCharacter const bCurrentLetter( rUserString[ aIndex ] );
aTarget += bCurrentLetter;
}
return aTarget;
}
};
void gUserCode()
{
ecStudent< zUserNameTraits > const bMyStudent( std::string( "john
smith" ), std::string( "Dr." ) );
eiPerson< zUserNameTraits > const* const bMyPerson( &bMyStudent );
std::cout << bMyPerson->fGetName() << "\n";
std::cout << bMyPerson->fGetHeader() << "\n";
};
}
itaj
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.moderated. First time posters: Do this! ]