
It's all Greek to me: Thoughts on code readability and aesthetics - avrmav
https://avraam.dev/posts/greek-to-me/
======
Rainymood
>Next time we have a conflict with a colleague on what is “readable”, let’s
ask ourselves “Am I talking about understandability or I am talking about
aesthetics?”

This is why I'm in favor of auto-formatters like Black for Python. Nobody
really likes it, but nobody really hates it either and you get used to it.
What this does is that it completely removes the style component of the
discussion, leading to better and more content-wise discussions of the code
written.

~~~
stereolambda
I'd say the main reason for strict formatting is the organizational one: when
you really need for the same file to be edited by many people and not turn
into a mess.

Otherwise, it _may be_ convenience, as I don't have to maintain consistency
manually. May be, because in languages where there are multiple syntactic ways
to do things (Python, JS), I want flexibility in emphasizing things. (Even if
I don't overuse it.) It's hard for people who came up with formatting to
predict everything what can be done in the language. People may use more
imperative, more functional syntax, mix things etc. This may be even warranted
in the context.

Of course, you can force a particular set of idioms, but this again becomes
shifted to the context of a project or organization. In languages where the
syntax is more uniform, it's easier to standardize formatting throughout the
whole ecosystem. And indeed it is standardized in Lisp and Go for example -
not in the C family for probably historical reasons.

~~~
makapuf

        languages where there are multiple syntactic ways to do things 
    

Python zen says: the should be one (and preferably only one) obvious way to do
it. Perl might fit your description better.

~~~
Avamander
Unfortunately we have many ways to do format strings now :P

~~~
EForEndeavour
list(map(f, iterable)) versus [f(x) for x in iterable] also comes to mind!

~~~
makapuf
If I remember correctly, it is recommended to use list comprehension (see
stackoverflow)

------
myfonj
OT question from non-native speaker: those commas that mimics speech pauses
are syntactically acceptable in English? (Or Greek?)

> In Greece, we have a similar phrase [...] > Readable code, is a piece of
> code [...] > In Germany, they say [...]. > In 16th century, in the
> Habsburgermonarchy [...] > [...] but let me, tell you a secret: [...] >
> Readable code, is a piece of code [...]

(I'm from Bohemian village where we were taught commas delimits sentences and
such usage would be technically incorrect, but I suppose there are different
rules in other languages.)

~~~
twic
A comma separates clauses that make grammatical sense on their own, or at
least where one of them does. So "In Greece, we have a similar phrase" is
fine, because "we have a similar phrase" is complete in itself. Whereas
"Readable code, is a piece of code" is not correct, because "is a piece of
code" is not complete - it's missing a subject. Likewise, "In Germany, they
say" and "In 16th century, in the Habsburgermonarchy" are fine, but "but let
me, tell you a secret" is not.

As a native speaker, i can understand those sentences well enough, but they
look wrong, and i wouldn't expect a fluent native writer to write them.

I have a Greek friend who is similarly scattershot with commas (eg "Hey send
me, the photo of your office!"). I wonder if this comes from mapping some
feature of Greek sentence structure onto English?

~~~
dalai
I am Greek and we don't use that many commas. Definitely not in this way. I
think the Greek language is also not as flexible with comma placement as
perhaps English is.

What I've noticed is that some people never learned how to use them. They just
write a sentence (or a whole essay) and generously sprinkle some commas
afterwards, normally wherever they would make a short pause. I've seen this
with colleagues from Germany, Greece, Russia and the US.

~~~
YeGoblynQueenne
I'm Greek also. I was taught at school that you place commas where you would
naturally have a pause when speaking a sentence aloud. You can hear that rule
very clearly in operation in the way school kids read when asked to read a
text aloud (e.g. in national holidays etc). They always _very deliberately_
pause after each and every comma.

Anyway, other than the last two examples, the examples above don't look wrong
to me.

------
gniv
I have yet to figure out what makes code readable. My own anecdote: I remember
reading some code written by Jeff Dean and was amazed by how easy it was to
parse and understand. Funny thing is it had quite a few violations of the
style guide. In contrast, when I read some of my own code a year later I was
scratching my head. It was too dense, variables had too-long names etc. (and
it’s the etc that I cannot fully articulate/correct)

~~~
hyperpallium
It's probably like prose: sorry to write such a long letter, I didn't have
time to write a short one.

To express something well, you need a sense for all the different ways to
express it, to be able to choose the right one. But to just express it, you
only need one.

anecdote: naming is hard. I can code something in a few hours, and still not
have ideal names after weeks. Some come the next day.

~~~
tonyedgecombe
I often think if I'm struggling to name something then perhaps the design
isn't what it should be.

------
AtticusTheGreat
Whenever this kind of disagreement happens with my team, we put it to a vote
and then the winning convention is enforced across the codebase from then on.
There are tons of things in programming that come down to opinion but the
important thing for me is that the team has a set convention and sticks to it.

~~~
viseztrance
I worked in a place where my team lead wanted us to vote on a technical
decision. I found that unfair because half of the team was at a junior level.

~~~
lonelappde
If you can't explain why your idea is good to a junior engineer, voting is the
lead of your problem. If you mistrust half your team as a rule, how can you
trust anything to get done well?

~~~
fouc
It's hard to explain to junior engineers why chasing fads is a bad idea. Why
boring technology is often the best choice. That's only something that most
people figure out with experience.

~~~
empath75
Seniors often don’t like doing new things for the simple reason that they
already know how to do things a different way and they don’t feel like
learning something new.

~~~
celticmusic
and juniors like to make mistakes because that's how they turn into seniors.

The point is, and will continue to be, that a senior's opinion should be
heeded or you disallow them from steering the ship away from the glacier that
they know is there.

You can always justify everything with a reason. If your goal is to justify,
then great, you did that. If your goal is to be effective, you need to stop
trying to justify.

------
jaclaz
As a side-side note:

[https://msfn.org/board/topic/158668-virtual-memory-on-
usb/?d...](https://msfn.org/board/topic/158668-virtual-memory-on-
usb/?do=findComment&comment=1018485)

>From John Phillip Mustachio of Houston, this excerpt from the trial testimony
of the plaintiff, whose first language is Greek.

Q. What I'm trying to do, Mr. Emmanonil, is to show that you have quite a bit
of experience in owning and operating real estate, do you not?

A. No. The only one experience I have is just to - to know how is the valuable
of the land is going to go up or down. That's I'm good only. But legal phrase
like this one, I'm zero. Like I say earlier, I have gift know when is good
piece of land or not. The rest of this stuff _it 's English to me_.

Original link is down, the sentence can be found here:

[https://www.texasbar.com/AM/Template.cfm?Section=Say_What_&T...](https://www.texasbar.com/AM/Template.cfm?Section=Say_What_&Template=/CM/ContentDisplay.cfm&ContentID=35605)

Somewhat Criminal by Jerry Buchmeier

VOL. 60 NO. 9 TEXAS BAR IOURNAL 991 October 1997

[https://www.texasbar.com/AM/Template.cfm?Section=Say_What_](https://www.texasbar.com/AM/Template.cfm?Section=Say_What_)
[https://www.texasbar.com/Content/NavigationMenu/NewsandPubli...](https://www.texasbar.com/Content/NavigationMenu/NewsandPublications/TexasBarJournal1/SayWhat/1990_s.htm)

------
siempreme
We really should stop formatting the actual code to make it 'readable'. The
editor or IDE should take care of formatting the displayed code to our
preferences with a built in linter/prettier. That should end the pointless and
annoying discussion.

~~~
slx26
I read your comment too fast and I almost dismissed it, thinking you were
talking, like everyone else, about formatters (gofmt, rustfmt). But what you
are saying is much more interesting, as we are all allowed to keep our
preferences. Is there any major editor/IDE working on this? You are making me
miserable, now that I read this I can't live with just formatters anymore :D

~~~
davnicwil
So, this is indeed a very cool idea, the fundamental issue you'd have though
is that you can't abstract away from the 'ground truth' formatting at the
source control level.

You could even sort of brute force this without IDE support by reformatting
everything to your preference on git pull and back to ground truth on git
stage/push, but when it comes to diffs, merges, etc, you _must_ work in terms
of the ground truth formatting. That's not even to mention doing stuff like PR
reviews in online tools, not in your local editor/IDE. Going back and forth
between the two like this would probably just be counter productive, you're
better off just thinking in terms of the ground truth formatting from the
start, I'd say.

I think while it might be possible under a very narrow set of limitations and
usecases, it's probably just a very leaky abstraction to try to 'hide' the
actual formatting of code in a text file.

~~~
slx26
I can definitely see it might have quite a few problems. Forest [0] and others
even attempt to abstract on syntax, which I generally disagree with as it
becomes a problem to learn the language or get help / discuss some things with
other people, especially online.

I'm not dismissing the default formatter, it's obvious you still need one
canonical representation of the code, but I don't think you should view it as
"hiding" the formatting. In my view, it's more like opening a web page with
one browser or another, or with one device or another. It always looks a bit
different. Or maybe I have a theme configured on my main browser or whatever.
I like to have my preferences, but if I have to look at the page from another
browser, it's not a big deal either. The extra configuration might not be
worth it or slightly inconvenient in some cases, but I doubt it's counter
productive. The same way as I might prefer to read/write with a certain font
or use this or that color palette.

Maybe the takeaway is that code is more personal for some people than we like
to generally admit. You are talking in a language and you want to be able to
express yourself as comfortably as possible. I mean, we have had turing-
complete and even "productive/decently ergonomic" languages for a while, and
yet a lot of people keeps coming up with new languages, because they are much
more than just a tool to get things working. We want to express ourselves as
we "think", and formatting may be a small part of that, but it's still a part
of it.

[0] [https://github.com/forest-lang/forest-
compiler](https://github.com/forest-lang/forest-compiler)

~~~
davnicwil
I definitely agree with most of this but I have to challenge the web browser
analogy because that's a scenario where the concept of the view (visual,
screen reader, etc) being interpreted from the textual representation is built
in - as in, there is no end user who consumes the raw markup as-is. So
different end users working with different views is a completey natural and
expected thing.

I guess that's what's missing to make this work for code. The raw code _is_
intended as the final representation to the end user.

Maybe what you'd need to make this work is to build in the concept of
formatting to the source control itself, so all the way through the tooling
you could 'render' the code as you'd like to see it, and do all operations on
it using that view (including diffs, etc). Maybe sort of like you can with
syntax highlighting, except with positional formatting instead.

------
smitty1e
> Let’s not try to be smart. Let’s try to be understood.

By myself later

When forced to wade through what seemed

So clear at the time

~~~
quickthrower2
It’s all Japanese to me...

~~~
tjpnz
わからない。

------
jt2190
I'm more troubled that we might be banishing perfectly good features for the
flimsiest of reasons.

Take, for example, JavaScript's double-equals == versus triple-equals ===
comparison operators. (I already know you have a strong opinion on these!) The
language designer saw fit to include both. Now, if I introduce one bug where I
need to use === explicitly instead of ==, should I advocate for a ban the use
of == across the entire program? How about if I introduce this bug twice?
Three times? What if I've only _heard_ from a senior dev that triple-equals is
"bad"? Or should we test the least-experienced member of the team and let
their understanding make the decision for us? What happens when that team
member gets more experience, do we lift the ban?

Double- versus triple-equals example is probably one of the most clear cut
trade-offs and worth exploring. What about all of the other rules? Double
versus single quotes, for example? What about declaring arrays using array-
literal syntax versus using the new operator?

~~~
mrmr1993
> The language designer saw fit to include both.

=== wasn't introduced until ECMAScript 3 in 1999, originally there was only ==
when the language was created in '95.

The accepted wisdom is to prefer the newer === in the interest of clarity and
consistency. With ==, it's easy to forget about one of the types it overloads
(e.g. string vs. number) when making changes to existing code, and correct-
looking code may behave unexpectedly for one of these types.

------
kinkrtyavimoodh
As far as linting and formatting is concerned, having a company-wide policy
and having IDEs implement it automatically and presubmit checks enforce it is
enough.

However a lot of the arguments over code review come from (sometimes)
aesthetic preferences about code decisions. Should this be pulled out as a
function? What should it be named? Should this be inlined or pulled out as a
variable? Is ~A or ~B more readable or ~(A and B) (the latter ends up causing
the ugly sandwich (!( in languages like C++ or Java), etc etc.

These don't have automated solutions, but can nevertheless spark impassioned
arguments.

------
taneq
Absolutely agree. So many times I’ve seen developers instantly dismiss
unfamiliar code as ugly and poorly written when it’s qualitatively very
similar to their own, underneath some cosmetic details.

------
nixpulvis
My rule about code comments applies here as well.
[https://nixpulvis.com/ramblings/2018-09-29-comments-in-
code](https://nixpulvis.com/ramblings/2018-09-29-comments-in-code)

I agree every language has what I call warts, but some are definitely worse
than others.

------
cutler
Ah but you didn't mention Clojure which is as near perfect as anything :)

------
izolate
In our world of Ship It/Get Shit Done/Move Fast Break Things, code readability
doesn't stand a chance.

I find there's little allowance for time spent thinking about the poor sucker
who has to read my code, lest the sprint burndown chart suffers.

That's why code linters and formatters are so important. When applied
correctly, it's the closest we can come to having the entire codebase looking
like it was written by one person. A single standard you can learn once. Go
and Dart are good at this.

~~~
caymanjim
This might be true at some shops, but if so, they're doing it wrong. You can
move fast and still maintain code readibility. No matter how fast you're
moving, code shouldn't be accepted into a shared repository unless it meets
minimum standards. A well-functioning agile team cuts corners by not over-
engineering, by not waiting for elusive completion, by releasing minimally-
viable products that provide user value to get feedback and drive further
development. Even breaking things is ok, but sloppiness is not. When you push
out crap code to meet an arbitrary velocity target, you're just digging an
inescapable hole of tech debt. If you're not thinking about the poor sucker
who has to read your code, you're doing it wrong.

