Executable Comments

By: Johnathon Wright on: October 07, 2020

One of the most important skills that differentiate an upper-mid-level developer from a lower-mid-level developer is the ability to write readable code. One strategy for increasing the readability of your code is to use something I've heard referred to as "executable comments" -- writing your code so that the variable names and structure give the reader maximum comprehension of the logic you're encoding.

Here is an example:

if roles.any? {|r| r.requires_segment? } && self.store_id.nil?
  errors[:store_id] = 'is required for users with these roles.'
end

If you aren't familiar with Ruby, this syntax can leave you a little confused. But translated into English, it would be "If there are any roles that require segments AND there is no store_id." And I can make the argument that it's fairly readable. As a loosely-typed language, Ruby tends to lend itself to readability already. And the names here are already evocative, semantic names. The structure is relatively simple. But consider this slight change:

segment_required = roles.any? {|r| r.requires_segment? }

if segment_required && self.store_id.nil?
  errors[:store_id] = 'is required for users with these roles.'
end

Adding that variable means that each line is just about as simple as it could possibly be. I don't think any of those lines could be broken down further, or any context added, that would improve comprehension. It requires a bit less mental energy to parse per line / per bite. And that makes the code dramatically easier to understand.





Comments:

off white clothing said: I and my friends appeared to be examining the great items from your web blog and so all of a sudden came up with an awful suspicion I never thanked the site owner for those techniques. Those young boys are already consequently warmed to read all of them and have in effect in actuality been enjoying these things. I appreciate you for really being well thoughtful and then for making a decision on such tremendous issues millions of individuals are really wanting to know about. My very own honest apologies for not expressing gratitude to earlier. off white clothing [url=http://www.offwhiteclothing.us.com]off white clothing[/url]

kobe 11 said: I enjoy you because of all of the effort on this blog. Betty take interest in doing investigation and it's really obvious why. Most people learn all regarding the powerful manner you offer powerful information on the web blog and as well as foster contribution from other ones about this area of interest then our princess is really studying a lot of things. Enjoy the remaining portion of the year. Your doing a brilliant job. kobe 11

yeezy boost 350 said: Needed to draft you this tiny observation to finally thank you again over the remarkable advice you've contributed on this page. It was simply incredibly generous of you to deliver openly precisely what many people might have offered as an electronic book in order to make some dough for themselves, mostly since you could have tried it in case you desired. Those pointers as well acted to be the easy way to be sure that other people online have similar desire much like mine to know more on the subject of this problem. I'm certain there are lots of more pleasurable periods ahead for those who discover your blog post. yeezy boost 350

yeezy boost 350 v2 said: I as well as my buddies were going through the good tricks from your web blog then instantly developed a horrible feeling I had not thanked the website owner for them. Most of the people were definitely certainly passionate to learn all of them and have in effect clearly been having fun with those things. Appreciation for really being considerably helpful as well as for picking this sort of useful subject areas most people are really desirous to be informed on. Our own sincere apologies for not expressing appreciation to you earlier. yeezy boost 350 v2

hermes handbags said: I am commenting to make you understand of the outstanding experience our daughter went through viewing your web page. She even learned numerous issues, which included what it is like to possess an awesome teaching spirit to make many more really easily know just exactly a variety of very confusing issues. You undoubtedly did more than our own expected results. Thanks for supplying those powerful, trusted, explanatory and also fun tips on this topic to Gloria. hermes handbags

kobe shoes said: Thanks so much for giving everyone remarkably marvellous chance to check tips from this website. It really is very useful and full of amusement for me and my office friends to visit your website no less than three times a week to study the latest stuff you have got. Of course, I'm so usually contented with the terrific techniques served by you. Selected 2 facts on this page are in reality the most suitable we have ever had. kobe shoes

yeezy boost said: I would like to voice my admiration for your kindness for folks that have the need for help with your area of interest. Your personal dedication to getting the message all over came to be really powerful and have frequently helped workers much like me to get to their targets. Your entire valuable report signifies this much to me and further more to my office colleagues. With thanks; from each one of us. yeezy boost

yeezy said: I just wanted to write down a quick note to express gratitude to you for these amazing tips you are placing at this site. My extended internet lookup has at the end been honored with useful knowledge to share with my companions. I would believe that we site visitors actually are unequivocally blessed to exist in a notable network with so many special people with valuable methods. I feel very much happy to have encountered your web site and look forward to plenty of more enjoyable minutes reading here. Thank you once again for everything. yeezy

jordan 4 said: Thank you so much for giving everyone an extraordinarily pleasant chance to read critical reviews from this blog. It's always very great plus stuffed with a lot of fun for me personally and my office co-workers to search your website the equivalent of three times a week to see the fresh things you have. And indeed, I'm so usually amazed with the excellent advice you serve. Certain two ideas on this page are truly the most impressive I've ever had. jordan 4

jordan 12 said: I'm also writing to make you understand of the cool discovery my child developed reading your webblog. She discovered too many things, with the inclusion of what it is like to have an amazing giving character to have the rest really easily gain knowledge of certain complex subject matter. You actually exceeded my expectations. Many thanks for delivering the beneficial, safe, explanatory and also cool thoughts on this topic to Jane. jordan 12
Back