Cognitive load is what matters (minds.md)

Depends on how you define smart. I worked at a place where income was directly tied to the quality of the ML models. Building what people love wouldn't have been the best strategy there.

Only if your goal is to be an entrepreneur. Not everyone chases that goal nor considers success in that fashion.

I’ve been interested in the same topic for a while now and the most difficult part, when explaining the concept to other programmers and defending against it in coding standards/reviews, is how to prove that cognitive load exists.

Cyclomatic complexity seems one indicator, but architectural complexity needs to be clarified. I agree that how much modules expose to each other is one trait, but again, needs clarification. How do you intend to go about this?

Been thinking about custom abstractions (ie those that you build yourself and which do not come from the standard libraries/frameworks) needed to understand code and simply counting them; the higher the number, the worse. But it seems that one needs to find something in cognitive psychology to back up the claim.

This is true and valuable, but it's worth mentioning that some aspect of cognitive load is subjective. The code I write is always lower cognitive load to me than anyone else's code, even if my code has more cyclomatic complexity and code smells, because I've built up years of neural representations dedicated to understanding my favored way of doing things via practice and repetition. And I lack the neural representations needed to quickly understand other people's code if they approach things differently, even if their approach is just better.

This is not to say we should keep practicing our bad habits, but that we should practice good habits (e.g. composition over inheritance) as quickly as possible so the bad habits don't become ingrained in how we mentally process code.

With LLM generated code (and any code really) the interface between components becomes much more important. It needs to be clearly defined so that it can be tested and avoid implicit features that could go away if it were re-generated.

Only when you know for sure the problem can't be coming through from that component can you stop thinking about it and reduce the cognitive load.

> I’d really love to have a discussion on how these heuristics of software development change with the likes of Cursor/LLM cyborg coding in the mix

I would also be interested in reading people’s thoughts about how those heuristics might change in the months and years ahead, as reasoning LLMs get more powerful and as context windows continue to increase. Even if it never becomes possible to offload software development completely to AI, it does seem at least possible that human cognitive load will not be an issue in the same way it is now.

I think this works only up to the point where the language gets too large and starts creating extra cognitive load all by itself. For me, C++ is a good example of a language that has too many bells and whistles, if I have to stop what I'm doing to look up some weird syntax construct, then having all those extra features stops being useful.

Totally agree. I think the biggest and most important things a language designer chooses is what to disallow. For instance, private/package/public etc is one small example of an imposed restriction which makes it easier to reason about changing a large project because if e.g. something is private then you know it's okay and probably easy to refactor. The self-imposed restrictions save you mental effort later. I also love lisps but am a Clojure fan. This is because in Clojure, 90+% of the code is static functions operating on immutable data. That makes it extremely easy to reason about in the large. Those two restrictions are big and impose a lot of structure, but man I can tear around the codebase with a machete because there are so many things that code /can't do/. Also, testing is boneheaded simple because everything is just parameters in to those static functions and assert on the values coming out. I don't have to do some arduous object construction with all these factories if I need to mock anything, I can use "with-redefs" to statically swap function definitions too, which is clean and very easy to reason about. Choosing the things you mr language disallows is one of the most important things you can do to reduce cognitive load.

I disagree with the first point. Say, the compiler figured out your missing semicolon. Doesn't mean it's easy for another human to clearly see it. The compiler can spend enormous compute to guess that, and that guess doesn't even have to be right! Ever been in a situation where following the compiler recommendation produces code that doesn't work or even build? We are optimizing syntax for humans here, so pointing out some redundancies is totally fine.

