[modi123_1]

http://improvingsoft...ting-your-code/

Hopefully this can help those with trepidations regarding their first job or internship. Good examples!

Quote

One of the first things you learn to do incorrectly as a programmer is commenting your code. My experience with student and recently graduated programmers tells me that college is a really good place to learn really bad code commenting techniques. This is just one of those areas where in-theory and in-practice don’t align well.
...
These tips are primarily intended for upstart programmers who are transitioning into the real world of programming, and hopefully will prevent a few from looking quite so n00bish during their first code review
...

• Comments are not subtitles
  
• Comments are not an art project
  
• Header Blocks: Nuisance or Menace?
  
• Comments are not source control
  
• Comments are a code smell

[jon.kiparsky]

There's one consideration that isn't discussed here. In some shops - like the one I'm at now - you have a lot of projects in a lot of languages, and everyone is expected to be able to make a go at working on any of them. Well, when you've got Java, C$ (nice typo, I'll leave it), coldfusion, PHP, various SSIS packages, all in the same repository, you can be pretty sure that at some point someone's going to be looking at something here, and they won't be very familiar with the language.

In a situation like this, I incline towards overcommenting, particularly anything that's likely to be confusing. Since I'm writing some perl to add to that heap just now, it's actually approaching a 1 to 1 comment ratio, because perl is one that my colleagues are not very familiar with, and there are a lot of idiosyncratic perl-isms.
And expression like
open FOO, "$path\\$_"||die "couldn't open $_ : $!\n");

is perfectly legible if you're familiar with perl, but it's likely to throw someone who's more C# and metastorm-capable. So I'll add a comment to let them know that I'm opening the next file in the sequence, or exiting with a warning message if the file doesn't open. That gives them a fighting chance at working through the code.

The other thing I'd add is that it's much more important to document the purpose of a program and any constraints than to get down into the details of what each part does. If you know exactly what I'm trying to do, you can probably figure out what each piece does - at that point, my comments will mostly be pointing out the reason for doing things in an odd way. (a line like "//In case the file name has embedded spaces" will help prevent incorrect optimizations).

In my organization, there are an absolute ton of platforms and tools, all of which talk to each other. It's almost impossible to know the whole thing unless you've been there for a while: good purpose-oriented comments and top-level documentation serve to orient the new programmer, and make them more useful more quickly. This is a good thing.