Developers like us pledge to support open-source

I was recently previously contributing to a project when something broke on the CI builds due to an issue with how a referenced library was misconfigured.

I didn't realize the library was being used. It was configured in a way that meant it didn't show up inside Visual Studio when working with the solution.

I also knew this library had a special (moral) license. This "required" those using it to support the project financially, but the business wasn't.

I wasn't using the functionality of the library, but when I discovered this, I did two things:

1. I made a personal financial contribution to the project.

2. I highlighted this to the business and indicated that they should be financially supporting the project if they wished to keep using the library. (The person who originally added the library pleaded ignorance--"But, it's open source, so we don't need to pay.")

People like us (developers like us):

• Support the people writing open-source software. Financially if possible (and requested).
• Respect the spirit of open-source licenses. Not just the minimum, enforceable legal requirements.

This incident raises other, bigger questions, but I'll discuss them at another time—maybe.

However, I mention this because I recently heard about the Open Source Pledge. An initiative to help encourage companies to "Do the right thing, support Open Source".

No, it's not going to solve the problem of funding and support for open source maintainers, but it will help.

My unique value

Having been ill most of this week, I'm feeling unmotivated and disappointed that I haven't achieved much in the last few days.

 One thing that has cheered me up a bit is the idea that:

Other people may know or be able to communicate individual ideas better than me, but I'm the only one who can put these disparate ideas together this way to produce this unique and valuable result.

I think this applies to coding, writing, events, and more... :)

Specific or vague answers to specific and vague questions

If the question is vague, is a specific or vague answer more helpful?

Actually, is either helpful?
Would clarifying the question (or scoping it) be a better response?

If the question is specific, a specific answer can be helpful, but a vague answer may help see the broader picture or help expand the view of the question.

Both can help or be useful in different contexts.

This feels like the opposite to the way to treat data. 

With data, we want to try and accept a broad range of options and return something specific or at least consistently formatted.

With questions, we want the question to be narrow (if not specific) and a potentially broad range of answers.

Now, how do I stop bringing all my thoughts back to software development? Or, more specifically, do I need to consider whether this matters?

Is it really a "workaround"?

Not using something is not a workaround.

A workaround is an alternative solution to the problem. Normally, slower, longer, or more convoluted than the desired solution (that has an issue.)

I think words matter.

I want to help people get past their problems. Even if that means doing the work of fixing things.

Some people seem more interested in arguing that a reported problem isn't something they need to do anything about than actually addressing whatever is making something hard to use.

Sometimes, I wonder if there's a gap in the market for customer service training for developers who respond to public issues and discussions on GitHub.

Emotional intelligence

Be more emotional.

But not all the time. Use your intelligence to decide when. ;) 

What's the value of reviewing a Draft PR?

Unless specifically requested, who's time is it the best use of?

trivial feedback and micro-optimizations in code reviews

When these are given, is it because there is nothing more important to say?

Or, does such feedback come from people who don't understand the bigger picture or want a quick way to show they've looked at the code without having to take the time and mental effort to truly understand it?

Before commenting

Are you just repeating what's already been said before?

Where/when appropriate, are you correctly attributing others?

Does your comment add value?

Are you adding a new/different/unique perspective?

Have you read the other comments first?

Have you thought about who (possibly many people) will read the comment?

"I'm not smart enough to use this"

 I quite often use the phrase "I'm not smart enough to use this" when working with software tools.

This is actually a code for one or more of the following:

• This doesn't work the way I expect/want/need.
• I'm not sure how to do/use this correctly.
• I'm disappointed that this didn't stop me from doing the wrong thing.
• I don't understand the error message (if any) that was displayed. 
• Or the error message didn't help me understand what I should do.

Do your users/customers ever say similar things?

Would they tell you?

Are you set up to hear them?

And ready to hear this?

Or will you tell me that I'm "holding it wrong"?

Don't fix that bug...yet!

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.

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.

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.

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.

Does code quality matter for AI generated code?

A large part of code quality and the use of conventions and standards to ensure its readability has long been considered important for the maintainability of code. But does it matter if "AI" is creating the code and can provide a more easily understandable description of it if we really need to read and understand it?

If we get good enough at defining/describing what the code should do, let "AI" create that code, and then we verify that it does do what it's supposed to do, does it matter how the code does whatever it does, or what the code looks like?

