Why You Should Focus On Writing Code With Clarity Discussion
Roman Alvarado M.
Good article Chris, ruby has the clarity implied, programmers don't...
however "ubiquitous language" is something that could help to
programmers on this, thanks for share your thoughts!
Chris Zempel
1.What's your take on defining methods purely to clarify the actions therein? for example, to cover up extremely ugly, unintuitive instances of operations like mapping and regex
2. I envision one of the oft-asked questions regarding this subject being "how long should method names be?" So I'll pose it also:
what's a better metric or guideline for method names than their length?
1. Often times in Ruby you'll see one or two line methods. This can be useful. In fact, user_signed_in? could be as simple as User.find(session[:user_id]). If it finds a user, you're signed in and it should return true. If it throws an exception because it can't find the record, you're not and it should return false.
But this is just one way of handling it. You may not choose to pull the record out of the database to verify they are signed in. It seems wise to both verify the user_id in the session AND load the user.
The merits of writing a method called user_signed_in? are such that you no longer have to care how the verification works. You just simply trust that it does its job and go about your business. In fact, I would venture to guess that a large amount of people haven't even contemplated how user_signed_in? works if they have never tried building an authentication system from scratch.
2. Related to point #1, your method names should be as concise as possible while still conveying clarity. We could have methods named check_if_user_is_signed_in but far too dramatic.
The way you describe the code in words out loud to a coworker often give insight into how the code should ideally be written. If you tell a programmer "okay, so we want this to happen if the user is signed in" translates almost directly to:
if user_signed_in?
the_thing_we_want_to_happen
endI think the closest thing to a metric I can give is how similar your code is to the way you speak. The closer your code reads to what you speak means that understanding can be conveyed at higher bandwidth.
There are no hard and fast rules to this as it changes between industries, environments, and even countries that you live and work in. Culture affects this strongly.
The way to learn this is to begin reading LOTS of source code for large, well-established, and well known projects like Sinatra, Jekyll, and Rails. See how they go about their naming schemes and find the style that's most appealing to you that also provides clarity.
As you see examples in other projects, you will be able to pick up on the subtle nuances that make the difference between directly naming something and naming with an added dash of clarity.