I have also become a big fan of long method and field names which lead to so-called “self-describing code”. If you do this then y = x z becomes weekly_salary = normal_weekly_salary this_weeks_bonus and you won’t need comments except where you explain an algorithm or a programmer decision to do things a certain way. It also is a good indicator for when thinsg should be split up. A method which takes an open file handle and is called calculate_sales_order_and_print_receipt_and_close_file looks silly and is primed for refactoring.

Big Hint of the day: You win more points in the field for maintainability over efficiency or cleverness. It is a hard lesson to take in but one well worth noting.

I personally program in java, and thoroughly comment for javadoc. An “add()” method in a Fraction class may have a description of merely “adds two Fraction objects”, but can have more detailed notes such as whether or not the resulting Fraction is reduced or how it handles certain input.

Inside code blocks such as methods where javadoc isn’t generated, I highly support self-documenting code. code such as z = x y is self-explanatory in what it does, but perhaps not why. I agree that a comment “z is sum of x and y” is in most cases redundant, but a comment of “adding the x and y values produces this object’s z value because of their Freudian relationship” (fake) or something similar.

I can’t comment on the usefulness of such docs with seemingly redundant descriptions – I’ve never had to build them. Now, since this blog focuses more on the education level programming, I’m going to maintain my original point – tell me why you are coding a certain way!

And I include redundant comments like that in code for building javadocs . When I comment at all.

* Add this number to another.
public Number add(Number num)

This is clearly redundant. If you are writing comments in style that Bashar’s “// Z is the sum of X & Y” professor is looking for, it should be a red flag.

Maybe it’s just more difficult to write meaningful comments for such a generic example. It’s easy to understand that class Number represents a “number”, without explanation. Though I still don’t get why we have to represent it in the first place. Where is it used? Why is it implemented this certain way? Are there any special caveats or edge cases that should be pointed out? I think the latter is an especially useful type of a comment.