alpaca princess (renniekins) wrote,
alpaca princess
renniekins

Comments

I was talking to the professor of my C++ class awhile back, and he was looking at my code.

"I'm actually pleasantly surprised by your code," he told me. "It's very good, very readable. The only feedback I have, and take this how you want... you don't use many comments. Actually, any comments."

I grinned. I was wondering when this would come up. That's right baby, that's the Agile Way!

I didn't answer that way of course; I was more polite. "Well, that's a kind of philosophy where I work you see. The idea is that comments will get stale. When code is changed, the comments may or may not change along with it. Instead the code itself should be clean and readable, thus creating its own documentation. You refactor it; you use very informative method names and variable names to make it understandable."

He wasn't entirely convinced. "Well your code is very readable. It's just there aren't many comments. Take that how you will."

I thanked him -- but I wasn't entirely convinced either.

The next assignment I turned in was a bridge-dealing exercise that I worked on during the drive back from Mackinac. I generously gave him a few comments. Since (for the sake of keeping my deliverables clean) each exercise is in its own single source file, I provided a comment on the top of each class definition for visual separation.

My pride and joy though, is the single informative comment I included in the code. It can be seen below.


/* MAIN */

int main() {
Deck deck;
deck.display("The clean deck: \n");

for (int i=0; i<7; i++) {
   // shuffling a deck past 7 times is shown to be statistically insignificant
   deck.shuffle();
}
deck.display("\nThe shuffled deck: \n");

deck.dealCardsTo("Rennie", "Sandra", "Rob", "Lisa");
deck.display("\nThe dealt deck: \n");

return 0;
}
Tags: school
Subscribe
  • Post a new comment

    Error

    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

    Your IP address will be recorded 

  • 20 comments