Yes, semicolons are totally unnecessary. That’s why nobody who works on JavaScript has ever regretted that automatic semicolon insertion was added to the language. It has never prevented the introduction of new syntaxes to the language (like discussed here: <https://github.com/twbs/bootstrap/issues/3057#issuecomment-5...>), nor motivated the addition of awkward grammatical contortions like [no LineTerminator here].

    func thing()
    {

Great points. I strongly agree with your first point. Regrettably, I haven't used any language that solves this. (But believe it's possible, and you've demonstrated with one I haven't used).

I'm stuck between two lesser evils, not having the ideal solution you found: 1: Rust: Commits the sin you say. 2: Python, Kotlin, C++ etc: Commits a worse sin: Prints lots of words.. (Varying degrees depending on which of these), where I may or may not be able to tell what's wrong, and if I can, I have to pick it out of a text well.

Regarding boilerplate: This is one of the things I dislike most about rust. (As an example). I feel like prefixing`#[derive(Clone, Copy, PartialEq)]` on every (non-holding) enum is a flaw. Likewise, the way I use structs almost always results in prefixing each field with `pub`. (Other people use them in a different way, I believe, which doesn't require this)

> the compiler can tell you that there needs to be a semicolon right here

I can see that this is an annoyance, but does it really increase cognitive load? For me language design choices like allowing arbitrary arguments to functions (instead of having a written list of allowed arguments, I have to keep it in my head), or not having static types (instead of the compiler or my ide keeping track of types, I have to hold them in my head) are the main culprits for increasing cognitive load. Putting a semicolon where it belongs after the compiler telling me I have to is a fairly mindless exercise. The mental acrobatics I have to pull off to get anything done in dynamically typed languages is much more taxing to me.

   bool function1(x y z):
          bool function2(x y z)

I agree up until the end. Languages that let you change the syntax can result in stuff where every program is written in its own DSL. Ruby has this issue to some extent.

Regarding Common Lisp, do you know of any articles that highlight the methods used to "change the syntax and add new constructs so that the language meets the problem and not the other way around."

> Another red flag is boilerplate. By definition boilerplate is something that you have to type not because it's required to specify the behavior of the code but simply because the language design demands it. Boilerplate is always unnecessary cognitive load, and it's one sign of a badly designed language. (Yes, I'm looking at you, Java.)

The claim that LLMs are great for spitting out boilerplate has always sat wrong with me for this reason. They are, but could we not spend some of that research money on eliminating some of the need for boilerplate, rather than just making it faster to input?

> Another red flag is boilerplate.

I have to disagree. Boilerplate can simply be a one-time cost that is paid at setup time, when somebody is already required to have an understanding of what’s happening. That boilerplate can be the platform for others to come along and easily read/modify something verbose without having to go context-switch or learn something.

Arguing against boilerplate to an extreme is like arguing for DRY and total prevention of duplicated lines of code. It actually increases the cognitive load. Simple code to read and simple code to write is low-cost, and paying a one-time cost at setup is low compared to repeated cost during maintenance.

> Another red flag is boilerplate. By definition boilerplate is something that you have to type not because it's required to specify the behavior of the code but simply because the language design demands it.

Two things: 1) this is often not language design but rather framework design, and 2) any semantic redundancy in context can be called boilerplate. Those same semantics may not be considered boilerplate in a different context.

And on the (Common) Lisp perspective—reading and writing lisp is arguably a unique skill that takes time and money to develop and brings much less value in return. I'm not fan of java from an essentialist perspective, but much of that cognitive load can be offset by IDEs, templates, lint tooling, etc etc. It has a role, particularly when you need to marshall a small army of coders very rapidly.

Completely agree! Common Lisp is truly the tool of the Gods.

The criticisms of Java syntax are somewhat fair, but it's important to understand the historical context. It was first designed in 1995 and intended to be an easy transition for C++ programmers (minimal cognitive load). In an alternate history where James Gosling and his colleagues designed Java "better" then it would have never been widely adopted and ended up as a mere curiosity like Common Lisp is today. Sometimes you have to meet your customers where they are.

It has taken a few decades but the latest version significantly reduces the boilerplate.

My gripe with the post is that there is no objective "cognitive load" solution. Arguably this varies from 1 person to another.

So with semi-colons, you have three basic options:

1. Not required (eg Python, Go)

2. Required (eg C/C++, Java)

3. Optional (eg Javascript)

For me, (3) is by far the worst option. To me, the whole ASI debate is so ridiculous. To get away with (1), the languages make restrictions on syntax, most of which I think are acceptable. For example, Java/C/C++ allow you to put multiple statements on a single line. Do you need that? Probably not. I can't even think of an example where that's useful/helpful.

"Boilerplate" becomes a matter of debate. It's a common criticism with Java, for example (eg anonymous classes). I personally think with modern IDEs it's really a very minor issue.

But some languages make, say, the return statement optional. I actually don't like this. I like a return being explicit and clear in the code. Some will argue the return statement is boilerplate.

Also, explicit type declarations can be viewed as boilerplate.. There are levels to this. C++'s auto is one-level. So are "var" declarations. Java is more restrictive than this (eg <> for implied types to avoid repeating types in a single declaration). But is this boilerplate?

Common Lisp is where you lose me. Like the meme goes, if CL was a good idea it would've caught on at some point in the last 60 years. Redefning the language seems like a recipe for disaster, or at least adding a bunch of cognitive load because you can't trust that "standard" functions aren't doing standard things.

Someone once said they like in Java that they're never surprised by 100 lines of code of Java. Unlike CL, there's never a parser or an interpreter hidden in there. Now that's a testament to CL's power for sure. But this kind of power just isn't conducive to maintainable code.

You can reduce your Java boilerplate to annotations or succinct XML or whatever. Code generation is used a lot on the JVM.

Can you show a real compiler message about such a semicolon?

    % cat test.c
    main () {
      int x
      x=1
    }
    % gcc test.c  
    test.c:1:1: warning: type specifier missing, defaults to 'int' [-Wimplicit-int]
    main () {
    ^
    test.c:2:8: error: expected ';' at end of declaration
      int x
           ^
           ;
    1 warning and 1 error generated.

   tst.c: In function ‘main’:
   tst.c:3:5: error: expected ‘=’, ‘,’, ‘;’, ‘asm’ or ‘__attribute__’ before ‘x’
       3 |     x=1
         |     ^
   tst.c:3:5: error: ‘x’ undeclared (first use in this function)
   tst.c:3:5: note: each undeclared identifier is reported only once for each function it appears in
   tst.c:3:8: error: expected ‘;’ before ‘}’ token
       3 |     x=1
         |        ^
         |        ;
       4 | }
         | ~       

         1 int main () {                                                                        
         2     int x                                                                            
     E   3     x=1 /\* E: 'x' undeclared (first use in this function)                            
         4 }

