code comments

[d000hg]

What about adding comments for stuff like JavaDoc to extract? To me it looks bad if some methods have no comment in the documentation at all... it makes me think they have not been thorough documenting the code. When you only get the library, not the source code, this is a bad feeling to have.

 

[minestrone]

I get QA emails every morning from my idiot technical lead telling me I have to put in comments, even getters have to be done so..

/**
*
* @return name
*/
public String getName(){
..

..will get me an email every morning until I change it to..

/**
* Returns the name associated with this object.

* @return name
*/
public String getName(){

Now you can see why I never took the extension they offered.

 

[BrilloPad]

Question.

Do you write comprehensive code comments, thus making the job much longer (kerrching) but making it much easier for someone else to pickup the code and replace you, or write cryptic comment free code that is quick to write (no contract renewal) but no bugger can pick it up (and get called back in on a new contract)?

I generally write just enough so that if I come back in a years time I can understand what I did.

 

[christhecontractor]

when I started programming I was taught that comments should be comprehensive enough so that if all the code was ripped out and only the comments left then it would be straight forward enough for someone to rewrite the program.

My comments vary from spartan to comprehensive depending on what its for.

I write a lot of migraiton scripts, these get run a limited number of times and usually by myself so no need for comments.

Interfaces which should survive past my contract end date get full comments
-- Headers which include version info
-- test scripts (i write SQL) so that someone debugging it already has a bunch of SQL to test the data with
-- then the body of the T-SQL has numbered comments broken down by section. These are compiled at the top for documentation purposes then repeated on the line above the piece of code they refer to

Anyone who needs to understand the stored procedure only needs to read the header and they could completely rebuild it

When writing the program I usually start with the comments, map out exactly what I want it do to, where and why then build the actual code around that.

That's interesting because it's the opposite of the philosophy that the code is self commented by meaningfull variable and function names.

Assuming that the code can be quite clearly read without comments (with meaningfull names etc) then don't you agree that the comments are redundant ?

Also, bugs in comments are a lot harder to spot than bugs in the code(because the compiler doesn't help you there), and it's not a functional requirement that all comments are correct so they are more likely than the code to be incorrect.

 

[Jaws]

I get QA emails every morning from my idiot technical lead telling me I have to put in comments, even getters have to be done so..

/**
*
* @return name
*/
public String getName(){
..

..will get me an email every morning until I change it to..

/**
* Returns the name associated with this object.

* @return name
*/
public String getName(){

Now you can see why I never took the extension they offered.

This sort of thing and xml comments in c# really get on my nerves. I've seen classes with about 10 lines of actual code over 100 lines long due to this (some coders even xml doc their private fields).
I thought the goal was to write your code so it can be easily read, turning commented sections into their own self describing methods where-ever possible.

 

[christhecontractor]

I get QA emails every morning from my idiot technical lead telling me I have to put in comments, even getters have to be done so..

/**
*
* @return name
*/
public String getName(){
..

..will get me an email every morning until I change it to..

/**
* Returns the name associated with this object.

* @return name
*/
public String getName(){

Now you can see why I never took the extension they offered.

When I read code like that I can't see anything - code littered with comments are like a crash site. When I try to understand someone else's code, the first thing I do normally is strip out all the comments so I can actually see what's important - the actual code.

 

[Zippy]

That's interesting because it's the opposite of the philosophy that the code is self commented by meaningfull variable and function names.

Assuming that the code can be quite clearly read without comments (with meaningfull names etc) then don't you agree that the comments are redundant ?

Also, bugs in comments are a lot harder to spot than bugs in the code(because the compiler doesn't help you there), and it's not a functional requirement that all comments are correct so they are more likely than the code to be incorrect.

Yep, I agree. A few comments can still be helpful to describe what a method is trying to do - but way above the level of 'getting message.
Only one slight problem - almost no b*gger writes code like this

 

[Spacecadet]

That's interesting because it's the opposite of the philosophy that the code is self commented by meaningfull variable and function names.

It's not opposite, it's complementary

Also meaningful function and variable names will only get you so far, at some point you will need to do some fairly complex logic, recursion, loops or string manipulation which need notes

Assuming that the code can be quite clearly read without comments (with meaningfull names etc) then don't you agree that the comments are redundant ?

Nope

Also, bugs in comments are a lot harder to spot than bugs in the code(because the compiler doesn't help you there), and it's not a functional requirement that all comments are correct so they are more likely than the code to be incorrect.

This is correct however, the comments are there for a guide not as a bible.
Comments can become out of date very quickly if not maintained with the code, however this doesn't mean that well written comments can't complement a well written program.

The real problems only start when a junior programmer starts work on it and neglects/can't be arsed to maintain the comments, then someone else needs to debuig those changes and junior "i don't need comments" programmer has done half a job.

All it takes is a bit of discipline

 

[Ruprect]

I recall years ago being told of a program written in assembler, that was hugely complicated, and stopped working. The developer responsible was on holiday, and couldn't be reached - no mobile phones in those day. The other programmers tried to work out what it was doing, and how to fix it, but there was only one comment, "BOH", at line 1066. This being the only place commented, it was felt this must be the important part of the code. But they couldn't work it out. They had to resort to some kind of manual workaround.

When the developer returned from holiday - to very black looks - he was asked about the comment.

"Oh", he said, "that's easy. 1066 Battle Of Hastings".

If you're writing a class that long you need to be shot.

 

[Zippy]

If you're writing a class that long you need to be shot.

In the eye