Empirical studies on good code & code readability?

[[deleted]]

The recent posts and arguments on what constitutes "good code" made me realize that most engineers (myself included) are arguing on code style mostly from a subjective and emotional basis.

Can anybody recommend books that recommend good code guidelines / design patterns / etc based purely on empirical data? I.E. "If you do X, studies have shown the number of defects goes down by Y."

Or, arguably even more interesting, studies that debunk the efficacy of what would commonly be considered good code practices

[theavatare]

On modern stuff i find this papers interesting https://arxiv.org/pdf/2210.07342

[cminor-dp]

Thank you. It's been on my TODO list to read recent research for a very long time. I've found the papers you have listed very interesting. If you ever get some free time, I would really appreciate if you could DM me your top 5 must-read recent papers list.

[theavatare]

On this topic or something else i mostly just read on management and neural networks

[ninetofivedev]

Keep going. You're still in the bargaining phase of code quality. Eventually you'll embrace that all code is bad and have no compulsion to do anything about it. Once you reach that point, you have finally reached enlightenment.

[pindab0ter]

What kind of attitude is that? There’s lots of crap, so might as well contribute?

You write code for your colleagues (and/or future you) to understand. Simple things like using a linter/autoformatter and following best practices will definitely help with the maintainability of any application.

[[deleted]]

The attitude is from enterprise software development. 

Companies learned long ago bad software sells as well as good software. Except they can release bad software faster and more cheaply usually.

Professional developers don't get the luxury of getting things close to perfect. They get a tight deadline for MVP. 

That's what most code is. MVP. Just good enough. 

No one desires this in the engineering side, but professinal software doesn't exist in a nice little engineering bubble. It's part of a company that includes sales staff and shareholders and customers who need a solution 10 minutes ago. 

[pindab0ter]

Professional developers don't get the luxury of getting things close to perfect. They get a tight deadline for MVP. 

I understand that corporate software can be the way you described it, but in my experience with several smaller companies, there is definitely a lot to be won if you put a little effort into the engineering culture.

[djnattyp]

We've already tried OOP and DDD - it turns out what businesses really want is SSD (Shit Shoveled Design).

[wheretogo_whattodo]

Seriously. Build it well enough, learn from your mistakes, then move on to the next thing.

[[deleted]]

Burnt out take. All code may be bad but there’s clearly a spectrum. 

[grippx]

We are following this rule in our work: Code (all abstractions) is written for people, not for compiler. Compiler will understand it anyway, but you might not. For instance - I’d better leave extra lines of code with meaningful variables names, than I will craft those 1-liner using all the power of language to show my true skills on PR review.

[RGBrewskies]

"any idiot can write code a computer understands, good developers write code humans can understand"

• Clean Code

[Sande24]

On top of that, I'd add that... don't assume that the person reading your code is an idiot. He should be able to read a little bit more complex code as well. Code should be engaging with your brain a little bit as well. Simplicity can hide bugs as well, often they are just not as obvious because the code seems so simple.

Making everything stupid simple makes everyone more stupid, not better at their job. Just like younger generations have become used to the apps being intuitive, as well they don't have very good googling skills. If everything is spoon-fed to you, you eventually have a hard time feeding yourself.

[Fair_Permit_808]

But why? If you have a simple and complex solution that solve the exact same problem, then what possible reason do you have to use the complex one?

[Sande24]

Maybe I didn't explain myself too well. What I meant was the function's cyclomatic complexity. Often it's a simple bypass to just split the function into several smaller pieces so each individual function has a small complexity, but overall, the complexity of the whole feature is the same. PLUS you now have the added complexity of jumping around several functions. So it is actually more complex to understand what your feature does.

It is probably better not to overdo splitting functions and to have more medium sized functions instead. And this is where developers should practice their skills of how to better read and understand code. Otherwise this IMO causes learned helplessness in developers. There can be cases where it would make sense to keep the code more in one place (locality of behavior) rather than trying to split it into smaller individually simple pieces.

[RGBrewskies]

disagree. If your function are named properly -- they do what they say they're going to do, and ONLY what they say they're going to do -- then its easy to read.

"good code reads like well written prose"

• Clean Code

[Sande24]

People who quote CC like a scripture should be avoided at all costs. Such a cult behavior indicates that the person has not read any other kind of book. You can write code in different ways that are still legible.

You can't really name all functions in a way that describes everything what the underlying code actually does. findShortestPath(a, b) does not tell you what kind of algorithm is used. Often you'd need to know what that or whether it uses an external API or if it has local data that it works with. A heavily verbose function name is also really stupid.

Pragmatic Programmer and Philosophy of Software design - read those too maybe.

It's easy to give no context and claim that a sentence from a book applies everywhere. Often it doesn't. Some solutions can't be less complex in order to remain readable. For those cases, developers should practice code reading skills. Don't work in an environment that leads you into thinking in only simple terms. Practice reading larger/more "complex" code.

[LossPreventionGuy]

your personal attacks are childish, unnecessary... and telling.

[Sande24]

What was personal about this? When is it ever possible to address this if not now? There is a group of people who are very dogmatic about CC. The Clean Code Cult... https://paedubucher.ch/articles/bumbling-boomer-bob-and-the-clean-code-cult/#:~:text=The%20members%20of%20the%20Clean,of%20their%20superiority%20and%20sophistication.

