It's all Greek to me: Thoughts on code readability and aesthetics | Hacker News Reader

It's all Greek to me: Thoughts on code readability and aesthetics

avraam.dev

67 pointsavrmav60 comments

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

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.

    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.

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

No, we only have fstrings now :) - I know -too well- backwards compatibility...

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

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

I think it's more productive to not care about the formatting. Allow redundant, pointless spaces that serve only to keep things out of alignment. Once it doesn't matter if the code is pretty - or if the autoformatter has been run - you just read the content.

Oh, there are many that hate it, we just get voted down fairly fast.

Agreed, the same applies in JS w/ Prettier.

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

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?

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.

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.

Russia and the US

AP style, or Oxford and a subtle political commentary? ;-)

English uses commas more liberally than many languages. None of the commas OP used are particularly surprising, but some of them would be considered improper in more formal contexts. They are used to delimit the boundary between dependent and independent clauses, as in my previous sentence. They are also used around some kinds of parenthetical remarks, like this one, or to separate an initial prepositional phrase from the subject of the sentence (“In Greece, we have”).

They should not appear between subject and verb (“Readable code, is...” or “let me, tell...”).

It’s been a long time since I got this stuff in school, so there’s probably a lot of subtleties I’m forgetting.

Most modern writers use fewer commas. It was common in 19th century English to use commas for pacing like in the article. So native speakers are familiar with the style, but I don’t recommend imitating it.

1, 3 and 4 are acceptable but unnecessary, and would probably be frowned upon by English teachers. The other examples are incorrect.

> 1, 3 and 4 ...

As we’re talking about comma usage in English, it may be worth noting that there is wide disagreement about the Oxford, Harvard, or serial comma[1] in lists; no matter which choice you make, it will look wrong to many people.

[1] https://en.m.wikipedia.org/wiki/Serial_comma

But that's a question of style and tradition, not correctness. "I, went, home" is incorrect, no matter if you adhere to Chicago or Oxford.

Well, it will look jarring, annoying, and wrong to those people who are wrong.

While overall the article is well-written (grammatically), the author uses too many commas in a number of sentences. I wouldn't say that their comma use is "unacceptable", but it's not proper. An editor would remove many of them, and an English teacher would ding them if grading it.

Yes, completely acceptable :-)

There might be some technicality/formality that insists otherwise but this is so natural a writing style, and so invisible as a result, I had to reread the examples a few times before I understood what you were asking about (thought initially you might be asking about the ... notation which is a bit more idiosyncratic and up for debate as to how to use correctly)

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)

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.

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

It's all about the "the fuck is this"s per minute it generates.[1]

Lower is better.

[1] https://www.osnews.com/story/19266/wtfsm/

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.

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.

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?

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.

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.

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.

Do both groups favor turning every decision into a dichotomy? If so, maybe those aren't seniors after all.

As a side-side note:

https://msfn.org/board/topic/158668-virtual-memory-on-usb/?d...

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

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/Content/NavigationMenu/NewsandPubli...

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.

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

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.

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

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.

Every editor can do this. Apply your formatter when you load a file, and apply the standard formatter whenever you submit a file to another machine.

I mean, that’s the most common argument on why tabs are better the spaces. It’s also an argument I tend to be sympathetic too.

Yeah following simple formatting rules is a job we can (and should) give to the computer.

Problems arise when you refer to lines/columns which are different from what you see by preference. I believe there will be much more friction in line-based tools than in people who do not like a particular style.

QBASIC got that right decades ago :-P

BASIC.

QBASIC mostly removed line numbers.

I was referring to the automatic formatting that QBASIC did.

> 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

It’s all Japanese to me...

わからない。

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?

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

Safety pretty much always comes at a cost (of some kind) Even if that cost is just being forced into a more restrictive model. In some cases this actually limits what you can do, but in the case of JS's === it's about doing what the programmer is expecting. I think many people would agree that JS casts types too liberally at times [1], and using === is a good way to avoid the confusion that can cause.

Other language features cause other confusions.

Quotes generally boil down to arguments about escaping, and have good reason for existing. Having a rule for when to use what quotes should be pretty inferable from when you need to use what quote to escape the data in question.

New array vs literal is more a pure aesthetics issue, and I can only really say, choose whatever you think the majority of people would read faster. Don't be different just to be different, and move on.

1: https://www.destroyallsoftware.com/talks/wat

The threequal operator aside, my experience is that none of these decisions really matter in themselves. What is far more important is agreement and consistency. Use the same style everywhere, enforce it automatically, don’t bikeshed over it, and get on with doing actual things that matter.

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.

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.

My rule about code comments applies here as well. 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.

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

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.

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.

Reply on news.ycombinator.com