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).
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!
Single Responsibility Principle (or SRP) is one of the most important concepts in software development. The main idea of this concept is: all pieces of software must have only a single responsibility.