Do you document "TODO" tasks?

It's common to add a TODO comment to some code you're working on, either because there's more work to be done here or because you've spotted a problem that will need to be fixed later. But how do you ensure these are tracked and followed up?

We add a TODO comment to our code when we have either identified or introduced technical debt as a way of showing other developers that there's work to be done here. It could be finishing the implementation of a feature, or it could be fixing a bug which (hypothetically) is limited in scope and therefore deprioritized. That's all well and good if another developer happens to be looking at that code and sees the comment, but if nobody looks at the code, then the problem could potentially never be fixed.

public class UserService(ApplicationDbContext context) : IUserService
{
    public async Task<UserDto> GetUserByEmailAsync(string emailAddress, CancellationToken cancellationToken = default)
    {
        var dbUser = await context.Users
          .AsNoTracking()
          .FirstOrDefaultAsync(u => u.Email == emailAddress, cancellationToken);

        // TODO: handle null user if not found
        return new UserDto
        {
            Id          = dbUser.Id,
            Name        = dbUser.Name,
            Email       = dbUser.Email,
            TenantId    = dbUser.TenantId.ToString()
        }
    }
}

Just like with any other technical debt, it's critical to ensure that it is captured on the backlog. When you add a TODO in your code, it should always be accompanied by a link to the PBI.

public class UserService(ApplicationDbContext context) : IUserService
{
    public async Task<UserDto> GetUserByEmailAsync(string emailAddress, CancellationToken cancellationToken = default)
    {
        var dbUser = await context.Users
          .AsNoTracking()
          .FirstOrDefaultAsync(u => u.Email == emailAddress, cancellationToken);

        // TODO: handle null user if not found. See: https://github.com/SSWConsulting/SSWSockDarner/issues/324
        return new UserDto
        {
            Id          = dbUser.Id,
            Name        = dbUser.Name,
            Email       = dbUser.Email,
            TenantId    = dbUser.TenantId.ToString()
        }
    }
}