.NET Coding Guidelines

Why not join our community?, there are 22 users online

home
tips & tricks
view story

DotNetKick.com is an open-source project. Please report any bugs and let us know your great suggestions. Currently running svn revision 637 (rss)

Kick Spy!, Kick Zeitgeist and Kick Widgets

32
kicks

kick it

.NET Coding Guidelines - Commenting

published 1 year, 4 months ago, submitted by wooyay 1 year, 4 months ago

3poundmass.wordpress.com — Nice rant about developers who don't comment their code, I can sympathize.

8 comments | category:

Tips & Tricks | Views: 1 | Get KickIt image code

tags: Tips, Comments, Code | tag it

Everyones tags:

Your tags:

Please login or signup.

Add a live kick counter to your blog >> liveImage

You can even customize the image by choosing your own colors, and then clicking the button below to update the preview and the html code:

"Kick It" text
"Kick It" background
kick count text
kick count background
border

Simply copy and paste this HTML into your blog post.

Users who kicked this story:

wooyay - bayarsaikhan - locrain -

yesthatmcgurk - IDelectable - ChadMoran -

gavinjoyce -

bentracy -

tiernano -

johnrummell -

boki - blisteringlunatic - motionblur -

D_Guidi - donthop -

JudahGabriel -

dove - ashithmr - grantg81 - monty - Glohamar -

javierRomero -

w3stfa11 -

mdopp -

gt1329a - qn111 - csharpnjava - pennyfx - PringlePop - RobChappel - MarthaBass

Comments:

Commenting code is over rated, I much prefer well written code which is self explanatory. If a piece of code needs comments, it may also need a refactor.

posted by

gavinjoyce 1 year, 4 months ago

I agree to an extent, I'd usually rather have well designed self-documenting code than awful code that's commented. But, especially with larger and more complex systems, it good to have documentation and comments too, so you can tell what the programmer was trying to do, and why. There's a limit to what you can infer from code alone, no matter how well designed it is.

posted by IDelectable 1 year, 4 months ago

That's a fair point. As with pretty much everything else, balance is key.

posted by

gavinjoyce 1 year, 4 months ago

Commenting for the sake of commenting is poor, however, commenting on the intent is a MUST. Simple easy to read code should not need comments. However, code the is odd/complex or is a 'hack' MUST have comments so the next guy can understand the 'intent/why' of what the code does.

posted by dwhittaker 1 year, 4 months ago

dwhittaker - I agree, for hacks it's handy to use "HACK" comment, same for "TODO", so they show up in the Visual Studio Task List.

posted by IDelectable 1 year, 4 months ago

After seeing a 200k LoC project we outsourced last year come back with 0 comments, I have to agree that it's better to be safe than sorry and require a certain level of commenting. In the end, that project literally got scraped, because even the people who wrote it were unable to maintain it a year later.

posted by

gt1329a 1 year, 4 months ago

I'm sure you'd all agree, but method/property commenting for use with Intellisense is a must in my book.

posted by

isuttle 1 year, 4 months ago

isuttle - definitely, it makes life so much easier when methods have XML comments that show up in IntelliSense. This feature will soon be available for JavaScript too, in Visual Studio 2008.

posted by wooyay 1 year, 4 months ago