links for 2008-12-21 : Uncertain Principles

Search

Profile

You've read the blog, now try the book: How to Teach Physics to Your Dog is published by Scribner, and available wherever books are sold.

"Uncertain Principles" features the miscellaneous ramblings of a physicist at a small liberal arts college. Physics, politics, pop culture, and occasional conversations with his dog.

"Prof. Orzel gives the impression of an everyday guy who just happens to have a vast but hidden knowledge of physics." (anonymous student evaluation comment)

Emmy is a German Shepherd mix, and the Queen of Niskayuna. She likes treats, walks, chasing bunnies, and quantum physics.

Greatest Hits

Chateau Steelypips

links for 2008-12-21

Category: Links Dump
Posted on: December 21, 2008 4:01 AM, by Chad Orzel

Sciencewomen : Thoughts on my AGU experience

Don't tell my university administrators, but sharing my latest science results is only a tiny fraction of the reason to go to a conference like AGU. Even hearing the latest and greatest science is not the entire reason. This is a lesson that is taking me a long time to learn.

(tags: science academia jobs meetings)
Respectful Insolence: Your Friday Dose of Woo: When a mad mathematician meets quantum homeopathy

Oh, Lionel Milgrom, no!

(tags: science blogs stupid medicine)
Minimal Advice to Undergrads on Programming

"You should treat "Thou shalt comment thy code" as a commandment which Moses brought down from Mt. Sinai, written on stone by a fiery Hand. I will treat it so when I grade you."

(tags: science education academia computing)
james_nicoll: Calibration

A highly scientific study of the incidence of bone breakage in people who read LiveJournal. It's more amusing if you know James's history.

(tags: medicine blogs science)

Share this: Facebook Twitter Stumbleupon Reddit Email + More

TrackBacks

TrackBack URL for this entry: http://scienceblogs.com/mt/pings/88408

Comments

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.

Posted by: Mike Kozlowski | December 21, 2008 9:39 AM

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.

Posted by: Mike Kozlowski | December 21, 2008 9:46 AM

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.

Posted by: Chad Orzel | December 21, 2008 9:55 AM

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.

Posted by: Mike Kozlowski | December 21, 2008 10:03 AM

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.

Posted by: Chad Orzel | December 21, 2008 10:09 AM

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.)

Posted by: Mike Kozlowski | December 21, 2008 10:24 AM

Oh, Lionel Milgrom, no!

To be nitpicky, the proper form is OH [NAME] NO--that is, no commas--after OH JOHN RINGO NO.

Posted by: Kate Nepveu | December 21, 2008 11:57 AM

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.

Posted by: Evan Goer | December 21, 2008 12:35 PM

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.

Posted by: Evan Goer | December 21, 2008 12:47 PM

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.

Posted by: Mike Kozlowski | December 21, 2008 1:53 PM

Uncertain Principles

Search

Profile

Recent Posts

Recent Comments

Greatest Hits

Chateau Steelypips

Blogroll

Scientists

Academics

Interesting People

Books

Punditry

Categories

Archives

links for 2008-12-21

TrackBacks

Comments

Post a Comment

ScienceBlogs

Search ScienceBlogs:

Go to:

Channels

RSS Feeds

More ScienceBlogs

Editor's Picks

Science News from NYTimes.com »

From NYTimes.com