10 ms·

When I advise people to write simpler code I do mean "not clever." Nor do I mean "insightful." In fact, please make it so obvious that in reading it I don't gai

When I advise people to write simpler code I do mean "not clever." Nor do I mean "insightful." In fact, please make it so obvious that in reading it I don't gain/need/curse/applaud any insights. Make it simple enough that a brand new completely green junior member of the team immediately understands it on first reading. And if you can't make the code completely obvious (e.g. the sorting example), just add a comment. A simple one. None of this is about the creator's cleverness or deep understanding or speed or what tooling can do. It's not about the creator or the machine at all. Simple code is about clarity for all the people who will read and (hopefully not) debug it later.

valenterry 5y ago
> Make it simple enough that a brand new completely green junior member of the team immediately understands it on first reading. That can be a goal, but it's not necessarily the best one. We could of course write code so that it is most easily understood by someone who never programmed before. But that then reduces productivity for everyone with lots of experience and familiarity with that project/style/code. Sometimes you can write code that achieves both goals, but often you cannot and in that case the "simpler" version is not always the best.
- xupybd 5y ago
  If we could make our domain specific code understandable to non coders we would have an easier time working with domain experts. That said it's near impossible to do that.
  - valenterry 5y ago
    The mistake lies in the assumption that technical details are not part of the domain - but they are. Sure, in some languages like C you cannot properly separate irrelevant technical details from the domain specific code. But for the more advanced programming languages that is certainly possible. The problem is just that things like the possibilities of errors, eventual consistency, concurrency and so on are relevant for the business domain as well. You simply cannot abstract over them in general. For domain experts who can actually deal with these issues as well, you can pick a language like Scala or Clojure which excel at creating embedded DSLs and then have the domain exports use them.
    - xupybd 5y ago
      Excellent insight.
  - bidirectional 5y ago
    Jane Street does this, traders contribute to code reviews by developers. Though at Jane Street a trader probably has a STEM degree from MIT.
userbinator 5y ago
Make it simple enough that a brand new completely green junior member of the team immediately understands it on first reading. This is why the software industry continues to decline: it's self-inflicted dumbing-down. I really don't understand where this rampant support for antiintellectualism comes from in the software industry, besides managers who want to make employees easily replaceable "cogs in the machine"; and dread what the world would look like if everyone was encouraged to do the same in other (natural) languages.
- jeffreygoesto 5y ago
  I don't think it is black and white. Disentangling a heavily optimized "clever" codebase took me four weeks once. Refactoring did not only make it more understandable but also faster. Seems like often "clever" is used with those quotes around it and really stand for "(accidentally) complicated". Edit: From the article: 'I’m drawn to this distinction because I feel like our discussions of “clever code” are too constrained.'
  - kenver 5y ago
    This made me think about how we use the term 'over engineered' in our industry. In most industries it seems to be a good thing (i.e. space shuttle). In our industry it's synonymous with bad, unnecessarily complex code. We seem to have a knack of taking positive attributes such as clever, and flipping them!
    - dgb23 5y ago
      It’s not exclusively used for clever code. I think a more common case for the term is to describe a program/system that covers way more ground than it needs to in terms of abstraction, tooling, features, scalability and performance. Example: I handed off a website a year ago that didn’t have any sort of remarkable engineering/usage requirements on the backend side. Internal operations of our client however insisted on deploying it on a kube cluster, so we had to accommodate for that. All they actually needed was maybe some caching, if at all. Mild case, but I think of these types of stories when thinking of “over engineering”.
