Thread: Commenting Style Preference

Quick: with javadoc style comments, document the header or the implementation?

I usually prefer documenting the header more extensively.

usually I comment every line I can... even on simple 2+2 statements.

I also don't normally comment while writing. I finish a function and then go back and write the comment and/or documentation, because it gets in the way sometimes...

usually I comment every line I can... even on simple 2+2 statements.
[...]
because it gets in the way sometimes...

Have you ever thought these two could be related?


I usually use Doxygen comments only at the start/declaration of every function/class/whatever. Then I might add other comments, which might wrap up a complicated piece of code or explain why I am doing something a particular way.

Originally Posted by CornedBee

Have you ever thought these two could be related?

you think I don't know that? maybe that could be why I don't start commenting until I have a working block of code?

I comment everything because if I come back to it, I want to be able to know what every line does with a glance. I want to know why I added two variables without looking through the source. besides, it's easy enough to strip code of all it's comments if I wanted to debug (which has already been done by the time I comment).

hell, I can write a program to do that, and then comment that program, and then use that program to strip the comments out of it's own source...

use that program to strip the comments out of it's own source...

How cruel!

So you explain the why of each line? That's different from most things I've seen so far.

Originally Posted by CornedBee

How cruel!

So you explain the why of each line? That's different from most things I've seen so far.

that depends on what it is... I don't really have much of a formula for how I comment each line (not a formal one at least), but I try to find a way, unless it's blatantly obvious.

Originally Posted by jwenting

Sooner rather than later it leads to disparaties between comments and code and the next time someone has to maintain it there'll be floating questionmarks everywhere.

umm, I fail to see how this would happen... and part of the reason is to make maintenance easier... if you have to maintain, you're going to have to go deeper than the header file. the comments on the header files will only tell you what it's supposed to do, but when you look at the definitions, you won't know why it's not doing that, you'll just know that it's not.

with commenting every line, you can see the intended logic as opposed to the written logic.

But not every single line of code forms a logical unit. Usually you have three or four lines perform a logical action. That's the way of imperative languages (in Haskell, I can indeed comment each line, because each line does a lot). And if you comment more than on each logical unit, you become redundant.

I very strongly agree with jwenting's point.

My typical method is as follows. Comments on purpose, parameters, and output go at the function declaration; comments about a class go at the top of the appropriate header file; comments stating name of function, and a purpose field (which is usually left blank or has something very generic) go right before each function definition, more as a break in the code between functions; comments in code preceding code which would otherwise be difficult or hard to understand by someone who is at least fairly familiar with the system (i.e. rarely).

Back to jwenting's point, a project I've worked on during my summers for the last few years is a rather large system (500k+ lines of C++ and Scheme). It has additionally undergone many changes over the past ten years. The consequence is, where people were extremely detailed in commenting everything, the details have often changed, and the comments have remained the same, and hence, they detract from the ability to understand what is going on because they are documenting long gone relics. I've been guilty of that a few times as well, but once realizing this problem, I switched to simply removing the comments, or updating them if time and patience permitted.

So, if you have a single developer project and you have the discipline to update things as you modify them, then you can be as liberal you want with your comments. But keep in mind that if you have multiple developers who are working (or will be working) on the project, there is a fair chance that the above situation could occur.

Cheers

Originally Posted by Zach L.

So, if you have a single developer project and you have the discipline to update things as you modify them, then you can be as liberal you want with your comments. But keep in mind that if you have multiple developers who are working (or will be working) on the project, there is a fair chance that the above situation could occur.

you don't seem to get my point though. removing comments is always faster and easier than writing new ones. therefore, writing them now and having to get rid of them later is better IMO than not writing them now and needing to figure them out later.

usually the way I comment lines is not exactly what is going on, but explaining what's intended to happen. therefore, if you look at a line like this:

Code:

total-=tax;  //add the tax

you can instantly tell that there's something wrong there. another example:

Code:

int x=(-B-sqrt(pow(B,2)-(4*A*C))/2*A); //positive value of quadratic formula

the latter is a better example to my point.

while developing, I usually read the comments and then strip them away so the code is more readable and you don't have the problem with comments not matching up with lines. another thing is, if you do need to go back and modify the code, as in the first two examples, what you fix will not make the comment wrong: it will actually make it right...

I have been getting better as of late. I ussually comment the header with what the class or struct is for, all the variables, functions, etc... Then throughout the cpp file comment some loops, if's and what not but most of my "green" is in the headers though

major_small, I understand your point, and in the cases you work with, I do not doubt that it works. You have the motivation and the discipline to make that system work, and you know exactly what the code should be doing and how. Therefore, the system works well for you.

The example I was talking about was a bit more complicated. There were a fair number of programmers that worked or had worked on the system, and more importantly, it is not that the code did not work and needed to be debugged. The code worked fine at some point when the comments were written, and conformed to the comments. As the system evolved, however, a good bit of the underlying design changed, necessitating the particular code to take on new roles, give up some roles, or simply do things a bit differently. Comments in the code, however, were not always appropriately updated, so the comments simply documented a relic (which wasn't always clear unless you went through the code and understood it).

If I understand what you are saying, then you have a multi-step process:
- Write code and associated comments.
- Debug code.
- Remove comments.
If this is the correct interpretation, then I agree with you that it is worthwhile, and I do it myself, but to a much lesser extent. Usually, I only apply this to large logical blocks of code, and then make sure to remove them before the code ever gets checked in (with the exception of those clearly documenting a specific, hard to follow piece of code as mentioned above -- but this is rare).

And as a side note, the reason that comments often did not or do not get updated is not entirely that the programmer (myself included) is lazy, but rather, that there are more pressing issues at hand that require usable code to be written. If the project is for yourself, or not running on a (tight) deadline, then your method would be much more successful.

My observations come from the software company I've worked for over the last several summers, where the conditions were pretty tight like that. I have since carried my habits over from there (partly because I personally don't find doing a lot of commenting fun).

Anyway, those are my thoughts. I don't completely disagree with you, I just think that your method has a limited domain.

Cheers