.

The very same reasons you find CL to lower your cognitive load are why ultimately after 60 years all lisps have been relegated to niche languages despite their benefits, and I say it as a Racket lover. It raises cognitive load for everybody else by having to go through further steps into decoding your choices.

It's the very same reason why Haskell monocle-wielding developers haven't been able to produce one single killer software in decades: every single project/library out there has its own extensions to the language, specific compiler flags, etc that onboarding and sharing code becomes a huge chore. And again I say it as an avid Haskeller.

Haskellers know that, and there was some short lived simple Haskell momentum but it died fast.

But choosing Haskell or a lisp (maybe I can exclude Clojure somewhat) at work? No, no and no.

Meanwhile bidonville PHP programmers can boast Laravel, Symfony and dozens of other libraries and frameworks that Haskellers will never ever be able to produce. Java?

C? Even more.

The language might be old and somewhat complex, but read a line and it means the same in any other project, there are no surprises only your intimacy with the language limiting you. There's no ambiguity.

> poor language design

We have an excellent modern-day example with Swift - it managed to grow from a simple and effective tool for building apps, to a “designed by committee” monstrosity that requires months to get into.

For unit testing those sub-sections in a clear and concise manner (i.e., low cognitive load). As long as the method names are descriptive no jumping to and fro is needed usually.

That doesn't mean every little unit needs to be split out, but it can make sense to do so if it helps write and debug those parts.

>why the hell would it be "easier to read" if I had to jump up and down the file to 7 different submethods when the function's entire flow is always sequential?

If the submethods were clearly named then you'd only need to read the seven submethod names to understand what the function did, which is easier than reading 100 lines of code.

    foo(...):
        f1(a,b,c,d,e,f)
        f2(a,c,d,f)
        f3(b,c,d,e)
        ...
        f7(d,e)

    foo(...):
        # Fields
        a
        b
        c
        d 
        e
        
        # Methods
        f1(f)
        f2(f)
        f3()
        ...
        f7()

    foo(...):
       // init
       f1(a,b,c,d,e,f)
       f2(a,b,c,d,e,f)
       ...
       f7(a,b,c,d,e,f)

    accum = []
    for x in something():
        for y in something_else():
            accum.append(operate_on(x, y))

    accum = []
    req = my_service.RpcRequest(foo="hello", bar=12)
    rpc = my_service.new_rpc()
    resp = my_service.call(rpc, req)
    
    req = my_service.OtherRpcRequest(foo="goodbye", bar=12)
    rpc = my_service.new_rpc()
    resp2 = my_service.call(rpc, req)

    for x in resp.something:
        for y in resp2.something_else:
            my_frobnicator = foo_frobnicator.new()
            accum.append(my_frobnicator.frob(x).nicate(y))