Probably not.

My first thought as a counterpoint to this was about the performance of the code. But that's easy to address with "AI":

"CoPilot, do the following:

- Create a benchmark test for the current code.

- Make the code execute faster while still ensuring all the tests still pass successfully.

- Create a new benchmark test for the time the code now takes.

- Report how much time is saved by the new version of the code.

- Report how much money that time-saving saves or makes for the business.

- Send details of the financial benefit to my boss."

Where does performance matter?

Performance matters.

Sometimes.

In some cases.

It's really easy to get distracted by focusing on code performance.

It's easy to spend far too much time debating how to write code that executes a few milliseconds faster.

How do you determine/decide/measure whether it's worth discussing/debating/changing some code if the time spent thinking about, discussing, and then changing that code takes much more time than will be saved by the slightly more performant code?

Obviously, this depends on the code, where it runs, for how, long and how often it runs.

Is it worth a couple of hours of developer's time considering (and possibly making) changes that may only save each user a couple of seconds over the entire time they spend using the software?

What are you optimizing for?

How do you ensure developers are spending time focusing on what matters?

The performance of small pieces of code can be easy to measure.
The real productivity of developers is much harder to measure.

How do you balance getting people to focus on the hard things (that may also be difficult to quantify) and easy things to review/discuss (that they're often drawn to, and can look important from the outside) but don't actually "move the needle" in terms of shipping value or making the code easier to work with?

Thought vs experiment

Scenario 1: Consider the options and assess each one's impact on usage before shipping the best idea.

Scenario 2: Ship something (or multiple things) and see what the response is. Then iterate and repeat.

Both scenarios can lead to the same result (in about the same amount of time.)

Neither is necessarily better than the other. However, it doesn't often feel that way.

Always using one isn't the best approach.

#NotesToMyself

Hat Tip: David Kadavy

Does AI mean software development will appeal to different people?

Certain personality types are attracted to software development.

The logic and absolute certainty appeals to those people.

AI removes that certainty. It's non-deterministic.

Will this put off some people who like (or need?) the absolutes?

May it attract different people with other interests and personality types?

The most important question on a PR checklist is...

Admit it, you thought I  was going to say something about Testing. Didn't you?

While testing is super important and should be part of every PR, the most important question to ask when working on something as part of a team is:

Does this change include anything you need to communicate to the rest of the team?

I've added this to PR templates and have been frustrated when "circumstances" have prevented me from doing so.

Why does this matter?

• Because if it's something low-level or fundamental, then everyone is likely to need to know it. You shouldn't rely on everyone reviewing the PR or checking everything that gets merged. 
• Because the change(s) in the PR might break the code other team members are working on.
• Because a "team" implies working together towards a common goal. Keeping secrets and not sharing things that "teammates" will benefit from knowing hurts the team and the project.

Not sharing important knowledge and information creates frustration, resentment, wasted effort, and more.

Doing things different in CI builds

Say you have a large complex solution.

Building everything takes longer than you'd like. Especially when building as part of CI checks, such as for a gated merge.

To make the CI build faster, it can be tempting to have a filtered version of the solution that only builds 'the most important parts' or filters out some things that take the most time (and theoretically change least often).

When such a filter exists, it can be tempting for developers in a team to use the filtered version to do their work and make their changes. If it makes the CI faster, it can make their development build times faster too.

However, there's an unstated trade-off happening here:

Shortening the time to build on (as part of) the CI

creates 

A reliance on individual developers to check that their changes work correctly for the whole solution.

If you get it wrong, developers (mostly?) only work with a portion of the code base, and errors can be overlooked. These errors (including things like being able to build the whole solution) can then exist in the code base for unknown periods of time......

Prompt engineering and search terms?

The prompts given to LLMs are compared to the text we can enter when searching the web.

Over time, people have learned to write search queries that will help them get better answers.

There's an argument that, over time, people will learn to write better prompts when interacting with LLMs.

However, over time, the way websites expose, format, and provide data that's fed into the search engine so that it will be more likely to be what is shown in the results for specific searches. (A crude description of SEO, I admit.)

What's the equivalent of providing data that will be used to train an LLM?

How do (or will) people make or format data to get the outcomes they want when it becomes part of the training data for the LLM?

Yes, this is like SEO for LLMs. 

LLM-Optimization? LLMO?

GPTO?