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]