I find "is_enabled(x)" to be easier to reason about than

    if (x.foo || x.bar.baz || (x.quux && x.bar.foo))

Even if it's only ever used once. Functions and methods provide abstraction which is useful for more than just removing repetition.

    if (
        x.is_enabled ||
        x.new_is_enabled ||
        (x.in_us_timezone && is_daytime()) ||
        x.experimental_feature_mode_for_testing 
        )...

I agree except I think 100 lines is definitely worth a method, whereas 15 lines is obviously not worthy for the most cases and yet we do that a lot.

My principle has always been: “is this part a isolated and intuitive subroutine that I can clearly name and when other people see it they’ll get it at first glance without pausing to think what this does (not to mention reading through the implemention)”. I’m surprised this has not been a common wisdom from many others.

Because a function clearly defines the scope of the state within it, whereas a section of code within a long function does not. Therefore a function can be reasoned about in isolation, which lowers cognitive load.

As a non English speaker, what does "so much this" mean?

Does it essentially just mean "I agree"?

To paraphrase a recentish comment from jerf, “sometimes you just have a long list of tasks to do”. That stuck with me. Now I’m a bit quicker to realize when I’m in that situation and don’t bother trying to find a natural place to break up the function.

    myfunction(data) {
        # do one thing to the data
        ...

        # now do another
        ...
    }

    myfunction(data) {
        do_one_thing_to_the_data(data)
        now_do_another(data)
    }

    do_one_thing_to_the_data(data) {
        ...
    }

    now_do_another(data) {
        ...
    }

    let shared_computation = do_shared_computation();
    
    let result_one = {
        let result = do_useful_things();
        other_things(&shared_computation);
        result
    }
    
    ...

It comes down to the quality of the abstractions. If they are well made and well named, you'd rather read this:

  axios.get('https://api.example.com', {
      headers: { 'Authorization': 'Bearer token' },
      params: { key: 'value' }
  })
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

than to read the entire implementations of get(), then() and catch() inlined.

> The whole point of functions and classes was to make code reusable.

I’m amazed that here we are >40 years on from C++, and still this argument is made. Classes never encapsulated a module of reusability, except in toy or academic examples. To try and use them in this way either leads to gigantic “god” classes, or so many tiny classes with scaffolding classes between them that the “communication overhead” dwarfs the actual business logic.

Code base after code base proves this again and again. I have never seen a “class” be useful as a component of re-use. So what is? Libraries. A public interface/api wrapping a “I don’t care what you did inside”. Bunch of classes, one class, methods? So long as the interface is small and well defined, who cares how it’s structured inside.

Modular programming can be done in any paradigm, just think about the api and the internal as separate things. Build some tests at the interface layer, and you’ve got documentation for free too! Re-use happens at the dll or cluster of dll boundaries. Software has a physical aspect to it as well as code.

Indeed and breaking out logic into more global scopes has serious downsides if that logic needs to be modified in the future, if your system still needs to support innovation and improvements, downsides not totally unlike the downsides of using a lot of global variables instead of local ones.

Prematurely abstracting and breaking code out into small high level chunks is bad. I try to lay it out from an information theoretic, mathematical perspective here:

https://benoitessiambre.com/entropy.html

with some implications for testing:

https://benoitessiambre.com/integration.html

It all comes down to managing code entropy.

>why the hell would it be "easier to read" if I had to jump up and down the file to 7 different submethods when the function's entire flow is always sequential?

Because you don't jump up and down the file to read it.

Each method that you create has a name, and the name is an opportunity to explain the process - naturally, in-line, without comments.

I write code like this all the time - e.g. from my current project: https://github.com/zahlman/bbbb/blob/master/src/bbbb.py . If I wanted to follow the flow of execution, I would be hammering the % key in Vim. But I don't do that, because I don't need or want to. The flow of the function is already there in the function. It calls out to other functions that encapsulate details that would be a distraction if I want to understand the function. The functions have names that explain their purpose. I put effort into names, and I trust myself and my names. I only look at the code I'm currently interested in. To look at other parts of the code, I would first need a reason to be interested in it.

