DEV Community

Cover image for Identifying the dirt in our code -  names, functions, and comments

Identifying the dirt in our code - names, functions, and comments

Rachel Curioso :D on September 29, 2019

The problem of having code that is not very clean is that, as we maintain it, the code will get more and more complex and its understanding become ...
Collapse
 
ccunha profile image
Carolina Cunha

I loved this article! In fact, I'm think I should print it :)

But I didn't understand that part. about abstraction:

When we talk about abstraction levels, we can classify the code in 3 levels:
1) high: getAdress
2) medium: inactiveUsers = Users.findInactives
3) low: .split(" ")

Can you explain it to me, please?

Collapse
 
rachc profile image
Rachel Curioso :D

The high level abstraction are functions that you create, like searchForsomething()

The medium level are methods in your object, like account.unverifyAccount

The low level are methods that the language provides, like map, to_downncase and so on (:

Collapse
 
ccunha profile image
Carolina Cunha

Ahhh!Thanks!Sorry, was pretty clear now that I get it :)

Very nice article, I'am looking forward for the others.

Collapse
 
yuripredborskiy profile image
Yuri Predborskiy

I believe repeating "Account" in account.unverifyAccount is not required. Do you think it is? Why?

Thread Thread
 
rachc profile image
Rachel Curioso :D

The Account in unverifyAccount is clearly an unnecessary addition of context. Thank you for the review

Collapse
 
ghost profile image
Ghost

shhh, don't say in public that you don't make your tests first. The TDD police may raid SWAT your house. (I don't test before either and I even add tests that I wouldn't think of beforehand, but don't tell anyone). Good article tho. How I've hated my past self making those errors, I can only hope my future self doesn't hate me that much :)

Collapse
 
rachc profile image
Rachel Curioso :D

hahahaha. Let me edit this post to prevent the TDD police to knock on my door.

I try to do TDD sometimes, but I think it's hard when I don't have clarity of what I'm developing. I intend to read Test Driven Development: By Example and try for real one day.

Collapse
 
ghost profile image
Ghost

I tried but doesn't work for me, I guess I'll have to remain a scum. If you succeed pray for us, we'll be right here sitting in the mud being worthless.

Collapse
 
codemouse92 profile image
Jason C. McDonald • Edited

Cursory response that avoiding comments isn't the answer; rather, ensure they only state why the code is there, not what it does. (If code and intent-comment ever mismatch, that often indicates a bug that should be addressed.)

Collapse
 
rachc profile image
Rachel Curioso :D

You made a very good point
Great article, by the way (:

Collapse
 
annadante profile image
Anna

Great material. There's a lot of legacy code out there that is violating a lot of these rules and a lot of developers are shaking their heads trying to understand the flow.

Collapse
 
rachc profile image
Rachel Curioso :D

Every day I bump into some code that violates one of those principles.

(and almost every week I receive a code review that I'm the one doing this. I think that write clean code is something that you get used with time)

Collapse
 
erasmuswill profile image
Wilhelm Erasmus

Absolutely amazing article! Thanks for sharing. You even unintentionally highlighted the danger of abbreviating variable names by swapping some of the letters around. I don't want to admit how many times I've gotten a compile-time error just because I swapped two of those damned letters.

Collapse
 
briansdevblog profile image
Brian Hannaway • Edited

Great article, Rachel. Dont agree with the section on comments though. I think comments play an important role in creating maintainable code. I agree they need to be used sparingly, but I also think that good quality comments can add value to a code base. I covered this in a blog post recently. briansdevblog.com/2019/08/the-impo...

Collapse
 
shaunchong profile image
shaunchong

Thanks for the article!

Could you clarify about the section "Avoid returning an error code"? Instead of returning an error code, how should I then structure my code?

I usually raise an exception if an error occurs and do a try/catch from the calling function.

Collapse
 
rachc profile image
Rachel Curioso :D

You could return a message and not an error code. Another option is (in some cases) to change the user flow, redirecting the user to another page, and another option is to just log the error instead show to the user.

The problem with returning an error code is that the user won't know what the error means.
And raising an exception you'll break the application leaving the user frustrated.

Collapse
 
shaunchong profile image
shaunchong

Thanks!

I misunderstood your original article and thought you meant that we should not be returning error codes in our functions. I think it's ok to return error codes/throw exceptions in our functions but it should be caught (or we should detect the error code before it reaches the user) and display a friendly error message to the user.

Collapse
 
ogaston profile image
Omar Gaston Chalas

This is a great article!

You've addreesed the most frecuently mistakes that we do often. I think we have to make the habit of refactor our codebase and put all these principles in practice.

Thanks for sharing Rachel.

Collapse
 
jebbx profile image
David Hedderwick

Thanks for the article. I'm learning how to write clean code the hard way - I have a decade old website and body of C# code that has been written by multiple people in various different ways - knowing how to approach the code and what to look for to clean up (said dirt) is very helpful.

Thanks!

Collapse
 
rossholloway94 profile image
Ross Holloway

"Class names
Should be nouns, and not verbs, because classes represent concrete objects. They are the representation of things."

This feels to me like it contradicts SRP. Sure, some classes model objects, but what about those classes which perform a service?

Collapse
 
rachc profile image
Rachel Curioso :D

You are right (:
I didn't mention the classes that perform a service, but I see these classes as something palpable.

When I think about those classes I remember when I had to connect my application with someone else's, and we called this class "connectors". They perform a service, but they are an "object" that group various actions.
(when I talk about object, it's not in a "programming" way)

Collapse
 
aminmansuri profile image
hidden_dude • Edited

I agree with your article mostly except for the part on comments.

Comments are an important part of method/function signatures. They cannot/should not be avoided. They should be used and maintained.

I know this is a new trend.. but its a bad one. I've dealt with million line programs and comments are key for rapid understanding of large code bases.

Collapse
 
swarupkm profile image
Swarup Kumar Mahapatra

I would forgive dirt in the code if it has all the TESTS, rather than dirt-free code with NO tests . :)
Tests gives opportunity beautify code .... later.

Collapse
 
rachc profile image
Rachel Curioso :D

Yeeeeees! Sometimes we have all the good intentions and we just overdo the "give a meaningful name" rule