tag:blogger.com,1999:blog-1531850453904970924.post4423122970147831118..comments2008-08-30T10:00:16.038-04:00RoboJennyhttp://www.blogger.com/profile/04085723385146006020noreply@blogger.comBlogger9125tag:blogger.com,1999:blog-1531850453904970924.post-83666310234992252822008-08-30T10:00:00.000-04:002008-08-30T10:00:00.000-04:00Good article with good advice! Thanks for sharing that. Will definitely take it to heart.<BR/><BR/>I tend to put comments in as if I'm writing to myself in the future when I look at the code and have no clue what the heck the past version of myself was thinking. That's the whole point anyway.<BR/><BR/>I think comments need to explain what I'm trying to accomplish, why I'm trying to accomplish it, and for less obvious subroutines, how I'm accomplishing it.<BR/><BR/>I picked up a habit of using a standard comment block above subroutines / objects and at the top of files. Description, input output side effect, etc. Makes it much easier to skim thru code later.<BR/><BR/>example code for Pokey: http://homepage.mac.com/michael_shimniok/Robot/PokeySource20080409.tgz<BR/><BR/>Michaelshimniokhttp://www.blogger.com/profile/17602015624941667574noreply@blogger.comtag:blogger.com,1999:blog-1531850453904970924.post-15626598866711165872008-08-30T00:02:00.000-04:002008-08-30T00:02:00.000-04:00Hehe "TODO/FIXME" is one of my favorite comments (and probably the only one on that list I use correctly every time)mdshttp://www.blogger.com/profile/14506141823071613677noreply@blogger.comtag:blogger.com,1999:blog-1531850453904970924.post-6112568428881121892008-08-29T21:28:00.000-04:002008-08-29T21:28:00.000-04:00Don't use inline comments, I gues the handgrenate story holds (see pointers). Never pull the pin, when you think you need it. Cause when you actually need it you'll know it. (mostly follows the list)<BR/><BR/>The rest folds(in any half decent IDE) so shouldn't have to hurt anyone.<BR/><BR/>"Complicated nested loop structure - This is the textbook case and should be clear."<BR/>Given cyclomatic complexity such a case shouldn't exist. split it up into separate methods.<BR/><BR/>"For example, writing javadocs for getters and setters on POJOs are unnecessary. If the API user cannot figure out what getName() and setName(String name) do, then I'm not really sure a comment would help them. Use comments for a purpose." You just missed the nail. Now name is perhaps a bad example but in other cases you might want to comment(lacking annotations) return value (non-)null / empty collection? etcMichael Bnoreply@blogger.comtag:blogger.com,1999:blog-1531850453904970924.post-62390036719275599832008-08-29T15:35:00.000-04:002008-08-29T15:35:00.000-04:00Damn Jenny you're pretty damn sexy. Anywhoo this really all boils down to comments should focus on WHY not how...tonnoreply@blogger.comtag:blogger.com,1999:blog-1531850453904970924.post-51524732633024945832008-08-29T14:27:00.000-04:002008-08-29T14:27:00.000-04:00I used to comment quite a bit, but then my girlfriend was, like, "I'm getting sick of your little comments", so I had to pare it down. Now I barely comment at all and, overall, I'd have to say that my relationship is better.Brukohttp://www.blogger.com/profile/16554253761930565252noreply@blogger.comtag:blogger.com,1999:blog-1531850453904970924.post-90998692908296548732008-08-29T12:13:00.000-04:002008-08-29T12:13:00.000-04:00As I stated in the post, I am in <I>no way</I> saying that code should not be commented. Neither code snippet were examples of the "correct" way, but rather two different examples of poor commenting. I was merely illustrating that even an example with commenting could be messier than the already incorrect example of not commenting at all.<BR/><BR/>What you stated is exactly an example I stated in my list of situations to comment: stating assumptions. I do think you explained it more eloquently though.<BR/><BR/>Thank you for you comments.RoboJennyhttp://www.blogger.com/profile/04085723385146006020noreply@blogger.comtag:blogger.com,1999:blog-1531850453904970924.post-1922401422261054332008-08-29T12:07:00.000-04:002008-08-29T12:07:00.000-04:00I totally agree with the premise of your post. But... :)<BR/><BR/>Given your code snippet I would use it as an example of under-commenting. I would at the very least expect a clarification on what happens when str is null (in Java you'd throw a NullPointerException in that code). Commenting code is more than explaining the "what" (which should be pretty obvious) but also the "why", preconditions, and postconditions that someone would need to know in order to use your code correctly.<BR/><BR/>Excellent point though.Chrishttp://www.grok-programming.comnoreply@blogger.comtag:blogger.com,1999:blog-1531850453904970924.post-47525680004387522202008-08-29T09:05:00.000-04:002008-08-29T09:05:00.000-04:00Heh. I think my code sample was actually pretty weak. I just wanted something short though to illustrate my point wrt overcommenting.<BR/><BR/>Sadly, I have seen far more egregious examples in production code at more than one of the companies I've worked for, but the same situation where every line is commented.RoboJennyhttp://www.blogger.com/profile/04085723385146006020noreply@blogger.comtag:blogger.com,1999:blog-1531850453904970924.post-76828781526630223322008-08-29T08:59:00.000-04:002008-08-29T08:59:00.000-04:00Here's my response (in code) in C# using .Net 3.5 extension method too, but also implemented as a regular static method that takes a string instance.<BR/><BR/><A HREF="http://pastebin.ca/1188468" REL="nofollow">http://pastebin.ca/1188468</A>Chris Benardhttp://chrisbenard.net/noreply@blogger.com