Minimal Advice to Undergrads on Programming

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.

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.

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

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.

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.

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