aspose file tools*
The moose likes Agile and Other Processes and the fly likes late code comments  - risk ??? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Spring in Action this week in the Spring forum!
JavaRanch » Java Forums » Engineering » Agile and Other Processes
Bookmark "late code comments  - risk ???" Watch "late code comments  - risk ???" New topic
Author

late code comments - risk ???

kri shan
Ranch Hand

Joined: Apr 08, 2004
Posts: 1378
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
Ranch Hand

Joined: Jan 28, 2008
Posts: 467
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.


Visit my blog: http://jnassef.blogspot.com/
Jeanne Boyarsky
author & internet detective
Marshal

Joined: May 26, 2003
Posts: 30764
    
156

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.


[Blog] [JavaRanch FAQ] [How To Ask Questions The Smart Way] [Book Promos]
Blogging on Certs: SCEA Part 1, Part 2 & 3, Core Spring 3, OCAJP, OCPJP beta, TOGAF part 1 and part 2
Robert Martin
Author
Ranch Hand

Joined: Jul 02, 2003
Posts: 76
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!


---<br />Uncle Bob.
Jeanne Boyarsky
author & internet detective
Marshal

Joined: May 26, 2003
Posts: 30764
    
156

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
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
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?


The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
kri shan
Ranch Hand

Joined: Apr 08, 2004
Posts: 1378
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
author & internet detective
Marshal

Joined: May 26, 2003
Posts: 30764
    
156

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
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
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
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
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.
 
It is sorta covered in the JavaRanch Style Guide.
 
subject: late code comments - risk ???