[wolco2]

Shorter is easier to read and understand at first glance.

Writing a paragraph kills any formatting in vi/vim.

Why not write a comment if a paragraph is required to understand what you are doing.

This sounds like Hungarian notion taken to the extreme.

[Geminidog]

>This sounds like Hungarian notion taken to the extreme.

No it's sanity taken to the extreme.

Have you ever noticed that all things written to communicate things to people in the United States outside of programming is written in a very verbose manner using a language called English? It's used for technical manuals, text books, and stories.

Is English "hungarian notation taken to the extreme?" No dude. People actually find verbose English stuff easier to read. You don't have English writers abbreviating words and coming up with elegant acronyms in a physics text book.

>Why not write a comment if a paragraph is required to understand what you are doing.

I didn't say name your function after a paragraph. A functions English language analog is a word and at most a sentence. A paragraph would be several functions chained together. If you name your functions well, composed procedures will read close to an actual English paragraph.

That being said there's nothing wrong with comments, comment away but don't call your function doXYZ and put the entire description in the comment. Your comment doesn't follow the a function call.

Here's an example:

    list_of_profiles = get_list_of_profiles_from_file("profiles.txt")
    list_of_profiles_named_bob = filter_profiles_by_name("Bob", list_of_profiles)
    list_of_profiles_named_jane = filter_profiles_by_name("Jane", list_of_profiles)
    list_of_profiles_named_bob_and_jane = concatenate_profile_lists(list_of_profiles_named_bob,
                                              list_of_profiles_named_jane)
    list_of_pairs_with_a_married bob_and_jane = merge_married_profiles_into_list_of_pairs(
                                                   list_of_profiles_named_bob_and_jane)

Trust me, you may think your eyes are bleeding but they are not. The above is actually closer to the English language then 90% of code out there. What you don't realize is that there wasn't a need for a single comment and there wasn't a need to dive into any of these functions to read the definition. You just read the variable and function names and you know exactly what's going on. If you recompose these functions to do something else it's like recomposing sentences and words in the english language. The end result is still readable without the need for new comments.

When you read a recipe or follow directions to build something does the writer give you those directions in some coded nomenclature? No the writer writes verbose English with clear grammar. The point is clarity in naming in these entities, it makes zero sense why we don't do the same in programming.

>Writing a paragraph kills any formatting in vi/vim.

You know this might be a really different chain of thought that goes against the grain...

But maybe due to this lack of formatting in vi/vim makes vi/vim an extremely bad editor for programming? Seriously, humans are weird (Japan for example still uses fax machines). If it's so bad why do so many people use it? Maybe to look smart or maybe for the same nonsensical irrationality as to why we have to come up with some unreadable but "elegant" name for every programming primitive but at the same time we have to be extremely verbose for ALL other forms of written communication with English.

Programmers like to think they're smart and original. Most aren't... they follow the same tropes as every other programmer trying to come up with elegant names for no reason whatsoever and strangely unable to see the purposelessness behind this whole naming thing. If you can't come up with a good "name" for it, make the name an entire sentence, it's that simple... it's the reason why sentences exist.

[BlargMcLarg]

"from_file", "by_name", etc. are fairly needless here. Most people are apt enough to grasp the first argument relates to the last word of the function name. Use properly named variables so a summary can take care of it, or only omit the noun, "get list of profiles from".

Get itself is a terrible prefix and could be omitted, especially if you keep "from". "list_of_profiles_from(X)" isn't any less clear. Alternatives like "read_list_of_profiles(file)" exist.

"List_of_profiles" can be changed to "profile list". You already did it with "concatenate_profile_lists", showing inconsistency. Alternatively, depending on the context, "list" itself can be omitted entirely, and just state "profiles".

"merge_married_profiles_into_list_of_pairs" can arguably be shorted to "merge_married_profiles" depending on IDE and language: that last bit should be clear from the returned value. Even without, it can still be shortened to "pair_married_profiles", as the context should make it obvious if we look for more than 1 married couple, there will be some kind of collection. Additionally, your naming has one problem: "merge_married_profiles". With all the verbose naming, it is still not clear what "married profile" is. I'll assume it means "pair profiles of married couples", where you might as well say "pair_profiles_of_married_couples".

>Programmers like to think they're smart and original.

It is because they think to be smart and original, they fall into the trap of overly verbose naming. Not from a lack of it. Have you looked at a legacy Java code base? Many of them can be slashed in half just by renaming variables to something that keeps the meaning, or draws meaning from the context very obviously. These guys are going against their own mind's natural ability to read context, or worse, conditioned themselves to learned helplessness.

