Program commenting how far do you need to go?

This is somthing I am never usualy shure of, I have more than 1000 lines of object oriented C++ code to comment. Some people say different things but am I right in thinking that you should not explain the code but explain the process?

For example is commenting for this bit of code sufficient?

Code:

void Ccacl3Dlg::OnBnClickedBtncosine()
{
	//cos is a function included in the math.h header.
	m_dValue = cos (m_dDisplay*m_dPi/180);
	m_dDisplay = m_dValue;
        //update the display with the new result.
	UpdateData(FALSE);
}

I know there are a few programmers here so I am just interested in finding out how you would comment that in a professional situation.

Thanks.

 

It is very useful to comment fully. I would say your example is ok, for more complex math maybe you would need to explain the operations being performed.
It is good for code that might be maintained by others, it also seems to gain brownie points in exams/assignments.
Just dont get lazy and stop commenting all together

 

Real programmers don't comment, except to point out something like:

// Exceptionally elegant piece of code coming up. Admire my l33t skillz

or

// TO DO: fix bug causing all data to be corrupted when user hits the Cancel button

-- Ian

 

also name all variables after friends

int Bob;
float Bill;
long Fred;

 

i include comments to punctuate the code.
"now work out [this]"
"now take [that] and calculate [something else]"
and more specific comments when code (read "logic") isn't obvious.

 

About a million years ago I used to work on a relational database OS called Pick. Pick BASIC offered the fantastic yet useless ability to redefine the meaning of some of the language elements. So you could put something like this in an include file and really confuse the hell out of people:

define true = false
define false = true

-- Ian

 

I have explained all my variables some times in detail, the problem is what is obvious to me may not be to other people. I have gone into detail the first time a type of function comes up, for example adding a the second byte of a number, but the button functions are repeated for each decimal number (0-9) so I haven't really commented the rest of these because it gets too repeative. The only difference in code is its passing a different number into the functions according to what button was pressed.

My biggest downfall on programming is I never comment my code, I have written entire websites and content management systems without a single line of commeting, this is because I know the only person using it is myself and its not for a client, coursework or any other professional purpose. The only probem is when I need to edit the code 6 months later it takes me an hour to work out how the hell my code works

 

I don't tend to comment my code...

However, my code usually looks something like this, and comments aren't really necessary (when you understand the language):

Code:

MAIN:
     BTFSC 0,5
     GOTO UP1
     BTFSC 0,4
     GOTO UP2
     GOTO MAIN

And yes, use of goto is acceptable.

 

I've never come across a compiler or interpreter which uses comments. The human reader has no guarantee that comments in program source code are in any way accurate. Programmers would better use the time they spend writing asinine comments ("add A to B") by writing clear code.

 

Argh goto's a lovely way to emulate the M6 in Birmingham. In fact I think the last time I used goto was QBASIC in around 1998 when I was 16.

Another really wonderful thing I have seen people to do, instead of putting repeative elements in a function some people seem to think its clever to use cut and paste - until of course they disover a :JPS: in that part of the code and they have to repeat the whole thing over again My main aim when writing code is to keep at as short as possible, commenting and legability is usualy the last thing on my mind

I bet the windows source code is not well commented for good reason

 

Both comments in your example are restatements of the obvious and are therefore redundant. Question is what does the function do and why?

And I think you may have a bug if you don't call 'UpdateData ( TRUE )' before using m_dDisplay, unless it's not related to user entry.

m_dDisplay also appears to start off as a value in degrees and end up as a cos, which is obviously between -1 and +1. This could use a comment. What happens when you press the button twice? How can that make sense?

Paul

 

It is commented I just missed that off by accident when I copied into here, when you press the button is just works out the cosine of what ever the last value was etc. I will add extra comments about the cosine.

The number is already entered and UpdateData(TRUE) is called in another part of the program before this function is called so it works fine. I admit its not the neatest calcualtor program in the world, the program is I was experimenting a lot when producing it. I think the quiality of code is worth around 20% and the 80% for what the actual calcualtor does and how well it works.

I have used the STRCAT and STRCPY methods to add stuff to the display string thouh which apparantly can cause memory leaks, this is the way my tutor told us all to it though so he can't mark us down for that.

A lot of people haven't even managed to get a series of numbers (i.e 4+2+6) working so I should gain extra marks there. The only major flaw of my calculator is it dosn't do presidence but that would have only added an extra 10% to my marks and the amount of work it involved meant it was not worth it, I would be better off doing that amount of work on another assignment.

I am not a programmer and never claim to be, I am just better at programming than a lot of people on my course.

 

Unless you have a 'coding standard' to work to then I think you should just comment the unusual and not the usual. So telling me where 'cos' comes from isn't useful, and I should already know what 'cos' is. In the context of the whole program the transference from the display to the m_dDisplay variable will be clear and so it doesn't need to be commented everywhere.

So the only comment I think this function needs is to explain m_dValue, unless this is part of another pattern and explained elsewhere.

Does your calculator handle rounding errors neatly? I remember the Windows calculator for a long time had trouble with '3.11-0.1' or somesuch, a tenth not being exactly representable in binary.

Paul

 

Thanks, I think thats pretty much what I have been doing, I have expalined what m_value does in detail else where. I am not sure what you mean exactly by rounding errors, 3.11-0.1 gives me 3.01 which is correct.

I haven't added any code this so I am not aware of any issues. I have fixed most the bugs I have been aware off but this has kind of made a lot of my code quite messy with many nested if statements. I am sure there must be some bugs though, the main one I know of is that the currency conversion tools do not round the value to two decimal points but this is because the floor function produced some odd results so I just left it out.

 

Write code in Cobol, no need to comment

 

:lol: