Coding Style Guidelines

To achieve the goal of better readability and consistency throughout the MeV source code, all contributing developers should conform with the Coding Styleguide described here.

As the original MeV source code written by Talin itself doesn't conform to all of these rules (it was not written with a "public audience" in mind), not all parts are fully converted as of yet.

Some fine comments on coding style have been written for the OpenTracker project, I don't want to repeat all of it here or go into as much detail. Unless conflicting rules are outlined in this text, you should follow the OpenTracker style guide in most respects.

Identifiers

Classes should always start with a capital C (for Class). Words should be separated by an uppercase initial for better readability.

	class CSomeExample
		

	void
	CExample::DoSomething()
		

	void
	CExample::_doSomeInternalOperation()
		

	int32     m_size;
		

	uint32    SOME_MESSAGE = ...;
	rgb_color SOME_COLOR = ...;
		

	struct some_struct
	{
	    int32    id;
	    char     short_name[16];
	};
		

Indenting & Braces

Generally all braces should go into the new line, except for one-line inline functions. The rest is better explained by examples...

Class declaration:

    class CExample :
        public CBase
    {

    public:                 // Constructor/Destructor

                            CExample(
                                int32 id);

       virtual              ~CExample();

    public:                 // Accessors

        Something *         GetSomething() const
                            { return m_something; }

    public:                 // CBase Implementation

        /** (method specific comments go here) */
        virtual void        DoSomething(
                                Some *argument,
                                uint32 flags);

    private:                // Instance Data

        /** (variable specific comments go here) */
        int32               m_id;

        Something *         m_something;
    };
			

    void
    CExample::DoSomething(
        Some *argument,
        uint32 flags)
    {
        if (...)
        	DoIt();
        ...
    }

    void
    CExample::DoSomethingElse()
    {
        if (...)
        {
            ...
        }
        else
        {
            ...
        }
        ...
    }
			

	switch (message->what)
	{
	    case B_ABOUT_REQUESTED:
	    {
	        // do something
	        break;
	    }
	    case B_QUIT_REQUESTED:
	    {
	        // do something else
	        break;
	    }
	    default:
	    {
	        BHandler::MessageReceived(message);
	    }
	}
			

Commenting & Documentation

To be able to make use of documentation generation utilities in the tradition of JavaDoc (like Doxygen or ScanDoc), we need to support some special commenting rules in the header files.

First and foremost, this means that every publicly visible class, function, variable, enum, etc should be documented by putting a comment block directly above its declaration. For example:

    public:

       /** Constructor for new destinations.
        *  @param id        The destination ID
        *  @param document  The document this destination belongs to
        *  @param name      Name of the destination.
        */
                                    CDestination(
                                        uint32 type,
                                        int32 id,
                                        CMeVDoc *document,
                                        const char *name);
		

Some documentation tools use special tags, but mostly the common denominator are the main tags used by JavaDoc:

• @author (list of contributors for a source-file, separated by commata)
• @see (reference to some other class or class member)
• @param (to describe a specific function argument)
• @return (to detail the possible return values of a function)