7 ms·

I like how this article explains that "clean" must be "readable for humans". However, the concerns raised are only superficial. It's much more important to get

I like how this article explains that "clean" must be "readable for humans". However, the concerns raised are only superficial. It's much more important to get the larger scale structure right. I recommend drawing diagrams and explaining the architecture to humans. Then again, I'm not saying overdo it, because some things are hard to draw, some are hard to explain. In the end, it's important to get a complete understanding of a certain module, and the code should then be relatively easy to write. I have learned to take a step back when I find myself having a hard time to get the code "clean". Often I put that thing to rest if possible, maybe for days, months, or even years. There could be a simple solution that solves 80% of the problem, and that can ease the pressure coming from the stakeholders. If it kind-of-works and can be produced in a short time, that is much better than going down a rabbit hole for months, coming out at the other side (probably burnt out) with a solution you can't deploy because it's too complicated.

Karellen 4y ago
> Show me your flowcharts (code) and conceal your tables (data structures), and I shall continue to be mystified. Show me your tables (data structures), and I won’t usually need your flowcharts (code); they’ll be obvious. -- Fred Brooks, The Mythical Man-Month, 1975 > a computer language is not just a way of getting a computer to perform operations but rather that it is a novel formal medium for expressing ideas about methodology. Thus, programs must be written for people to read and only incidentally for machines to execute. -- Abelson & Sussman, The Structure and Interpretation of Computer Programs, 1984
- sidlls 4y ago
  The first quote is an over-simplification that often does not hold in practice: one usually needs both. The exceptions are mostly trivial programs.
  - gilch 4y ago
    It's the reason Excel is easier to learn than Java.
  - Karellen 4y ago
    Most pithy aphorisms are over-simplifications. "Want cleaner code? Use the rule of six" probably is too. But they can still give you a useful way of thinking about a problem that you might have forgotten to consider, and can give you a Platonic ideal as a useful guiding star even if you know you'll never reach that sort of purity in the real world.
  - lelanthran 4y ago
    > The first quote is an over-simplification that often does not hold in practice: one usually needs both. The exceptions are mostly trivial programs. Depends, but not on the complexity of the application. Given the data design of even the most complex set of applications that all interact with the same data, you can almost always predict what business logic is supported by the set of applications. Given all the code for the same set of applications, and you'd find it difficult, if not impossible, to predict what the business logic is across all the applications.
    - sidlls 4y ago
      > Given the data design of even the most complex set of applications that all interact with the same data, you can almost always predict what business logic is supported by the set of applications. How so? Every table, file, or other data structure added increases the possible of uses with factorial complexity (think of, e.g., the traveling salesman or other graph/network problems). Without seeing something else, e.g., the code, a flowchart, or other diagrams it is impossible to predict what the program actually does. One can guess at bits and pieces of it, but not more. It’s like saying that given a table of numbers one can predict exactly what functions produced them.
      - lelanthran 4y ago
        > How so? Every table, file, or other data structure added increases the possible of uses with factorial complexity (think of, e.g., the traveling salesman or other graph/network problems). Only if they're randomly named. > Without seeing something else, e.g., the code, a flowchart, or other diagrams it is impossible to predict what the program actually does. Seeing a table named "invoices", which has a column named "user_id" that is a foreign key for table "user" doesn't give you at least a few clues about the business logic there? Seriously, I want to see an example (choose an open source project) of a project where the data structures don't give any clue to what the business logic is. Once you go looking for that example, you'll see why the data structures are more revealing than looking at the code.
        4y ago
- Shorel 4y ago
  Well, dealing with graph algorithms, none of them are obvious from the representation. Which is usually a matrix. In fact, Gauss Jordan is also not obvious, just seeing a matrix.
