Commenting techniques

A place to discuss the implementation and style of computer programs.

Moderators: phlip, Moderators General, Prelates

Sagekilla
Posts: 382
Joined: Fri Aug 21, 2009 1:02 am UTC
Location: Long Island, NY

Commenting techniques

Postby Sagekilla » Thu Sep 16, 2010 2:28 am UTC

Background first: I have a roughly ~3000 LOC project that I've been working on for the past year or so.
It's gone through probably over 2 dozen revisions and rewrites (I mean completely from scratch rewrite), until I decided one week to go on a furious coding rampage.

I went through and started making my code more structured and logical, trying to make it compact yet readable. No where in this process did I throw in comments (yes I know, bad idea).
I haven't touched in quite some time, mostly because this past summer I was working in my Physics department and didn't have time to do anything with it.

So now that I've come back to it, and I'm at a bit of loss as to how the hell I should comment this, since I want to work on it with my friend or others.
Only problem is, when I stare at it, I don't see how I could possibly comment it without there being these comments that make you think "NO, REALLY?"

So, I'm in a bit of a rut. I wanna add some sort of documentation and inline comments to make it clear as to what the code does, but I don't know where to start :(



tl;dr: What's some good commenting strategies for a medium sized project? Also, what's a good way to generate code documentation?
http://en.wikipedia.org/wiki/DSV_Alvin#Sinking wrote:Researchers found a cheese sandwich which exhibited no visible signs of decomposition, and was in fact eaten.

User avatar
thoughtfully
Posts: 2253
Joined: Thu Nov 01, 2007 12:25 am UTC
Location: Minneapolis, MN
Contact:

Re: Commenting techniques

Postby thoughtfully » Thu Sep 16, 2010 4:51 am UTC

Good code is fairly self-commenting. Use comments for documenting classes/functions and each source file, and any nonobvious bits within functions. You might also consider a separate document (or documents) that describes the high level design and how the whole thing interfaces to the outside.

Poke around with the search function, too. There's one or two good threads on the topic, but it pretty much boils down to the above.
Image
Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.
-- Antoine de Saint-Exupery

Axidos
Posts: 167
Joined: Tue Jan 20, 2009 12:02 pm UTC
Location: trapped in a profile factory please send help

Re: Commenting techniques

Postby Axidos » Thu Sep 16, 2010 9:12 am UTC

thoughtfully wrote:Good code is fairly self-commenting.

On that note, refactoring can do magic in a lot of situations where comments cannot.

User avatar
Berengal
Superabacus Mystic of the First Rank
Posts: 2707
Joined: Thu May 24, 2007 5:51 am UTC
Location: Bergen, Norway
Contact:

Re: Commenting techniques

Postby Berengal » Thu Sep 16, 2010 3:24 pm UTC

What it says above. Here's a list ordered by the happiness and well-being I feel when I encounter new projects/libraries:
  1. +10 happiness: Self-documenting code. The names are well-chosen, not too long, distinct enough from each other. There are no hidden dependencies or requirements; if you must call foo before calling bar, I want not doing that to be a compile-error. If a class has requirements I want them specified in the constructor. If a function uses a non-constant value, I want it to be an argument. If a method modifies some variables, I want that clearly reflected in the name. No magic tricks.
  2. +7 happiness: Documented classes/modules, explaining what its reason for existence is and its relation to the rest of the system. Secondary: A high-level description of various functions and features, preferably with examples, works as a worse-but-acceptable alternative to function-level documentation. More useful when the functions themselves are pretty obvious but their interactions are more important, or when the module is small, or for some reason grouping all the function-level documentation in one place makes more sense.
  3. +5 happiness: Function-level documentation, explaining the function's reason for existence, and roughly what it does, what its parameters mean and what the return values mean.
  4. +4 happiness: For libraries: Example-code
  5. +2 happiness: Package-documentation for larger projects that don't have a flat module structure.
  6. 0 to -10 happiness (depending on amount): Inline comments. When code, language-grok not good. Context switch make core dump. Inline comments are either useless or excuses for crappy code and they take up valuable screen real-estate. In all editors I use, I set the comment color to something very close to the background color, and when I encounter them I usually delete them, or rewrite the code to be more understandable, then delete the comments. To a lesser degree, this also applies to useless function-level comments (e.g. "/** Sets the foo. @param foo the foo*/ void setFoo(Foo foo){this.foo = foo;}")
It is practically impossible to teach good programming to students who are motivated by money: As potential programmers they are mentally mutilated beyond hope of regeneration.

snoose
Posts: 15
Joined: Thu Jan 07, 2010 10:04 pm UTC

Re: Commenting techniques

Postby snoose » Thu Sep 16, 2010 10:38 pm UTC

Going back to old code to comment it is a complete waste of time. Comments that are put in later usually don't help, they generally tell you what the code is doing (the code does this anyway), not why. As mentioned before, good code is self commenting.

Just use this experience to learn to comment code as you are writing it (if needed)...

User avatar
Area Man
Posts: 256
Joined: Thu Dec 25, 2008 8:08 pm UTC
Location: Local

Re: Commenting techniques

Postby Area Man » Fri Sep 17, 2010 4:06 am UTC

At the very least put headers on functions, summarizing inputs, outputs, error indicators, side-effects, assumptions, and purpose.
Then run a doxygen-type tool to browse the app without opening each file and reading each line. This gets everyone up to speed a lot quicker, showing structure from different altitudes.

Those comments will serve as another sanity-check to confirm that the function does what the author thought he was doing, and help guide re-writes or adding new code, e.g., may help you see that a function is too busy.

Having others add annotations as they try to grasp your code would serve everyone.
I often insert notes when debugging, re-writing lines or routines, documenting why the old way was wrong or insufficient so that the next person doesn't waste time unknowingly (or in trying to "simplify") reverting and re-discovering the problem the hard way. Sometimes the old line is even left as an illustration.
Bisquick boxes are a dead medium.


Return to “Coding”

Who is online

Users browsing this forum: No registered users and 4 guests