Quick: with javadoc style comments, document the header or the implementation?
Printable View
Quick: with javadoc style comments, document the header or the implementation?
I usually prefer documenting the header more extensively.
One of the idaes behind the header/source separation is that you can distribute the headers without giving away your code. That means is that the headers are the only part of your program most people will ever see (and in fact the only part they should need to see). Comments that are not there are useless to anyone but you.
I usually comment above functions indicating their purpose, and inside the functions to let you know what's going on at hard to read places.
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...
Have you ever thought these two could be related?Quote:
usually I comment every line I can... even on simple 2+2 statements.
[...]
because it gets in the way sometimes...
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.
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?Quote:
Originally Posted by CornedBee
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...
How cruel!Quote:
use that program to strip the comments out of it's own source...
So you explain the why of each line? That's different from most things I've seen so far.
commenting ever line is bad practice.
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.
Rather you should write your code to not need such elaborate comments, to effectively comment itself.
Rather comment blocks of code the function of which isn't readily apparent, and document method and class headers by giving a functional description.
Do the latter in the headerfiles.
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.Quote:
Originally Posted by CornedBee
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.Quote:
Originally Posted by jwenting
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
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.Quote:
Originally Posted by Zach L.
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:
you can instantly tell that there's something wrong there. another example:Code:total-=tax; //add the tax
the latter is a better example to my point.Code:int x=(-B-sqrt(pow(B,2)-(4*A*C))/2*A); //positive value of quadratic formula
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 :)
I comment anything I feel I may forget in the future. When I was first getting expoed to C#, I commented just about everyother line, unless the line was self-explainatory. In c++ I comment things that need to be commented. When putting in new variable to help get something to work, I often don't name it very well the first time (ok ok I use single letter vars -_-), so I comment them on what they are supposed to do. Commenting everyline, I feel, should only be done in the very very beginning of learning a language.
<southern drawl>Nice...</southern drawl> :cool:Quote:
In c++ I comment things that need to be commented.