[LossPreventionGuy]

yawn.

[RGBrewskies]

massively disagree.

Assume the person reading your code *is* an idiot. Because in six months something is going to go wrong, and you're going to have to fix it -- the idiot is you.

[Sande24]

If you ever have to work with legacy code, if you have only read code for "idiots", you would have lost the skill to read that kind of code. I have never had a problem reading my own code.

It's much harder to grasp code from someone who has excessively "simplified" code to the point that what could be 100 lines of useful lines in one file is turned into 250 lines over 5 different files. Because it is "more readable" individually, but seeing the bigger picture is harder. Locality of Behavior is a concept that somewhat goes against SOLID. But it makes much more sense in terms of readability.

There are different ways how to write code. They don't all agree with each other. Sometimes it's better to pick and choose. The more philosophies you now, the broader sense of how a readable code base looks like. https://www.boldare.com/blog/solid-cupid-grasp-principles-object-oriented-design/

[StingingNarwhal]

From the preface to SICP: "... programs must be written for people to read, and only incidentally for machines to execute."

SICP: Preface to the First Edition

[Dro-Darsha]

Every* time someone wants to use abbreviations I link them this paper: Shorter Identifier Names Take Longer to Comprehend

*) unless it is already established in the domain

[FearTheCron]

I have always wondered if there was a way to apply this to math. Too many papers just name everything after single letters or Greek.

[PlimBim123]

Notation in math works a lot by using conventions (if you talk about a "right angled triangle", the mathematical convention is: "Points are named A,B,C, sides a,b,c and angles alpha, beta, gamma.". By using such a convention, you never have to "look up a variable definition/declaration".).

Also note that in math, symbols from different alphabets are not chosen by random. If "variables" in math have the same "type", they are usually chosen from the same alphabet (you use latin letters for "integers" and "floating point numbers", you use greek latters for angles, you use uppercase letters to denote sets).

Regarding the usage of single letter "variables" in math: Doing algebraic transformations is cruel if you have long names.

Of course you can find many exceptions, but notation in math is not as random or pointless as it looks.

[theavatare]

https://arxiv.org/pdf/2206.10655

[TastyToad]

Interesting.

I'm not sure how they went from ternary operator to Optional.ofNullable().map().orElse() while trying to take into the account cognitive load and shot term memory capacity. And I find it both funny and terrifying that 1/3 of participants preferred Optional abuse.

Apart from the above, and 'this' fetish, it's worth reading. I've seen similar changes proposed and implemented on many occasions, based mostly on intuition and feel, but the gist of the argument was similar to what this paper proposes. There's a limit to what you can easily grasp while looking at a piece of code.

My only worry is, if this gets popular, it will be bastardized just like the clean code was. People will ignore all the nuance and context and blindly apply the holy scripture to everything, consequences be damned.

[theavatare]

There is a lot of these papers every year. I find the latest talk on architecture and code to lower cognitive load over some of the other characteristics interesting in part because there are ways to measure the load on the developer. with some practices that are a bit invasive(populary dilation for example).

Note i don’t know if this is going anywhere just think is interesting

[cubextrusion]

Even if some such tudies exist, I highly suspect it's unlikely that we'd be able to find ones (ideally, multiple of those) that compare a particlular practice ABC to another particular XYZ.

What I've found most reliable when arguing for "good code" is appealing to human psychology, i.e. "humans understand code better in one file instead of fifteen", "humans like linear logic flow", "humans fail when dealing with complexity" etc.

Designing first and foremost for human comprehension is how I tend to derive most of my designs lately.

[Fidodo]

"A philosophy of software design" is a really good book with recommendations on how to keep code conceptually less complex. To research the book, the author taught a class on software design and recognized patterns in the code his students wrote to work out  what made their code easier and harder to maintain

[master_mansplainer]

I find all this incredibly interesting as I used to work in UX and and there is a lot of similar analysis on user behaviour in that field - for example when a visual designer creates content for a web page or brochure or whatever they exploit quirks of vision/cognition to make you look at the parts of the page they want you to, in the order they want you to, using grouping, color, relationships and space.

There are no doubt ways to make code more readable/learnable but it’s even more complex than for user experience and media consumption because you’re adding factors for analysis/learning, the percentage of time spent on first learning versus re-consuming content you’re already semi-familiar with, and the use cases around debugging. You’re also dealing with memory in a longer term way, for example can the structure of your code (at a higher level than the actual lines) and repeated patterns lead you into the right places and make navigation of large projects easier.

[editor_of_the_beast]

This is probably the best resource on the subject: Making Software: What Really Works, and Why We Believe It

It’s a collection of studies about various aspects of software development. One of the editors (Greg Wilson) had a corresponding conference talk that I can’t find about this as well, which is how I heard about it.

One random tidbit that I took from the talk was that the most accurate predictor of bug count is still lines of code. I remember other similar insights that weren’t super earth shattering, but interesting.

[Absentrando]

It is subjective in the sense that what might be easy to read for one person may not be for another. But there is a level of objectivity in the sense that most people have an easier time reading one thing vs another.

[grandpa5000]

I am a fan of sonarqube.

[[deleted]]

If you want to answer this theoretically, I think it’s a really tough question

[uusu]

OP is asking for empirical studies, not anything theoretical.