8

At the risk of starting a war, what are folks opinions on in-line comments?

Personally, I'm against them. Self documenting code for the what, SCM for the why.

Comments can get out of date if not maintained; code cannot lie.

Comments
  • 2
    Im wit' ya
  • 3
    I'm generally against them because I think the code should usually be clear enough to speak for itself. However, I still think they have their place to call out specific nuances that might not be apparent from just looking at code. They can also help explain reasoning that might have taken place and is very unapparent from the code itself.
  • 3
    If you name things right, that should avoid > 90% of comments.

    Still use them for obscure stuff you know will come back to get you. And of course for funny content

    let foo = 42; // it's the answer to everything
  • 2
    I agree with @dfox (not sure if that works).

    I also like to comment classes with a short description, my contact info, and date.
  • 2
    I like inline comments if they are used correctly.. Sometimes we have to maintain programs written by contractors that apparently didn't know normal coding conventions..man do I wish they put some comments..
  • 1
    I mainly use them if I either have:

    a) A chunk of variables declared at the top which each require a few more words about them (mainly to stop long variables names). Comments then get tabbed so they look nice

    b) If I need to explain a slightly more complex if statement. I ain't breaking up the flow with comments! Inline, you go
  • 1
    Seems like the consensus so far is that they're ok if used sparingly and only when absolutely required. I can definitely agree with that
  • 2
    Inline comments are known to be an anti pattern (when misused). If you need to comment your code to explain what's going on then you should probably refactor. #SOLID

    I am also with @dfox on that there is cases where they are required. Especially if there is a line of code that fixes a critical bug. The change might be seen from GIT log but an unknown maintainer might not crawl the file GIT history before updating.

    In these edge cases the comment should point to external docs or changelog.
  • 0
    If something unintuitive or unobvious has been done (sometimes some fairly esoteric stuff is needed to hit performance benchmarks) - I comment right then and there.
    Better to have a readily available explanation than to force some poor shmuck, years from now, to figure out wtf is going on.
Add Comment