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 ... [Read Full]
markdown guide

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?


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 (:


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

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


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

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


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


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.


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.


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


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


I think that only by getting better at naming we'd improve our codebases a lot. I liked that you highlighted that when trying to comply with meaningful names, people end up creating redundancy, because there is a context given by say, the method name.


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


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.


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.


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)


Na, clean code is not a thing you'll ever achieve. The principles you're working to are always going to be wrong one day or another. It'd be better to call then suggestions instead.

See, having "small functions" might be a principle, but a single 100-line function is much more understandable than those same 100 lines split into 20 5-line functions. Your ability to grok the code diminishes with every jump away from the block you're working with. the same with swich v polymorphism - it may sound fantastic in principle to a student, and simple examples "prove" it, but in the real world the large codebase built on polymorphism can be next to impossible to understand. I've been there!

Your best, and possibly only, means to mitigate every bit of "unclean code" is the thing you already said is considered harmful. Comments.

Comments are the documentation you never write anyway, they are the primary assistant standing between a mess of code and human understanding. Sure, you shouldn't litter your code with pointless comments, and sure you should treat your comments as if they were code themselves (ie keep them updated) - a comment that doesn't match the code should be an outright code review failure.

All the modern practices, all the principles, they're all irrelevant and pointless if you have good comments. Good comments cure all ills in a codebase.

I think the commenting part is undervalued because of the approaches like Uncle Bob's, where you hack code together until it sort of works and then tidy it up to be "nicer". That all goes against commenting becuase there's little thought gone into what you're doing. In my day the approach for coding was:

a) think about what you're trying to achieve
b) understand how you're going to achieve that
c) write the code.

In this approach, commenting works as you can even write your codebase in comments and then add the code to match them afterwards, leaving you with code documented with comments throughout. But it doesn't lend itself to hackaway coding.


"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?


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)


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.


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.



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.


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


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.



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.


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.


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.

code of conduct - report abuse