loading...

re: Is Commenting Code that necessary? VIEW POST

FULL DISCUSSION
 

"Nothing can be quite so helpful as a well-placed comment. Nothing can clutter up a module more than frivolous dogmatic comments. Nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation" - Clean code by Robert C. Martin.

Basically you need to be very aware of how and what you comment. I am very much against mandatory comments. It can clutter up code and at best provides double information like Benito pointed out at worst provide information is outdated because the code is updated but the comments aren't.

Personally, as a rule of thumb, I comment on public methods of interfaces. They should adhere to the open/close principle anyways so the comment on the interface should remain up to date. I make sure I name my variables and methods in implementations and private methods so that they're self-documenting.

Way too often I see comments used as an excuse to mix application and domain logic to one hot tangled mess of code. If you separate interfaces and domain logic in separate layers the code becomes self-explanatory.

 

Thank you for the information and yes these tips are very much helpful.
And I agree with the point that "we need to know which part of the code is to be commented".

 

I have worked in a "clean code" aficionado environment and it's one of the points where you can clearly agree to disagree. Being able to read the code and understand what you were doing back then maybe comes with experience but if you're starting out and come back to something after a month or two, you don't know what you were doing anymore. Comments need to be maintained in the same way that code is, but there's no reason why it can't be read through during the code review as well for example.

code of conduct - report abuse