Checking My Comments

Burdette Lamar - May 18 '19 - - Dev Community

This morning I was going to start on a post about doing this:

  • Find a code passage that has an explanatory comment.
  • Turn it into a well-named method that doesn't need a comment (because the method name does that work).

I wondered whether I could glean a good example from my own code (and thereby improve my code, too).

Well....

I looked into my code for markdown_helper, checking up on what I had commented.

Found several things:

  • A code-inspection pragma from RubyMine that certainly does not belong in open-source code. (What? You mean some people don't use RubyMine?)
  • Two nearly identical passages of code, both with nearly identical explanatory comments. (Hey, I'm 76! I forget things!) That code should become a method not only to form the comment into the method name, but also just because -- refactoring.
  • A wonderful commented passage that should be changed into a method. What that code does is very necessary, but is presence at the beginning of the surrounding method impedes thought-flow if you're trying to read and understand that method.

These last two will eventually become part of the post I was considering.

Moral of the story (for me): Review comments!

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .