Skip to main content
Software Engineering

You are not logged in. Your edit will be placed in a queue until it is peer reviewed.

We welcome edits that make the post easier to understand and more valuable for readers. Because community members review edits, please try to make the post substantially better than how you found it, for example, by fixing grammar or adding additional resources and hyperlinks.

3
  • 5
    I find it a good rule to follow that if the code reviewer asks me why I did something (and after a conversation we agree that it was the right choice) then the maintainer will probaly have the same question and the why needs to be explained. This is often true even when the maintainer is me but six months or more have passed. This is especially true when the requirement was not something we would normally do. Honestly, how many devs go back and research all the old requirements to see why we did something? Commented Feb 17, 2012 at 16:36
  • As time goes by I use fewer comments than I used to, preferring to use object, function, and variable names that tell the story a much as possible. I do still try and put myself in the place of the poor smuck who will wind up maintaining my code, who will appreicate the odd extra clue for things that aren't crystal clear. Commented Feb 17, 2012 at 16:51
  • 2
    It's all about how long it takes to comprehend the code afterwards. If having a comment makes it quicker for someone else to pick up the code and understand it, you should put them in there. The time taken to write and maintain them is completely irrelevant, most coding time (by far) is spent understanding with existing code and dealing with problems caused by a lack of understanding existing code. If you don't believe me, count the LOC in your project and divide by man hours to see how much actual code is typed an hour over the life of a project--it's not as much as you think. Commented Nov 15, 2014 at 9:34