29athrowaway 4y ago
What is easier to read: a) 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 b) 20 If all the code in your project was written like a), how would you feel? Does it make your job easier or harder? I'll tell you how most people feel when they read code that looks like a): - The author didn't care about other maintainers. - The author is selfish and does not have empathy for others. - The author ruined my fucking day. - Team members are competing by sabotaging each other's productivity. - If I clean this, by the time I am done, the author would have pushed 10 more commits that look exactly like this and eventually become my boss. - The author is wasting everyone's time. - The author is forcing others to volunteer to clean up after them. - Why does management tolerate code following the a) style? A simple intervention would make it go away and my job would be so much better. - It's sad that everyone is too busy looking at Jira and nobody cares about the actual fucking product. - This is slowing everyone down and I have stuff to do. - The code is error prone, one day I'll break it. - Why should I contribute quality code if low quality is acceptable? As you can see, it objectively fucking sucks. It's draining, demoralizing to read, it's frustrating, it wastes people's time, it gives people the perception that nobody fucking cares and the code is everyone's toilet with no trip lever. And while it's "superficial", it's the surface that all engineers interact with. If I spread superglue over the surface of your kitchen counter and every dish and utensil in your kitchen every day around lunch time, that problem will also be "superficial", but it will ruin your life. So, the conclusion is: Just fucking write clean code. Shitty code ruins the morale of people who care, who are the people that want to build great things not the ones cashing a paycheck and resting and vesting. You are not a full-time architect, you are not in business development/marketing/finance or whatever, you are in the fucking engineering department. Your contribution to the business are your deliverables. The "superficial" stuff you talk about is your job. Do it. "Ah ah ah, you didn't say the magic word!! ah ah ah!" Don't be the fucking Dennis Nedry of the team. Format your code, make it readable by your team and your future self. Do you want everyone to love you? Write code like this: https://norvig.com/spell-correct.html https://norvig.com/spell-correct.html
- jstimpfle 4y ago
  What the f* is wrong with you?
overgard 4y ago
I tend to find that top-down designs usually end up clunky. In my experience, bottom up designs (starting with specific things and creating new abstractions as they're needed) tends to create simpler and more obvious designs. You also don't waste time on hypotheticals, since every line you write has a purpose. This blog post really nails it: https://caseymuratori.com/blog_0015 https://caseymuratori.com/blog_0015 In that context, I don't think this is superficial at all. If your code is hard to read, I suspect your design is hard to read too. Sure, for super important architecture decisions you have to make a few top-down (spatial partitioning structures, database decisions, network architecture, etc.), but I think it's generally better to late-bind on those decisions if you can.
- jstimpfle 4y ago
  It is superficial. No amount of trying to pretty up the code can fix underlying design deficiencies. That's what I said, so we're not even disagreeing here :) I know the semantic compression post, and I don't think it makes a point for bottom-up design. I find top-down and bottom-up to be quite misleading anyway. Someone told me, they don't like to think of things at the "top" and the "bottom". It's data transformations, maybe more like "left to right". If you design bottom-up, you end up with lots of artifacts you never needed (and likely still missing the ones you can make use of). If you design top-down, you end up with lots of code you don't need. (this is where semantic compression comes in, in my understanding). I suspect that if you like to think bottom-up, maybe that's because you like it more at the bottom (you are a low-level type of guy, or like to make libraries). If you like to think top-down, maybe you like it more at the top. I like the semantic compression term because it reduces the act of design to the essentials, without introducing fluff terms or opinions. I find myself doing this compression no matter what kind of code I'm writing.
  - overgard 4y ago
    Well, you might know of that blog post, but might want to reread it, I don't think it says what you think it says. The example he steps through is very clearly bottom up. He even outright says it: > This is a very bottom-up programming methodology, a pseudo-variant of which has recently gained the monicker “refactoring”, even though that is a ridiculous term for a number of reasons that are not worth belaboring at the moment. ... > Like a good compressor, I don’t reuse anything until I have at least two instances of it occurring. Many programmers don’t understand how important this is, and try to write “reusable” code right off the bat, but that is probably one of the biggest mistakes you can make. My mantra is, “make your code usable before you try to make it reusable”. > I always begin by just typing out exactly what I want to happen in each specific case, without any regard to “correctness” or “abstraction” or any other buzzword, and I get that working. Then, when I find myself doing the same thing a second time somewhere else, that is when I pull out the reusable portion and share it, effectively “compressing” the code. I like “compress” better as an analogy, because it means something useful, as opposed to the often-used “abstracting”, which doesn’t really imply anything useful. Who cares if code is abstract? And I don't understand how you'd end up with artifacts you don't need with that approach. Do you mean intermediate steps you refactor? In that case I suppose so, but that's an important part of the process, not a waste. You're never going to get the initial design exactly perfect so you need to iterate on it.