[spion]

They are in fact bleeding.

Clear writing is about structure, not verbosity or repetition. Concise-and-clear is preferred over verbose-and-clear.

[ybothr]

You mean "being more conciseness is better if you don't have to sacrifice clarity for it"? Or just - "conciseness is a good thing"?

How would you rewrite that example, specifically, to make it more concise without sacrificing clarity, then? Do you mean to change the names without omitting type or relational information somehow? Or to omit some variables entirely in favor of nesting function calls?

If the latter, I don't see the relevance to that commenter's actual point about short vs long names; reducing the number of names is entirely tangential.

[spion]

I would omit most information that can be inferred from context so long as context locality is good.

Single-letter names are OK for context smaller than 1 line (like lambdas), type information can be omitted for context up to 10 lines (lists etc) and generic functions (filter, concat, inner_join) are better over custom domain functions when the audience consists of other programmers.

Abbreviations are best avoided unless they are extremely common and familiar in the specific domain / industry. If they are only ever used within that team and company, that's probably bad.

Example here: https://news.ycombinator.com/item?id=25477495

[Geminidog]

>I would omit most information that can be inferred from context so long as context locality is good.

context also changes with time as other people edit your code. Your single variable name with simple context can balloon in complexity and move around. Don't assume locality is fixed.

Additionally locality wastes precious time. It is preferable to read a variable name and not even need to touch context.

>generic functions (filter, concat, inner_join) are better over custom domain functions when the audience consists of other programmers.

Not true. For filter and innter_join especially the predicate or inner lambda can be intricately complicated and hard to decipher, better to wrap all that complexity in an english name. You save programmer time by having the programmer read an english over deciphering even simple code.

Rule of thumb: It is far easier to read one line of english then it is to read a one line of code. So it is better to allow readers to ascertain meaning from naming over context. You are wasting the programmers time otherwise.

[spion]

> context also changes with time as other people edit your code

And you change the code accordingly, IF it does. Typically though, its best to change the structure of the code, not to increase its local complexity. If the context gets complicated, think about what makes sense to be split out. Local complexity should be kept minimal.

> can be intricately complicated and hard to decipher

And you change the code accordingly, IF they are. But you name the lambda, not the generic function. There is a huge value in using a standardized vocabulary. Even in English, we get value out of "baby" versus "small human between the age of 0 and 2 years")

More generally, I've seen this kind of thinking before. A programmer discovers some "universal truth" which applied well in some context and they get so obsessed with it that they start applying it everywhere. Please, stop and think before you overcommit to such ideas. They are not nearly as universal as they seem - caveats apply. If you ignore those caveats, your fellow team mates will suffer - so check with them frequently too. At the end of the day it doesn't matter what you think about your own code's readability, but what others think.

[Geminidog]

>They are in fact bleeding.

>Clear writing is about structure, not verbosity or repetition. Concise-and-clear is preferred over verbose-and-clear.

Except this is where the contradiction lies. In both well written literature and great text books... clarity trumps all even when conciseness is sacrificed. English is one of the most verbose languages out there. I can take your sentence and make it concise:

>My eye bleed.

>Writing about struct. No verbose or repeat. Short n' Clear beter den wordy n' Clear.

Is that better? Your misguided logic paints my concise version of your comment as "preferred" even though it has the exact same clarity. The stark reality is, for purely human reasons, people prefer the former example over the later and there is no real rationality behind it.

Try to think a bit outside of the box here. You share the biased and delusional opinion of a typical average programmer.

The real logic is, that the conciseness or verbosity is inconsequential. Our human nature allows us to prefer contradictory approaches in code vs. english because verbosity and conciseness doesn't actually matter that much. Clarity is king by a long shot hence the reason why most humans prefer reading literature over code.

My code displays the ultimate clarity. You insultingly claim that your eyes may be bleeding, but I guarantee you that unless you're mentally deficient, no part of my code was unclear. It was 100% obvious and crystal clear what my intentions are. The best part is, you only need to read it one time.

When is the last time in your life you've read a similar snippet of unfamiliar production code at first glance and left with the exact same level of clarity? Most similar production code needs a good number of guesses and hypothesis and a couple of reads and code following to develop the same level of clarity and confidence of understanding that my code can produce on a SINGLE reading.

I would wager we can agree on that point and if your claim otherwise I would wager that you are lying.

