Menu

Subscribe

A Comment Is An Invitation For Refactoring

Uncle Bob Martin has a pretty strict view on comments. He goes as far to say:

A comment is an apology for not choosing a more clear name, or a more reasonable set of parameters, or for the failure to use explanatory variables and explanatory functions. Apologies for making the code unmaintainable, apologies for not using well-known algorithms, apologies for writing 'clever' code, apologies for not having a good version control system, apologies for not having finished the job of writing the code, or for leaving vulnerabilities or flaws in the code.

A pretty purist view - but can we really go coding without comments? What about how code should tell you the how and comments should tell you the why?

The more code I read, the more I believe that most inline comments can be eliminated by refactoring the code itself (note the emphasis on most). Whenever you come across a comment in the code, ask yourself: could I refactor the code to remove this comment? The answer will be yes, in many cases.

And this is a great thing. Every comment that becomes part of the code will make refactoring more difficult - because when refactoring, not only the code, but the comment also needs to be changed. And we usually end up forgetting about them. In Clean Code the section on comments says:

The problem with comments is that they have no compile-time check and tend to be forgotten. It’s very easy to change your code but forget about the comments.

Almost all inline comments are ones that could be removed or moved while making the code more readable and easier to refactor. Let's look at 3 examples where comments are an indication that the code could be better organized.

1. Comments Inside (Too) Long Methods

I come across this pattern fairly often, where there are several comments splitting up parts of a long method:

override func viewDidLoad() {
   super.viewDidLoad()

   // setup the navigation bar
   self.searchBar.searchBarStyle = .Minimal
   self.searchBar.translucent = true
   self.searchBar.placeholder = "Search"

   // setup table view
   self.tableView.delegate = self
   self.tableView.dataSource = self
   self.tableView.estimatedRowHeight = 150.0
}

This is an invitation to again extract the sections the comments refer to. The comments are explaining the "how" in this case, not the "why" - a no-brainer to move the parts into methods of their own:

override func viewDidLoad() {
   super.viewDidLoad()
   self.setupNavigationBar()
   self.setupTableView()
}

Which version is easier to read? My vote goes for the second one - it's easier to read as the method is now shorter - and easier to refactor, as we no longer have to maintain the comment when changing the code.

2. The Bugfix Comment

Many comments I come across explain how a bug is eliminated by some otherwise hard to understand line(s) of code. Take this example:

func willPresentSearchController(searchController: UISearchController) {
    // Fixing searchbar disappearing on iOS9 when search controller is active
    if let navigationController = self.navigationController {
        self.storedNavigationBarTranslucency = navigationController.navigationBar.translucent
        self.navigationController?.navigationBar.translucent = true
    }
}

This comment is an invite to extract the bugfix code in its own method:


func willPresentSearchController(searchController: UISearchController) {
    self.preventSearchBarFromDisappearingWhenSearchControllerIsActive()
}

// Fixing searchbar disappearing on iOS9 when search controller is active    
func preventSearchBarFromDisappearingWhenSearchControllerIsActive() {
    if let navigationController = self.navigationController {
        self.storedNavigationBarTranslucency = navigationController.navigationBar.translucent
        self.navigationController?.navigationBar.translucent = true
    }
}

The readability of the code is just as good - and the bugfix code is extracted in its own logical item, a method. It's fine to keep the comment in place - but now it's obvious that the bugfix method does one thing, providing the workaround.

3. The Commented Out Code Comment

Every now and then I come across comments addressing commented out code.

// NOTE: temporary removed until the calendar functionality is removed. Re-enable afterwards by uncommenting this line:
//self.setupNativeCalendarAccess()

Another invitation... to delete the whole comment altogether. Commented out code is dead code, and dead code rots your codebase. There should be no reason to keep the code in place - this is exactly what source control is there for - if someone will need the original code, they can find it in the commit logs.

Coding Without Comments?

Comments certainly have their use and place. A use case where they're invaluable are API documentation and explaining things that code just can't convey (or it would be too complex). Here's what Jeff Atwood says about coding without comments:

If your feel your code is too complex to understand without comments, your code is probably just bad. Rewrite it until it doesn't need comments anymore. If, at the end of that effort, you still feel comments are necessary, then by all means, add comments. Carefully.

Apart from documenting your public API, you should treat each comment as an opportunity to refactor your code, to make it even more readable, with or without the comment. Comments have their use and place - make sure its a valid one before using them.

Featured Pragmatic Engineer Jobs

  1. Full-Stack Engineer at Farmlend. £85-95K + equity. London.
  2. Senior Backend Engineer at Farmlend. £85-95K + equity. London.
  3. Senior Full Stack Engineer at Perfect Venue. $150-180K + equity. San Francsico or Remote (US).
  4. Senior Software Engineer at AI Build. London or Remote (Europe).
  5. Senior DevOps Engineerr at AI Build. Remote (US).
  6. Full-Stack Engineer at Vital. $70-120K + equity. Remote (Global, within 5 hours of GMT).
  7. Backend Engineer at Vital. $70-120K + equity. Remote (Global, within 5 hours of GMT).
  8. Technical Lead - Platform at Vannevar Labs. Remote (US).
  9. Senior Software Engineer, Fullstack at Vannevar Labs. Remote (US).
  10. Computational Geometry Engineer at AI Build. London or Remote (Europe).
  11. Senior QA Engineer at AI Build. London or Remote (Europe).
  12. Lead Backend Developer at Cineville. €53-79K + equity. Amsterdam.
  13. Senior Software Engineer, Distributed Systems at Mixpanel. $200-270K + equity. New York, San Franciso, Seattle or Remote (US).
  14. Senior Software Engineer, Fullstack at Mixpanel. $200-270K + equity. New York, San Franciso, Seattle or Remote (US).
  15. Principal Engineer at Shoplift. $185-205K. New York.
  16. Senior Engineer at Sixfold AI. New York.

The above jobs score at least 10/12 on The Pragmatic Engineer Test. Browse more senior engineer and engineering leadership roles with great engineering cultures, or add your own on The Pragmatic Engineer Job board and apply to join The Pragmatic Engineer Talent Collective.

Want to get interesting opportunities from vetted tech companies? Sign up to The Pragmatic Engineer Talent Collective and get sent great opportunities - similar to the ones below without any obligation. You can be public or anonymous, and I’ll be curating the list of companies and people.

Are you hiring senior+ engineers or engineering managers? Apply to join The Pragmatic Engineer Talent Collective to contact world-class senior and above engineers and engineering managers/directors. Get vetted drops twice a month, from software engineers - full-stack, backend, mobile, frontend, data, ML - and managers currently working at Big Tech, high-growth startups, and places with strong engineering cultures. Apply here.