IncRnd 5y ago
> Make it simple enough that a brand new completely green junior member of the team immediately understands it on first reading. This is fine for writing business logic, but this is not good for domains that require insightful code in order to execute within certain time constraints. Some problems require domain knowledge and expertise, which means that you cannot as easily hire and treat programmers as replaceable commodities of junior level people.
- eru 5y ago
  Do keep in mind that there's a difference between reading and writing code. You might very well need experience and domain-level knowledge to write the code, but often you can still make it readable to beginners. Of course, 'often' doesn't mean always. See eg https://en.wikipedia.org/wiki/Fast_inverse_square_root https://en.wikipedia.org/wiki/Fast_inverse_square_root for an example of code that falls in this gap.
  - xupybd 5y ago
    Yes but this can be harder than writing good documentation along side the code. For example I work with software that automates CAD manufacturing. Knowing what side of the part is side A is hard to communicate. But we have drawings that help explain it all. I've yet to find a way to have this embedded into the code. Asci art comments are as good as I've gotten.
    - eru 5y ago
      Donald Knuth thought about this problem before: https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming (and https://wiki.c2.com/?LiterateProgramming https://wiki.c2.com/?LiterateProgramming)
    - TeMPOraL 5y ago
      > Asci art comments are as good as I've gotten. This is good, and people should use it more. But, to go further than that, I recommend: - Setting an official, designated place for rich documentation related to code. A wiki, or a folder in a repo, or a separate repo - either works, as long as every developer is made aware the thing exists and is important. - Put references to documentation in that place in your code comments. Having done that, you can now put in your comments things like: // Which side is 'A' and which is 'B' is determined by // Some Method. The code below implements this logic. // The exact explanation (with diagrams) of the method can // be found in docs:/Algorithms/Some Method.docx Of course, that documentation storage place needs to be treated as an extension of the code repository - i.e. devs should have the same access rights (both technical and cultural) to it as they have to the codebase, so they can both peruse the documentation and keep it in sync with the code. -- On the ASCII diagrams, it might be worth checking if your specific case allows richer content to be embedded in code comments directly. For example, in the past, I worked in a Java shop, and realized I can embed images in the comments - the IDE I used would parse data URLs (like: "data:image/png;base64,iVBORw...") in one JavaDoc tag (don't remember which) and render the image in the tooltip! I only ever did embed a cat picture like this, because I soon realized not all Java IDEs will display the images - but if your team standardized on tooling that can handle it, it's an easy way to sneak in proper diagrams. It would be great if IDEs came with PlantUML support in code comments - there's a bunch of diagrams I have now that I'd love to embed in the source code, but can't, because nobody else can make their tool handle them automatically. (In general, it's worth investigating team/tooling-specific options you have for quality-of-life enhancements. For example, even though everyone in my current team uses different tooling for C++, they all use the same debugger - the one in Visual Studio. So I started producing Natvis definitions for some of the complex types we use, as well as error codes from proprietary APIs. While not exactly documentation, they remove some type noise and save you from searching for error codes.)
anonytrary 5y ago
A good junior is an expert at writing clever code. I think this desire is squashed out of people once they realize there are many more stakeholders in the code you write than just you. Being clever is often a waste of everyone's time.
hyperpallium2 5y ago
Read over your code, and wherever you meet with a section which you think is particularly fine, strike it out.
- yesenadam 5y ago
  This is a paraphrase of Samuel Johnson's "Read over your compositions and, wherever you meet with a passage which you think is particularly fine, strike it out.” I learnt the truth in this when I spent years writing orchestral music. I think it's very similar to avoiding premature optimization. Each piece would take months, first sketching in the broad features - melody, harmony in a few voices, gradually adding more until I reached what seemed the end, then revising until no improvements came to mind on listening through, and lastly adding the large-scale dynamics, pauses, tempo changes, percussion. I learnt to always write/add just what I heard in my head, to try whatever it occurred to me to try, keep whatever changes sounded better, but never to plan anything. Sometimes, early on, a particularly nice bit would emerge fairly fully formed, of which I was proud, and I'd polish that moment immediately to a near-complete state. But then for months it was fixed, couldn't flex and evolve with the rest of the piece, being already "perfect"—or it was originally, not in its final context—and usually I'd regret it was there, all dead and shiny. They felt like fossilized vanity.
nsoonhui 5y ago
>Make it simple enough that a brand new completely green junior member of the team immediately understands it on first reading. But what if the junior member can't understand OOP, functional programming, has no idea of abstraction and can only produce duplication and duplication of code,should we also try to adjust to that level? I do see the need to keep code simple, but sometimes an additional layer of abstraction and complexity is needed because code maintenance task requires it, junior people most likely can't appreciate it until they are no longer junior.
- panta 5y ago
  Then probably it’s too junior, and not ready to be a contributor to the project. He should be brought up to speed with the basic technologies and tools used. Project quality should not be sacrificed.
- j_wtf_all_taken 5y ago
  > But what if the junior member can't understand OOP, functional programming, has no idea of abstraction and can only produce duplication and duplication of code ... then this person obviously did not pay attention in class and should probably not have been hired.
- ClumsyPilot 5y ago
  "But what if the junior member can't read english and mutiply 5 by 5"
clusmore 5y ago
> Make it simple enough that a brand new completely green junior member of the team immediately understands it on first reading. This is pretty close to Tony Hoare's quote: > There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult. It demands the same skill, devotion, insight, and even inspiration as the discovery of the simple physical laws which underlie the complex phenomena of nature.
Mikhail_Edoshin 5y ago
I'm writing an UTF-8 decoder (just for fun) and there's quite a lot of information to understand even before starting that. And as I started I found that it naturally codes itself into a state machine with 12 byte types, 8 decoding states and 11 moves. If I rewrite my notes to condense them I expect to get maybe 4 screenfuls of comments :) Not complex but not something easily digestible by a completely green junior member perhaps.
bryanrasmussen 5y ago
>In fact, please make it so obvious that in reading it I don't gain/need/curse/applaud any insights. at some point clarity requires succinctness, at some point obviousness becomes stupidity. The above requirement has not actual measurable parts and as such we can never know if we have made things too stupid in our attempt to make our code understandable by all parties. Finally as languages evolve and gain new syntactical structures it means that things come into the language that will not be known by everyone, if you want everything understandable by the least knowledgeable that means that you cannot improve your code base. Your biggest legacy problem becomes the least advanced programmer on your team.
dqpb 5y ago
Weakest Link Oriented Programming

valenterry 5y ago

> Make it simple enough that a brand new completely green junior member of the team immediately understands it on first reading. That can be a goal, but it's not necessarily the best one. We could of course write code so that it is most easily understood by someone who never programmed before. But that then reduces productivity for everyone with lots of experience and familiarity with that project/style/code. Sometimes you can write code that achieves both goals, but often you cannot and in that case the "simpler" version is not always the best.

xupybd 5y ago
If we could make our domain specific code understandable to non coders we would have an easier time working with domain experts. That said it's near impossible to do that.
- valenterry 5y ago
  The mistake lies in the assumption that technical details are not part of the domain - but they are. Sure, in some languages like C you cannot properly separate irrelevant technical details from the domain specific code. But for the more advanced programming languages that is certainly possible. The problem is just that things like the possibilities of errors, eventual consistency, concurrency and so on are relevant for the business domain as well. You simply cannot abstract over them in general. For domain experts who can actually deal with these issues as well, you can pick a language like Scala or Clojure which excel at creating embedded DSLs and then have the domain exports use them.
  - xupybd 5y ago
    Excellent insight.
- bidirectional 5y ago
  Jane Street does this, traders contribute to code reviews by developers. Though at Jane Street a trader probably has a STEM degree from MIT.

userbinator 5y ago

Make it simple enough that a brand new completely green junior member of the team immediately understands it on first reading. This is why the software industry continues to decline: it's self-inflicted dumbing-down. I really don't understand where this rampant support for antiintellectualism comes from in the software industry, besides managers who want to make employees easily replaceable "cogs in the machine"; and dread what the world would look like if everyone was encouraged to do the same in other (natural) languages.

