Is it so hard to comment your code?

I work on collab projects here and there and both the comments and documentation are both awful, nearly always, there are some exceptions.

This is a plea to all those who teach anyone to program. "This performs a loop" is not a helpful comment, nor is "This sets variable x to 1" where the line below is "let x = 1".

The last piece of code brings me on to my next point meaningful variable names. If x is a variable that stores the age of a machine call it ageOfMachine or age_of_machine. Not aom, not x but what it actually is, modern IDEs and text editors will fill this out for you.

Finally documentation, a good friend of mine sent me this quote a while back, I can't find the image but "Documentation is like sex, when it's good, it's great. But when it's bad it's better than nothing." Your documentation should be good, a good pattern to follow is the Node.js documentation, it tells the function, what it does and what parameters it takes.

Anyway rant over; and I'm sure that this applies to people outside of this community only.

  • 2
    You're so right. Nothing's worse than silly, meaningless comments. You're not the only one who has to fight his way through shit like this :)
  • 2
    @Klanowicz so yes I agree, if you have to comment every line of code then it's ridiculous, but a general summary of what function does is quite nice to have. It just lets you look at the description without having to read and interpret all of the code
  • 2
    @Klanowicz I disagree.

    Useful comments make the work easier - especially when working with multiple developers at the same time.
    An example would be the implementation of AES in Javascript. I have no idea of the internal functioning of AES. Without comments I would be helpless.

    In summary:
    1. Shitty code with worthless comments sucks.
    2. Shitty code with meaningful comments sucks less.
    3. Good code with shitty comments sucks.
    4. Good code with meaningful comments doesn't suck.
  • 0
    @tracktraps XD That is one of the best lists I have seen in a while. I feel like that needs to be a tshirt
  • 1
    Code as if the person who will maintain your code is a violent psychopath who knows where you live
Add Comment