how to comment code (the right way)

petfo · Guest

i know this isn't realy a CCS PCx related thread, but i would realy like to see how you guys comment your code.

how detailed etc. would you for example comment and explain the source code of ex_mouse.c ?

Steve H. · Guest

Commenting on comments, eh?

That's always a matter of personal taste. I personally like to write comments so I put bunches of them in. You can browse my hobby site and see some code examples at www.geocities.com/hagtronics

I would recommend that you buy and read "Code Complete" by Steve McConnell - this is the best book on coding I have ever read.

Steve H.

rwyoung · Joined: 12 Nov 2003 Posts: 563 Location: Lawrence, KS USA

Comment as much as the code needs and no more. Twisted Evil

In my opinion, comments have two lifetimes. Thier first lifetime is during program creation and debug when the likelyhood of the same person who wrote the code and comments will also be reading the comments. Their second lifetime is maintenence when it is more likely that somebody other than the original programmer(s) will be reading the comments.

When I comment my code I try to keep in mind that somebody else may have to work on the code after I've been killed in a freak espresso machine accident.

As to style, "Code Complete" is a good book to read but I always get a chuckle out of the fact that it is from Microsoft Press... Also the "Pragmatic Programmer" is good. There are several other "style" books around. And I found a nice (although probably a little too anal for hobby use) code formatting guide on Jack Ganssle's web site. That one you will have to Google for but I think the web site is www.ganssle.com

One last thing about comments, I try to use complete sentances with punctuation when describing code in the header block I put before each new subroutine. But inside a function I'm generally a bit more terse when commenting on the same line as code.
_________________
Rob Young
The Screw-Up Fairy may just visit you but he has crashed on my couch for the last month!

dest · Joined: 17 Apr 2004 Posts: 2

Try to make your commenting efficient and to the point (don't comment for the sake of commenting). I don't like the huge comment block in ex_mouse.c because of all the time it would take to get the slashes to line up correctly. I see a lot of people try to get their comments to look good. Work on content rather than formatting.

I also recommend "Code Complete" it has some of most well rounded discussion on commenting that I have seen.

Also, always document your functions. Either in the declaration or definitions. Document the parameters and return value along with what are acceptable values for the parameters. It is also good to include the original author and creation date at the top of the file.

By using good variable and function naming (Code Complete talks about this) you can reduce the amount of documentation you will need.

I believe good, clear coding is more important than good commenting. However for embedded systems, sometimes you have to pull tricks to make your code more efficient. Anything that someone would have to think about to know what you are doing should be commented.

I was always taught to comment while you code rather than afterwards. I actually don't recommend this. Often, when first creating a file, you will have to make substantial changes and work out how it will work (even if you do good design). This will make it hard to maintain comments and code (and often make your comments out-of-date). I comment after I am fairly confident that the code won't need many modifications. If you don't put it off or rush it, your commenting end up being better.

PCM programmer · Joined: 06 Sep 2003 Posts: 21708

If you look at what Code Complete recommends and what MS
actually puts in for comments, there is quite a difference. LOL.
http://www.kuro5hin.org/story/2004/2/15/71552/7795
They say the code is dated in July, so maybe these guys were
mostly summer hires ?

Steve H · Guest

PCM's remark is funny - there is always a THEORY and an actual PRACTICE! I think this is also where the: "Managing software people is like herding cat's" theory comes in!

RW's remarks were directly at the point. I hope no one took it that I suggested that lot's of meaningless comments are worthwhile. I try to document code so I can figure out what I was doing 6 months from now - or that someone else stands a chance of figuring out my code. In my case that takes a lot of comments!

There is nothing worse than looking at a three page function where everything is a pointer to a pointer to a pointer to a table of pointers with no comments! That's why Steve M's book is such a good read - he has "Coding Horror's" sprinkled around....

;-)

Steve H.