When you look at yourself in the mirror, and notice your hand, do you feel compelled to examine your hand in detail before you can consider anything about the rest of your reflection? Would you prefer to conceive of that image as a grid of countless points of light? Or do you not find it useful that your mind's eye automatically folds what it sees into abstractions like "hand"?

35 years into my journey as a programmer, the idea of a 100-line function frightens me (although I have had to face this fear countless times when dealing with others' code). For me, that's half of a reasonable length (though certainly not a hard limit) for the entire file.

    # Can't import at the start, because of the need to bootstrap the
    # environment via `get_requires_for_build_*`.
  

There's just no way I buy that I could safely make a change in a 100 loc function and know that there won't be an impact 30 lines down, where with a few additional function you can define the shape of interactions and know that if that shape/interface/type is maintained that there won't be unexpected interactions. Its a balance though as indirection can also readily hide and obscure interactions or add unnecessary glue code that also takes up mental bandwidth and requires additional testing to confirm.

I thought these things were pretty inferable

Is this bait?

hi, tiling window manager and neovim user here.

I don't think about states much, it's all just muscle memory. Like doing a hadouken in street fighter.

I commented on this in another thread here.

What I read it as is don’t over-index on creating separate layers/services if they are already highly dependent on each other. It just adds additional complexity tracing dependencies over the networking stack, databases/datastores, etc that the services are now split across.

In other words: a monolithic design is acceptable if the services are highly intertwined and dependent.

I think the 'Layered Architecture' section is all over the place.

There are a lot of terms thrown around with pretty loose definitions - in this article and others. I had to look up "layered architecture" to see what other people wrote about it, and it looks like an anti-pattern to me:

  In a four-layered architecture, the layers are typically divided into:
    Presentation
    Application
    Domain
    Infrastructure

  These layers are arranged in a hierarchical order, where each layer provides services to the layer above it and uses services from the layer below it, and each layer is responsible for handling specific tasks and has limited communication with the other layers. [1]

It looks like an anti-pattern to be because, as described, each layer depends on the one below it. It looks like how you'd define the "dependency non-inversion" principle. Domain depends on Infrastructure? A BankBalance is going to depend on MySQL? Even if you put the DB behind an interface, the direction of dependencies is still wrong: BankBalace->IDatabase.

Back to TFA:

> In the end, we gave it all up in favour of the good old dependency inversion principle.

OK. DIP is terrific.

> No port/adapter terms to learn

There is a big overlap between ports/adapters, hexagonal, and DIP:

  Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases. [2]

That is, the Domain ("application") is at the bottom of the dependency graph, so that the Infrastructure {Programs, Tests, Scripts} can depend upon it.

> If you think that such layering will allow you to quickly replace a database or other dependencies, you're mistaken.

Layering will not help - it will hinder, as I described above. But you should be able to quickly replace any dependency you like, which is what DIP/PortsAdapters/Hexagonal gives you.

> Changing the storage causes lots of problems, and believe us, having some abstractions for the data access layer is the least of your worries. At best, abstractions can save somewhat 10% of your migration time (if any)

I iterate on my application code without spinning up a particular database. Same with my unit tests. Well worth it.

[1] https://bitloops.com/docs/bitloops-language/learning/softwar... [2] https://alistair.cockburn.us/hexagonal-architecture/

If you feel like you are missing key parts of the argument, like I was, it might help to switch the view from "short" to "long" - there's a little slider on the right hand side of the screen. This adds in some paragraphs that help the piece flow better. (I'd never seen a blog post with this feature before.)

I agree. I find this part of the article weird as it has contracting statements:

> No port/adapter terms to learn

and

> we gave it all up in favour of the good old dependency inversion principle

Both use interfaces, just in different ways. We use hexagonal (ports and adapters) pattern in my project. If you asked anyone on my team to define hexagonal architecture they'll have no idea what you're talking about. They just follow the project coding patterns. There's no additional complexity.

> If you think that such layering will allow you to quickly replace a database or other dependencies, you're mistaken

