/ C#

Avoid Commenting Your Code

When I’m answering questions on Stack Overflow, I see a lot of questions with code like this:

// Convert our ciphertext into a byte array.
byte[] cipherTextBytes = encryptedBytes;

...    

// Create uninitialized Rijndael encryption object.
TripleDESCryptoServiceProvider symmetricKey = new TripleDESCryptoServiceProvider();

...   

// Define memory stream which will be used to hold encrypted data.
MemoryStream memoryStream = new MemoryStream(cipherTextBytes);

...

// Define cryptographic stream (always use Read mode for encryption).
CryptoStream cryptoStream = new CryptoStream(memoryStream, decryptor, CryptoStreamMode.Read);

...    

// Start decrypting.
int decryptedByteCount = cryptoStream.Read(plainTextBytes, 0, plainTextBytes.Length);

...

// Close both streams.
memoryStream.Close();
cryptoStream.Close();

...

// Return decrypted string.   
//return plainText;
return plainTextBytes;

(Code snippets taken from this SO post. Sorry José Arthur Ortiz Antunes, I’m not trying to pick on you!)

What I see here is a lot of useless text that clutters up the code. Most of these comments don’t assist the reader in understanding the program, they just get in the way. For instance, the lines

memoryStream.Close();
cryptoStream.Close();

are self documenting – you don’t need the //Close both streams comment at all. In one case the comment is actually wrong! The comment for

TripleDESCryptoServiceProvider symmetricKey = new TripleDESCryptoServiceProvider();

says // Create uninitialized Rijndael encryption object., but the code is doing exactly that – initializing it!

In college the phrase “Always comment your code” is hammered into poor students’ fresh minds until the professor is blue in the face. But I don’t think that’s right. In fact I think it’s so not right it’s actually wrong. I propose a new motto:

Avoid commenting your code at all costs

I think programmers shouldn’t add comments to their code unless absolutely necessary. Code should be self documenting – it’s something all programmers should strive for. The information the code presents by itself, the variable and method names created, the algorithms in place – those should be enough explanation that comments are redundant.

Another reason to avoid commenting code is that upon refactoring comments often get forgotten. Code gets deleted but the comment remains. Maybe a for loop is updated with new logic but the comment explains the previous revision. Not only do comments often clutter code, they add confusion when they are left in place and not updated. Pretend ‘ol Jimmy Maintenance Man comes in to optimize a method and reads a comment that wasn’t updated and attempts to map the information in the comment to the lines of code underneath. He spends 5 minutes and 47 seconds reviewing the comment, reviewing the code, F12’ing into methods and writing notes before realizing “Wait a minute. CartTotal was updated from a double to a decimal months ago. This method makes use of the decimal parse method but the comment explains how we dealt with the double.” Good job Jimmy! You got to the bottom of it! Now what did you originally come here to do?

Professors, please stop pushing students to comment. Push them to write self documenting code. Push them to make their code stand on its own without need for further explanation. If there is absolutely, positively no possible way that you can write a chunk of code that is self explanatory, then I will allow a comment. But it should be avoided at all costs.

comments powered by Disqus
David Zych

David Zych

Dave is a dad, husband, programmer, (amateur) photographer, half-Canadian, alumnus of CSUCI, and an overall nice guy.

Read More