pair programming with comments

Question

Over the years, I've discovered that green-programmers tend to read the comments rather than the code to debug issues.

Does having one person document the other person's code (and vice-versa) with the code writer's approval increase code quality in the long term?

Is this a good idea?

aside: I'm looking for middle-ground between solo programming and pair programming in terms of budgeting.

Answer 1

I've found that "pair programming" works best when one person writes the code and the other one writes unit tests (working side by side so they can see what each other is doing). You can swap the roles around occasionally too.

Answer 2

People tend to look for the easiest solution to a problem. If there's an "human" description available, it's likely to be utilized before the reader delves into esoteric code. IOW, the comments will often be considered first, regardless of how green the programmer happens to be.

Comments should maintained as well as possible. Unfortunately, they can easily become stale (because they cannot be validated by the compiler). Therefore, they should be kept to a reasonable minimum, because, ultimately, the code itself is the only real comment that can be trusted.

As for who should write the comments, it depends at what level the comments are being written. For example, at higher levels the comments should describe the outside behavior of a module, and could be written by a larger group of people. Internally, however, the comments should explain the intent of the various chunks of code. That way, its easier for the reader to glean the mannerisms of the code. Those comments should be written by the coder.

Answer 3

You run a higher risk of misinterpreting algorithms if the original author does not document the code. In my opinion, the only thing more frustrating than inadequately documented code is incorrectly documented code.

You may wish to try this approach:

• Perform code reviews with a developer that was not involved in the programming effort.
• Have the review performed without the physical presence of the code's author. Just the reviewer, a copy of the code from source control, and written documentation.
• If the reviewer can not reasonably understand the code without outside assistance, it is not adequately documented and should be given back to the author.
• Repeat as necessary.

Answer 4

I tend to write comment first and code immediately after that or at times or at times side by side. By the time I end up writing my comment the code becomes very clear in my mind (thanx to the fact of verbalizing my ideas while writing the comment). I don't like to comment the code which I haven't written. And whenever I come back to revise the code, first read the original comments, then think of new comments, write them and write the code side by side.

Answer 5

I find it works best when the helper does the broad scope thinking (i.e. What are we trying to accomplish) and the keyboard cowboy does the detail scope thinking. I don't think comments have anything to do with it.