Let’s be honest, there’s only one main purpose to blogging. To translate concentrated rage into HTML. To that end, I humbly offer a series of guidelines to you shoddy developers who regularly infect my source tree with your twisted code-wrongs.
Part 1 — Comment your .NET code
You might very well think that. I couldn’t possibly comment.
— Francis Urquhart
By glancing at your uncommented code I can tell instantly that you’re either an amateur or, more likely, a lazy and selfish sociopath. It’s not like I’m asking you to write a novel. Would it really impede your productivity so much that you can’t find time to furnish your garbled, obfuscated nonsense with some sort of mitigating explanation? Oh, and when I tell you to start adding comments, I don’t expect you to start littering code with superfluous crap like:
populateControls(); // populate the controls
string name = getName(); // set the name
Comment as you go along, or you’ll forget. If you’re so inclined, use comments to structure your functional design before you write code, this is the Pseudocode Programming Process. As a general rule, comment what your code is doing, and why it’s doing it. I should already be able to see how your code works, because you’ve used meaningful and precise names for your classes, functions and variables.
// create a SqlConnection object using connectionString
SqlConnection cnn = new SqlConnection(connectionString);
I can see you’re using a SqlConnection because the programming syntax conveniently forces you to include the class type in its variable declaration. It is also very clear from the code that you’re passing connectionString as a parameter. The bigger picture is a mystery. What is your intent? Why are you connecting to the database? What data are you expecting back? If these things aren’t clear then explain.
Don’t comment every single line, instead give a brief summary for each block of related code. If you’re working on an API then use a documentation generator like Javadoc or SandCastle and format comments accordingly.
Other people will probably have to extend or maintain or your unintelligible mess. You might think it’s good for job security if you’re the only one who can understand your code. It really isn’t.
Read more about commenting code:
Follow up post:
