-
Notifications
You must be signed in to change notification settings - Fork 7
Coding Commenting and Documenting
For the love of all that is sacred YES. The more comments the better. In proprietary code, your own personal code, you can get away with not doing it because everyone who is ever going to work on it will already be familiar with the code but with an open source project (especially with newbie programmers) we don't have that luxury. We don't even have the luxury of always having the original developers on hand to explain the code.
Therefore it is extremely important to comment and document as you go but there is such a thing as bad commenting. Comments that do not actually explain the why and the how for example, but do explain the what and the when (which is often already apparent) are examples of bad comments.
As a final word on the matter, comments should never be necessary. With proper naming and proper care, code should read like good book. The comments however are there to explain the why and wherefores of the code, the reasons behind making code a certain way for example compared to other ways or simply to express elegant or otherwise hard to read code in another way. C++ doesn't always make for pleasant reading in the shortest amount of code. If there is a need for lots of comments, it might be better to refactor and reorganize the code to be more understandable from a human perspective.
While code does need to be commented, we are hoping to use Doxygen in order to provide a suitable documentation source so that it can be used by any developer wishing to get their hands dirty. This makes it easier for developers but only as long as they leave a trail of good comments behind.
Vega Strike makes use of three commenting syntax.
- C-style:
/* */Often referred to as multi-line comments. - C++-style:
//Often referred to a single-line comments. - Doxygen-style:
/** **/
Any comment should not describe what the code is doing or how it is doing it, that should be mostly be apparent. Instead the comment should focus on what the code is for and why it's done that way. It is preferable to follow Doxygen manuals here.
/**
* Licence: GNU v.3 (link)
* Description: What is happening in this file and if necessary, what isn't happening.
**/
/** Function Description **/
double buying(int vegetable, int count)
{
/**
\param vegetable The vegetable that the customer picked up.
\param count The number of said vegetables that were picked up.
\return The total cost of the vegetables.
**/
/** Local variable defining the cost of a carrot with the least amount of memory. **/
float carrotCost = 9.99;
....
return cost;
}
Commit messages should be informative. They should say, what the type of problem is, when and where it occurs, a brief description of how it was fixed.
[type][short path to file][stage reached]Title; Description of the problem; What you did to solve it; Optional Contact details
[Warning][src/main.cpp][make]Narrowing from Double to Float; Warning displayed in GCC on line 92 whereby a function elsewhere was expecting a float but was being give a double. Decided that the function parameter needed to be changed to accept the increase in memory, so change the parameter from float to double as the variable needed more precision.