Refactoring is not so scary

Maciej Posłuszny on August 19, 2017

What is refactoring? The answer to this question is very crucial for your understanding of the whole process. Refactoring is making ch... [Read Full]
markdown guide

Don't use comments. Instead try to name your functions and variables > better. Comments are allowed only for TODO, FIXME (not on master branch > though) and some special cases where you would want to describe your > intentions instead of mechanism.

I don't agree with this. The only case where comments aren't useful are autogenerated comments by IDE's (Java I'm looking at you).

It makes it easier and quicker to understand the source code, Especially in open source projects with a lot of contributors.

I've found that it's easier for me to understand the code if they're helpful comments about what a particular block of code/function does. I can just skip the code if the comment says it does something different that I'm not interested in. I don't need to read it.

On the other hand, if there's no comment (and you have just "special" comments) you'll spend a lot of time reading a lot of code that has nothing to do with what you're interested in at that moment No matter how clear the function/method name is.


Of course it is easier if comments explain the code.
But what if comments and code become desynchronised?
How about some self-explaining code instructions?

That is the purpose of don't use comments: functions names, variables names, code organization that self-explain its intention.


Don't use comments. Instead try to name your functions and variables better.

Comments are perfectly fine if they're doing their job correctly. They should focus on why it was done this way rather than what it does.

Bad code and bad comment:

var t = .24; // tax rate

Good code and good comment:

var taxRate = .24; // tax rate as per the 2018 tax code

The comment expresses that the hardcoded value was set to that, which helps a new developer or future you know why at a glance. They can be more helpful if I actually used functionality as an example rather than variable initialization, but it gets the gist across.


I was reported a wrong result from our accountant. I checked the code: it seems than taxRate has a wrong value, but the comment says it is the tax rate as per the 2018 tax code. I checked on the internet and found that .24 was the tax rate as per the 2017 tax code, the tax rate as per the 2018 tax code is .25. Comment were source of noise.


Just what I needed. I was writing a pagination helper and i realised it wasnt following the single responsibility principle. I changed it up. Havent finished writing it. But this validated me today, thanks!!


This is amazing. I've been working on a big refactoring/modularization project at work for the last 6 months, and this perfectly captures everything I've learned in this process, and so much more.

One thing I would add: learn your application's lifecycle, and design your APIs around that lifecycle. Rather than having "methodA() calls methodB() which calls methodC()...", recognize the fact that these are 3 sequential steps, and create a "lifecycle method" which does the work of calling them in sequence.


function a() { b() }
function b() { c() }
function c() { // so on... }


function a() { }
function b() { }
function c() { }
function onLIfecycleAction() {

This will make each method more individually-testable, and also more reusable. You really start to realize why you need this when one method passes parameters to another, because when each method relies on the lifecycle for moving data along, then you have to return those arguments from the method rather than just passing them, and you get more discriminatory about which data is going where in your application.


I don't understand how do you compute 150 as the maximum lines of a class. It's a magic number! Please provide some scientific proof. Even in the Java API there classes with several hundred lines perfectly accomplishing SOLID principles. About comments I have no words, take any complex algorithm without comments and you won't understand shit.


Nice article Maciej!

A couple of things I would like to add:

  • tests :-) refactoring is definitely easier (and less scary) if you have tests for the code
  • code linting tools: most programming language and editors can easily integrate configurable linting tools so you can have a common setup for you and your team.

I'm not fluent in Java but in Ruby I always use tools like rubocop that can automatically tell you stuff like "your line is too long", "your method is too long", "hey there are too many parameters" and so on.



"Functions length should be 7-20 lines of code." - shouldn't that be "Maximum 7-20 lines of code?".
Your example functions are not 7 lines long ;)


Well that could be simplified to "maximum 20 lines of code" if we were being all programmery about it.


Ahh but then it would all go wrong when someone puts in 0 or -1 lines of code.
and are we only allowing integers....

this is trickier than I thought ;)


MOST important, write unit tests. More specifically, pin down tests.

Pinning Tests
Legacy Code Challenge

Depending upon how much time I have while in a file, I take refactoring in steps.

  • If no tests write unit tests, little refactoring
  • Else time box and play to heart's content

Always follow the boy scout rule!


Hey Justin, thanks for the good read and nice tips!

code of conduct - report abuse