Understability of code should be the default priority

All things being equal, so not when performance is an issue, and in addition to any existing coding conventions, the understandability of code is the most important thing.

Typically this means, "can I read the and easily understand 'everything' about it?"

In the past, I've said that "readability" is the most important thing but what I've realized lately is that I mean: can I easily read it AND understand it?

This is more important than "SOLID principles" or "Clean Code."

Delivering value is the end goal when writing code. The code is a means to an end. It's not an end on its own. The primary goal is not to have code that meets a specific standard. Even if there are appreciable benefits from following that standard. The goal is to benefit the people using the code.

Yes, there are many reasons for following established principles, practices, and conventions. I recommend and follow many myself. But they're not the most important thing.

It doesn't matter how great the code is if you don't ship.

It's great that you've structured code to make it easy to maintain, but if you don't release bug fixes or new features, I question the value of the effort put into how the codebase is structured.

I've seen code that is technically "clean" but is slow and hard to understand and modify.

I recently met some developers at a company who highly prioritize "clean code." But, their shipping schedule was so slow that their customers complained about the infrequency of new features and updates. They had a massive backlog of "core" functionality that was expected to take years to be implemented. Their competitors had more features, more customers, and a better reputation. The developers at this company wanted to create a better product but admitted that their focus on "clean code" meant their development process wasn't as fast as it could be. I'm not implying it's the only issue or factor, but the product, their customers, and ultimately their business weren't as competitive as they could be because of an arbitrary set of rules they were enforcing upon themselves.

Obviously, there are multiple factors to consider when deciding what to prioritize. Priorities will also differ for products, domains, and personal preferences, but having a fixed rule that is never changed can hurt as much as it's designed to help.

Test coverage is also an important related factor. If I'm not writing something "test-first" (because sometimes this isn't practical or desirable), my guiding principle is that anything "non-trivial" should have tests. I define "non-trivial" as anything where I can't look at the code and immediately see and understand every code path and likely error case. It's not always perfect, but it's served me well for years.   

I don't have any "hard and fast rules" for when to play specific practices or when to structure code in specific ways, but "is this easy for me to read and understand?" is my guiding principle. And if I'm working with a team, having code reviews can verify that others working on the code can read and understand it too.

If I can understand it, I'm aware of the potential consequences of any changes, regardless of how it's structured.

I'm curious if others have general principles for planning and structuring code. Anything that doesn't include "must" or "always" (or treats "should" like "must") but instead acknowledges the complexities of managing multiple priorities in different circumstances.

The problem with XAML

Regardless of how you feel about XAML, you'll have a very hard job convincing me it's the best it can be.

What do I mean?

• There's not a lot of (if any) development or investment being done by Microsoft (or other companies) in new and improved tooling that can help people write and work with XAML.
• There have been no real changes in XAML and its capabilities since it came out.
• There's fractured ownership of XAML dialects and tooling within Microsoft. 
• No experimentation or investigation is being done on what can make it better.
• XAML being written today looks (mostly) the same as that written 15+ years ago. 

Think about writing C# code the way you did 15 years ago.

At best, I'd argue that XAML can really only be considered as being at version 2.0.

Imagine if you still had to use version 2.0 of C#. Would that be as pleasant, enjoyable, and productive as you'd like?

As things are, the "problem" with XAML has some consequences:

• Because things haven't changed, there's an expectation that things can't get better. We complain about how bad things are but don't think about improving them.
• Fear of change is common, and a lack of change helps create a self-enforcing feedback loop that means any change is feared even more.
• Because no one is asking questions, it creates an expectation that no one should.
• We get so used to seeing things the same way that it's easy to assume that anything new (or different) is automatically assumed to be wrong. Yes, this is a form of Stockholm Syndrome.

Tens (hundreds?) of thousands of companies are building applications with XAML.

There are millions of apps in existence that use XAML and they are used by even more people, but they're not as easy to write, support, maintain, and improve as they could be.

Why aren't more people talking about how things can be better?

I have ideas about how things can be improved and will share them.

However, I want to be wrong about this.

I want to be wrong about XAML!

I've been rethinking how XAML looks and is written.

It's not controversial to say that XAML has its criticisms.

There are lots of things that can be better about XAML, which will make it easier to write, read, and maintain.

But "everyone" writes XAML the same way.

"Everyone" writes XAML the same way it was written 15+ years ago.

I think things can be better.

I think that we can learn from other languages and ways that software development has changed over the years since XAML was first launched.

I have examples and justifications.

I've been talking at a few user groups and conferences about this, and everyone I've spoken to agrees with me.

But I WANT TO BE WRONG!!!

I don't want to have been doing it poorly for so many years.

I don't want "everyone" to be doing things in a sub-standard way all these years and have so many code bases that could be significantly easier to support and maintain.

