YMMV (a lot), but usually I reserve comments for the higher-level stuff. For example, I prefer to comment function specs (prototypes for you C people :-)) so that a person looking at my code know *what* a function/method does. Also, I usually put comments in the head of my packages, so that people know what is the duty of that package. It is very, very unusual that I put comments in the actual code, unless I am using a very involved algorithm with non-obvious actions. I prefer to give long, descriptive names rather than resorting to comments. For example, if you see
function Exist_Device(Serial_Number : Integer) return Boolean
is
begin
for I in Device_Table.Range loop
if Device_Table(I).Serial = Serial_Number then
return True;
end if;
end loop;
return False;
end Exist_Device;
is pretty clear what it does, without the need of comments.
"Feedback does not pay the bills, so this is not a substitute for paying the right wages."
Indeed. Appreciation is nice, and I agree that it can be a strong motivation force (I contribute to Open Source projects for this reason). However, since a "thank you" is very cheap, there is the risk that your employee thinks that "thank you" is just an inexpensive replacement for a larger paycheck. If the employee has this feeling, the "thank you" can backfire quite badly. See many Dilbert comics about motivational gifts...
Authored Comments
YMMV (a lot), but usually I reserve comments for the higher-level stuff. For example, I prefer to comment function specs (prototypes for you C people :-)) so that a person looking at my code know *what* a function/method does. Also, I usually put comments in the head of my packages, so that people know what is the duty of that package. It is very, very unusual that I put comments in the actual code, unless I am using a very involved algorithm with non-obvious actions. I prefer to give long, descriptive names rather than resorting to comments. For example, if you see
function Exist_Device(Serial_Number : Integer) return Boolean
is
begin
for I in Device_Table.Range loop
if Device_Table(I).Serial = Serial_Number then
return True;
end if;
end loop;
return False;
end Exist_Device;
is pretty clear what it does, without the need of comments.
"Feedback does not pay the bills, so this is not a substitute for paying the right wages."
Indeed. Appreciation is nice, and I agree that it can be a strong motivation force (I contribute to Open Source projects for this reason). However, since a "thank you" is very cheap, there is the risk that your employee thinks that "thank you" is just an inexpensive replacement for a larger paycheck. If the employee has this feeling, the "thank you" can backfire quite badly. See many Dilbert comics about motivational gifts...