• potustheplant@feddit.nl
    link
    fedilink
    arrow-up
    14
    arrow-down
    1
    ·
    4 months ago

    Hard disagree. It’s a lot easier and faster to understand a function that is prefaced with a small line of text explaining what it does rather than trying to figure it out yourself.

    It’s not about whether you can understand the code or not, it’s about efficiency and clarity.

    • Aurelius@lemmy.world
      link
      fedilink
      arrow-up
      7
      ·
      4 months ago

      Yeah, just 15 seconds and jot down a comment. Whenever I’m even hesitant, I just leave a comment. Doesn’t hurt anything and it can always be removed if not needed

      Easier to remove later rather than add it after the fact

    • Aux@lemmy.world
      link
      fedilink
      arrow-up
      4
      arrow-down
      5
      ·
      4 months ago

      Hard disagree - that’s just dumb:

      // Calculates tax
      function calculateTax() { }
      
      • uis@lemm.ee
        link
        fedilink
        arrow-up
        11
        arrow-down
        1
        ·
        edit-2
        4 months ago

        Hard disagree - that’s very helpful:

        // Calculates Personal Income Tax by formula from section 1.2.3 of tax code. Other taxes like VAT are not calculated.
        function calculateTax() { }
        
        • Aux@lemmy.world
          link
          fedilink
          arrow-up
          1
          arrow-down
          5
          ·
          4 months ago

          If it calculates personal income tax, just call calculatePersonalIncomeTax.

            • usernamefactory@lemmy.ca
              link
              fedilink
              arrow-up
              3
              ·
              4 months ago

              I’m a new developer. Is that referring to page 123 of the in-house documentation? Version 12.3 of the code? I have no clue.

              You’d have to call it something like calculatePersonalIncomeTaxPerTaxCodeSection1_2_3, but I get exhausted just looking at that. There comes a point where the cognitive work of reading crazy long camel case names is more trouble than it’s worth.

              An explanation of what specification a function was written to implement is a perfectly appropriate comment. Could be improved by a direct link where possible. But it’s worth noting what that comment isn’t doing - specifying any implementation details. For that, I really can just read the code.

    • weststadtgesicht@discuss.tchncs.de
      link
      fedilink
      arrow-up
      3
      arrow-down
      4
      ·
      4 months ago

      If done right, the “what it does” is in the method name. If your method is too complicated to summarize in its name, chances are good you should split it up or extract parts of it.