''A SelfDocumentingCode practice.''

'''''Place (only) important information in prominent places.'''''

A document is only as good as how quickly it takes to find information. SelfDocumentingCode is the same. When someone wants a piece of information, they want to find it quickly.

'''Therefore,''' emphasize the important information. Place it in separate sections, or at the top, or near its context. Keep the most important information in the most active areas ''and the most relevant.''

'''Corollary:''' ReduceUnimportantInformation.

For instance, a very good C++ class template might look like this:

 class ClassName
 {
     friend MyBuddy;

     static const int HARDCODED_CONSTANTS;

 public:
     static const int PUBLIC_CONSTANTS;

     static ClassName *NamedConstructor();     

     ClassName();
     ClassName( ClassName const &krClone );
     virtual ~ClassName();
     ClassName &operator =( ClassName const &krClone );

     // A public method that does this and that.
     // It has these caveats.
     virtual void aPublicMethod();

     // More public methods go here.

 protected:
     int m_iMemberVariable;
     // More member variables go here
     
     // This is a Template Pattern callback to paint the widget
     virtual void paint() = 0;

 private:
     CCriticalSection m_csSocket;

     void PrivateImplementationMethod();
 };

It's a matter of preference whether to put class methods above or below instance methods. I prefer below unless the class is an instance of the FlyweightPattern or otherwise static heavy. Named constructors are special, however. Usually you won't have public constructors if you have named constructors anyway.

The essential idea is that people who wish to use your class are more interested in the public interface, especially the constructors. Grouping the constructors, destructor and assignment operator is just a C++ thing to GroupRelatedInformation.

Constants also need to be found quickly. Member variables are similarly more important than methods, especially if they are all protected or stronger (and they are, ''right...?''). Since there are theoretically more than one subclass (or else why did you create a separate class?), there are more people interested in the protected methods than the private ones.

Some people may wish to move the friend declarations to the bottom. It really doesn't matter whether they are private, protected or public anyway. However, since they violate encapsulation bigtime, it's important to flag that for potential users, extenders and implementors of the class.

-------

An EverythingIsRelative-weenie will suggest that importance is relative. Every feature is probably important to some stake-holder or situation somewhere, otherwise it wouldn't be included.

----
CategoryInformation