late code comments - risk ???

[kri shan]

We have been writing the code two years, now we are thinking of adding comments for most of the logic instead of adding the code comments during coding. Is it good idea ? What is the risk of adding code comments after too many code deliveries to the customer.

[Alaa Nassef]

What's the risk? Well, not much, since you'll not be changing any code. You just have to make sure that your builds are correct. Is it the right thing to do? Not really. The right thing to do is to try to make your code cleaner through refactoring, to use more descriptive method and variable names, splitting large methods/classes into smaller ones, etc. What's the risk of that? If you're not agile enough to have unit sets covering 100% of your code, you're in a risk of introducing bugs. So should you do the comments thing? Well, it's better than nothing, but if you can refactor your code to make it cleaner in the sense that you make it very readable and maintainable, it would be a lot better.

[Jeanne Boyarsky]

Kri,
If you can't refactor the code to make it clearer, adding comments describing what you have learned about the code is better than nothing.

[Robert Martin]

Originally posted by kri shan:
We have been writing the code two years, now we are thinking of adding comments for most of the logic instead of adding the code comments during coding. Is it good idea ? What is the risk of adding code comments after too many code deliveries to the customer.

The risk is that you will comment dirty code rather than clean it. Your FIRST priority is to make sure the code is clean and easy to read. Only after you have tried to clean a module, and failed to get it to express itself, should you comment it.

Of course this only works if you have tests that allow you to safely clean the code. You _do_ have such tests don't you? You'd better!

[Jeanne Boyarsky]

Originally posted by Robert Martin:
The risk is that you will comment dirty code rather than clean it. Your FIRST priority is to make sure the code is clean and easy to read.

If you aren't allowed to clean the code (maybe you are near a release), are you saying it's better to do nothing than comment your understanding of the dirty code?

[Ilja Preuss]

Originally posted by Jeanne Boyarsky:

If you aren't allowed to clean the code (maybe you are near a release), are you saying it's better to do nothing than comment your understanding of the dirty code?

Well, I'd define that a failure to clean the code, and therefore interpret Bob's rule to allow the comment.

You are aware that there are teams out there that don't have any trouble cleaning up there code near a release, because they trust their tests so much?

[kri shan]

When we started our project nobody bother about code comments because we had very tight delivery schedule. Now it's almost project closing stage. Hence we are worrying about quality process(code comments,....).

[Jeanne Boyarsky]

Originally posted by Ilja Preuss:
You are aware that there are teams out there that don't have any trouble cleaning up there code near a release, because they trust their tests so much?

Yes . For an emergency production fix, I still wouldn't though. I'd make a note and clean the code in the HEAD rather than the branch for the emergency fix.

[Ilja Preuss]

Originally posted by Jeanne Boyarsky:

Yes . For an emergency production fix, I still wouldn't though. I'd make a note and clean the code in the HEAD rather than the branch for the emergency fix.

I might do that, too - but more because merging bigger code changes isn't fun.

We are currently exploring what we need to do to get totally rid of branches...

[Ilja Preuss]

Originally posted by kri shan:
When we started our project nobody bother about code comments because we had very tight delivery schedule. Now it's almost project closing stage. Hence we are worrying about quality process(code comments,....).

In my experience, not worrying about code quality actually slows you down, so although I see how it could be tempting under stress, it's actually counterproductive.

Having said that, I wouldn't say that comments are a sign of a quality process. Most comments are actually a sign of code that could use improvement.