Archive for the ‘Coding Style/Conventions’ Category

Why Inline Comments Are Generally a Bad Idea

Thursday, October 8th, 2009

Bellow is a single function commented in two different ways. Which one is better?

NSString* MD5StringOfString(NSString* inputStr)
{
	//UTF8 encoding is used so the hash can be compared with hashes of ASCII strings
	NSData* inputData = [inputStr dataUsingEncoding:NSUTF8StringEncoding];
 
	unsigned char outputData[CC_MD5_DIGEST_LENGTH];
	CC_MD5([inputData bytes], [inputData length], outputData);
 
	NSMutableString* hashStr = [NSMutableString string];
	int i = 0;
	for (i = 0; i < CC_MD5_DIGEST_LENGTH; ++i)
		[hashStr appendFormat:@"%02x", outputData[i]];
 
	return hashStr;
}
NSString* MD5StringOfString(NSString* inputStr)
{
	//convert the string to UTF8 encoded byte data
	NSData* inputData = [inputStr dataUsingEncoding:NSUTF8StringEncoding];
 
	//calculate the hash
	unsigned char outputData[CC_MD5_DIGEST_LENGTH];
	CC_MD5([inputData bytes], [inputData length], outputData);
 
	//convert hash to a hexadecimal string
	NSMutableString* hashStr = [NSMutableString string];
	int i = 0;
	for (i = 0; i < CC_MD5_DIGEST_LENGTH; ++i)
		[hashStr appendFormat:@"%02x", outputData[i]];
 
	//return the hexadecimal string
	return hashStr;
}

(more...)