A Comment on Commenting

recursivefaults profile image Ryan Latta Updated on ・3 min read

Steve is new to software, they spend a lot of time reading documentation, writing code, commenting it out, and trying again.

Laura works a little differently. She doesn’t comment out blocks of code, but she uses branches and stashes to preserve her thoughts as she works.

Ralph doesn’t leave commented code, and rarely uses branches or stashes. He will reset his work back to a known state frequently. He throws away everything that isn’t used.

More than likely you work as one of these three developers. Steve and Laura both operate with a desire to hang on to old versions of their work and ideas. Ralph keeps only what is working. Steve and Laura wonder, “What if I need it.” Ralph says, “You aren’t going to need it.”

Before I go further, let me say this. Each of these three modes of working is effective. They each have consequences. Considering what it looks like to work a different way may expose certain things in your current workflow that you like and may not like.

About Steve

Steve will finish his feature, and begin to clean up the code. Cleaning up for Steve is dominated by removing all those bits of commented out code that he kept around. After he is done with that, how much energy does he have for refactoring? When he refactors will he begin another cycle of commenting his code while he attempts to clean it up? More than likely he’ll refactor shallowly. He will rename a few variables and functions. He’s already tired, and the act of removing comments was an intentional act of cleaning the code up.

About Laura

Laura comes to her work, building her code, keeping what works, but stashing and branching frequently to explore no ideas. She leaves a trail of stashes and branches behind. Maybe she’ll refactor more deeply. After all, she hasn’t spent any time cleaning things up yet. She’ll get her code refactored by renaming things and maybe extracting code to new methods. When she comes back to her next feature she sees a bunch of stashes and branches left behind. She’s not sure what’s in them, but she’ll have to get rid of them soon. Maybe she’ll accidentally merge one or delete the wrong one. She has some extra work to maintain those stashes and branches.

About Ralph

Ralph keeps nothing but working software. He rarely branches and doesn’t comment anything. The only way he can do this without losing too much work is by making tiny commits. He makes small, sometimes one line, changes and commits them. If he was wrong he goes back. He uses source control and his editor to save state for him. When he goes to clean up his code and refactor he renames, extracts, and may even have the energy to build new classes and look at coupling and cohesion between classes. He may see other opportunities to refactor. He doesn’t have to invest anything in cleaning up after his work. He doesn’t have to deal with stashes or branches. He doesn’t have to delete the commented code.

Walk in Their Shoes

My suggestion to anyone who is looking to improve, think about who you are in this story. Try walking in someone else’s shoes for a few days. It’ll be challenging. You may even come to the conclusion that this new way doesn’t work. Remember, each of these people has careers in software. Each of them is effective.

I’d recommend working like Ralph. He is effective in his workflow because he works small and maintains working code at all times. What does that look like for you?

This article was inspired by this tweet

Posted on by:

recursivefaults profile

Ryan Latta


I've been in software since 2009. I help software companies get the results they want and developers get the career of their dreams.


markdown guide

Pst! The tweet link doesn't point to the post, only to her page.

That aside, great blog by giving examples. Based on this, you may also like reading Clean Code by Robert Martin if you haven't already :D. I see a lot of similarity in the message.


Eep! Thanks for the head's up. I thought I had caught that. It's all fixed now!


I'm not Laura, but I think I'm somewhere between Steve and Ralph.