What are your "hard rules" about commenting your code?

 

I have seen the other questions but I am still not satisfied with the way this subject is covered.

I would like to extract a distiled list of things to check on comments at a code inspection.

I am sure people will say things that will just cancel each other. But hey, maybe we can build a list for each camp. For those who don't comment at all the list will just be very short :)

I have one simple rule about commenting: Your code should tell the story of what you are doing; your comments should tell the story of why you are doing it.

This way, I make sure that whoever inherits my code will be able to understand the intent behind the code.

  • I comment public or protected functions with meta-comments, and usually hit the private functions if I remember.
  • I comment why any sufficiently complex code block exists (judgment call). The why is the important part.
  • I comment if I write code that I think is not optimal but I leave it in because I cannot figure out a smarter way or I know I will be refactoring later.
  • I comment to remind myself or others of missing functionality or upcoming requirements code not present in the code (TODO, etc).
  • I comment to explain complex business rules related to a class or chunk of code. I have been known to write several paragraphs to make sure the next guy/gal knows why I wrote a hundred line class.

    • If a comment is out of date (does not match the code), delete it or update it. Never leave an inaccurate comment in place.

    链接地址: http://www.djcxy.com/p/85282.html

    上一篇: 在IF THEN ELSE构建中放置注释的地方

    下一篇: 关于评论你的代码有什么“硬性规则”？