Data wrangler, software engineer, systems programmer, cyclist. Unix (mostly Solaris) for aeons. I talk C, Python, SQL, Performance, Java, Kafka and Makefiles.
Location
Brisbane, Australia
Education
BA (Mathematics, Modern History), University of Queensland
There are two paragraphs in your piece which provide the meat of your argument - but you bury them. Those paragraphs are
We have a responsibility to make our work accessible. To make it
readable and useful. When we write code to use in production, both
the code itself and the accompanying documents must be easy for others
to understand, because unreadable code is almost useless.
and
Foo is a barrier to people understanding your examples, and while all
code should be easy to understand your examples should be the easiest
part to read!
The question that I don't believe you really answered is "why is Foo a barrier to understanding?". I answer that question as follows:
Variables used in example functions should relate directly to those
functions. Since "Foo" is a made-up word, it *cannot* relate to
anything in those functions, which works against the point of the
example.
As a long-time C programmer I found your walkthrough of the example function annoying - it is my opinion that if you are going to provide an example you should use a language where you can make that point with ease. Freely admitting that you don't know C is fine - but please do not then use an example written in that language. [I'm more than happy to write a different discussion of that function if you'd like - DM me].
I am an OpenEdge (aka Progress) developer that loves clean code and good looking applications that are easy to use. My main pet project is the Progress DataDigger
I found it a bit weird that the author does have the knowledge to dissect a program in a language she does not understand, but lacks the knowledge that foo and bar are non-meaning variables.
She does have a point though, that 'foo' and 'bar' are 100% meaningless and could easily be replaced with names that do make sense.
I personally feels like it works better because it is a language he isn't too familiar with.
Because most of the people looking at examples with foo and bar are the ones who are just getting into the language, and speaking from experience having examples there really does harm readability and some function/variable names would have been better off if they were given a more specific name instead.
Some people were probably fine reading through foo/bar examples, but that doesn't negate the fact that a good chunk of people out there would rather have sensible naming for examples so that they can visualize the code they're trying to learn better
The thing is, if I am doing code review or telling someone they are not following Single Responsibility Principle by throwing everything in main, I will tell them to:
There are two paragraphs in your piece which provide the meat of your argument - but you bury them. Those paragraphs are
and
The question that I don't believe you really answered is "why is Foo a barrier to understanding?". I answer that question as follows:
As a long-time C programmer I found your walkthrough of the example function annoying - it is my opinion that if you are going to provide an example you should use a language where you can make that point with ease. Freely admitting that you don't know C is fine - but please do not then use an example written in that language. [I'm more than happy to write a different discussion of that function if you'd like - DM me].
I found it a bit weird that the author does have the knowledge to dissect a program in a language she does not understand, but lacks the knowledge that foo and bar are non-meaning variables.
She does have a point though, that 'foo' and 'bar' are 100% meaningless and could easily be replaced with names that do make sense.
I personally feels like it works better because it is a language he isn't too familiar with.
Because most of the people looking at examples with
fooandbarare the ones who are just getting into the language, and speaking from experience having examples there really does harm readability and some function/variable names would have been better off if they were given a more specific name instead.Some people were probably fine reading through
foo/barexamples, but that doesn't negate the fact that a good chunk of people out there would rather have sensible naming for examples so that they can visualize the code they're trying to learn betterThe thing is, if I am doing code review or telling someone they are not following Single Responsibility Principle by throwing everything in main, I will tell them to:
def foo():
bar0 = process0()
...
barN = processN()
baz = doing_stuff(bar0, ..., barN)
return baz
Foo bar baz is a specific way to show theory, principles, and has it's place. Much like the comment below . and
xin math.