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.

11
  • 11
    If you are using a document generation system like JavaDocs or Doxygen, comments are literally documentation.
    – user53141
    Commented May 14, 2012 at 2:13
  • 5
    YANGNI (xprogramming.com/Practices/PracNotNeed.html). Document your code to your satisfaction. Let the customer (if there is ever one) pay you to write the documentation to their satisfaction. Don't worry about what a lot of people you talk to say (unless they are paying you).
    – emory
    Commented May 14, 2012 at 4:59
  • 1
    Of your 2 comments the 2nd is useless, why not replace $foo with bar. If this is not true then the comment is wrong. The first comment is wrong. It is an assignment.
    – ctrl-alt-delor
    Commented May 14, 2012 at 13:06
  • 2
    When ever you wish to add a comment, change your code to be so clear that it needs no comment. Everything is documentation, code is documentation, Comments usualy have no [additional] information, or are wrong. Document the intention the what (code contracts can help with this), and the why. Keep documentation close to the code, use comments. Documentation over Documents: Comments over Documents, Clear Code over Comments.
    – ctrl-alt-delor
    Commented May 14, 2012 at 13:11
  • 2
    Is YANGNI "you ain't not going to need it"
    – Chris S
    Commented May 14, 2012 at 15:03