Karellen 4y ago

> Show me your flowcharts (code) and conceal your tables (data structures), and I shall continue to be mystified. Show me your tables (data structures), and I won’t usually need your flowcharts (code); they’ll be obvious. -- Fred Brooks, The Mythical Man-Month, 1975 > a computer language is not just a way of getting a computer to perform operations but rather that it is a novel formal medium for expressing ideas about methodology. Thus, programs must be written for people to read and only incidentally for machines to execute. -- Abelson & Sussman, The Structure and Interpretation of Computer Programs, 1984

sidlls 4y ago
The first quote is an over-simplification that often does not hold in practice: one usually needs both. The exceptions are mostly trivial programs.
- gilch 4y ago
  It's the reason Excel is easier to learn than Java.
- Karellen 4y ago
  Most pithy aphorisms are over-simplifications. "Want cleaner code? Use the rule of six" probably is too. But they can still give you a useful way of thinking about a problem that you might have forgotten to consider, and can give you a Platonic ideal as a useful guiding star even if you know you'll never reach that sort of purity in the real world.
- lelanthran 4y ago
  > The first quote is an over-simplification that often does not hold in practice: one usually needs both. The exceptions are mostly trivial programs. Depends, but not on the complexity of the application. Given the data design of even the most complex set of applications that all interact with the same data, you can almost always predict what business logic is supported by the set of applications. Given all the code for the same set of applications, and you'd find it difficult, if not impossible, to predict what the business logic is across all the applications.
  - sidlls 4y ago
    > Given the data design of even the most complex set of applications that all interact with the same data, you can almost always predict what business logic is supported by the set of applications. How so? Every table, file, or other data structure added increases the possible of uses with factorial complexity (think of, e.g., the traveling salesman or other graph/network problems). Without seeing something else, e.g., the code, a flowchart, or other diagrams it is impossible to predict what the program actually does. One can guess at bits and pieces of it, but not more. It’s like saying that given a table of numbers one can predict exactly what functions produced them.
    - lelanthran 4y ago
      > How so? Every table, file, or other data structure added increases the possible of uses with factorial complexity (think of, e.g., the traveling salesman or other graph/network problems). Only if they're randomly named. > Without seeing something else, e.g., the code, a flowchart, or other diagrams it is impossible to predict what the program actually does. Seeing a table named "invoices", which has a column named "user_id" that is a foreign key for table "user" doesn't give you at least a few clues about the business logic there? Seriously, I want to see an example (choose an open source project) of a project where the data structures don't give any clue to what the business logic is. Once you go looking for that example, you'll see why the data structures are more revealing than looking at the code.
      - 4y ago
Shorel 4y ago
Well, dealing with graph algorithms, none of them are obvious from the representation. Which is usually a matrix. In fact, Gauss Jordan is also not obvious, just seeing a matrix.

29athrowaway 4y ago

