Friday, April 12, 2024

Don't fix that bug...yet!

An AI generated image of a computer bug - obviously

A bug is found.
A simple solution is identified and quickly implemented.
Sounds good. What's not to like?

There are more questions to ask before committing the fix to the code base. 
Maybe even before making the fix.

  • How did the code that required this fix get committed previously? 
  • Is it a failure in a process?
  • Have you fixed the underlying cause or just the symptoms?
  • Was something not known then that is now?
  • Could a test or process have found this bug before it entered the code base?
  • Are there other places in the code that have the same issue?
  • Are there places in the code that do something similar that may also be susceptible to the same (or a variation of the) issue?
  • How was the bug reported? Is there anything that can be done to make this easier/faster/better in the future?
  • How was the bug discovered? Can anything be done to make this easier, more reliable, or automated for other bugs in the future?
  • In addition to fixing this bug, what can be done to prevent similar bugs from happening in the future?
  • Is there anything relating to this issue that needs sharing among the team?

As a developer, your job isn't just to fix bugs; it's to ensure a high-quality code base that's as easy (or as easy as possible/practical) to maintain and provides value to the people who use it.
At least, I hope it is.

Thursday, April 11, 2024

Formatting test code

Should all the rules for formatting and structuring code used in automated tests always be the same as those used in the production code?

Of course, the answer is "it depends!"

I prefer my test methods to be as complete as possible. I don't want too many details hidden in "helper" methods, as this means the details of what's being tested get spread out.

As a broad generalization, I may have two helpers called from a test.

One to create the System Under Test.

And, one for any advanced assertions. These are usually to wrap multiple checks against complex objects or collections. I'll typically create these to provide more detailed (& specific) information if an assertion fails. (e.g. "These string arrays don't match" isn't very helpful. "The strings at index 12 are of different lengths" helps me identify where the difference is and what the problem may be much faster.)

A side-effect of this is that I may have lots of tests that call the same method. If the signature of that method needs to change, I *might* have to change it everywhere (all the tests) that call that method.

I could move some of these calls into other methods called by the tests and then only have to change the helpers,  but I find this makes the tests harder to read on their own.

Instead, where possible, I create an overload of the changed method that uses the old signature, and which calls the new one.

If the old tests are still valid, we don't want to change them.

If the method signature has changed because of a new requirement, add new tests for the new requirements.

Tuesday, April 09, 2024

Varying "tech talks" based on time of day

I'll be speaking at DDD South West later this month.

I'm one of the last sessions of the day. It's a slot I've not had before.

In general, if talking at part of a larger event, I try to include something to link back to earlier talks in the day. Unless I'm first, obviously.

At the end of a day of talks, where most attendees will have already heard five other talks that day, I'm wondering about including something to draw together threads from the earlier sessions and provide a conclusion that also ties in with what I'm talking about. I have a few ideas...

I've seen someone do a wonderful job of this before but it's not something I've ever heard mentioned in advice to (or books on) presenting... I guess if you'll there you'll see what I do.

Monday, April 08, 2024

Comments in code written by AI

The general "best-practice" guidance for code comments is that they should explain "Why the code is there, rather than what it does."

When code is generated by AI/LLMs (CoPilot and the like) via a prompt (rather than line completions), it can be beneficial to include the command (prompt) provided to the "AI". This is useful as the generated code isn't always as thoroughly reviewed as code written by a person. There may be aspects of it that aren't fully understood. It's better to be honest about this.

What you don't want is to come to some code in the future that doesn't fully work as expected, not be able to work out what it does, not understand why it was written that way originally, and for Copilot's explanation of the code to not be able to adequately explain the original intent.

// Here's some code. I don't fully understand it, but it seems to work.
// It was generated from the prompt: ".
// The purpose of this code is ...

No, you don't always need that first line.

Maybe xdoc comments should include different sections.

"Summary" can be a bit vague.

Maybe we should have (up to) 3 sections in the comments on a class or method:

  • Notes for maintainers
  • Notes for consumers
  • Original prompt

Writing a comment like this may require some bravery the first few times you write such a thing, but it could be invaluable in the future.

Sunday, April 07, 2024

Reflecting on 1000+ blog posts

1200 posts, 1026 published, 172 drafts, 2 scheduled
These are the current numbers for my blog. (Well, at the time I first started drafting this. I expect it will be several days before it's posted and then they will be different.)

These are the numbers I care about.

The one most other people care about is 2,375,403. That's the number of views the articles have had.

But this isn't a post about statistics. This is a post about motivation and reward.


I started writing this blog for me.

That other people have read it and got something from it is a bonus.

If I were writing for other people, I would write about different topics, I would care about SEO and promotion, and I would have given up writing sooner.

I get lots of views each day on posts that I can't explain.

I know that most views of this blog come from "the long tail," and Google points people here because there is a lot of content. The fact that I've been posting for 17+ years also gives me a level of SEO credibility.

There have been periods where I have written very little. This is fine by me. By not forcing myself to publish on a particular schedule, the frequency of posting doesn't hold me back or force me to publish something for the sake of it.

I publish when and if I want to.,

Some people need and/or benefit from forcing themselves to publish on a regular schedule. If that works for you, great. If it doesn't, that's okay, too.

Others might think a multi-month gap in posting is bad, but if that's what I want or need, it's okay. Over a long enough period, the gaps are lost in the overall volume of posts.

I'm only interested in writing things that don't already exist anywhere else. This probably holds me back from getting more views than if that were my goal, but it probably helps me show up in the long tail of niche searches.

And yet, some people still regularly show up and read everything I write. Thank you. I'm glad you find it interesting.

Will I keep writing here? I can't say for certain but I have no plans on stopping.

I'm only publishing this post because I thought I might find it useful to reflect on all that I've written, and 1000 posts felt like a milestone worth noting, even if not fully celebrating. Originally, I thought I'd want to write lots about this, but upon starting it feels a bit too "meta" and self-reflective. I don't know what the benefit is of looking at the numbers. What I find beneficial is doing the thinking to get my ideas in order such that they make sense when written down. That's, primarily, why I write. :)