jeffreygoesto 5y ago
I don't think it is black and white. Disentangling a heavily optimized "clever" codebase took me four weeks once. Refactoring did not only make it more understandable but also faster. Seems like often "clever" is used with those quotes around it and really stand for "(accidentally) complicated". Edit: From the article: 'I’m drawn to this distinction because I feel like our discussions of “clever code” are too constrained.'
- kenver 5y ago
  This made me think about how we use the term 'over engineered' in our industry. In most industries it seems to be a good thing (i.e. space shuttle). In our industry it's synonymous with bad, unnecessarily complex code. We seem to have a knack of taking positive attributes such as clever, and flipping them!
  - dgb23 5y ago
    It’s not exclusively used for clever code. I think a more common case for the term is to describe a program/system that covers way more ground than it needs to in terms of abstraction, tooling, features, scalability and performance. Example: I handed off a website a year ago that didn’t have any sort of remarkable engineering/usage requirements on the backend side. Internal operations of our client however insisted on deploying it on a kube cluster, so we had to accommodate for that. All they actually needed was maybe some caching, if at all. Mild case, but I think of these types of stories when thinking of “over engineering”.

IncRnd 5y ago

> Make it simple enough that a brand new completely green junior member of the team immediately understands it on first reading. This is fine for writing business logic, but this is not good for domains that require insightful code in order to execute within certain time constraints. Some problems require domain knowledge and expertise, which means that you cannot as easily hire and treat programmers as replaceable commodities of junior level people.