What is easier to read: a) 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 b) 20 If all the code in your project was written like a), how would you feel? Does it make your job easier or harder? I'll tell you how most people feel when they read code that looks like a): - The author didn't care about other maintainers. - The author is selfish and does not have empathy for others. - The author ruined my fucking day. - Team members are competing by sabotaging each other's productivity. - If I clean this, by the time I am done, the author would have pushed 10 more commits that look exactly like this and eventually become my boss. - The author is wasting everyone's time. - The author is forcing others to volunteer to clean up after them. - Why does management tolerate code following the a) style? A simple intervention would make it go away and my job would be so much better. - It's sad that everyone is too busy looking at Jira and nobody cares about the actual fucking product. - This is slowing everyone down and I have stuff to do. - The code is error prone, one day I'll break it. - Why should I contribute quality code if low quality is acceptable? As you can see, it objectively fucking sucks. It's draining, demoralizing to read, it's frustrating, it wastes people's time, it gives people the perception that nobody fucking cares and the code is everyone's toilet with no trip lever. And while it's "superficial", it's the surface that all engineers interact with. If I spread superglue over the surface of your kitchen counter and every dish and utensil in your kitchen every day around lunch time, that problem will also be "superficial", but it will ruin your life. So, the conclusion is: Just fucking write clean code. Shitty code ruins the morale of people who care, who are the people that want to build great things not the ones cashing a paycheck and resting and vesting. You are not a full-time architect, you are not in business development/marketing/finance or whatever, you are in the fucking engineering department. Your contribution to the business are your deliverables. The "superficial" stuff you talk about is your job. Do it. "Ah ah ah, you didn't say the magic word!! ah ah ah!" Don't be the fucking Dennis Nedry of the team. Format your code, make it readable by your team and your future self. Do you want everyone to love you? Write code like this: https://norvig.com/spell-correct.html https://norvig.com/spell-correct.html

jstimpfle 4y ago
What the f* is wrong with you?

overgard 4y ago

I tend to find that top-down designs usually end up clunky. In my experience, bottom up designs (starting with specific things and creating new abstractions as they're needed) tends to create simpler and more obvious designs. You also don't waste time on hypotheticals, since every line you write has a purpose. This blog post really nails it: https://caseymuratori.com/blog_0015 https://caseymuratori.com/blog_0015 In that context, I don't think this is superficial at all. If your code is hard to read, I suspect your design is hard to read too. Sure, for super important architecture decisions you have to make a few top-down (spatial partitioning structures, database decisions, network architecture, etc.), but I think it's generally better to late-bind on those decisions if you can.

jstimpfle 4y ago
It is superficial. No amount of trying to pretty up the code can fix underlying design deficiencies. That's what I said, so we're not even disagreeing here :) I know the semantic compression post, and I don't think it makes a point for bottom-up design. I find top-down and bottom-up to be quite misleading anyway. Someone told me, they don't like to think of things at the "top" and the "bottom". It's data transformations, maybe more like "left to right". If you design bottom-up, you end up with lots of artifacts you never needed (and likely still missing the ones you can make use of). If you design top-down, you end up with lots of code you don't need. (this is where semantic compression comes in, in my understanding). I suspect that if you like to think bottom-up, maybe that's because you like it more at the bottom (you are a low-level type of guy, or like to make libraries). If you like to think top-down, maybe you like it more at the top. I like the semantic compression term because it reduces the act of design to the essentials, without introducing fluff terms or opinions. I find myself doing this compression no matter what kind of code I'm writing.
- overgard 4y ago
  Well, you might know of that blog post, but might want to reread it, I don't think it says what you think it says. The example he steps through is very clearly bottom up. He even outright says it: > This is a very bottom-up programming methodology, a pseudo-variant of which has recently gained the monicker “refactoring”, even though that is a ridiculous term for a number of reasons that are not worth belaboring at the moment. ... > Like a good compressor, I don’t reuse anything until I have at least two instances of it occurring. Many programmers don’t understand how important this is, and try to write “reusable” code right off the bat, but that is probably one of the biggest mistakes you can make. My mantra is, “make your code usable before you try to make it reusable”. > I always begin by just typing out exactly what I want to happen in each specific case, without any regard to “correctness” or “abstraction” or any other buzzword, and I get that working. Then, when I find myself doing the same thing a second time somewhere else, that is when I pull out the reusable portion and share it, effectively “compressing” the code. I like “compress” better as an analogy, because it means something useful, as opposed to the often-used “abstracting”, which doesn’t really imply anything useful. Who cares if code is abstract? And I don't understand how you'd end up with artifacts you don't need with that approach. Do you mean intermediate steps you refactor? In that case I suppose so, but that's an important part of the process, not a waste. You're never going to get the initial design exactly perfect so you need to iterate on it.