[yxhuvud]

The problem is that all those words make it harder to find the meaning. Well-chosen naming exposes it.

[Geminidog]

If it can be found. But more often then not it can't be found. Do you always search for the most elegant single word to describe a point in English? Sometimes. But more often then not you have to resort to sentences.

There's no reason why this logic can't be applied to programming.

[amatecha]

Yeah, I don't need conciseness or brevity. The processor or the network connection needs conciseness. Programmers need specificity and clarity. Verbosity is fine too, IMO :)

[spion]

My comment was already concise to begin with. Your change reduced clarity. Here I will exaggerate your example:

    list_of_profiles_that_we_got_from_reading_a_file_named_profiles_dot_txt = get_list_of_profiles_from_file("profiles.txt")
    
    list_of_profiles_from_the_file_named_profiles_dot_txt_which_are_filtered_by_name_where_the_name_was_bob = 
      filter_profiles_by_name("Bob", list_of_profiles_that_we_got_from_reading_a_file_named_profiles_dot_txt)
    list_of_profiles_from_the_file_named_profiles_dot_txt_which_are_filtered_by_name_where_the_name_was_jane = 
      filter_profiles_by_name("Jane", list_of_profiles_that_we_got_from_reading_a_file_named_profiles_dot_txt)
    combination_of_the_profiles_from_the_profiles_dot_txt_file_containing_both_the_profiles_with_a_name_bob_and_the_profiles_with_a_name_jane = 
      concatenate_profile_lists(
        list_of_profiles_from_the_file_named_profiles_dot_txt_which_are_filtered_by_name_where_the_name_was_bob,
        list_of_profiles_from_the_file_named_profiles_dot_txt_which_are_filtered_by_name_where_the_name_was_jane
      )
    list_of_pairs_from_the_profiles_txt_file_where_the_first_person_is_named_bob_the_second_is_named_jane_and_they_are_also_married = 
      merge_married_profiles_into_list_of_pairs(
        combination_of_the_profiles_from_the_profiles_dot_txt_file_containing_both_the_profiles_with_a_name_bob_and_the_profiles_with_a_name_jane
      )

There is a point where verbosity decreases clarity by overwhelming the reader with irrelevant detail which can already be inferred from context.

Lets try a concise example:

  profiles = get_profiles_from_file("profiles.txt")

  bobs = profiles.filter(p => p.name == 'Bob')
  janes = profiles.filter(p => p.name == 'Jane')

  marriages = bobs.inner_join(janes, (bob, jane) => bob.partner == jane)

Does it matter whether profiles is a list or not? If the typical data structure / convention you use for plural variables is a list, you don't have to say it.

Do I have to say that the variable bobs is a list of people named bob? Not if its obvious from the context on the right hand side that I'm filtering by name

Do I have to use a more verbose argument name in the lambda passed to `filter`? Not really - its short and there is plenty of context around to deduce that its a profile, especially if the reader is familiar with a commonly used standard library function.

The last one is tricky, and it depends who you're communicating with. Do you expect your readers to be familiar with the standard library of the language, even less commonly used functions? If so, then its fine. If not, again it depends. Is the reader familiar with SQL or relational algebra? If so, then yes they probably have no problem with this.

As long as your context and conventions are clear, you can leave a lot of details out and still get the message across. Its better to err on the side of caution, yes, but it doesn't mean that unlimited verbosity leads to unlimited clarity. As with writing - your audience is what matters.

[Geminidog]

> My comment was already concise to begin with. Your change reduced clarity. Here I will exaggerate your example:

Your comment was concise because it was just a statement. You didn't attempt to prove a point.

My comment was a proof against your point hence why it's longer. Now you're trying to disprove my proof which also explains why your subsequent reply is also significantly longer.

> There is a point where verbosity decreases clarity by overwhelming the reader with irrelevant detail which can already be inferred from context.

I agree with the above completely, but I also think the point is obvious. I never stated there was a level of verbosity that is excessive because I thought that notion is actually completely clear to all readers.

Here's a good rule of thumb to follow. We clearly don't think the English language is too excessive in verbosity. So All I'm saying is bring programming to the level of verbosity of English and don't go past that.

Obviously your first example is excessive and past typical English verbosity. But your second example is below English verbosity and has several problems.

> Does it matter whether profiles is a list or not? If the typical data structure / convention you use for plural variables is a list, you don't have to say it.

