Comment from my group project teammate. You don’t need to comment every line lol

  • @[email protected]
    link
    fedilink
    13
    edit-2
    6 months ago

    Good advice, just to add to this:

    • Comments should be part of code review, having at least two pairs of eyes on comments is crucial. Something that’s obvious to one person maybe isn’t so obvious to another. Writing good comments is as hard or harder than writing good code, so having it checked for mistakes and quality is a must
    • Comments aren’t the actual documentation and aren’t a reason not to write documentation to go along with your code. Often I see larger projects where each class and function is documented in comments, but the big picture and the how and why of the overall structure is completely missing. Remember that in the real world you often have a lot of folk that need to understand how the code works, who aren’t programmers themselves. They can’t read the code or don’t have access to the code. Writing documentation is still important.
    • Please for the love of god when you change code, check if the comments need to be updated as well. Not just around the immediate area, but also the entire file/class and related files. I’ve worked on large codebases before with a high wtf factor and having the code do something different to or even opposite the comments is a nightmare. I’d rather have no comments than wrong comments.