Proposed: Commenting Standard


#1

I brought this up on the mailing list, but based on the initial response, I wanted to repost it here for reach and lifespan, as stuff on mailing lists tends to get buried. (You can read the thread at sourceforge.net/p/synfig/mailman … /33087616/, though it would seem my message didn’t get properly saved, so see it inline on the reply.)

In a nutshell, I’m implementing a commenting standard at my company to help improve code readability, and speed up coding overall. I think Synfig Studio could benefit from it (as I mentioned in the post). I know we can’t really enforce it, as Carlos pointed out, but even if those of us who regularly work on the project were to adopt it, it would go a long way.

The biggest benefit, of course, would be that our doxygen api docs would be a LOT more readable. Right now, there’s no denying that those are rather thick, heh.

The standard is still a work-in-progress, so input is greatly appreciated. Again, the current standards draft is mousepawgames.com/downloads/csis … draft1.pdf. To be honest, half the reason I wrote this standard was to help overcome by own bad habit of not documenting code.

I really look forward to your input on this.

EDIT: I wrote up a quick code sample, demonstrating CSI-D, which is the CSI standard following Javadoc conventions.

[code]/**CSI Commenting Example

  • An extended “Hello, world.” intended to demonstrate the CSI-D
  • Commenting Standard.
  • @since 1.0
  • @author Jason C. McDonald
    */

#include

//Function prototypes.
void requestName(std::string*);
void sayHi(std::string&);

int main()
{
///A buffer to hold the name string input by the user.
std::string nameBuffer = “”;
//Ask for the user’s name.
requestName(&nameBuffer);
//Say hello to the user, using their name.
sayHi(nameBuffer);

//Exit the program.
return 0;

}

/**requestName asks the user for their name.

  • @param buffer: the string pointer to write to.
    /
    void requestName(std::string
    buffer)
    {
    //Ask the user for their name.
    std::cout << “What is your name?” << std::endl;
    getline(std::cin, *buffer);
    }

/**sayHi greets the user, using their given name.

  • @param name: the name to use.
    */
    void sayHi(std::string& name)
    {
    //If the name is not empty…
    if(name != “”)
    {
    //Print out the greeting, with the user’s name.
    std::cout << "Hello, " << name
    << “! Nice to meet you.” << std::endl;
    }
    //Otherwise, if the name is empty…
    else
    {
    //Print out the greeting, without a name.
    std::cout << “Hello! Nice to meet you.” << std::endl;
    }
    }[/code]

ETL replacement
#2

Hi, Jason,
apart of what I commented on mailing lists I don’t have more to say than I applause the initiative and invite any coder to make an effort to follow that guide and report any possible improvement.
Cheers
-G


#3

For anyone using or considering this standard, the latest revision is now officially published at standards.mousepawgames.com.