Minimal Advice to Undergrads on Programming

http://cscs.umich.edu/~crshalizi/weblog/593.html

by antiform • 18 years ago

6 7 18 years ago

cscs.umich.edu

jackowayed• 18 years ago

Does anyone comment to that degree?

My general policy is to follow the "Use meaningful names" policy and use that as the commenting. The meaningful names of the function give you an idea of what they do and what side effects they have. The meaningful names of the parameters tell you what they do.

Maybe it's not a perfect system, but I think it's a happy medium between eating up a lot of time commenting and having totally unreadable code

jbjohns• 18 years ago

Personally I try to only comment the "why", as this is what you can't figure out from code. Having a good revision control system allows you to log the "why" why even better.

Comments themselves have, especially when you have lots of them, a really high danger of not getting updating and therefor becoming a liability.

When you write code you are supposed to write (1) the tests, (2) the documentation and (3) the actual code. Only one of those can make what you want to happen happen, and one of those is annoying if it doesn't get fixed but one of those wont do anything if completely wrong. At least not right away.

russell• 18 years ago

I always add a one or two sentence description for a method and reference book or url if it implements a particular algorithm. I go for the meaningful names approach and document parameters and returns when meaningful isn't enough. I try to keep methods short enough that internal comments aren't usually needed.

If there are assumed states or input ranges, asserts are better than comments. Comments drift out of correctness, asserts don't.

I try to design data and configuration files with comments and then comment them with field descriptions and examples.

charcoal• 18 years ago

> Does anyone comment to that degree?

As an undergrad, it's probably better to err on the side of too many comments. Then trim them down later as you get better at it.

Good comments also probably helps your prof grade your work.

rcoder• 18 years ago

Other than the explicit dependency listing, the author's list of expected comment items reads almost item-for-item like the contents of a well-formed Javadoc block, so I think it's safe to say that a large number of both student and professional programmers do write comments that thorough.

These days, though, TDD is winning a lot of converts as a more effective means of specifying the expected behavior or code. Whether you consider that a good thing probably depends on your relative opinion of executable vs. human-readable specifications.

silentbicycle• 18 years ago

I'm not sure that asking people to document things that heavily is a good idea, because it creates a strong incentive against his latter suggestion to "Break your code into many short functions" -- you'll probably be less inclined to break out a fairly self-contained block into its own function when you know you'll have to write out yet another formal comment.

And agreed, code with many short, _well-named_ functions is generally more readable than code with a few cumbersome, but heavily documented ones. Also, the places where I'm inclined to put a line comment are usually natural boundaries for extracting code into its own function.

gommm• 18 years ago

I comment this way only when I'm coding a library or some sort that I'll be using in more than one application... Those are then the comments of my public api

Minimal Advice to Undergrads on Programming

Related Stories