• 4 Posts
  • 837 Comments
Joined 2 years ago
cake
Cake day: June 12th, 2023

help-circle













  • Later on, I learned that an excess of comments is actually not considered a good practice.

    Pointless or uninformative comments are not good, regardless of the quantity.

    Useful and informative comments are always good, regardless of the quantity.

    I learned that comments might be a code smell indicating that the code is not very clear.

    When I’m looking at someone else’s code, I want to see extensive, descriptive comments.

    Good code should be so clear, that it doesn’t need comments.

    That hits me like something a teacher tells you in a coding class that turns out to be nonsense when you get to the real world.

    I’m not sure how others do it.

    As I’m coding, the comments form part of my plan. I write the comments before the code. As I discover I’ve made incorrect assumptions or poor decisions, I correct the comments with the new plan, then correct the code to match the updated comments.

    As a final step in coding, when I feel it is complete, I’ll review comments to determine what should remain to help future me if I ever have to dig into it again.

    Variable names should be reasonably memorable and make contextual sense, but that’s it. That’s what they exist for. Don’t overload the purpose of anything I’m the code.