Variations on "the boy scout rule" in coding

Many developers talk about versions of the boy scout rule of:

"Try and leave this world a little better than you found it."

Not everyone interprets this the same way and I'm aware of 3 basic variations:

1. Make improvements as part of every change.
2. Leave it (the code) as you'd like to find it.
3. Leave the code a little better than you found it.

Some developers use variation one as an excuse to include their preferences or desires as part of other changes.

Some developers use variation two as an excuse to rewrite the pieces of code they're working on in the way they'd have written it originally.

Some developers think that variation three means that they have to make other changes to a codebase in addition to whatever new feature or bug fix they're working on.

I'm not sure it's any of these interpretations.

This "rule" or "principle" is generally good. Understanding how some people might be manipulating or mis-understanding it can be more helpful.

I like to understand the rule to mean:

"While I'm in this area of the code, are there any important things that also need working on? Or are there any simple fixes I can also address while I'm here?" 

I'll then make those changes as separate commits and/or PRs either immediately before or after whatever task caused me to look at that code.*

I've previously heard this as "code-gardening". It's like the day-to-day removing of "weeds" you notice while doing other things in the garden.

Hmm, there's probably a gender neutral version of this rule we should also consider using instead.

* Side note: I massively improved the work rate at one company when I suggested they switch from randomly assigning changes as part of each release to having all changes related to one area of the code be done by one person and at the same time. This was a very large and very old codebase with a medium-sized team working on it. The change in allocating work removed the majority of merge conflicts and issues from multiple people wanting to work on the same files at the same time. It allowed people to gain a deeper knowledge of some areas of the code, rather than everyone having a superficial knowledge of a lot of it. In turn this meant that solving trickier problems became easier as someone already knew the code well. The change in working allowed developers to take "ownership" of the code they were working on as they'd spent so much time on it and so cared about the quality. And it increased collaboration between developers when they were assigned a new area to work on with the next release. "You, worked on this area for the last release, what do I need to know before I take it over?" Overall, they started shipping faster and with fewer bugs being introduced.

I'm reminded of that change when I hear someone mention the BS rule.

Maintainable software requires these three things

For software to be considered maintainable, it requires 3 things:

1. For there to be (documented) knowledge of everything the software does (and doesn't/shouldn't) do.
2. For there to be a simple way of verifying the software behaves as intended.
3. For it to be written in a way that makes it clear to a person looking at the code what it does, so it avoids any unintentional side effects when changed.

Point 1 doesn't require a specific format or way of recording this information. Use what works best for you, the team, the company, and the project.

Point 2 can involve a combination of tools and may require some manual effort.

Point 3 is dependent upon the skills and existing knowledge of the person making a change. It's okay to require a minimum level of knowledge of the language, framework, codebase, etc. The goal, as far as possible and in combination with other requirements, is to have unambiguous code that is clear about what it does. (With documentation--and possibly comments--explaining why, where necessary.)

"As an architect, part of my job is to improve the way we do things"

I was recently listening to a podcast and was struck when the interviewee (a "senior software architect" at a large company) confidently stated that:

"As an architect, part of my job is to improve the way we do things."

Two things jumped out at me about this statement and the way it was made:

1. It implied that other people at the company don't look for ways to improve things.
2. It implied that other people at the company aren't allowed to suggest improvements.

I find this concerning.

I consider it everybody's job to always be on the lookout for ways to improve things.

Not that people should be spending a lot of dedicated time focusing on looking at and evaluating alternatives, but that everyone should have an awareness of challenges and opportunities for improvement and should share these when appropriate.

Many years ago, after the weekly developer team meeting at a company I was about to leave, someone else on the team asked why I had suggested a change to a process in that I'd be leaving in a few days.

I made the suggestion because it would be better for everyone working there. Even if that only included me for a few more days.

That other person was happy to be told what to do and then do it. No questions asked.

I don't want to work like that (and probably wouldn't last that long in such an environment.)

Why UI code matters

As a simplification, there are three types of software:

