links for 2008-12-21

10 comments

  1. That is terrible advice to undergrads. I would forcibly advise anyone commenting code like that to knock it off immediately.

    Comments should never explain “what” or “how” because those change, and when comments and code can conflict, comments stand a great chance of lying, so must be ignored. Comments should only ever explain “why.”

    If you find yourself having to write explnatory comments because what a method does is unclear, the fix for that is generally to rename your method so that its name explains its purpose — and if its purpose is hard to explain in a few words, consider whether your design actually makes sense in the first place.

    Really, what’s easier to understand:

    int GetSumOfNLargestElements(int[] inputArray, int n) {
    
 if (inputArray.Length < n || n <1) { 
    
  throw new InvalidArgumentException();
    
 }
    
 return (from i in inputArray
    
  orderby i descending
    
  select i).Take(n).Sum();
    
}

    or:

    /* FUNCTION PURPOSE:  Get the sum of the "n" largest elements
    
 *                    from a given array.
    
 * INPUTS:  a -- the input array
    
 *          n -- the count of how many elements to sum
    
 * PRECONDITIONS:  n must be positive and a must have at least 
    
 *                 n elements; otherwise, an exception will be
    
 *                 thrown
    
 * DEPENDENCIES:  This method uses the Linq extension methods
    
 *                Select, OrderBy, Take, and Sum, and depends on
    
 *                the System.Linq namespace, as you can see from
    
 *                the header of the file where I declared that.
    
 * SIDE EFFECTS:  None
    
 * OUTPUTS:  Returns an integer value containing the sum of the
    
 *           n largest values in the array.
    
 */
    
int retsnl(int[] a, int n) {
    
 if (a.Length < n || n <1) {
    
  throw new InvalidArgumentException();
    
 }
    
 return (from i in a
    
  orderby i descending
    
  select i).Take(n).Sum();
    
}

    If you know how to program in the language used here, the first is much, much more obvious with a zillion times less visual clutter and redundancy. Beginning programmers like the second because they don’t know how to program, so want English translations of the obvious. This habit needs to be broken, not reinforced.

  2. And of course to get the full effect, the second example should really say that its dependencies are Array.Sort and its side effects are that it sorts the input array, because they changed the implementation but never changed the comments, and now the comments are not just useless but are actively lying to you.

  3. I think there’s a very significant difference in what you want from professional programmers and what you want from, say, physicists who need to do a little programming now and then along the way to some other goal. While you may be right regarding the commenting practices of professional programmers, I would much rather see something like your second example in code written by a research student, or a student in one of my classes.

    Computer programming is something a physicist needs to know how to do, but it’s not something that an experimentalist like me will do every day, or even every year. We don’t spend enough time fiddling with code for it to always seem intuitive. Thus, more comments are better.

  4. I suppose if you change the dude’s advice to say “this is how you should do it if you’re not good at this, and have no intention of getting good at it, and are just going to cargo cult your way through the programming portion of the class,” I couldn’t very well disagree, but ew.

  5. Do try to bear in mind the fact that the person giving the advice is not a professional programmer or computer scientist. His CV is on the web, and his degrees are in physics and math.

    And, as the post makes clear, this is advice being given to students coming into his course on statistics without having had any programming classes. And, in fact, includes the line “Actual software engineering is another discipline, over and above basic computational thinking; that’s why we have a software engineering institute. There is a big difference between the kind of programming I am expecting you to do, and the kind of programming that software engineers can do.”

    Given the audience, I think the advice is very good.

  6. What I take exception to is the “THIS IS THE WORD OF GOD AND I WILL GRADE YOU ON IT” bit. If you say, “Hey, here are some helpful tips for novice semi-programmers — you won’t want to do this if you really know what you’re doing, but I think it’s helpful for freshmens like you who do not know what they’re doing,” that’s fine even though I think it’s still misguided. (Relying on the comments is a BAD PRACTICE. You will at some point spend HOURS trying to debug something only to find out that the code didn’t do what the comments said it did, and you were reading the comnments instead of the code.)

  8. Actually, having spent ten years in the industry at several different software companies large and small, I can safely say that the majority of professional software engineers (particularly the experienced ones) agree with Cosma Shalizi.

  9. And the reason they agree with Cosma Shalizi is that in industry, you are very often programming against a small, well-defined public API. More often than not you don’t even get to *see* the source code — but even if you can see the source code, the well-documented behavior of a public function or method should not just change willy-nilly because the programmer briefly thought of a better idea. THAT’s the definition of bad software engineering.

    Where Mike is right is that you don’t need to spend a lot of time documenting private functions. For internal code, you only need to make comments where you are doing something kind of unusual or tricky. Those instances should be rare.

  10. Yes, APIs should be documented — but documenting an API isn’t “commenting your code”, it’s defining the behavior of it. The difference there is that with an API, if the code deviates from the comment, the code is broken. In other cases, it’s almost certainly the comment that’s wrong, because the code is what’s running.

    But most programmers, most of the time, aren’t writing APIs for external consumption.

Comments are closed.