Hacker News Reader

Comment by lamplovin | Hacker News Reader

Why would it be a problem to write code in a way that's easily understood by others reading it? If your code is so complicated that a little bit of documentation can't explain it or at least help get people started then you're probably being too "clever" with your code and need to simplify it a bit. Simple code doesn't mean it has to be under-engineered or non-performant, and creating a culture that doesn't take the time to help others understand what's going on is how teams get to the point of depending entirely on 2 people to do all their enhancements/fixes.

View on HN

Because sometimes the clever code may be easier to understand by an experienced developer even if it is less accessible to a less experienced developer. Non-coding example: "Two plus Three times Five" is easy to understand, because you don't need to know math symbols. But to anyone who knows math, "2 + 3 * 5" is easier/quicker to read.

For a coding example, in Javascript you have things like arrow functions that make the code more concise. But that is also harder to read for someone who hasn't picked up on them yet (which may have been the case when they were first introduced).

I agree with you on language syntax choices, but as far as the articles examples are concerned it seemed like the "clever" solutions to them were more about OO architecture choices via abstraction for example. In which case, if it's not a codebase that you have experience in, then those architecture choices can get very confusing if not properly documented

It is ambiguous,

"Two plus Three times Five" as a sentence reads and is naturally processed from left to right for a result of " is twenty-five".

But to anyone who knows math (precedence), "2 + 3 * 5 = 17"

The order of operations doesn't change because the equation is written out in English versus mathematical notation.

How do you say and/or spell out parentheses?

Easy: Take two plus five and multiply it by six

"There is no ambiguity because my context is the only context"

I learned a few years back that lawyers will give you a bunch of "ands" and "ors" in an expression without any concept of precedence. That doesn't necessarily mean left to right works, either.

Yeah. That's a trivial case but I'd still probably use parentheses). For more complex precedence operations I definitely would.

That's watered down and overly simplified.

We can have an argument over ternary operators and new users and I'm going to argue that they're part of the common vernacular of computer science and everyone needs to sit down and learn them.

But nested ternaries three levels deep are horrendous. Stick with one level and simple expressions and keep it readable (assuming the background of just understanding the operator). Don't overuse it.

Similarly lambda functions are part of the vernacular, everyone is going to need to learn that necessary amount of complexity. But at some point nested lambda functions containing lambda functions are going to get difficult to read and reason about.

The real problem is that the while the same code might look obvious to John Carmack, it might not look obvious to $outsourced_bodyshop_ressource_0443434.

Then you start coding for the lowest common denominator.

What if the NYTimes had journalists that described the news in their specific prose or worse, poetically. Speak plainly, it’s the news, report it as plainly and accurately as possible.

Often many people like to attach mathematics and science to Software Engineering to signal elitism, but truthfully this profession is a lot closer to writing. Write clearly, first and foremost, and above all else.

$outsourced_bodyshop_ressource_0443434 needs to be able to read the news too.

Great comment. Thank you

"Let's not use inheritance, it's complicated and could confuse programmers. Better to just copy-paste code."

"Source control? I don't know, this git command line is a little bit too much. Let's just use zip files and email the source"

That is not what I am suggesting, but alas, you seemed to have proven my point. I did not write clearly enough, and behold the outcome. Now imagine if we all do this in a codebase.

What were you suggesting?

Your writing was fine. HN is big enough that you can't take a single critical comment as strong evidence you were unclear. Maybe it's them, not you.

I'm not sure if this comment was in jest or not but I've seen both of these things happen in real projects.

Inheritance is the worst method of code reuse ever invented. I virtually never use it, and whenever I do, I usually regret it later.

I'm starting to notice a correlation between my prose and my code. Writing has not been my strength and I've quietly worked on it. Learning to organize my thoughts to best communicate with others has enabled me to organize my code for others to read. I've found this has improved the maintainability of my code. I wish I had put more effort into writing through out my schooling and early career.

I've noticed that the most successful business people I know are good at written communication. Much like programming often the better communicators write less to achieve more.

> What if the NYTimes had journalists that described the news in their specific prose or worse, poetically.

Eh, I think the news landscape would be improved if there was a news source providing it in poetic form. I wouldn't want everyone to do it that way.

Recently we hired a consultant for our infrastructure. I wrote the code for that infrastructure using best practices I learnt from books, workshops etc.

While some ppl from my team have huge issues understanding it, the consultant read it ONCE and knew everything. He was simply a good dev that had a pleasure working for other big shops that wrote the books I read and lead those workshops I attended to.

So its like always a matter of „Do I hire cheap HR resource or an expert?” question.

Nothing more, nothing less. The issue with writing smart code is that there is not a lot of smart devs. Thats why we always derotate to lowest denominator.

Are you the good guy in this story? Writing code that no one else can understand unless they've read multiple books to push through the complexity? Do you write in Java by chance?

Good guy? Depends how you define that. And it would be challenge to write infra code in java..

In my opinion, writing code that is so complex it takes an expert to understand it, is undesirable.

But where do we draw the line? If someone does not understand the idea behind interfaces or proper exception handling, who is to blame? If you write Java and Streams are the natural solution, but the developer you work with never bothered to look them up, because they are "complex" and "FP-something"?

These are polemic examples, but there is a line where sticking to the lowest common knowledge will hurt your best developers by either sucking the joy out of their work or by forcing write them a lot of boilerplate code. And I've heard of teams, where the whole team would ban features of a new standard of the language, because they've written code for 20 years without them before.