1. Client/frontend
2. Headless/backend
3. Embedded

(Sure, there is some overlap and some things straddle these loose definitions.)

What separates client/frontend software from the others is that it has a graphical user interface (GUI).

I'm a big fan of GUIs.
I like that they make software easier to use because I can see things and don't have to remember as many options, commands, or a set of seemingly magic words to get the software to do what I want.

For many, many people, GUIs make software possible, usable, and desirable.

However, for many developers, creating GUIs can be a source of frustration.

Regardless of whether using markup to describe the structure of the code or an imperative language that describes how to create it, GUI code can easily become verbose and hard to maintain.

If code is hard to maintain it becomes slower and therefore more expensive to modify without unintended consequences and negative side effects.

If spending extra time modifying hard to change code that means less time for doing other work. Such as fixing bugs or adding new features.

There are also the negative emotions and blows to motivation developers feel about having to work with hard to maintain code.

The GUI is also important as it's the part of the application that people (users) see and interact with. It's what many people will know as the face of the application that they may spend hours looking at each day. They may spend more time looking at it than other people or the faces of their loved ones. For something that gets that much time and attention from the people using the software, doesn't it deserve adequate consideration from a development perspective too?

It can be easy to dismiss the GUI as less important than other parts of a code base, but doing so is a mistake.

If it's a "proper" programming language is irrelevant

I changed the way I think about programming when I realised that compiled software is predominantly made of three things:

1. Binary assets (images, fonts, etc.)
2. Text files written (and/or readable) by people
3. Items generated by the above.

It's the second group that's most interesting.

Regardless of whether those text files are scripts, "code" to be compiled, mark-up, or pretty much anything else: if people are going to read (and/or write) it, isn't it beneficial that those files:

• are easy to read
• are easy to write
• are consistently formatted
• use meaningful words (names) to aid comprehension 
• are unambiguous 
• avoid duplication 
• are succinct (so as to avoid unnecessary verbosity)
• highlight issues/mistakes (or make them easy to spot)
• have good/appropriate tooling to aid in working with them

When this isn't true, those files are harder to maintain. This makes making changes lower and, therefore more expensive.

99.985% of coding is maintenance*

Maintaining code means changing it.

Those changes could be alterations to what's already there or in addition to what exists.

This isn't only true once a version has been released or shipped.

This is also true during initial development. 

Once there is other code, this needs to be read and understood, and additions/changes made in light of what already exists. 

Whether there is one existing line of code or one million; if what exists is hard to understand and reason about, future alterations to the code can be hard to integrate and risk unintended consequences. Both of which take more time/money. 

Maybe that's not a problem for you, but every developer I've ever met has more things they need to do. More bugs to fix, more features to add, or new products to create. Having more maintainable code means they get to more of those things; and faster!

Optimize for maintenance (ease of reading/comprehension) to save time/money in the short, medium, and long terms.

* Not a fact but an educated approximation.

"This is just demo code" is not an excuse

Many, many times, I've seen and heard people show code for the purpose of demonstrating something.

To allow them to focus on a specific aspect they may do some things in a sub-optimal way or a way that makes future maintenance of that code harder.

Sadly, it's common for such demonstrations to be accompanied by the disclaimer that "this is just demo code and you shouldn't write code like this in real projects." 

Technically, such disclaimers are good, but they're worthless if there is no separate example of what good looks like. (Ideally, the person giving the demonstration will point to such examples.)

If all the code people ever see is "demo quality" and not what "should" go in a robust, production-quality code base, that's all they'll ever write.

This also applies to overall maintainability.

If parts of a codebase are over-simplified/neglected/mistreated/obscured to give prominence to the particular aspect being demonstrated, it can be easy for people to think that the maintainability of ALL code isn't important, and so they start writing code like that too.

Please don't give such demos.
And, please, call me out if you ever see me doing this.

Speaking at conferences and being careful about what I wish for