I think most people do not stay at companies long enough to see the price of not abstracting away these things. That's the next developer's problem. The code tends to be tightly coupled to the libraries and frameworks used. Eventually, the projects dependencies have to be upgraded (usually due to security issues) and the migrations are usually incredibly difficult, expensive, and fragile. The product's business logic is tightly coupled with the framework and libraries used at the time. Even if the company realizes that framework has no future, they're kind of locked into their initial decision made a decade ago. At least, that's been my experience.

We have two major products at my company. Both started with the same initial framework, but the project I architected that used hexagonal was migrated to a faster and more modern framework within 4 weeks. The other product had a multi-year migration to a newer version of the same framework (and by the time it was completed is already two major versions outdated). Both products are similar in scale and code size.

Also depends on whether it’s obvious why I need a list of odd numbers.

Rather depends if we can trust that it's Python's "filter" or if it's another language you're making look Pythonic, and we don't know who implemented filter/2 or how.

- The first one might be an in-place filter and mutate "numbers", the second one definitely isn't.

- The first one might not be Python's filter and might be a shadowed name or a monkeypatched call, the second one definitely isn't.

- The first one isn't clear whether it filters odd numbers in, or filters them out, unless you already know filter/2; the second one is clear.

- The first one relies on you understanding first-class functions, the second one doesn't.

- The first one isn't clear whether it relies on `numbers` being a list or can work with any sequence, the second one clearly doesn't use list indexing or anything like it and works on any sequence that works in a `for` loop.

- The first one gives no hint what it will do on an empty input - throw an exception, return an error, or return an empty list. The second one is clear from the patterns of a `for` loop.

- The first one has a risk of hiding side-effects behind the call to filter, the second one has no call so can't do that.

- Neither of them have type declarations or hints, or give me a clue what will happen if "numbers" doesn't contain numbers.

- The first one isn't clear whether it returns a list or a generator, the second one explicitly uses () wrapper syntax to make a generator comprehension.

- The first one has a risk of hiding a bad algorithm - like copying "numbers", doing something "accidentally n^2" - while the second one is definitely once for each "n".

Along the lines of "code can have obviously no bugs, or no obvious bugs" the second one has less room for non-obvious bugs. Although if the reader knows and trusts Python's filter then that helps a lot.

Biggest risk of bugs is that odd(n) tests if a number is part of the OEIS sequence discovered by mathematician Arthur Odd...

