The question of whether you should include in-line comments in your code is a running one in the development community. To some, they are part of the process of ensuring the ongoing maintainability of a codebase. To others, comments are the spawn of satan, lower than cockroach droppings, or slightly above a Justin Bieber song.
Regardless of where you fall on this spectrum, it's reasonably certain that the following isn't considered 'acceptable'.
public string Null2(string input) { //this returns a null value to prevent errors being generated //at runtime when this programme is executed. //this makes sure that when null2 is assigned to a property // it wont' crash all the time return null; }
This is an example of what Roger faced on an all-too-regular basis. Code that was not only commented, but commented obviously...mostly obviously. With all of the really important stuff (like WTF would you ever need to have a method like this) left out. Maybe the developer was paid by the line (not line of executable code, but lines in the code file)?
But that's not the lowest level to which comments can sink. Consider what happens when this same developer not only believes that his comments are gold, but who has the analytical skills of a Labrador Retriever. Exhibit A is the following method, which attempts to determine if a word has a vowel in it.
public string HasAVowel(string theword) { try { //this sets a default value to a boolean property variable //so that the application wont crash bool does = false; //this creates my "extraBool" which is a fantastic way of handling additional //logics so that as well as true & false, we can also have like no value string extraBool = "No text value".ToString(); //we also have another extrabool for invalid values. this is handy and very important string extraBool2 = "Invalid value".ToString(); //always try your best to handles any errors in the best possible way //so that there will be no error messages for the user //this checks to see if anything was put in //if not then return my new extraBool if (theword.ToString() == "") { return extraBool.ToString(); } //We are now going to start checking the word to see if any values exist in it foreach (char myCharacter in theword.ToString()) { switch (myCharacter.ToString()) { case "a": case "e": case "i": case "o": case "u": does = true; return does.ToString(); break; //remember sometimes the letter y is a vowel depending on the word thats used. //it just depends on what you use the word for case "y": extraBool = "almost - sometimes it's a vowel and sometimes it's a consonant".ToString(); return extraBool.ToString(); break; case "bcdfghjklmnprstvwxz": does = false; return does.ToString(); break; default : //in any other case we should always return something as it's excellent good practice to have //things like this does = false; return does.ToString(); break; } } //because visual studio has put a red zigzag underneath the name of my procedure //I need to return something always so it's more efficient to build up some text and then return it string myDefaultReturnedString = ""; myDefaultReturnedString = myDefaultReturnedString.ToString() + " " + does.ToString(); myDefaultReturnedString = myDefaultReturnedString.ToString() + " " + extraBool.ToString(); myDefaultReturnedString = myDefaultReturnedString.ToString() + " " + extraBool2.ToString(); //this bit will return a message if not able to parse if (myDefaultReturnedString.ToString() == "") { return "nothing returned".ToString(); } else { return myDefaultReturnedString.ToString(); } } catch (Exception) { return "error unknown".ToString(); } }
Now this isn't all bad. Because the developer (who is no longer with Roger's company) was wise enough to include the default case in the switch statement, the fact that he forgot that 'q' was a letter didn't introduce any bugs. Whew. That was close.