Today, I was privileged to get to speak at the first MAUI Day in London. (I expect to write more about the conference overall and the things I showed--some for the first time anywhere--in the coming days.)

One of the aims of the talk was to get people thinking about something in a new way. 

Based on conversations with many of the people I spoke to after my talk, I was successful. 

However, what I didn't realize is that "you've really got me thinking" is a bit of a conversation stopper.

I need to let people have time to think.
I helped people recognize that something they thought to be an unchanged absolute doesn't have to be that way.
The status quo isn't the only option, and there are simple and not-so-simple ways of making significant change for the better.

For people who have been doing something for many years, to suddenly be shown and accept something new can be a lot to take in.

I wanted people to appreciate the situation so we could start having conversations about improving things.

I'm ready to have those conversations now, but others need more time to process their thoughts.

It would be nice if there was another conference next week where we could continue the conversation once people have had that mental processing time. Sadly, that's not the way attending conferences works (especially when so many attendees had travelled a long way to be there).  It's also rare, in my experience, for a talk to potentially change people's ideas on such a level. 

Still, overall, it's definitely a positive situation. 

And I'm looking forward to some of those future conversations.

Windows Phone - I remember you well - Now what?

I recently found myself with some spare time (because of a lack of a broadband connection and living remotely), and so I did some tidying up of things I'd been meaning to get around to.

I discovered a "box of broken dreams" - a box full of old phones, tablets, and assorted electronic devices - that have long since passed their usefulness (even as test devices).

In that box were 21 different old Windows Phone devices. They ranged from one of the first test devices in the country to one of the last models released and a wide variety of things in between.

Here is a video where I look at them and reminisce.

But after that trip down memory lane, what now?

What do I do with all these old devices?

What should I do with the promotional devices that are still in their boxes?

Bonus question: Any idea how I get images off a device running Windows Phone 7.5 and that won't connect to Zune over USB? (And no, there's no file system, and while it can connect to the internet, there's no way to upload the images via a website.)

Improving accessibility in MAUI

 

.NET #MAUI has an ever-improving set of tools to help build apps that are accessible to as many people as possible.

However, I recently needed to add some accessibility-related features to one of my apps, only to find that there wasn't an easy way to do this. So, I made one.

Specifically, I created a library that means that it's possible to see if the device (Windows, Android, iOS, or Mac) that the app is running on has been configured to use reduced motion or to show text at a different size.

It means that I can easily make it so that my app doesn't show animations when a person has requested that the OS (& apps running on it) don't show motion.

Also, while the built-in MAUI text controls automatically account for OS-level text sizing, if I need to draw text myself (e.g. to add to an image), I can do this in a way that respects the needs and requests of the person using the app.

As these are both accessibility-related features, I called the library Plugin.Maui.Accessibility.

The library is available on NuGet, and the source is on GitHub.

It's an almost embarrassingly simple API exposed by the library. It just has two properties. One lets you know if the device is configured to use reduced motion. The other tells you the factor by which to scale any text.

The library is based on the great work that Gerald Versluis did with Plugin.Maui.Feature.

Originally posted on LinkedIn (Note. I currently accept all connection requests there)

What is involved in making XAML "better"?

I've talked to a lot of people about how to make XAML "better", and by that, I mean making it easier to read, understand and maintain.

Seeing the " better " principles in the abstract makes sense to most people, but how do you apply them to an existing code base?

My friend Joe had this question,  so we got together on a call to see how to make some changes to one of his apps.

And for the benefit of others, we recorded the conversations:

Part One - Helping Joe make XAML more maintainable

In the first part, we look at:

• Understanding existing inconsistencies
• Creating simple custom controls through inheritance
• Inheriting from an existing control and customizing the content
• Creating a simple User Control
• Applying standardization through styles.

Part Two - Helping Joe write maintainable XAML

In the second part, we focus on:

• Extracting complex nested XAML
• Using services to isolate logic
• Using messaging for simple communication scenarios between different parts of the app

I'd love to know if the is helpful, and if we should make a third part...

