Cognitive load is what matters

The approach that I am trialing with my team now, so far to good results, is as follows.

* Our coding standards require that functions have a fairly low cyclomatic complexity. The goal is to ensure that we never have a a function which is really hard to understand.

* We also require a properly descriptive header comment for each function and one of the main emphases in our code reviews is to evaluate the legibility and sensibility of each function signature very carefully. My thinking is the comment sort of describes "developer's intent" whereas the naming of everything in the signature should give you a strong indication of what the function really does.

Now is this going to buy you good architecture for free, of course not.

But what it does seem to do is keep the cognitive load manageable, pretty much all of the time these rules are followed. Understanding a particular bit of the codebase means reading one simple function, and perhaps 1-2 that are related to it.

Granted we are building websites and web applications which are at most medium fancy, not solving NASA problems, but I can say from working with certain parts of the codebase before and after these standards, it's like night and day.

One "sin" this set of rules encourages is that when the logic is unavoidably complex, people are forced to write a function which calls several other functions that are not used anywhere else; it's basically do_thing_a(); do_thing_b(); do_thing_c();. I actually find this to be great because it's easy to notice and tells us what parts of the code are sufficiently complex or awkward as to merit more careful review. Plus, I don't really care that people will say "that's not the right purpose for functions," the reality is that with proper signatures it reads like an easy "cliffs notes" in fairly plain English of exactly what's about to happen, making the code even easier to understand.

> Our coding standards require that functions have a fairly low cyclomatic complexity. The goal is to ensure that we never have a a function which is really hard to understand.

https://github.com/fzipp/gocyclo

> * We also require a properly descriptive header comment for each function and one of the main emphases in our code reviews is to evaluate the legibility and sensibility of each function signature very carefully. My thinking is the comment sort of describes "developer's intent" whereas the naming of everything in the signature should give you a strong indication of what the function really does.

https://github.com/mgechev/revive

> Now is this going to buy you good architecture for free, of course not.

It's not architecture to tell people to comment on their functions.

Also FTR, people confuse cyclomatic complexity for automagically making code confusing to the weirdest example I have ever had to deal with - a team had unilaterally decided that the 'else' keyword could never be used in code.

> he weirdest example I have ever had to deal with - a team had unilaterally decided that the 'else' keyword could never be used in code.

Not weird at all:

https://medium.com/@matryer/line-of-sight-in-code-186dd7cdea...

This sounds like hell to me.

Not everything is complicated, most functions don't need comments, why require it? Just fix complexity when it arises. Don't mandate that you can't make any complexity.

I can understand why else is sometimes not needed. JS linters will remove unnecessary else statements by default.

https://eslint.org/docs/latest/rules/no-else-return#rule-det...

But never using it is crazy.

Well, I found it weird - the else keyword has been a stalwart of programming for... several decades now.

Maybe one day we will abstract it away like the goto keyword (goto is a keyword in Go, and other languages still, but I have only seen it used in the wild once or twice in my 7 or 8 years of writing Go)

Goto is still used in almost every language, but it's abstracted away, hidden in loops, and conditionals (which Djikstra said was a perfectly acceptable use of goto), presumably to discourage its direct use to jump to arbitrary points in the code

In a similar vein to how I just responded to the other person, maybe eventually we'll abstract `else` away so that it's use is hidden, and the abstraction ensures that it's only being used where we all collectively decide it can/should be used.

What is a function supposed to do and why?

I found this type of approach (where you try to meet subjective readability goals with objective/statistical metrics) to not produce clear code in practice. Instead, I suggest this one weird trick: if your colleagues are confused in code review, then rewrite and comment the code until they aren't confused anymore. Don't just explain it to them ad-hoc, make the code+comments become the explanation. There is no better linter than subjective reading by your colleagues. Nothing else works nearly as well. Optimize to your team's understanding, that's it. Somehow, this tends to keep working great even as the team changes.

Agreed. If you need a comment to tell you what the function does, you should think deep about naming, and if this fails, consider if this is the correct abstraction. Comments are a way to kick the can down the road - "I was unable to make this code clear enough, so here is the hint to help you".

Edit: sometimes the comments are the best of all evils, and you should use them to explain the constraints that led to this code - they just shouldn't be mandatory.

It's one message I struggle to convey to people I do code reviews for: don't make me understand it, make it more self explanatory so every reader does. (And, yes, I ask for it explicitly too)

(I sometimes "ask" questions for something it took me a few back and forths through code to get so they'd think about how it could be made clearer)

Unfortunately, most people focus on explaining their frame of mind (insecurity?) instead of thinking how can they be the best "teacher".

Yeah, not easy, but it helps to build some rapport first, so people learn what you’re after. The way I tend to do that is by leaving a review comment with an example code snippet that makes me understand it better, and a question “what do you think about this version? I tried to clarify a few things here.”. + Explain what was clarified. I find the effort usually pays off.

But this might require too much effort from the reviewer

I found that to be a double edged sword: some copy and paste it verbatim without thinking it through and adjusting at all.

It's a delicate balance we need to keep in mind between many of:

- maintainable code

- getting things done

- feeling of accomplishment

- feedback loop speed

- coaching

- motivation and emotional state ("why are they pestering me, the code works, I just want to feel productive and useful: this was hard enough to get right as it is")

...and more!

At the same time, some do get the point, but getting readable code is really an art/craft in itself, and nothing but experience and learning to look at it from outside is the main driver to learning.

These points are about organising code and workflow. Even if you have organised your functions to the lowest possible unit of work you can still have a mess of async queue microservice hell which is the actual architecture.

Architecture is another topic entirely and the scope is higher abstractions across multiple systems.

In a sense, all of these coding practices -- whether restricting goto to loops and conditionals, which has broad acceptance these days, or avoiding else to "keep the happy left", or anything else in a coding style guide -- are just doing one thing: restricting the language to a smaller subset of itself.

And in general the primary benefit of such restriction is to reduce cognitive load. Scheme is easier than C++. The downside of such restriction is loss of expressiveness. Whether the net benefit is good depends on how these two things trade off. Experience and developer preference are inputs to that equation, which is why devs fight over coding guidelines. But I think it's helpful to boil it down in this way at a high level.

The ideal is smaller language where the expressiveness you've cut away is only rarely useful, and often error-prone.

Yeah, this does require a certain team culture building effort. Just starting cold without any expectation-setting might not be received well.

One "rule" I try to meta-promote is — working code is the first step, and a great foundation to then proceed to clear and maintainable code.

Another, is that code reviews are first-class citizens deserving mindfulness.

I actually think this is antithetical to the philosophy. Cyclometic complexity is very much not the same as "is this code difficult to understand".

Arbitrary structure rules like "do_thing_a(); do_thing_b(); do_thing_c();" also is not unless you can explain how this helps make it easier to understand compared to say, one big function with "// DO THING A" comments.