may the force be with you

Should I write comments? What is a good comment? Is it possible to comment a class in 5 minutes? I would discuss these questions. I would be happy if, after reading, you will be thinking that good comments are the key to your project success.

I must admit that I hated to write comments. I was finding them boring and unnecessary. And the worse thing I was afraid is that during my design some of my methods or classes might go away together with my time spent for writing my good comments. So the first thing I would discuss is


Why?

Here is the first reason for comments. Comments can make your design clearer. You could mark the class with its responsibilities using comments. You can check then how much your class respects its responsibilities, and that it doesn’t do something which is not its responsibility. Moreover, you can check how much your class respects Single Responsibility Principle and make some decisions to improve the design.

But I think that primary reason which can force you to write comments is to make your code understandable for others. The rule is simple. If you will hide your code for forever - nobody is going to know if it is commented or not. As soon as you are going to share your code with some other person - unless you are not writing it all together from the beginning - he or she will be happy to see your class comments. Of course you could be happy to explain it to everyone personally. But you want to avoid phone calls asking what your class does while you are on vacation.

Do you know any other reasons which make you to start writing comments? If yes - I will be happy to include them here. Personally I find an important reason to have a good rest on vacation. So the next question will be -


How?

What is a good comment? Should we judge how good the comment is by its word count? Should we have each method commented? I would say we don’t, or else our comments could end up time-consuming for us and being boring for our readers.

Antipattern

It’s so easy to mark a class with extended description of its name. We end up with class TransactionManager marked as Represents a Transaction Manager. Would this be descriptive enough? No sense to include this in comments at all. I can read a class name by my own. I would be more happy to see TransactionManager marked as Manages (creates, disposes and provides) transactions.

Personally I find very useful an old proven approach for class comments. CRC cards was used for a long time (since at least 1989) and hugely adopted with modern techniques like Agile Development (see http://martinfowler.com/articles/designDead.html and http://www.agilemodeling.com/essays/agileModelingXP.htm). We can take two good things from there and supply our comments with: class responsibilities, and class names our class is planned to communicate with.

Note that OO design tells our class to respect Single Responsibility Principle. Here is where your comment becomes an important design tool. If you find it impossible to name your class’s responsibility with a single combination of verb and noun – it is a good chance your class is taking too much on itself and should be split. One trick here is - use of manages helps.

Antipattern

Someone might want to describe here how other classes are going to communicate with our class. I would move this information into corresponding class.

We should end up with class comments which are pretty short but descriptive enough. And what about method comments? No clear recommendation for now. I would recommend to name a method as much descriptive as possible. It could make its comment unnecessary. I would mention some exception situations however. For example, I would describe what the method does if no item with given key available. Will it return null? Will it throw an exception?

Ok! Now we know which kind of comments we are going to write. Now the question is


When?

I dislike to do something which will be thrown away. I dislike to write comments which will be thrown away. During my design, I create new classes, play with them, throw them away and create new instead. I would find a way to save my time and write a comment when I have a decent hope my class will remain within the system.

The point to start writing comments is... when the code is ready to be presented for others. This could be the time before commit to a main source repository, or insert your case here. For this time, I have pretty stable class design, and good chance my comments will live long. I am pretty sure with my class’s responsibilities and what classes it will collaborate with. I can spend as much as 2 minutes writing this information as a class comment. Everybody’s happy!

source:http://dkrukovsky.blogspot.com/2005/07/how-to-write-comments.html

The operation lasted several hours

Surgeons in France have carried out the first face transplant, it has been reported.

The woman had lost her nose, lips and chin after being savaged by a dog.

In the controversial operation, tissues, muscles, arteries and veins were taken from a brain-dead donor and attached to the patient's lower face.

Doctors stress the woman will not look like her donor, but nor will she look like she did before the attack - instead she will have a "hybrid" face.

This is the first face transplant using skin from another person Iain Hutchison, Barts and the London Hospital Q&A: First face transplant

It has been technically possible to carry out such a transplant for some years, with teams in the US, the UK and France researching the procedure.

Skin from another person's face is better for transplants as it will be a better match than skin from another part of the patient's body, which could have a different texture or colour.

But the ethical concerns of a face transplant, and the psychological impact to the patient of looking different has held teams back.

Concerns relating to immunosuppression, psychological impact and the consequence of technical failure have so far prevented ethical approval of the procedure in the UK, though doctors here are fully able to perform transplants.

'Gravely disfigured'

The 38-year-old French patient from the northern French town of Valenciennes underwent extensive counselling before her operation, which is believed to have lasted at least five hours, and which took place at the weekend at a hospital in Amiens.

The French magazine Le Point reports that the tissues, muscles, arteries and veins needed for the transplant were taken from a multi-organ donor in the northern city of Lille, who was brain-dead.

The operations were carried out by a team led by Professor Bernard Devauchelle and Professor Jean Michel Dubernard.

In a statement, the hospital said the woman had been gravely disfigured in the attack in May this year.

She has been unable to speak or eat properly since.

It added that the woman - who wishes to remain anonymous - was in "excellent general health" and said the graft looked normal

It is not clear whether an individual could be left worse off in the event that a face transplant failed Stephen Wigmore, British Transplantation Society

Live donors

Like any other transplant patient, the woman will have to take immunosuppressant drugs to help her body cope with the donated tissue.

Doctors working in the field say many could benefit from the procedure, including 10,000 burns victims in the UK.

Iain Hutchison, an oral-facial surgeon at Barts and the London Hospital, said: "This is the first face transplant using skin from another person."

But there are medical, and ethical, concerns of facial transplants.

Mr Hutchison, who is chief executive of Saving Faces - the Facial Surgery Research Foundation, warned blood vessels in the donated tissue could clot, the immunosuppressants could fail - and would increase the patient's risk of cancer."

Mr Hutchison added there were ethical and moral issues around donating facial tissue.

"Where donors would come from is one issue that would have to be considered.

"The transplant would have to come from a beating heart donor. So, say your sister was in intensive care, you would have to agree to allow their face to be removed before the ventilator was switched off.

"And there is the possibility that the donor would then carry on breathing."

Stephen Wigmore, chair of British Transplantation Society's ethics committee, said: "The extent of facial expression which will occur in the long term is unknown.

"The skin tends to promote rejection by the immune system very strongly and immunosuppression is likely to need to be kept at high levels for prolonged periods of time.

"It is not clear whether an individual could be left worse off in the event that a face transplant failed."

Mr Michael Earley, a member of the Royal College of Surgeon's facial transplantation working party, said: "If successful, this is a major breakthrough in facial reconstruction.

"It appears that this has been a partial face transplant incorporating the nose and lips; therefore issues relating to similarity in appearance between donor and recipient are unlikely to be a major problem.

"We wish the patient and the team a successful outcome and look forward to learning more about the details of the procedure which could be a major step forward for the facially disfigured."