DEV Community

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 post

Osaetin Daniel • Feb 14 '18

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.

enguerran 🐐💨 • Jul 19 '18

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.

Jason C. McDonald • Oct 25 '19

I agree with intent-commenting, but I can answer your other two concerns...

But what if comments and code become desynchronised?

Then fix both. My team has used intent-commenting as a mandatory part of the code base for years, and desync nearly always indicates a logic bug. You'll note no one makes this complaint about function names, even though those are just as likely to fall out of sync. They fix the name.

How about some self-explaining code instructions?

Code should always self-explain what it does, but it is virtually impossible for code to explain its own code-agnostic intent.

To Comment Or Not To Comment?

Jason C. McDonald ・ Jan 20 ・ 12 min read

#coding #culture #productivity

ItsASine (Kayla) • May 23 '18

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.

enguerran 🐐💨 • Jul 19 '18

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.

rhymes • Aug 19 '17

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.

Bye!

Maciej Posłuszny • Aug 19 '17

Hey, thanks for your feedback and stopping by!

HawiCaesar • Aug 19 '17

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!!

Maciej Posłuszny • Aug 19 '17

Glad it helped! Cheers :)

Chris Shepherd • Aug 19 '17

"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 ;)

Ben Sinclair • May 24 '18

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

Chris Shepherd • May 24 '18

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 ;)

Maciej Posłuszny • Aug 19 '17

Of course it should. Thank you :)

Lluís Josep Martínez • Feb 14 '18

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.

Casey Brooks • Jul 18 '18

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.

From

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

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

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.