eru 5y ago
Do keep in mind that there's a difference between reading and writing code. You might very well need experience and domain-level knowledge to write the code, but often you can still make it readable to beginners. Of course, 'often' doesn't mean always. See eg https://en.wikipedia.org/wiki/Fast_inverse_square_root https://en.wikipedia.org/wiki/Fast_inverse_square_root for an example of code that falls in this gap.
- xupybd 5y ago
  Yes but this can be harder than writing good documentation along side the code. For example I work with software that automates CAD manufacturing. Knowing what side of the part is side A is hard to communicate. But we have drawings that help explain it all. I've yet to find a way to have this embedded into the code. Asci art comments are as good as I've gotten.
  - eru 5y ago
    Donald Knuth thought about this problem before: https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming (and https://wiki.c2.com/?LiterateProgramming https://wiki.c2.com/?LiterateProgramming)
  - TeMPOraL 5y ago
    > Asci art comments are as good as I've gotten. This is good, and people should use it more. But, to go further than that, I recommend: - Setting an official, designated place for rich documentation related to code. A wiki, or a folder in a repo, or a separate repo - either works, as long as every developer is made aware the thing exists and is important. - Put references to documentation in that place in your code comments. Having done that, you can now put in your comments things like: // Which side is 'A' and which is 'B' is determined by // Some Method. The code below implements this logic. // The exact explanation (with diagrams) of the method can // be found in docs:/Algorithms/Some Method.docx Of course, that documentation storage place needs to be treated as an extension of the code repository - i.e. devs should have the same access rights (both technical and cultural) to it as they have to the codebase, so they can both peruse the documentation and keep it in sync with the code. -- On the ASCII diagrams, it might be worth checking if your specific case allows richer content to be embedded in code comments directly. For example, in the past, I worked in a Java shop, and realized I can embed images in the comments - the IDE I used would parse data URLs (like: "data:image/png;base64,iVBORw...") in one JavaDoc tag (don't remember which) and render the image in the tooltip! I only ever did embed a cat picture like this, because I soon realized not all Java IDEs will display the images - but if your team standardized on tooling that can handle it, it's an easy way to sneak in proper diagrams. It would be great if IDEs came with PlantUML support in code comments - there's a bunch of diagrams I have now that I'd love to embed in the source code, but can't, because nobody else can make their tool handle them automatically. (In general, it's worth investigating team/tooling-specific options you have for quality-of-life enhancements. For example, even though everyone in my current team uses different tooling for C++, they all use the same debugger - the one in Visual Studio. So I started producing Natvis definitions for some of the complex types we use, as well as error codes from proprietary APIs. While not exactly documentation, they remove some type noise and save you from searching for error codes.)

anonytrary 5y ago

A good junior is an expert at writing clever code. I think this desire is squashed out of people once they realize there are many more stakeholders in the code you write than just you. Being clever is often a waste of everyone's time.

hyperpallium2 5y ago

Read over your code, and wherever you meet with a section which you think is particularly fine, strike it out.

yesenadam 5y ago
This is a paraphrase of Samuel Johnson's "Read over your compositions and, wherever you meet with a passage which you think is particularly fine, strike it out.” I learnt the truth in this when I spent years writing orchestral music. I think it's very similar to avoiding premature optimization. Each piece would take months, first sketching in the broad features - melody, harmony in a few voices, gradually adding more until I reached what seemed the end, then revising until no improvements came to mind on listening through, and lastly adding the large-scale dynamics, pauses, tempo changes, percussion. I learnt to always write/add just what I heard in my head, to try whatever it occurred to me to try, keep whatever changes sounded better, but never to plan anything. Sometimes, early on, a particularly nice bit would emerge fairly fully formed, of which I was proud, and I'd polish that moment immediately to a near-complete state. But then for months it was fixed, couldn't flex and evolve with the rest of the piece, being already "perfect"—or it was originally, not in its final context—and usually I'd regret it was there, all dead and shiny. They felt like fossilized vanity.

nsoonhui 5y ago

>Make it simple enough that a brand new completely green junior member of the team immediately understands it on first reading. But what if the junior member can't understand OOP, functional programming, has no idea of abstraction and can only produce duplication and duplication of code,should we also try to adjust to that level? I do see the need to keep code simple, but sometimes an additional layer of abstraction and complexity is needed because code maintenance task requires it, junior people most likely can't appreciate it until they are no longer junior.

panta 5y ago
Then probably it’s too junior, and not ready to be a contributor to the project. He should be brought up to speed with the basic technologies and tools used. Project quality should not be sacrificed.
j_wtf_all_taken 5y ago
> But what if the junior member can't understand OOP, functional programming, has no idea of abstraction and can only produce duplication and duplication of code ... then this person obviously did not pay attention in class and should probably not have been hired.
ClumsyPilot 5y ago
"But what if the junior member can't read english and mutiply 5 by 5"

clusmore 5y ago

> Make it simple enough that a brand new completely green junior member of the team immediately understands it on first reading. This is pretty close to Tony Hoare's quote: > There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult. It demands the same skill, devotion, insight, and even inspiration as the discovery of the simple physical laws which underlie the complex phenomena of nature.

Mikhail_Edoshin 5y ago

I'm writing an UTF-8 decoder (just for fun) and there's quite a lot of information to understand even before starting that. And as I started I found that it naturally codes itself into a state machine with 12 byte types, 8 decoding states and 11 moves. If I rewrite my notes to condense them I expect to get maybe 4 screenfuls of comments :) Not complex but not something easily digestible by a completely green junior member perhaps.

bryanrasmussen 5y ago

>In fact, please make it so obvious that in reading it I don't gain/need/curse/applaud any insights. at some point clarity requires succinctness, at some point obviousness becomes stupidity. The above requirement has not actual measurable parts and as such we can never know if we have made things too stupid in our attempt to make our code understandable by all parties. Finally as languages evolve and gain new syntactical structures it means that things come into the language that will not be known by everyone, if you want everything understandable by the least knowledgeable that means that you cannot improve your code base. Your biggest legacy problem becomes the least advanced programmer on your team.

dqpb 5y ago

Weakest Link Oriented Programming