when "make it work, make it right, then make it fast" was wrong!

In a reflective mood today, I recalled a time when the "make it work, make it right, then make it fast" approach failed to work for me.

As part of a large-ish development team (about 20 developers, designers and testers,) I was tasked with building the data access component. It was a large, new application that was highly complex and also high profile. 

I was the first developer on the team and did some early experiments and research into the new platform we'd be building for and the new framework we were to use.

After a few weeks of R&D, I went on holiday (vacation.)

While I was away (and without my knowledge), work on the project started "properly". One of my POC/experiments was assumed to be good enough to start the work, and people were quickly added to the team. While all this was happening, the app's requirements were still being decided.

When I came back, I found people busy trying to implement the individual sections of the app they had been assigned and I was asked to work on the "common data layer" that would provide everyone access to the data they needed.

I was scrambling to provide the other developers with the data they needed while the other developers were also dealing with designs that kept changing and so needing new/different data.

I just about kept up, but as the requirements of the data retrieval and caching were still being decided and worked out, I focused on building a data access API that the other developers could use and could hide the caching such that no other parts of the code had to pay them much mind beyond being able to specify if and when cached data was or wasn't acceptable. (i.e. If the user has specifically forced/requested a reload of data, then don't rely on the cache.)

I repeatedly told people, "This is how you get the data. I know it's slow, but it will get faster. I'll add the caching once things get a bit more stable." 

I either didn't say this loud enough, or people didn't want to hear it.

One day, the project manager decided that I wasn't doing a good enough job with the data retrieval as it was too slow, so someone else was assigned to it. I was to work on something less important. The other person had already started making the changes and my opinion or thoughts on the decision were irrelevant. A decision had been made.

Very quickly, the other developer got the caching working. Things were stable by then, and the code was clearly laid out with comments and TODOs indicating what caching had to go where and how to implement it. I'd been leaving comments and notes for myself, so I knew what still needed to be done.

When the other developer showed what they'd done, they were praised as the savior of the data access code as they had done something I hadn't (and so it was assumed I couldn't.) My competence was also questioned: why hadn't I done something the other developer could do in a seemingly quick and easy fashion?

I had assumed that getting it right and then making it fast was the way to go. 

The powers that be wanted something faster, sooner.
They were also used to things having to be changed and reworked repeatedly until they were right. The idea that anyone could get the design right the first time was anathema to them.

What went wrong:

• We weren't clear about goals and expectations.
• Communication was incomplete.
• We were working off different assumptions about what was required and what was good enough at the current stage of development.

What I'd do differently today:

• Firstly, I'd try and avoid the situation where lots of people start working on a codebase where everyone is doing different things as we all try and learn a new platform, and while the requirements were still being established.
• Be clearer about requirements and deliverables.
• Be more transparent about my progress and expected deadlines.
• Possibly, try and show something that mimics the complete final experience as early as possible. ('This part of the code shows what the final user experience will be like, but as these other parts are still in development, we haven't flipped the switch on ')
• If there's more work than can be done in the time, establish prioritisation. ('I'm deliberately not focusing on the performance yet so I can ensure everyone has the data they need and isn't blocked. Once that's done, I'll add the caching. I know how to do it, and it won't take long, but I don't want to hold other people up. Is this Ok?')

The above all happened over a decade ago but still has relevance. ;)

"We don't write design docs, we write code"

If you "don't write design docs, [but you] write code", then:

How do you know what the code is supposed to do and if it does the right thing?

AI can't tell you why the code was written

I recently heard of a new "AI" based tool for developers that can explain both what a piece of code does and why.

The claim about "why" can easily sound appealing, but it is very open to misinterpretation.

It may be possible for the tool to explain why the code works, but it can't explain why the code exists.

It can't say why this code is the best way to solve the problem it exists to address or what the person using the software is trying to achieve.

It's necessary to know more than just the code to understand why software exists and what it does for the people who use it.

I know developers (and many companies) don't want to hear it, but it's necessary to record (document) more than just the code.