Reviewing documentation is like reviewing code

 Two quick, but key points.

1. What is it meant to do? And, where/what/who is it for?

You can't review code fully unless you know what it's meant to do. You might be able to point out if something doesn't compile or account for an edge case that hasn't been covered, but if you can't say if the code does what it was meant to do, you can't provide a useful review.

It's the same with documentation. If you don't know what the document was intended to achieve, communicate, or teach, how do you know it is correct, appropriate, or does what it's meant to?

2. Take advantage of tools before you involve people.

Use spelling and grammar checkers before asking someone to review it.

It's like asking for a code review on code that doesn't compile or meet coding standards.

"LGTM" isn't automatically a bad code review comment

What's the reason for doing a code review?

It's to check that the code does what it is supposed to and that the reviewer is happy to have it as part of the code base.

If the code changes look fine and the reviewer is happy, they shouldn't be expected or obliged to give (write) more feedback than is necessary.

What's not good is pointless comments or references to things that weren't changed as part of what is being reviewed.

A reviewer should not try to prove they've looked at the code by providing unnecessary or unnecessarily detailed feedback.

It's not a good use of time for the person doing the review.

Dealing with (responding to) those unnecessary comments is also not a good use of the time for the person who requested the review.

Writing something, even if it's a few characters (or an emoji) that indicates that the approval wasn't fully automated or done by accident is fine by me.

Of course, if all someone ever did was comment on code they're reviewing this way then that should raise different concerns.

Don't write more than you need to or for the sake of it.

Don't comment just to show you've looked at something.

Before you "add AI" to your software...

Is your software amazing?

Are there no usability issues?

Do the people using your software never have problems?

Are there "niggly" little issues that can be frustrating but have never been given enough priority to actually be fixed?

Do these things annoy, frustrate, disappoint, upset, or turn off users?

If your software (app/website/whatever) can't get the basics right, it might be tempting to "add AI" (in whatever form) to your app but the hype may not be worth it.

Yes, AI is powerful and can do amazing things, but if the people using your software see you failing to get the basics working correctly, how will they feel when you add more sophisticated features?

If you've demonstrated a failure to do simple things, will they trust you to do it he complex things correctly?

Especially if you can't explain how the new feature works or directly control it?

I'm not saying don't use AI. I'm asking that if you demonstrate to your customers that you can't do simpler things without issue, should you really be doing more complex things?

Do you run tests before checking in?

If not, why not?

That the CI will (should) run them is not an excuse for you not to.

I think it's right - but haven't checked, is not professional or good enough.

Even worse than simply relying on the CI to run all the tests of the work you've done is asking for someone else to review the changes before the CI has even run the automated checks against it. 

How would you feel if I asked you to review some of the work I've done but haven't verified it's correct and doesn't break some other part of the system?

The same applies to linting or ensuring that code meets the defined standards and formats. You shouldn't be relying on something checking this after you've said you have finished.
You really should be using tooling that does this as you go.

Some test suites do take a very long time to run. Have you tried running only the tests related to the area you're working on?

If your test suite takes too long to run:

- Have you run the bits relevant to your changes?

- What work is being done (or planned) by you and your team to make the test suite run faster?

Why you shouldn't use LangVersion = latest

Unless you absolutely must.

Never being one to be concerned about being controversial, this is why I don't think you should ever use the LangVersion of "latest" in your C# projects.

TLDR: "Latest" can mean different things on different machines and at different times. You avoid the potential for inconsistencies and unexpected behavior by not using it.

I've had the (let's call it) privilege of working as part of a certain distributed team on a large code base.

