Proposed: Commenting Standard

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 … /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 … 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


//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.
//Say hello to the user, using their name.

//Exit the program.
return 0;


/**requestName asks the user for their name.

  • @param buffer: the string pointer to write to.
    void requestName(std::string
    //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…
    //Print out the greeting, without a name.
    std::cout << “Hello! Nice to meet you.” << std::endl;

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.

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