Welcome to MSDN Blogs Sign in | Join | Help

jaredpar's WebLog

Code, rants and ramblings of a programmer.

Syndication

News

Now Reading

Expert F#

What's a better book to read when learning F#?

Essential WPF

Thus far the best book I've read on WPF. Gets right down to working with WPF and the goals/history.

Purely Functional Data Structures

Reading this book makes me feel like I'm back in college. It will really get your mind going and is best read with a whiteboard handy.

Blog Roll

Eric Lippert
Dustin Campbell
Jon Skeet
Coding Horror
Brian McNamara
Brian Bondy
Hub FS
Full List

Comments

If only people spent as much time writing comments as they did speaking to the evils of comments.  Everything from useless, inaccurate, to many comments make code unreadable, you should code better ... etc. 

I haven't ever looked at a piece of code and thought "wow, way too many comments" or "that code would be beautiful if it weren't for the comments."

Do the next guy a favor, comment your code. 

Published Tuesday, August 26, 2008 8:00 AM by Jared Parsons

Filed under:

Comments

# send flowers » Comments @ Tuesday, August 26, 2008 8:04 AM

PingBack from http://hubsfunnywallpaper.cn/?p=2348

send flowers » Comments

# re: Comments @ Tuesday, August 26, 2008 8:45 AM

> Do the next guy a favor, comment your code.

I'm usually glad to, but, for example, at one place I've worked in the path, we had an _official_ policy of "no verbose comments" (because "they contaminate the code and make it harder to read"), which was enforced to the point that, effectively, no comments were written at all - because that way you'd be sure to pass the code check, whereas even a single line of comments could be said to be "unnecessary", because "the code is self-documenting".

I wish I were kidding...

int19h

# re: Comments @ Tuesday, August 26, 2008 11:01 AM

@int19h

Only one word to describe that bad situation: wow :(

Jared Parsons

# re: Comments @ Tuesday, August 26, 2008 11:09 AM

I hear ya.  However, unit tests are pretty good "comments" too.

Kris Krause

# re: Comments @ Tuesday, August 26, 2008 12:35 PM

I can think of a time when comments are superfluous and just plain pointless:

I was asked to comment the functionality of PInvokes into standard Windows functions (such as GetWindowText, CreateEvent, etc) a month ago. What's even worse is that I used your PInvoke Utility to mass import a bunch of them. My reaction: "... so, have you heard of MSDN or Google?"

Koush

# re: Comments @ Tuesday, August 26, 2008 5:27 PM

@Koush,

The PInvoke tool comments are as verbose as possible.  Mainly because I wrote it as a tool to help people understand the issues involved with PInvoke.  Giving a full type history hit this band.  

At the same time it's generated code so turning off comments is easy.  I've gotten several requests to add the MSDN information for the particular function.  I'm definately looking at doing that.  

Jared Parsons

# re: Comments @ Tuesday, August 26, 2008 6:05 PM

Plenty of comments have led me astray, causing me to waste time trying to merge the text laid out in the comment and what the actual code seemed to be doing, only to find out the comment is wrong, formulated in a way that seems confusing, or using vague terminology I don't get.

Comment = more stuff to keep up to date, and there's no compiler aiding you, to keep the text in check with the code.

Svend Tofte

New Comments to this post are disabled
Page view tracker