• jonathanvmv8f@lemm.ee
    ·
    edit-2
    2 months ago

    Asking as a newbie programmer: how do you suggest we write comments that explain the 'why' part of the code? I understand writing comments explaining the 'what' part makes them redundant, but I feel like writing it the former way isn't adding much help either. I mean, if I created code for a clock, is writing "It helps tell what time it is" better than writing "It is a clock" ?

    It would really help if someone could give a code snippet that clearly demonstrates how commenting the 'correct' way is clearly better than the way we are used to.

    • TheDoctor [they/them]
      ·
      edit-2
      2 months ago

      I often use comments as ways to say, “I know this is cursed, but here’s why the obvious solution won’t work.” Like so:

      /**
       * The column on this table is badly named, but
       * renaming it is going to require an audit of our
       * db instances because we used to create them
       * by hand and there are some inconsistencies
       * that referential integrity breaks. This method
       * just does some basic checks and translates the
       * model’s property to be more understandable.
       * See [#27267] for more info.
       */
      

      Edit: to answer your question more directly, the “why not what” advice is more about the intent of whether to write a comment or not in the first place rather than rephrasing the existing “what” style comments. What code is doing should be clear based on names of variables and functions. Why it’s doing that may be unclear, which is why you would write a comment.

    • pixelscript@lemm.ee
      ·
      edit-2
      2 months ago

      I recognize three kinds of comments that have different purposes.

      The first kind are doc block comments. These are the ones that appear above functions, classes, class properties, methods. They usually have a distinct syntax with tags, like:

      /*
       * A one-line description of this function's job.
       *
       * Extra details that get more specific about how to use this function correctly, if needed.
       *
       * @param {Type} param1
       * @param {Type} param2
       * returns {Type}
       */
      function aFunctionThatDoesAThing(param1, param2) {
          // ...
      }
      

      The primary thing this is used for is automatic documentation generators. You run a program that scans your codebase, looks for these special comments, and automatically builds a set of documentation that you could, say, publish directly to a website. IDEs can also use them for tooltip popups. Generally, you want to write these like the reader won't have the actual code to read. Because they might not!

      The second kind is standalone comments. They take up one or more lines all to themselves. I look at these like warning signs. When there's something about the upcoming chunk of code that doesn't tell the whole story obviously by itself. Perhaps something like:

      /* The following code is written in a weird way on purpose.
      I tried doing <obvious way>, but it causes a weird bug.
      Please do not refactor it, it will break. */
      

      Sometimes it's tempting to use a standalone comment to explain what dense, hard-to-read code is doing. But ideally, you'd want to shunt it off to a function named what it does instead, with a descriptive doc comment if you can't cram it all into a short name. Alternatively, rewrite the code to be less confusing. If you literally need the chunk of code to be in its confusing form, because a less confusing way doesn't exist or doesn't work, then this kind of comment explaining why is warranted.

      The last kind are inline comments. More or less the same use case as above, the only difference being they appear on the same line as code, usually at the very end of the line:

      dozen = 12 + 1; // one extra for the baker!
      

      In my opinion, these comments have the least reason to exist. Needing one tends to be a signal of a code smell, where the real answer is just rewriting the code to be clearer. They're also a bit harder to spot, being shoved at the ends of lines. Especially true if you don't enforce maximum line length rules in your codebase. But that's mostly personal preference.

      There's technically a fourth kind of comment: commented-out code. Where you select a chunk of code and convert it to a comment to "soft-delete" it, just in case you may want it later. I highly recommend against this. This is what version control software like Git is for. If you need it again, just roll back to it. Don't leave it to rot in your codebase taking up space in your editor and being an eyesore.

      • TheDoctor [they/them]
        ·
        edit-2
        2 months ago
        dozen = 12 + 1; // one extra for the baker!
        

        I got mad at this when I first saw it but then I remembered there’s some code at work that defines an hour as 50 minutes

        pain

    • flashgnash@lemm.ee
      ·
      edit-2
      2 months ago

      "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)

    • QuazarOmega@lemy.lol
      ·
      edit-2
      2 months ago

      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

      • jonathanvmv8f@lemm.ee
        ·
        2 months ago

        Interesting to see your opinion on how commenting shouldn't be mandatory. I specifically go the extra mile to ensure my code is readable for everyone, by naming my variables and functions to be as self-explanatory as possible and breaking down long expressions to store chunks in variables. This is why I was feeling confused as to what more I could add to explain my code better, though I must admit there are still considerable complex portions in some of my projects that would appreciate similar simplification.

        • QuazarOmega@lemy.lol
          ·
          2 months ago

          Yes, I feel like some kind of bell should ring in your brain when something needs to be commented, most often if you struggled to write out the solution or you had to do a lot of digging from various places to achieve the final resulting piece of code, it doesn't make a lot of sense to pressure yourself into thinking you should comment everything, because some knowledge has to be assumed, nowadays you could even add that if someone completely extraneous to the codebase entered without any knowledge, they could feed the parts of code they need to understand into some LLM to get a feel for what they're looking at, with further feedback from actual devs though, you never know what random bs they might write.
          Good one on the variables to store results of expressions, I agree with that method, though I always forget to do that because I get so lost in the pride of writing that convoluted one-liner that I think, "oh yeah, this is perfectly beautiful and understandable 😇", I have to check myself more on that.

          complex portions in some of my projects that would appreciate similar simplification

          So I'm not alone on that haha.

          This is why [...] better

          Sorry, what's the subject of that?

          • flashgnash@lemm.ee
            ·
            2 months ago

            This is unfortunate for new programmers cause I think it's some kind of learned instinct rather than a hard rule

          • jonathanvmv8f@lemm.ee
            ·
            edit-2
            2 months ago

            This is why [...] better

            Sorry, what's the subject of that?

            I was just referring to my original question i.e. how I should write comments in my code to explain its working if I have already done so in the code itself