There was a global setting, hidden away somewhere, which set the LangVersion to latest. This was mostly fine until one member of the "team" updated the code to use some language features in version 10 on the day it was released. They committed the code, and other team members pulled down the changes. But now the other team members (who hadn't yet updated their tooling--it was, after all, only release day) were getting errors and they couldn't understand why code was suddenly breaking. The use of the new language features wasn't necessary, and the confusion and wasted time/effort trying to work out where the errors had come from could have been avoided if the actual number had been updated in the settings and they hadn't relied on a value that changes over time and from machine to machine. The rest of the team would still have had to update their tool, but at least they would have gotten a useful error message.

And then, there was another project I worked on.

We were using an open-source library and as part of some "clever" MSBuild task that they included in the package, it was doing a check for the LangVersion. At some point in the past, they needed to do a workaround for a specific version number and also added that workaround for "latest". In time, the underlying issue was fixed, and so when the package was used in a project that tried to use the "Latest" LangVersion, the package was trying to apply a fix that was no longer necessary and actually caused an exception. Yes, this was a pain to resolve. And yes, by "pain", I mean a long, frustrating waste of time and effort.

"Latest" may be useful if you're doing cutting-edge work that is only supported by that LangVersion setting. For all other cases, you should specify an actual number.

Of course, you're free to ignore these arguments. If you do, I'd love to know why.

If XAML has problems, why not just abandon it?

I often hear that XAML has problems, so you should use C# instead.

If you really strongly object to using XAML and can't be persuaded otherwise, feel free to only use C#. I'm not going to stop you. I'm more interested in you producing high-quality software that you can maintain and that provides value to people and they can easily use.

If you're not going to make a purely emotional decision, read on.

• If you already have existing XAML code, rewriting it probably isn't the best use of your time.
• XAML or C# is an artificial distinction. It was never the case that you were intended to only ever use XAML and not C# for the UI of anything but the most basic of applications. There are some things that are very hard in XAML, and there are some things that _should_ feel strange and unnatural when done in C#.
• There are better ways to write XAML than the very basic ways shown in almost all instructions and training material.

"Quickies"?

With the social media app/platform space as it now is, I don't have a single place where it feels right to post my shorter thoughts and ideas.

These thoughts are also often longer than the default character limits of most platforms.

So, I'm experimenting with posting them here and tagging them "quickie". No promises, I'll keep it up, but this is my site, so I thought it was a suitable place to experiment.

Why AI (LLMs) is not the solution to your problems with XAML

If you work with XAML (or you've tried to) you might think of it as being verbose, long, and hard to maintain.

For many people, AI is a solution to many technical problems. Working on the basis that if you can describe what you want or start writing it, the "AI" can generate what it thinks is likely what you want.

This is great if you're doing something that has been done many times before or you want to do something new in a very similar way to what already exists.

If, however, you aren't keen on what already exists or have complaints or concerns about the way things are currently done this isn't going to help. "AI" works by looking at existing data (mostly the contents of the internet for general-purpose and public AI services) and creating based on that.

But, come back to XAML. The criticisms aren't as much about writing the code, they are more focused on reading and modifying it. Having the code written more quickly doesn't address the problems of reading, understanding, and maintaining it. Tasks that are widely accepted to be what most developers spend most of their time doing.

If you want XAML that is easier to read, understand, maintain, and modify without unexpected consequences, you need to think about writing it differently. 

"AI" is great at giving you things similar what already exists, but if you don't want more of the same (and when it comes to XAML I don't think you do) now might be the time to start thinking about writing XAML in a different way....

Working with time is hard - why the film starts in "1 hour and 60 minutes"

Recently, I saw a display inside a cinema that said a film was starting in "1 hour and 60 minutes"

Be careful how you round times and parts of times before displaying them!

As 1 hour is 60 minutes, why didn't the display say the film starts in "2 hours"?

I can't say for sure, but I'd guess that the actual time until the start is 1 hour, 59 minutes, and more than 30 seconds.

Because there are less than 2 hours in the difference between now and the start, the hours were reported as 1. As the hours have been dealt with, they moved on to calculating the number of minutes. Because the number of seconds wasn't shown, the number of minutes was rounded to the nearest value. As there are more than 30 seconds in the timespan, this was rounded up to 60.

Ok, this is an edge case that happens in a very small window of time. Most people (customers & potential customers) will never see this.

Why does this matter?

Why care about such potentially trivial issues?

If your customers can't trust the simple things they can see, why should they trust you with things they can't see?

If your app is slow, unresponsive, crashes, displays duplicate information, displays obviously incorrect information, has usability or accessibility issues, or any of dozens more things, why should people trust you with things like:

• Keeping data secure?
• Keeping data accurate?
• Making calculations correctly?
• Meeting regulatory requirements correctly?
• Charging correctly?
• Maintaining a reliable service?

If the visible parts don't show care and attention to detail, why should the people using your software assume that you've spent more time and focus on the things people can't see?

That's not what code reviews are for!

So, you're reviewing some code.

Here are some things you shouldn't be doing:

• Leaving comments just to prove you've looked at it.
• Commenting on existing parts of the code base not directly related to the specific change/PR.
• Checking the code builds - CI should do this before you review anything.
• Checking the tests run (& pass) - CI should do this before you review anything.
• Checking that coding/styling/formatting conventions are met - tooling should enforce this, not you!

Instead, here's what you should be doing:

• Verifying the code does what it's supposed to do?
• Verifying the code does not do anything it shouldn't?
• Checking the code doesn't introduce any new issues/bugs/potential future problems.
• Confirming that you'd be happy to support and maintain this as part of the code base.
• Ensuring that any follow-up work (including accrued technical debt) is appropriately logged. 

These are not complete lists, but hopefully, they are still useful.