1 o’clock and 10 o’clock are the the wrong angles.

Not everything needs a comment - knowing when comments add value is the key… “what” vs “why” is usually a good indicator but some code just doesn’t need a comment.

“tells the user the current time” would be an excellent comment for a clock

I’m not the best at commenting my code, but generally I just try to think of what information I’d want to know if looking at this 10 years from now

Imo comments are best used sparingly, don’t bother commenting something that anyone with a basic understanding of programming would understand straight away by reading the code

Functions should generally be commented with what parameters are and what they’re for, plus what they output

use reqwest::Client;

// create a http client class that all other files can import 
// so as to only create one instance globally 

pub struct HttpClient {
    client: Client,

}
impl HttpClient {
        pub fn new() -> Self {
            HttpClient {
                client: Client::new(),
            }
        }

        pub fn client(&self) -> &Client {
            &self.client

        }

}

Here’s an example where if I were to stumble onto this file 10 years from now, I might think wtf is this looking at it out of context, the comment explains why it exists and what it’s used for

(we’ll ignore the fact I totally didn’t just add this comment because I suck at commenting personal projects)

the “what” is interesting on interfaces or when you generate documentation with some tool like sphinx or javadoc.

the “why” is interesting when you are somewhere inside a class or function and do something in a “strange” way, to work around a quirk in the codebase or something like that, or when you employ optimizations that make the code harder to read or atleast less obvious why somethings are done.

Write comments that explain why the code isn’t obvious just by reading it. Why did you do things the long way? What did you need to work around? Why didn’t you do the thing that anyone reading the code would expect you to do?

Also write comments that explain the purpose of the functions you use, in case the names of those functions don’t make it clear on their own.

“Why” comments make more sense as application complexity grows.

You also have to consider interaction of the code with other external systems - sometimes external APIs force you to write code in ways you might not otherwise and it’s good to leave a trail for others on your team (and your future self…) about what was going on there.

Making up an example on the spot is kinda difficult for me, but I’d look at it this way with a bold statement, you should hope that most code won’t need comments. Let’s exclude documentation blocks that are super ok to be redundant as they should give a nice, consistent, human readable definition of what x thing does (function, constant, enum, etc.) and maybe even how to use it if it’s non-intuitive or there are some quirks with it.
After that, you delve in the actual meat of the code, there are ways to make it more self explanatory like extracting blocks of stuff into functions, even when you don’t think it’ll be used again, to be used with care though, as not to make a million useless functions, better is to structure your code so that an API is put into place, enabling you to write code that naturally comes out high level enough to be understood just by reading, this thing is very difficult for me to pinpoint though, because we think of high level code as abstractions, something that turns the code you write from describing the what rather than the how, but really, it’s a matter of scope, a print statement is high level if the task is to print, but if the task is to render a terminal interface then the print becomes low level, opposite is also true, if you go down and your task is to put a character onto stdout, then the assembly code you’d write might be high level. What I mean to say is that, once you have defined the scope, then you can decide what level of knowledge to expect of the reader when looking at your code, from there, if some process feels fairly convoluted, but it doesn’t make sense to build an abstraction over it, then it is a good place to put a comment explaining why you did that, and, if it’s not really clear, even what that whole block does

//forgive my sins, it took me 2 hours to nail down this arcane spell. if anyone touches this they will know my wrath
=(/&)((//((%=)(&)%)(&()

Glory to you and your house!