Useful code comments [modified]
-
Here's a C code fragment that I recently came across. Not making this up! :-D
// check string length, when shorter then 10 do nothing
if ( len >= 8 )
{As you may understand, it took me a little while to figure this particular one out :confused:
modified on Tuesday, May 10, 2011 4:03 AM
-
Here's a C code fragment that I recently came across. Not making this up! :-D
// check string length, when shorter then 10 do nothing
if ( len >= 8 )
{As you may understand, it took me a little while to figure this particular one out :confused:
modified on Tuesday, May 10, 2011 4:03 AM
I think such code should not be commented at all. I know someone who would comment
// Check if the string length is greater or equal to 8, if it is then go into the if. If it is not then go into the else
Such comments are really just littering your code with the obvious. It doubles development time and has no added value... If you need comments to understand that you are obviously not at your right place. A more helpful comment might be WHY the string must be at least 8 chars. Your example is rather hilarious (or is that sad?) though :laugh:
It's an OO world.
-
I think such code should not be commented at all. I know someone who would comment
// Check if the string length is greater or equal to 8, if it is then go into the if. If it is not then go into the else
Such comments are really just littering your code with the obvious. It doubles development time and has no added value... If you need comments to understand that you are obviously not at your right place. A more helpful comment might be WHY the string must be at least 8 chars. Your example is rather hilarious (or is that sad?) though :laugh:
It's an OO world.
My point exactly, thanks. And not only does it double development time, it also puts a burden on the next programmer that has to maintain the code. What should (s)he do? Update the comment? Remove it altogether? In this example, the maintainer apparently forgot to update the comment.
-
My point exactly, thanks. And not only does it double development time, it also puts a burden on the next programmer that has to maintain the code. What should (s)he do? Update the comment? Remove it altogether? In this example, the maintainer apparently forgot to update the comment.
Fred van Lieshout wrote:
What should (s)he do? Update the comment? Remove it altogether?
Shoot the programmer who put the comment there? :)
It's an OO world.
-
Fred van Lieshout wrote:
What should (s)he do? Update the comment? Remove it altogether?
Shoot the programmer who put the comment there? :)
It's an OO world.
-
Send out a memo saying everyone needs to start using Octal.
The enemy of my enemy of my enemy of my enemy is Kevin Bacon. My Mu[sic] My Films My Windows Programs, etc.
No, no, no. That's too simple. Instead, send out a memo congratulating everybody on the positive response to the company-wide move to Octal, and gently reminding them that the two hold-outs will be receiving negative reviews this year.
Real men don't use instructions. They are only the manufacturers opinion on how to put the thing together. Manfred R. Bihy: "Looks as if OP is learning resistant."
-
Here's a C code fragment that I recently came across. Not making this up! :-D
// check string length, when shorter then 10 do nothing
if ( len >= 8 )
{As you may understand, it took me a little while to figure this particular one out :confused:
modified on Tuesday, May 10, 2011 4:03 AM
If I were to log a bug against it I'd say that "magic numbers were used". Rather create a constant. Avoid magic numbers at all cost.
/*--[ Private Literals ]-------------------------------*/
#define MAX_STR_LEN 10/*--[ Public Functions ]-------------------------------*/
/*
This is the main entry point of the software.
*/
public int main()
{
if (CheckStringLength)
{
// perform operations
}
else
{
// do nothing
}return 0;
}/*--[ Private Functions ]-------------------------------*/
/*
This function validates string length.
*/
private boolean CheckStringLength(char* str)
{
boolean result = false;
unsigned int len = 0;
while(str++ != '\0')
{
len++;
}/* validate string lenght */
if (len <= MAX_STR_LEN)
{
result = true;
}
else
{
result = false;
}return result;
}In actual fact it would of probebly been better to define the constant in a header file. This way when the string length changes the actual source file doesn't change but just the value of the constant defined in the header file and thus the testing of the source file is not required again.
"Program testing can be used to show the presence of bugs, but never to show their absence." << please vote!! >>
modified on Wednesday, May 11, 2011 6:52 AM
-
If I were to log a bug against it I'd say that "magic numbers were used". Rather create a constant. Avoid magic numbers at all cost.
/*--[ Private Literals ]-------------------------------*/
#define MAX_STR_LEN 10/*--[ Public Functions ]-------------------------------*/
/*
This is the main entry point of the software.
*/
public int main()
{
if (CheckStringLength)
{
// perform operations
}
else
{
// do nothing
}return 0;
}/*--[ Private Functions ]-------------------------------*/
/*
This function validates string length.
*/
private boolean CheckStringLength(char* str)
{
boolean result = false;
unsigned int len = 0;
while(str++ != '\0')
{
len++;
}/* validate string lenght */
if (len <= MAX_STR_LEN)
{
result = true;
}
else
{
result = false;
}return result;
}In actual fact it would of probebly been better to define the constant in a header file. This way when the string length changes the actual source file doesn't change but just the value of the constant defined in the header file and thus the testing of the source file is not required again.
"Program testing can be used to show the presence of bugs, but never to show their absence." << please vote!! >>
modified on Wednesday, May 11, 2011 6:52 AM
Couldn't agree more. Thanks for the post!
-
My point exactly, thanks. And not only does it double development time, it also puts a burden on the next programmer that has to maintain the code. What should (s)he do? Update the comment? Remove it altogether? In this example, the maintainer apparently forgot to update the comment.
-
Here's a C code fragment that I recently came across. Not making this up! :-D
// check string length, when shorter then 10 do nothing
if ( len >= 8 )
{As you may understand, it took me a little while to figure this particular one out :confused:
modified on Tuesday, May 10, 2011 4:03 AM
a) the comment is inaccurate -- the worst kind b) a comment on this statement is entirely unnecessary c) as someone else mentioned, the statement it comments uses a magic number. Defining it as a constant might also provide the explanation that this comment fails to provide. d) than/then confusion: one of my pet peeves.
