What to write when Commenting?

No I’m not dead. Yes I haven’t updated this in an age (well maybe not that long it’s only been… oh wow…). What have I been doing in the time since I last made a post? Well Skyrim mainly.

Anyway we’re back at it again with new coursework, deadlines, work and all that it entails. Here’s a little something I have to work on, most of the code is kindly provided and i just need to take what I need and apply it correctly (yay for learning). But what’s with all the green text? Comments. Little nuggets of wisdom that I as a Developer need to leave for the far future when some new Dev. looks over my code and tries to work out just what the hell I’m doing. They’re supposed to be little explanations to help with that. But really I just want to drop lots of sarcastic comments in because if you can’t work out that the AddCompetitor method is going to ‘ADD’ a ‘COMPETITOR’ to the array/list/dictionary but it will require you to provide a ‘NAME’ and ‘ADDRESS’ then clearly there’s a language barrier that I’m not aware of.

Yes it may seem like I’m ranting on that but this is part of my problem with commenting code: I just don’t know what is appropriate. Do I comment every variable with an explanation of what it is (string CompetitorName ///the Name of the Competitor) even when it’s obvious what they’re for? Same with methods, I have one called FindCompetitor, but do I really need to comment and tell you that this is a searching method? Or what it is that it will look for and find? Are you actually unable to work that out?

 Then again I could just include a recipe for chicken soup.

 

Advertisements

One thought on “What to write when Commenting?

  1. Personally when I leave comments behind its either talking about what I’ve just changed and why (dated) so if I come across it in another change I’m not undoing something. Plus, leaving an small explanation of what it is, and why, means you don’t have to work it out again even if it’s named obviously. You could have a really complex piece of code with an obvious name, so the comment would briefly explain what the code is actually doing.

    Or at least that’s how I comment my code!

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s