What is refactoring?
The answer to this question is very crucial for your understanding of the whole process. Refactoring is making ch...
For further actions, you may consider blocking this person and/or reporting abuse
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.
I agree with intent-commenting, but I can answer your other two concerns...
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.
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
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:
Good code and good comment:
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 thetax 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.Nice article Maciej!
A couple of things I would like to add:
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!
Hey, thanks for your feedback and stopping by!
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!!
Glad it helped! Cheers :)
"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 ;)
Of course it should. Thank you :)
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.
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()
callsmethodB()
which callsmethodC()
...", recognize the fact that these are 3 sequential steps, and create a "lifecycle method" which does the work of calling them in sequence.From
to
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.
This is the point so many seem to miss. It's not done before it's refactored. And yes, it doesn't have to be perfect because it never will be.
I heard this phrase somewhere about legacy code that i really like.
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.
Always follow the boy scout rule!
Hey Justin, thanks for the good read and nice tips!