Hacker News Reader

Comment by ser0 | Hacker News Reader

Sometimes I find myself writing in reviews for less experienced developers the comment: this is clever but not clear.

I think as developers we get too enthralled in the problem solving and forget that in the long run we are more like journalists noting business rules at a snap-shot in time, which a future maintainer of our software must act as historian/archaeologist in order to understand.

What's funny is that often our future selves is the maintainer of our software. However, as we lament choices in the past, we continue to write intricate code in the name of elegance/conciseness.

These days I'm pretty pleased when I can say a piece of code utilises only syntax and statements taught in an introductory programming course.

View on HN

> These days I'm pretty pleased when I can say a piece of code utilises only syntax and statements taught in an introductory programming course.

This sounds like optimizing for read-time. This is subtly wrong, IMO. You should be optimizing for comprehension-time, i.e. how much time it takes for the next person to wrap their head around the (piece of) codebase. Often, you can have significant gains in code comprehensibility if you raise the minimum level of competence for the next person.

Or in other words: programming is a profession. You're not supposed to stay at the level of introductory programming course. You're supposed to be continuously learning and getting better. That applies to the next person too, so if your "clever" but clean abstraction is too hard for them, they're supposed to suck it up and open a book. They can afford the book, it's not like programmers are underpaid.

> programming is a profession

We like to think that, but it's not really true. Professions tend to include some kind of guild, union, or association to represent the interests of practitioners and require/evaluate formal ongoing education (reading blogs doesn't count). There are typically barriers to entry. There's usually a licensing process as well as a disciplinary process that may revoke one's right to practice.

Programming has none of those things.

Offtopic, but whenever I read someone referring to a programmer having to be an archeologist, I can't help but think about Vernor Vinge's _A Deepness In The Sky_[1], where there was so much legacy code that there was a need for "programmer archaeologists" to dig through it all looking for something suitable for whatever current problem needed to be solved.

1: https://en.wikipedia.org/wiki/A_Deepness_in_the_Sky

Everything is unclear until you become used to it, though. I mean, used to it, as in, you can read it without stepping yourself through the steps manually. And to a novice programmer, pretty much everything they come up against represents this.

Turning five lines into one line with a reduce function sounds like a normal thing to do for experienced programmers, but to a beginner, they'll think you're a genius for pointing it out to them. So it's not surprising when they try to apply their genius and come up with something clever, too.

You'll also find that some experienced programmers specifically turn 1 line into 5. It's the beginner that tries to create the 1 liner because they think it's genius.

One-liners are bad if they are obscure and experienced programmers know that. However I wouldn't go as far as say that experienced programmers don't use one-liners at all. As usual in programming, it's all about balancing clarity/conciseness.

For example, I find this much clearer as a one-liner (Python):

    validated_items = filter(is_validated, items)

rather than

    validated_items = []
    for item in items:
        if is_validated(item):
            validated_items.append(item)

Or:

validated_items = [x for x in items if is_validated(x)]

I prefer the other one, because then I don't have to consider whether there is an outer variable 'x' that is being clobbered.

Most linters would have suggested correcting it to:

validated_items = [_ for _ in items if is_validated(x)]

where _ is used as a safe variable that can always be clobbered. (Though this does also clash with its use as a gettext function for strings).

In python 3, x is locally scoped to the comprehension :-)

Ruby version is a pretty clear one-liner:

    validated_items = items.select { |item| is_validated?(item) }

Though I'd expect a check for validation to be an instance method, so it'd probably look like:

    validated_items = items.select(&:validated?)

I don't find either of the Ruby versions clear at all. Both contain unnecessary syntax.

Ruby seems to be going down the same path as Perl in trying to make all possible combinations of characters valid programs.

    my @validated = grep { is_validated($_) } @items;

I'd argue the Perl version is clearer... assuming you know its syntax, that is.

Even if it's not an instance method you can write the first as

  validated_items = items.select(&method(:is_validated?))

(Typed on my phone but I'm pretty sure that's the right syntax)

It is! I'd forgotten about Kernel.method. Thanks!

"filter" has to be the worst library name. I have no clue what it's doing unless I read the documentation. On the other hand "append" feels like a much more conventional and comprehensible name.

>"filter" has to be the worst library name. I have no clue what it's doing unless I read the documentation

It, I dunno, FILTERS a collection keeping only certain elements (those that match the filter)? What else would it possibly do? Besides a standard CS term, it's also a concept from real life...

To me the name is crystal clear.

A filter creates two sets, one with the thing, and the other without. When you filter something, you might be interested in what is filtered in, or what is filtered out.

Ponder for a second the phrases, "filtered water", "coffee filter", "camera filter", etc. In all of those cases, you are interested in the set without the filtered thing, not with.

Compare this to "select" which is a much clearer name.

>Ponder for a second the phrases, "filtered water", "coffee filter", "camera filter", etc. In all of those cases, you are interested in the set without the filtered thing, not with.

