6 ms·

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 enthrall

by ser0 10y ago

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.

gravity13 10y ago
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.
- pugworthy 10y ago
  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.
  - jmcomets 10y ago
    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)
    - graton 10y ago
      Or: validated_items = [x for x in items if is_validated(x)]
      - im3w1l 10y ago
        I prefer the other one, because then I don't have to consider whether there is an outer variable 'x' that is being clobbered.
        Singletoned 10y ago
        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).
        aidos 10y ago
        In python 3, x is locally scoped to the comprehension :-)
    - brobinson 10y ago
      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?)
      - Singletoned 10y ago
        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.
        mfontani 10y ago
        my @validated = grep { is_validated($_) } @items; I'd argue the Perl version is clearer... assuming you know its syntax, that is.
  - TeMPOraL 10y ago
    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.
TallGuyShort 10y ago
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."
- AstralStorm 10y ago
  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.
- TeMPOraL 10y ago
  And in my experience, like most insults, this usually says more about the person saying it than about your code.
ryandrake 10y ago
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 https://en.wikipedia.org/wiki/A_Deepness_in_the_Sky
yomly 10y ago
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.
myFathersFace 10y ago
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
lacampbell 10y ago
> 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?
TeMPOraL 10y ago
> 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.
- colefichter 10y ago
  > 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.
userbinator 10y ago
The counterargument: http://www.linusakesson.net/programming/kernighans-lever/ 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.

by ser0 10y ago

gravity13 10y ago

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.

pugworthy 10y ago
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.
- jmcomets 10y ago
  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)
  - graton 10y ago
    Or: validated_items = [x for x in items if is_validated(x)]
    - im3w1l 10y ago
      I prefer the other one, because then I don't have to consider whether there is an outer variable 'x' that is being clobbered.
      - Singletoned 10y ago
        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).
      - aidos 10y ago
        In python 3, x is locally scoped to the comprehension :-)
  - brobinson 10y ago
    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?)
    - Singletoned 10y ago
      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.
      - mfontani 10y ago
        my @validated = grep { is_validated($_) } @items; I'd argue the Perl version is clearer... assuming you know its syntax, that is.
- TeMPOraL 10y ago
  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.

TallGuyShort 10y ago

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

AstralStorm 10y ago
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.
TeMPOraL 10y ago
And in my experience, like most insults, this usually says more about the person saying it than about your code.

ryandrake 10y ago

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 https://en.wikipedia.org/wiki/A_Deepness_in_the_Sky

yomly 10y ago

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.

myFathersFace 10y ago

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

lacampbell 10y ago

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

TeMPOraL 10y ago

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

colefichter 10y ago
> 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.

userbinator 10y ago

The counterargument: http://www.linusakesson.net/programming/kernighans-lever/ 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.