[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.)

[Geminidog]

>And we get to the key point you are missing. Its clear from the context.

I understood this point utterly and completely you have misunderstood the point I was making. I am saying you can't rely on context because context can grow in complexity and can actually live far away from where you are using a variable or a function. Relying on context leads to code that will inevitably become less and less readable as complexity grows. Read my post. I literally addressed "context" and you literally missed my point.

Let me spell it out for you. If I have a 500 line piece of code, Bobs is created on line 1 then reused again on line 500, and I'm currently looking at line 500, you're expecting the reader to scroll all the way back to line 1 to decipher context. Couple that with multitudes of other concepts littered throughout your code with context strung throughout the page and located in different files.... This is my point that I demonstrated to you earlier to COUNTER your point. Once you realize this, you'll know that you're the one who missed the point.

You function name should be so clear that a reader should never have to read context. He reads the name and he can move on with life without decoding everything you did.

If I called the variable list_of_profiles_named_bob, no context is needed. Critical information lives and moves with the concept.

Let me reiterate my point: Context used in place of naming is done by programmers who are bad at writing readable code.

>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.

This is 100% better. Nobody needs to know what a function actually does, this is how abstraction works the point is that you only need to dive in when there is bug, but before there's a bug complexity should be abstracted away so we can make sense of the bigger picture.

>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?

I assume the audience can understand english. No need to use "inner join" when both the person who knows SQL also knows english. I chose the methodology that everyone can understand. What is the cost of doing this? Nothing. Just a longer function name that actually does zero harm to the structure of a program.

>Context and audience matter.

Audience matters, assume the audience can read English and generally program, that's it. Context as a communication medium is a crutch used by bad programmers to avoid abstracting concepts and giving things clear names.

> Verbosity can be a lazy cop out for bad structure.

Verbosity and naming have nothing to do with structure this is categorically wrong, and also obvious but whatever, I'll show you..

   func add_two_nums(x,y):
        return x + y

   func add(x, y):
        return x + y

Literally, 2 functions that do the exact same thing. You may claim the bottom function is better because it's shorter. And I claim it's shorter by a measly two words, who cares, both functions convey equal meaning and equal structure.

>are we talking to a language expert, or a domain expert?

Literally domain expert code is a synonym for bad code. All code that is bad, when studied long enough will produce a domain expert that knows that shitty code inside and out. A domain expert is someone who mastered (or wrote) code only readable by other masters of reading that same bad code. Think about it this way, if you posted your code on github and people started reading the code, all domain expert code will be regarded as shitty code. This is the colloquial definition of bad code. The best code is code on github that should be readable by non-domain experts on a single pass.

Now I admit that there are some cases where it's just too hard to do this. You can't program a simulation in relativity that's so readable that someone who doesn't understand relativity can read the code. Of course that's just too much to ask. What I'm saying is that "inner_join" is utterly unnecessary and that "merge_married_profiles_into_list_of_pairs" way better then what you came up with.