> But where do we draw the line?

Well, we can draw the line based on who is going to maintain the code after we are gone. If we know that the organization is only going to hire rockstar ninja experts, then we can make code that is readable for rockstar ninja experts. If we know that the organization is going to hire mediocre developers, then we need to make code that is understandable by mediocre developers. If you think mediocre developers can't understand streams, then don't use streams. (Personally I think your examples of interfaces, exception handling, and streams, are all things that have their time and place, so it would be fine to use them when needed, and just expect that developers after you will know/learn that stuff.)

> If we know that the organization is going to hire mediocre developers, then we need to make code that is understandable by mediocre developers.

There's a secret third option: The organization could just hire good devs.

> There's a secret third option: The organization could just hire good devs.

That's rarely up to the individual developer to decide. If you cook a complex bowl of abstraction soup, knowing that mediocre developers will maintain it after you, that's on your conscience.

The evaluation objective for those medicore devs should be to „get up to speed” or the company will never improve and soon become overrun by competition.

Aha. And should every single company employ above-average developers? How does that work out, mathematically?

It doesn't: The average startup goes bankrupt.

The average corporation doesn't go bankrupt, so you moved the goalpost from "corporation" to "startup". Ok, sure. So, in your view, a developer who leaves behind over-architected complexity to "mediocre" developers is a surefire recipe for going bankrupt... and this was supposed to be in defense of overarchitecting complex codebases? To me it sounds like going bankrupt is bad, so we as developers should strive to prevent our employers from going bankrupt, no? So if you work for a startup that you know is going to hire mediocre developers after you, surely you should strive to leave behind the kind of codebase that doesn't bankrupt the company after you leave?

> The average corporation doesn't go bankrupt, so you moved the goalpost from "corporation" to "startup".

For a lot of corporations, making the jump to software is effectively starting a new company within the company.

> To me it sounds like going bankrupt is bad, so we as developers should strive to prevent our employers from going bankrupt, no?

Bad hires tank companies.

> So if you work for a startup that you know is going to hire mediocre developers after you, surely you should strive to leave behind the kind of codebase that doesn't bankrupt the company after you leave?

That's a red flag right here. It means sell your RSU as soon as you can.

> Bad hires tank companies.

We weren't talking about bad hires, we were talking about mediocre hires. It seems like you expect all companies to higher above-average developers, even though that is mathematically impossible.

> It seems like you expect all companies to higher above-average developers, even though that is mathematically impossible.

No, but that's what I expect from the companies that will succeed.

I dont know a corporation in IT that doesnt have evaluation programs. All management expects you to get better over time.

So using the opportunity to learn from a better dev is a great objective that positively will impact not only you but also the company you work for.

On the other hand if developers stagnate and dont improve -> this is a red flag for company growth. And each corporation wants to grow. Such dev is just a bad hire and will tank the company.

Of course developers should learn and improve. Nobody is arguing otherwise. Yes, people can improve, that doesn't change the fact that the average company employs average developers. If your company hires average developers, then you need to maintain your codebase complexity at a level that is manageable by average developers. All this talk about "bad hires" and such is really missing the mark here.

IMHO If the company hired you for your superiour knowledge and expects you to deliver. You should deliver. Its really not your problem they opened hiring for someone out of their league. Even worse if managers agree to your improvement plan.

Dont you think that someone before or after hiring of a real expert dev should check whether you really need that ?

They can always fire someone for being „too good” or like you say „decreasing own standards”.

Thankfully those experts sooner or later leave those medicore companies but they are not responsible for the mess that was left - its always the management that did not create clear expectations towards hires…

There is no code in existence that will look obvious to $outsourced_bodyshop_ressource_04434.

> that's easily understood by others reading it?

The problem in these discussions always comes back to "others" aren't a monolithic entity. Different people find different things to be readable vs not. Different people will even use the exact same phrases (e.g. "as concise as possible without being opaque!") but still mean different things due to having different interpretations of key words in those phrases.

IME, writing code as concise as possible (semantically and syntactically) is almost always the best route. I don't believe superfluous assignments, parenthesis, braces, visibility modifiers or comments make things more easily understood by others. In time, experience and mastery of the language will reveal superfluous code as something that does the opposite as well as much cleverness as mere utilization of the language or abstraction.

That's the key...in time.

In time doesn't help when the majority of your devs are junior which is a common case in large internal dev shops.

How will they learn to better express logic or master the language without experience?

They won’t. They’ll be mentoring other juniors and then onto management long before then.

I think this blog post is highly relevant https://daedtech.com/how-developers-stop-learning-rise-of-th...

Strongly disagree. Working on codevase that was written by "short is better" people was harder and I hated it.

I don't care for your saved strokes. Make it apparent.

From a syntax perspective, I would argue the grammar of a language does make it apparent.

You're generally not supposed to think about grammar rules when you read or write a language you know (code or prose)

Your omission of a period is ironic.

He is doing exactly what he says; that isn't irony in any sense of the word. You could call it emblematic, but not ironic.

You're making my point: the period being there or not does not matter, what matters is that you were able to parse my sentence and understand it without issue, and without needing to think about its grammar, thanks to the pattern-matching abilities of your brain.

Reply on news.ycombinator.com