Filtered is akin to "cleansed" (it refers to the "main body") not akin to "picked out" (which would have applied to the undesirable elements.

It's actually the water (or the light, in the case of camera filter) that's filtered (hence the name "filtered water" and not "filtered dust and detritus").

The other stuff is not what's being filtered -- just what's "filtered out".

I agree with you that `filter` is less explicit than something like `copy_if` (C++).

Does it return elements matching the predicate or not matching it? I struggled with this for a while in CS.

After learning different programming languages and getting some field experience I noticed that the `filter` pattern is pretty common in the programming world. It's one of those pervasive functional patterns that are so practical that they were included at some point in imperative languages.

Experienced programmers will strive to write the code in a way that best communicates its intent and scope of effect. Sometimes that involves turning 5 lines into 1, sometimes the other way around.

Honestly, when I see people complaining that the code is "too clever", my default reaction is: programming is a profession, you're supposed to learn new stuff and get better, not complain that something is beyond what they taught you in Programming 101.

One of the most valuable things I got from university was my professor's saying, "When somebody tells you your code is clever or interesting, that's an insult."

Unless it is an interesting algorithm or contains well documented optimizations. (with reasons for them, preferably grounded in measurements)

Rules of thumb only go as far as your thumb. Sometimes a clever abstraction makes everything clean and obvious, as opposed to a dumb abstraction.

And in my experience, like most insults, this usually says more about the person saying it than about your code.

This, I have very rapidly found myself writing code which only very occasionally uses something fancy and otherwise generally opt for the most plain, boring and straightforward code. Internally, I describe the code as idiot proof.

Putting it more kindly, my litmus test for my own code is "will a 5 year old understand this?". In the many instances where I have since returned to my code to maintain it, I am often grateful for every less minute I spend reunderstanding all my own code.

To use your analogy of engineers being like authors, as a teenager, I would often find every excuse to use some exciting sentence structure or long word - doing so made me feel authoritative and clever. But once reading more, you find that some of the most powerful, and clever, writing is concise and plain.

Be Hemingway, not Nabokov.*

*not to say Nabokov wasn't clever.

The counterargument:

http://www.linusakesson.net/programming/kernighans-lever/

It's worth looking at all the other pages on his site both before and after reading that article. Do you think he would've be able to accomplish all that if he "utilises only syntax and statements taught in an introductory programming course"?

What's funny is that often our future selves is the maintainer of our software.

IMHO if you find it difficult to understand code you wrote years ago, you have not actually improved. In fact, if this was any other skill (natural language, maths, etc.), the inability to do what you used to be able to, would be considered none other than a regression.

> These days I'm pretty pleased when I can say a piece of code utilises only syntax and statements taught in an introductory programming course.

Why?

Shouldn't you be building up from that towards the problem you are actually trying to solve? Is it reasonable to expect someone to understand every single bit of code in a large project without reading documentation of the components below it?

I appreciate that you are one that can recognize the beauty of originalism. There is something to be said for first principles, and something that we can all learn by doing what we can to abide by the idea that every piece of knowledge that is taught is done so not only by design but with our best interests at heart.

Needless to say, I want to share a little piece of code I wrote that uses first principles in terms of data structures, and is perhaps my magnum opus. It's not sophisticated, but it does work, and it works because I refined it again, and again, and again. And I think that is the gist of this article. Refinement reduces cognitive load more than any other technique (in my perhaps not so humble opinion..haha).

If you'd like to look at my code, please go to github.com and search for justSomeGuyWhoLearnedToCode. The Trust repository has the code that I wrote as a trust fund for some very good friends of mine, but as I cannot seem to get in touch with them, I am sharing it with the world.

It requires some compiling, but man when that thing cooks, it cooks with gas, mi amicis.

I'm working on a sequel using NLP that I am going to add to the repo on Monday, so keep your eyes and ears open for that too.

And if you fret about how well you write code, just remember, the mere fact that you are writing code speaks to your tenacity as a problems solver and your participation in the process is well being commendable if and when you step back from your "self" and look at all of the progress you have made. Don't write functional code, or perfectly simplisitic code, or code that sparkles when you're done, instead write code that reads like poetry. Write your life into it. Write your heart into it. Write your soul into that logic, because that code is forever. It is your statement to the world that you are an artist, and your art is the marriage of logic and beauty, of solutions to probelsm so large we harness the power that binds the atoms together, and have machines building machines building machines to lithograph the transistors that can fit (like so many angels) a thousand on the head a pin.

Bless serendipity, and bless the dudes at Bell labs, Alan Turing, Charles Babbage, Rosy the fucking Riveter, and everyone else who made the computer possible. We are on the cusp of a new age, and quantum computers will revolutionize (a word I almost never use) the way we make medicine, and the way to outer space then become much, much easier and the world that we live in will become much happier as we share our progress with the less fortunate. Get ready, folks, because the whole shmear is waiting just around the next bend.

And for you "older" fogies, check out the Win 10 default wallpaper, and think of the line: "You are in a room, and you see a window".

Peace is God

Reply on news.ycombinator.com