It doesn't hurt if I put "list" or "profiles" in the name it's just some additional letters letters and adds more information. It doesn't matter at all. Also your assumption is wrong. Many containers can be plural including linked lists, hash maps, trees and graphs.

>Do I have to say that the variable bobs is a list of people named bob? Not if its obvious from the context on the right hand side that I'm filtering by name

You don't have to, but you don't not have to either. The Bob variable can be used in a section very far away from the context... then what is a bobs? What is a janes? How do you even know it's a list of profiles? You're literally making me follow and decipher code to figure it out. That is the point. Give a function an English name where I don't need to decipher anything. I read the function name and I don't have to dive in to decode anything.

>Do I have to use a more verbose argument name in the lambda passed to `filter`? Not really - its short and there is plenty of context around to deduce that its a profile, especially if the reader is familiar with a commonly used standard library function.

There is nothing you "have to do" here. You can do whatever you want. I am saying what you're doing is actually is worse for communication and that my way is better for communication with the incredibly negligible downside of being more verbose. That being said context can balloon in complexity, reading code is harder than reading english so make the reader read english when he can rather then code.

>The last one is tricky, and it depends who you're communicating with. Do you expect your readers to be familiar with the standard library of the language, even less commonly used functions? If so, then its fine. If not, again it depends. Is the reader familiar with SQL or relational algebra? If so, then yes they probably have no problem with this.

All your variables can be used far away from the context where they are created. You can't rely on the fact that the creation of Bobs is right next to it's usage in marriages. Often times your style of coding will result in people having to follow code and dive into definitions to figure stuff out.

First off marriages. Marriages of what? Sam and Bob? George and Shirley? Second the expression itself. Again what is a bob and jane? What is a partner? Partners in crime? Also seriously:

   bob.inner_join(janes, (bob, jane) => bob.partner == jane)

compare the two.

   list_of_pairs_with_a_married bob_and_jane = merge_married_profiles_into_list_of_pairs(
                                                   list_of_profiles_named_bob_and_jane)

I think most people will agree that mine is more clear in communicating what's going. Your version despite the brevity needs some deciphering.

Also you can't expect that the profile data structure is so simple that it can be done in a one liner. You assumed the data structure to be very simple. What if the data structure is an incredibly complex graph structure of profiles. Marriages can only be found by a complex graph algorithm. I don't want people to decipher a graph algorithm to decode what I'm trying to do here.

Write your function names so people can avoid deciphering meaning from context. The point is so people can decipher meaning from English because English is ten times easier.

[spion]

> Marriages of what? Sam and Bob? George and Shirley? Second the expression itself. Again what is a bob and jane? What is a partner? Partners in crime? Also seriously:

And we get to the key point you are missing. Its clear from the context. The code we had wasn't some imaginary code where the variable was far away and had a ton of context. It was that particular code. Different code might be better written in a different way. If you a have different code context in mind with higher complexity, show that one.

Additionally, "merge_married_profiles_into_list_of_pairs" is not necessarily better. When debugging the code, we don't know what that part really does. An implementation using a more generic standard library function lets us glance over that bit since we already have understanding of it. (And again, it might depend on the audience - are we talking to a language expert, or a domain expert? Do we have a well tested and well defined library of domain functions that everyone has a clear understanding of?)

Context and audience matter. Verbosity can be a lazy cop out for bad structure. (That's applicable to writing English as well.)

[throwaway201103]

Programming is more like mathematical notation than english prose.

In mathematics we write a² + b² = c² to describe the relationship between the lengths of the sides of a right triangle. We don't write it out in english words longhand, because the notation is brief, packs a lot of meaning into a small amount of space, and lets our minds focus on larger concepts rather than parsing long phrases and keeping their meanings organized.

[Geminidog]

>In mathematics we write a² + b² = c² to describe the relationship between the lengths of the sides of a right triangle.

Therein lies the problem. Can you explain to me the meaning of a² + b² = c² without English? Can you just write down an equation and expect me to know what you're talking about?

Can you explain to me the concept of entropy by just showing me all the equations?

Can you explain to me the meaning of your program with only one letter variable names as shown in your Pythagorean equation above?

You can't. That's why math texts consist of equations AND English, and there's no reason programming shouldn't either.

Anyway a side note, have you ever heard of literate programming?

[MrPatan]

Yeah!

Why is matematical notation full of one-letter variables?

Cool when paper and ink is expensive and you're trying to send your proof to the other mathematician, in a letter in the mail, in the 16th century, but now? Why?!