Communication is everything in software development.<\/p>\n
Unless you work on a team of one, it’s important that your code communicates easily to your team members. Even if you do work on a team of one, it’s important to communicate to your future self<\/b>. Yeah, everyone has to read their own code once in a while, and unless your brain is a steel trap, you’ll forget stuff.<\/p>\n
So do yourself and your team a favor. Choose names carefully. Here are some examples.<\/p>\n
Example 1: Use enumerations instead of booleans<\/b><\/p>\n
This example is C++. Let’s pretend you’re writing a parse()<\/tt> function that looks like this:<\/p>\n
bool parse(const char *file_name, employee *e, bool validate_only)<\/tt><\/p>\n
That seems pretty clear, doesn’t it? Let’s break it down:<\/p>\n
Inputs:<\/p>\n
Outputs:<\/p>\n
So far so good? Yeah, probably.<\/p>\n
Reading the code so far, the purpose of each parameter is very clear, but don’t make people read your header files if they don’t have to. Consider the code that actually calls<\/b> this function. It would look something like this:<\/p>\n Without looking back at the header file, can you tell me what this function does? For the most part, it’s obvious, but that true<\/tt> parameter is not clear. I’m also not happy with the boolean return value (though it is the lesser of the two offenders).<\/p>\n Don’t make me think so hard. If I stumble across the code above, I shouldn’t have to go hunt down a header file just to figure out what it does. We can make this easier on developers by changing those bool<\/tt>s to enum<\/tt>s, like so:<\/p>\n By making these changes, callers would see this instead:<\/p>\n Instead of true<\/tt>, we read validate_only<\/tt>, and it’s immediately clear what this function is doing. The returned value is also very clear. There is no need to consult documentation or other header files to figure it out.<\/p>\n Example 2: Mutants<\/b><\/p>\n In Python, you can remove white space from strings with the strip()<\/tt> function. However, if I stumbled across code like this, I probably wouldn’t realize that it had a bug:<\/p>\n That’s because the strip()<\/tt> function doesn’t actually strip whitespace from the string, but rather it returns a new string<\/b> with the whitespace stripped.<\/p>\n In this case, I would recommend that strip()<\/tt> be renamed stripped()<\/tt> or tostripped()<\/tt> to make it more clear that it returns a new string.<\/p>\n For methods that mutate<\/b> their instances, I recommend present-tense verbs like strip()<\/b>, rename()<\/b>, or clear()<\/b>. But for methods that return modified copies of the instance, I recommend past-participle names like stripped()<\/b>, renamed()<\/b>, or cleared()<\/b>.<\/p>\n Qt4 got this right with their changes to QString<\/tt>. Under Qt3, QString<\/tt> had a method called stripWhiteSpace()<\/tt>, so bugs like this were common:<\/p>\n In version 4, they renamed this method to trimmed()<\/tt>, so now there’s no question:<\/p>\n Example 3: Be specific<\/b><\/p>\n When reading others’ code it is common to come across words like data<\/b> or ret<\/b> or node<\/b>. While there are exceptions to this rule, these words usually aren’t specific enough to communicate your intent.<\/p>\n For example, let’s say I’m writing a Python program to run Linux commands and store their results in a map. Perhaps I make a function like this:<\/p>\n This just runs each command given to the function and puts the command’s output into a dictionary. Obviously, this is a tiny function, and as such, it may be an exception to the rule. However, if this were a more complicated function, perhaps one that executed each command in a separate thread and aggregated the results, data<\/b> would not be very clear. Instead, I’d recommend renaming data<\/b> to command_results<\/b>. I might even go so far as to name it command_results_dict<\/b> so it could be perfectly clear. Obviously, this rule can be taken too far. I would not recommend, for example, using a variable name like command_subprocess_stdout_result_dict<\/b>. That would be insane.<\/p>\n Conclusion<\/b><\/p>\n So there you have it. Just a few pointers that are probably obvious to most of you already. We can all stand to clean up our communication now and then, so take this as a chance clean up the code you write today. I know I will.<\/p>\n Happy hacking!<\/p>\n","protected":false},"excerpt":{"rendered":" Communication is everything in software development. Unless you work on a team of one, it’s important that your code communicates easily to your team members. Even if you do work on a team of one, it’s important to communicate to your future self. Yeah, everyone has to read their own code once in a while, […]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-860","post","type-post","status-publish","format-standard","hentry","category-code-and-cruft"],"_links":{"self":[{"href":"https:\/\/thesmithfam.org\/blog\/wp-json\/wp\/v2\/posts\/860","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/thesmithfam.org\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/thesmithfam.org\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/thesmithfam.org\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/thesmithfam.org\/blog\/wp-json\/wp\/v2\/comments?post=860"}],"version-history":[{"count":22,"href":"https:\/\/thesmithfam.org\/blog\/wp-json\/wp\/v2\/posts\/860\/revisions"}],"predecessor-version":[{"id":1516,"href":"https:\/\/thesmithfam.org\/blog\/wp-json\/wp\/v2\/posts\/860\/revisions\/1516"}],"wp:attachment":[{"href":"https:\/\/thesmithfam.org\/blog\/wp-json\/wp\/v2\/media?parent=860"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/thesmithfam.org\/blog\/wp-json\/wp\/v2\/categories?post=860"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/thesmithfam.org\/blog\/wp-json\/wp\/v2\/tags?post=860"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}\r\nemployee e;\r\nbool ret = parse(\"\/tmp\/foo.txt\", &e, true);\r\nif (ret) {\r\n ...\r\n<\/pre>\n\r\nenum parse_result { success, failure };\r\nenum parse_mode { validate_only, full_parse };\r\nparse_result parse(const char *file_name, employee *e, parse_mode mode);\r\n<\/pre>\n\r\nemployee e;\r\nparse_result result = parse(\"\/tmp\/foo.txt\", &e, validate_only);\r\nif (result == parse_success) {\r\n ...\r\n<\/pre>\n\r\ns = \" foobar \"\r\ns.strip()\r\nprint s # What does this print?\r\n<\/pre>\n
\r\nQString str = \" foobar \";\r\nstr.stripWhiteSpace();\r\n\/\/ BUG: Is str actually stripped now?\r\n<\/pre>\n
\r\nQString str = \" foobar \";\r\nstr.trimmed();\r\n\/\/ The bug is more obvious now\r\n<\/pre>\n
\r\ndef run_commands(commands):\r\n data = {}\r\n for command in commands:\r\n output = subprocess.Popen(command,\r\n stdout=subprocess.PIPE).communicate()\r\n data[command] = output[0]\r\n return data\r\n<\/pre>\n