61–70 of 177 posts
When structuring code, elegance and efficiency always take top priority. However, when naming, my philosophy is always clarity over elegance. for example (in python): def reverseListAndAddOneToEachElement(input_list): Ugly, but clear. I don't even need to write out the full definition you already know exactly what it does.
I disagree strongly with one or two of the rules. But an even bigger problem is that some (or even most) of the advice either has little value or doesn't really apply to programming. In english, shorter is better, but I'd much rather a longer class name that I can understand than one that's abbreviated to the point where I am forced to look up what its doing. A good rule of thumb that I try to follow is that for the most part, your code should be self explanatory (comments should cover the rest). We have these rules in programming for how to write variable names, and they're better than the ones in that slide. Another rule, that trumps any other is consistency. If you're working on a project that uses the passive voice (which I think works better for some cases) then use that. The nature of programming is different than natural language writing, and so it makes more sense that these rules that are trying to be transferred over are ill equipped to do so.
I mentioned that some of the things just don't make sense As an example, this was one of the slides, "when writing a novel a writer should create living people; people not characters. A character is a caricature." What does this mean? Its ironic that the slide preaches being short and to the point, and yet is bloated with abstract fluff.
"Most of the things programmers say about comments in code are excuses for not writing any comments at all"
This is true. Here is my excuse:
1. Follow all rules for writing good comments 2. Comment is now short, crisp and concise 3. Apply "Extract Function" refactoring, use comment as function name 4. Your comment is a compiled entity now 5. Write testcases for the function that explicitly explain corner cases and weird behavior 5. You have no comments in the code any more
This rule can be applied almost all the time, although it can be quite hard to use when global variables or wide scopes are used (e.g. 1000 line for-loops in C). Comments are either obvious or they're lying. Why would you write something that the compiler will ignore eventually?
Earlier quoted context omitted.
Hopefully a function that can be corectly named.
What do you think is a better name? reverseListAndAddOneToEachElement is describing the function but I agree it feels ugly.
def convertDF4ToMX6(data):
# The MX6 format is read as a stack rather
# than a queue, and requires data to be 1
# indexed rather than 0 indexed like DF4
# link_to_MX6 format spec 1.3.2 (v5)
# link_to_DF6 format spec 1.2.0 (v1)
This would then mean the calling points might look something like
mx6_data = convertDF4ToMX6(loadDF4(file))
return processMX6(mx6_data)
mx6_data = reverseAndAddOneToEachElement(loadDF4(file))
return processMX6(mx6_data)
The author states: "Most of the things programmers say about comments in code are excuses for not writing any comments at all" This is true. Here is my excuse: 1. Follow all rules for writing good comments 2. Comment is now short, crisp and concise 3. Apply "Extract Function" refactoring, use comment as function name 4. Your comment is a compiled entity now 5. Write testcases for the function that explicitly explain…
My early days of OOP, I started keeping a thesaurus on my bookshelf at work. Probably went overboard on naming for a while, but reigned it in. (Every writer shudders at their first efforts. Hoo boy).
We would also hold short discussions about names for things (I don't see this in the article's list of tools: Involve other people in the names you are choosing. After all, they'll be using the code, too).
When structuring code, elegance and efficiency always take top priority. However, when naming, my philosophy is always clarity over elegance. for example (in python): def reverseListAndAddOneToEachElement(input_list): Ugly, but clear. I don't even need to write out the full definition you already know exactly what it does.
I like the logic of this, but it goes against all books that i've read to keep it short. Why do we need to keep it short?
An important rule is missing here: variables should be named with their scope in mind. So if a variable is longer lived and has larger scope its name should be that much more descriptive because when you're looking at it the only thing that will tie the value of the variable to the context within which it can be used is its name. So 'i' is fine for a loop control variable with a scope of five lines but totally inadeq…
i heard a tale of some graph layout code that ended up as part of a Microsoft product - all of the things were named after birds.