The argument isn't about these minor syntactic or API differences. It's about the structure of the code, in the SICP (https://en.wikipedia.org/wiki/Structure_and_Interpretation_o...) sense.

I find that it comes most from intelligence. I see plenty of super experienced but not very smart engineers design terrible over engineered systems. On the other hand, juniors err in the opposite direction with long functions with deep nested branching and repetition. And the latter is better. Easier to refactor up in abstraction level than down.

I love what you're saying. But, I've met a lot of people who have say 10-20 years experience designing applications with unnecessary and sometimes incredible cognitive load. There are serious incentives to NOT write "simple" code, let me share a few of them.

Root causes from my perspective look like: 1. Job security type development. Fearful/insecure developers make serious puzzle boxes. "Oh yea wait until they fire me and see how much they need me, I'm the only one who can do this."

2. Working in a vacuum/black hole developers. Red flags are phrases like "snark I could have done this" when working together on a feature with them. Yes, that is exactly the point, and I even hope the junior comes in after and can build off of it too.

3. Mixing work with play "I read this blog post about category theory and found this great way to conceptualize my code through various abstractions that actually deter from runtime performance but sound really cool when we talk about it at lunch".

4. Clout/resume/ego chasing "I want to say something smart at stand up, a conference, or at a future job, so other people know they are not on my level and cannot touch my code or achieve my quality."

Some other red flags. They alone maintain their "pet" projects for everything serious until they couldn't. Minor problems/changes come up, someone else goes in and fixes it. Something serious happens it's a stop the world garbage collection for that developer and they are the only one who can fix it disrupting any other operations they were part of.

Yeah it's kind of a weird narrative. Writing complex code is leaps and bounds easier than writing simple code. Often takes both experience and intelligence to see the correct way.

Had to re-read this several times to grasp the meaning..

Curious, what is your background and day to day work to be able to express your thinking in these terms?

Same deal with DRY, the principle is obviously correct but people can take it too literally. It's so easy to get yourself in a huge mess trying to extract out two or three bits of code that look pretty similar but aren't really used in the same context.

This is the bane of my existence at the moment after ~20 years into my career, and it frustrates me when I run into these situations when trying to get certain people to review pull requests (because I'm being kind, and adhering to a process, and there is really valuable feedback at times). But on the whole it's like being dragged back down to working at a snails pace.

- Can't refactor code because it changes too many files and too many lines.

- Can't commit large chunks of well tested code that 'Does feature X', because... too many files and too many lines.

- Have to split everything down into a long sequence of consecutive pull requests that become a process nightmare in its own right

- The documentation comments gets nitpicked to death with mostly useless comments about not having periods at the ends of lines

- End up having to explain every little detail throughout the function as if I'm trying to produce a lecture, things like `/* loop until not valid */ while (!valid) {...` seemed to be what they wanted, but to me it made no sense what so ever to even have that comment

This can turn a ~50 line function into a 3 day process, a couple of hundred lines into a multi-week process, and a thousand or two line refactor (while retaining full test coverage) into a multi-month process.

At one point I just downed tools and quit the company, the absurdity of it all completely drained my motivation, killed progress & flow and lead to features not being shipped.

Meanwhile with projects I'm managing I have a fairly good handle on 'ok this code isnt the best, but it does work, it is fairly well tested, and it will be shipped as the beta', so as to not be obstinate.

  * tried to review most things within like half an hour of their announcement
    in the shared MR channel

  * requested a pair programming session and offered to do a pair programming
    session for any large and semi-or-fully automated refactoring session,
    like running a linter or doing a multi-file variable rename
    (the pair programmer immediately comments on and approves the MR when it
    appears)

  * tried to limit my PRs to approximately 400 lines (not a rigid rule)

It's the same with writing. The best authors occasionally break the rules of grammar and spelling in order to achieve a specific effect. But you have to learn the rules first, and break them only intentionally rather than accidentally. Otherwise your writing ends up as sloppy crap.

(Of course some organizations have coding conventions that are just stupid, but that's a separate issue.)

If a function is longer than what I can display on a single screen, it better has to be argumented with very exceptional relevant requirements, which is just as straight forward to judge for anyone with a bit of experience.

I've seen a book promoting the idea that methods should not be longer than 5 lines.

Of course now I know these ridiculous statements are from people hardly wrote any code in their lives, but if I'd read them at 18 I would have been totally misled.

You're confusing this with a software development process problem. It's really just good old fashioned psychological abuse.

I like to call these smells, not rules. They're an indication that something might be wrong because you've repeated code, or because your method is too long, or because you have too many parameters. But it might also be a false positive because in this instance it was acceptable to repeat code or have a long method or have many parameters.

Sometimes food smells because it turned bad, and sometimes it's smelly because it's cheese.

>It almost always comes from a lead or manager who reads too many business books and then cargo cults those books on to the team.

Worse, they behave as though they have profound insights, and put themselves on an intellectually elevated pedestal, which the rest of their ordinary team mortals cannot achieve.

I'm an experienced developer and I enforce these kinds of rules upon myself without giving it much thought, and I very much prefer the results.

In my experience it usually devs that do that to themselves after reading stuff on the internet and thinking “I want to be a professional and I want to show it to everyone.”

Then rules stay and new people just continue with same silly rules instead of thinking if those are really that useful.

Hard rules are the problem. There is a lot of "it depends."

After over 40 years of programming, I continue to reduce the size of functions and find it easier to write and understand when I return to them. Ten lines are now a personal guideline.

However, a linear function with only tiny loops or conditionals can be easily understood when hundreds of lines are long, but not so much with nested conditionals and loops, where there is natural decomposition into functions.

I observed that the same guidelines became rules problems when test coverage became popular. They soon became metrics rather than tools to think about code and tests. People became reluctant to add sanity check code for things that could should never happen because it brought down code coverage.

Doing things the right way always introduces a shackle to your ankle. Oh am I to package my functions as discrete packages I call via library name carefully crafted to install into some specific folder structure that I now have to learn and not make mistakes with. Or I can do it “improperly” and just write a function and start using it immediately.

Not everything has to be designed like some standardized mass produced part ready to drop into anything made in the last 40 years. And what is crazy is that even things written to that standard aren’t even compatible and might have very specific dependencies themselves.

Well said.