13 ms·
It's all Greek to me: Thoughts on code readability and aesthetics
- smitty1e 7y ago> 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 7y agoIt’s all Japanese to me...
- tjpnz 7y agoわからない。
- Rainymood 7y ago>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.
- cartlidge 7y agoI 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.
- deleted 7y ago[deleted]
- stereolambda 7y agoI'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 7y agolanguages 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 7y agoUnfortunately we have many ways to do format strings now :P
- makapuf 7y agoNo, we only have fstrings now :) - I know -too well- backwards compatibility...
- EForEndeavour 7y agolist(map(f, iterable)) versus [f(x) for x in iterable] also comes to mind!
- makapuf 7y ago
- niix 7y agoAgreed, the same applies in JS w/ Prettier.
- strokirk 7y agoOh, there are many that hate it, we just get voted down fairly fast.
- taneq 7y agoAbsolutely 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.
- siempreme 7y agoWe 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.
- bartwe 7y agoYeah following simple formatting rules is a job we can (and should) give to the computer.
- wruza 7y agoProblems 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.
- badsectoracula 7y agoQBASIC got that right decades ago :-P
- lonelappde 7y agoBASIC. QBASIC mostly removed line numbers.
- badsectoracula 7y agoI was referring to the automatic formatting that QBASIC did.
- slx26 7y agoI 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
- AtticusTheGreat 7y agoWhenever 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 7y agoI 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 7y agoIf 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 7y agoIt'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 7y agoSeniors 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 7y agoand 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 7y agoAs a side-side note: https://msfn.org/board/topic/158668-virtual-memory-on-usb/?do=findComment&comment=1018485 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_&Template=/CM/ContentDisplay.cfm&ContentID=35605 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/AM/Template.cfm?Section=Say_What_ https://www.texasbar.com/Content/NavigationMenu/NewsandPublications/TexasBarJournal1/SayWhat/1990_s.htm https://www.texasbar.com/Content/NavigationMenu/NewsandPubli...
- gniv 7y agoI 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 7y agoIt'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 7y agoI often think if I'm struggling to name something then perhaps the design isn't what it should be.
- huffmsa 7y agoIt'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/ https://www.osnews.com/story/19266/wtfsm/
- myfonj 7y agoOT 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.)
- kd5bjo 7y agoEnglish 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.
- davnicwil 7y agoYes, 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)
- tlb 7y agoMost 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.
- atombender 7y ago1, 3 and 4 are acceptable but unnecessary, and would probably be frowned upon by English teachers. The other examples are incorrect.
- izolate 7y agoIn 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 7y agoThis 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.
- jt2190 7y agoI'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?
- matthewmacleod 7y agoThe 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.
- deleted 7y ago[deleted]
- nixpulvis 7y agoSafety 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 https://www.destroyallsoftware.com/talks/wat
- nixpulvis 7y agoMy 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 7y agoAh but you didn't mention Clojure which is as near perfect as anything :)
- kinkrtyavimoodh 7y agoAs 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.