• 𝘋𝘪𝘳𝘬@lemmy.ml
    1·
    6 hours ago

    Write an ungodly large amount of code-comments - up to a point where you add 20 lines of explanations to a 6 lines long function where two lines are variables assignments.

    Source code is for humans to read. The compiler ignores the comments.

  • MrScottyTay@sh.itjust.worksEnglish
    3·
    14 hours ago

    comment anything that needs extra info to explain what and why (if the code is not inherently self explainable)

    • spooky2092@lemmy.blahaj.zoneEnglish
      4·
      10 hours ago

      And depending on your audience or how often you (don’t) go back and review it, it can help to comment the things that are self explanatory.

      I write a lot of scripts for my team and have to make them “maintainable” by the people in my department (who are as familiar with the concept, as your buddy that calls the gym the James), so I will regularly over comment so that any ape can come along and hopefully know what the script does.

    • ☆ Yσɠƚԋσʂ ☆@lemmy.mlOP
      13·
      10 hours ago

      Works great in theory, but then people inevitably forget to update the comments and code gets out of sync with what the comment says. At which point you’re in even worse situation than not having any comments at all.

      • MrScottyTay@sh.itjust.worksEnglish
        1·
        7 hours ago

        If you’re ever the one updating code with comments and not ensuring they match to the new updates, you are the problem, the comments are not.

        • ☆ Yσɠƚԋσʂ ☆@lemmy.mlOP
          11·
          6 hours ago

          Sure, yet the fact that this happens regularly is the reality of the situation. Simply wagging your finger and saying it’s the fault of people who don’t update the comments isn’t really solving anything. Not to mention the fact that people might accidentally update the comments in a wrong way while being well intentioned. Since there’s no way to validate that the comments are correct, it’s very easy for mistakes to creep in. Anybody who’s done actual software development would understand this problem.

          • MrScottyTay@sh.itjust.worksEnglish
            1·
            6 hours ago

            This is why you have style guides, policies and safeguards, with others checking PRs as they go through to catch this sort of stuff.

            Plus I’m not saying everything should be commented. By default things should be explainable through the code and making sure variable and method names are descriptive, along with strong typing if your language has it.

            Comments are there for when the code itself is not enough. But you’re right shit always creeps in eventually regardless of the best intentions. Which is why teams need tech debt breaks where no new features are added and they go through the code fixing the niggly things that haven’t been worth fixing whilst doing other features, and ensuring critical sections (the kind that usually have comments on them) are still working as intended and described accurately.

            This is from a senior dev in the industry.

            • ☆ Yσɠƚԋσʂ ☆@lemmy.mlOP
              11·
              5 hours ago

              Again, I’m perfectly aware of how the process is supposed to work and what purpose comments serve. This is the exact same argument people make when complaining that everybody is doing Agile wrong. What I’m explaining to you, as another senior dev in the industry, is that a lot of the time people start cutting corners because they have deadlines, or they don’t understand the code because it was written a long time ago by somebody who doesn’t work at the company anymore, or a myriad other reasons. Keeping comments in sync with the code is not trivial in practice, and it’s often done poorly.