1. 11

This is the start of the SIGCSE thread that resulted in this article.

  1.  

  2. 6

    Angersock’s Law of Comments

    Comment every change in level of abstraction or encapsulation, and any algorithm that has subtlety–otherwise, just don’t use opaque identifier names and you’ll be fine.

    1. 3

      most of my comments tend to be either of the “why is this code here at all?” variety (which is a separate issue from algorithmic subtlety or bad variable names), or as section headers for a long function or file that for various reasons would be worse off if broken up.

      1. 1

        Special exemption for regex?! ;-)

        1. 2

          Falls under “subtlety”.

      2. 2

        Replace the urge to comment with refactoring to improve your position in the Rusty scale… http://sweng.the-davies.net/Home/rustys-api-design-manifesto

        Alternatively add an assert, think of an assert as an executable comment and at least bumps you to level 5 on the scale.

        1. 2

          Sure, if you own the API, but I comment to talk about the nasty inner workings of other APIs, because usually my API exists so you don’t have to do the dancing and ceremony of the other API yourself. If it were easy and hassle free, I’d let end users do it themselves or just not comment.