Is it bad practice to comment almost every line and every function of your code?

  • 7
    Yes, and no. It is always good practice to comment, but its far too over the top to comment every line.

    The best way to describe it is that the code should document itself, and you should document your thinking/logic.
  • 0
    To me personally i'd say yes, as that way i feel like you will read more comments than code
  • 2
    I would say that you should comment the functions, what they do and all parameters to the function or events in the code. I, personally, find it very hard to follow the source code if each other row is a comment.
  • 4
    I once stumbled on a GitHub repo with some code I needed, and there were like 5 line comments for every 3 lines. It was so annoying I replaced all the lines with comments with a blank. To me, the uncommented version of the code was more understandable than the commented one.
  • 1
    Maybe also comment what some loops and ifs are meant for :) and if you do something in your code that might be confusing for someone else, maybe if you stumbled over a problem and came up with a fix, comment on why and how you got to the solution
  • 5
    As a rule of thumb, you should comment *why* you wrote your code like that and not just what it does.
  • 11
    At library/program/function level, comment *what* it is doing.

    Inside function, comment *how* it is doing what it is doing.

    At (block of) statement(s) level, comment *why* it is doing what it is doing.
  • 0
    If you're at the point where you comment everything you might need to re think your code
  • 1
    Shit comments are always bad. A developer who comments "i++" with "increase i by 1" deserves being whipped with a parallel port printer cable.

    OTOH, I have code fragments with two or three times as much comment lines than code lines. That's when the code is not an obvious representation of the problem domain, or when the code does things totally unrelated to the program logic (like coding around EMI issues or hardware bugs).
  • 0
    @Fast-Nop that's why I wrote *almost* 😄
  • 8
    Usually I comment quite a bit so that future me can recall why the fuck this or that function is present, what it's doing and in some cases have some extra nibbles from linked sources that I used.
    Example: https://gitlab.com/irc.condor/...
    (.zshrc because I'm not really a dev, just a sysadmin ¯\_(ツ)_/¯)
  • 1
    No. It helps new people to read your code. Noobs will thank you. Also it helps you to sort thoughts and see clearer.
    If senior devs are bothered by it, one can easily select a text color which is close to the background color so one can skip the comments easier.
  • 0
    It is bad practice if almost every line of your code needs commenting. Commenting by it self isnt bad practice
  • 0
    If you have to comment every line, you re eitber coding in an ancient lost language or your code is unreadable. Which is pretty much the same.

    Id say no.
  • 1
    I like beer... But to much beer...
  • 1
    I usually comment at the beginning of each function (what does the function do, what the different parameters do and what does it return). Other than that I only add extra comments when the code gets extra complicated. Anyone that reads my code should know the language good enough to understand what it does, but there are always some clever tricks that need some more explaining (although I'm not that clever a lot of the time).
  • 2
    Imo, code should be as self-documenting as possible. If it isn't, it can probably be rewritten in order to be clearer.

    Too many comments littered throughout the code become white noise and are easily skipped over. It's better to point out pertinent code points so that comments catch the eye.

    Where comments are made, they shouldn't point out anything that the code doesn't already tell you. For example, the following is redundant as the code is self-explanatory:
    // Print output to console

    It is also very good practice to name variables as obviously as possible, as this reduces the need for comments and helps self-documentation.

    A prob with commenting is that comments can become outdated if code is updated. It creates an extra maintenance step which should always be considered. This is why describing "why" the code is there is better than describing "what" it is doing.

    I generally comment:
    - Public APIs
    - Obscure practices
    - Complex algorithms (e.g. math)
  • 0
    Very unless you are writing in assembler
Your Job Suck?
Get a Better Job
Add Comment