I don't want to be the only person thinking about how things can improve.

I'd love to know that the way we write and work with XAML is the best way, and it can't be made better.

But, I don't think I am...

Yes, more on this will follow...

Will AI replace me? - I doubt it

Many times in my career a new technology has come along or an older technology has gone away and people who use the older technology have worried about their future.

What I've always pointed out to those people is that (hopefully) their knowledge goes beyond knowing a specific technology or set of APIs.

An example.

A few months ago I was at a hackathon and came up with the idea of creating a DSL (Domain Specific Language) for creating types/classes.

You write something in English and it generates the C#, Python, or TypeScript.

We got the basics working at the event but it's still an ongoing side project.

On the second (final) day, someone saw what we were doing and wondered if AI could do the same thing.

We gave them a copy of the language spec we'd written (including samples) and they fed it into GPT3.

They could then give it new input and the result was surprisingly accurate. I'd say about 80% of what it produced was correct.

Having already hand-coded an implementation, had I wasted several hours? Perhaps.

But it was only 80% accurate. That's not good enough.

Rather than GPT3, what if we asked ChatGPT to write the code to implement the spec?

That might do better. Also, rather than producing a black box algorithm we'd have some code that I could manually adjust to improve the accuracy.

So would it replace me?

No.

If all I could do was write code to meet a spec, I might be worried, but I can do much more than that.

It couldn't come up with the original idea. I can.

It couldn't write the spec for what it should do. I can.

It couldn't test the accuracy of the output (including knowing if it was correct) and adjust it accordingly. I can.

Yes, there's an argument for not adjusting the generated code but instead providing more input examples to improve the accuracy of what is produced.

But, will that always be the best option? Time will tell, but I can see lots of scenarios where it's much quicker and simpler to manually tweak a generated algorithm rather than write significantly more input examples.

Side thought: Could I create a method signature and multiple test case, then have AI generate an implementation that makes all the tests pass? - It might be a simpler way to write a complex algorithm....?

I try and remember that my ultimate goal is rarely to write code but to provide value as a result of what I create.

If I can create more value by not writing code, or I can create value faster by not writing code then that's a good thing.

I do, however, enjoy the creative act of writing code. I don't think I'll be stopping any time soon. I'm told there's something special about my code: it's easy to read. (I was recently approached about doing some work for someone because they appreciated the readability of my code!)

I've not studied code generated by any AI sufficiently enough to say how readable it is, but I do know that the readability (and therefore understandability) of code is probably the most important thing. Yes, readability is probably even more than being functionaly correct.

Code is read a lot more than it's written. Code also needs to be changed (as bugs are fixed, requirements change, and features are added.) If generated code can't easily be understood, and changed it's just going to produce more problems in the long term.

If you can't read (& understand) the code, it's much harder to know if it is correct. Or change it when you need to.

How often have you encountered systems that were originally built quickly but end up having to be rewritten to add a feature as that's going to be easier/quicker/cheaper than modifying what already exists? I imagine it's more than you want or expect.

I write code so that I can quickly and easily see what it does. I don't want to have to try and remember all the nuances and finer points (I couldn't even if I trie.) Nor do I want to have to repeatedly look at external documents.

When AI can write the code I need in a way that's just as easy to understand, I'll use it.

Ultimately, AI is a tool. Knowing about different tools, how to use them, and what they're good for can improve productivity and the quality of what is produced. You just can't rely on a single tool.

Give a Great First Technical Talk: Share your experiences at user groups and meetups - Available now!

 

My third book is now available on Kindle. It's called: Give a Great First Technical Talk: Share your experiences at user groups and meetups

User groups and meetups are perfect places to gain public speaking experience. They also provide a great way to build professional and personal networks by sharing what you’ve been working on.

This book provides a simple way to give a short talk based on three questions. It’s been used successfully over many years, for many topics, by hundreds of people.

This short guide shows how to use these questions and explains why it works.

For group organizers, the outlined talk structure provides a simple and practical way to build community while encouraging and supporting new speakers.

It's a very short book (about 7000 words) and should take you less than an hour to read.

It's 24 chapters plus an appendix.

Yes, very short chapters. To give you a sample, here are the first two.

Tech Advent Calendars - 2022

It seems that the idea of communities releasing posts on tech topics each day through December is becoming increasingly popular.

Here are the ones I know about

Festive Tech Calendar posts daily articles and videos on various topics.

.NET Advent Calendar posts daily on things related to .NET

.NET MAUI Advent Calendar posts (week) daily about .NET MAUI 

C# Advent Calendar reveals 2 new C# blog posts every day

PowerAdventKalender daily videos about the Power Platform [In German]

WPMarmite  daily WordPress related posts

Related:

Advent of code is a series of small daily programming puzzles.

Know of any others?