I've seen quite a lot of code that kind of looks like this:

   // Increment the total
   log.Debug("total before increment=" + total);
   total++;
   log.Debug("total after increment=" + total);
   

I find myself looking at it and going where is stuff actually happening!

I sort of wish someone would allow comments and logging to be combined as language features.

Check out Smart::Comments module in Perl [1].

It allows the specially-formatted comments to produce debugging output.

From the synopsis:

    use Smart::Comments;
     
    my $var = suspect_value();
     
    ### $var
     
    ### got: $var
     
    ### Now computing value...
     
    # and when looping:
     
    for my $big_num (@big_nums) {  ### Factoring...      done
        factor($big_num);
    }
     
    while ($error > $tolerance) {  ### Refining--->      done
        refine_approximation()
    }
     
    for (my $i=0; $i<$MAX_INT; $i++) {   ### Working===[%]     done
        do_something_expensive_with($i);
    }

[1] https://metacpan.org/module/Smart::Comments

Noooooo..... Not magic comments.............

Magic comments are evil, the pox of the earth, etc. I have nothing good to say about comments as code. This totally messes up the separation between code and comment.

The typical case where this happens is that the logging was added because of some bug somewhere and this was put in place to figure out what was going on with total. See it as an archaeological record more than anything else ;-)

Hm, my code didn't format as intended. What you wrote is what I meant.