DEV Community

Burdette Lamar
Burdette Lamar

Posted on

Checking My Comments

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!

Top comments (1)

Collapse
 
samwho profile image
Sam Rose

I'm an ardent believer in turning comments in to methods, as well! Nice to find others who think the same. :)