4 comments
Comment actions Permalink

There is this problem that much of the article flows from an arguably
flawed premise.

"Good comments increase code quality." is an idea that once reigned
supreme, but the agile methodology crowd has shot some pretty big holes
in it.

I am one of the believers that the premise is flawed. I prefer "Legible
code increases code quality." and that tools that help programmers
reorganize the code to make it more understandable will do more for
improving quality than anything that makes it easier to write better
comments.

That's right - IDEA already does that - that's one of the main points of
refactoring.

Norris Shelton wrote:

This article is about Eclipse, but it does list some features that would
be nice additions to IntelliJ.

Part 1 <http://www.developer.com/design/article.php/3342481>

Part 2 <http://www.developer.com/java/ent/article.php/10933_3346291_1>

0
Comment actions Permalink

In general, I agree with you that "Legible code increases code quality" much
more than comments. In fact, I believe that free-form code comments should
be used only in very limited places, if ever.

However, maintaining correctly synchronized standard and custom javadoc tags
in comments makes the understanding of your APIs and reusable classes much
easier for the developers that use them. They shouldn't need to read your
code no matter how legible it is. Only the maintainers of code should have
to read it.

IDEA provides pop-up javadocs, which are immensely helpful if the comments
are complete and correct. They are frustrating and even dangerous if they
are incomplete or worse, incorrect.

Tim

-


Original Message -



From: "Donald F. McLean" <dmclean@stsci.edu>
Newsgroups: jetbrains.intellij.eap
Sent: Friday, April 30, 2004 11:19 AM
Subject: Re: Article: Can IDEs Do More to Improve Code Quality?

There is this problem that much of the article flows from an arguably
flawed premise.

>

"Good comments increase code quality." is an idea that once reigned
supreme, but the agile methodology crowd has shot some pretty big holes
in it.

>

I am one of the believers that the premise is flawed. I prefer "Legible
code increases code quality." and that tools that help programmers
reorganize the code to make it more understandable will do more for
improving quality than anything that makes it easier to write better
comments.

>

That's right - IDEA already does that - that's one of the main points of
refactoring.

>

Norris Shelton wrote:

This article is about Eclipse, but it does list some features that would
be nice additions to IntelliJ.

>

Part 1 <http://www.developer.com/design/article.php/3342481>

>

Part 2 <http://www.developer.com/java/ent/article.php/10933_3346291_1>



0
Comment actions Permalink

"Donald F. McLean" <dmclean@stsci.edu> wrote in message
news:c6tqpq$vup$1@is.intellij.net...

There is this problem that much of the article flows from an arguably
flawed premise.

>

"Good comments increase code quality." is an idea that once reigned
supreme, but the agile methodology crowd has shot some pretty big holes
in it.


Rule #1: Comments lie

--
Jordan Zimmerman
http://www.jordanzimmerman.com


0
Comment actions Permalink

"Jordan Zimmerman" <jordanz@altura.com> wrote in message
news:c6u0d9$vu1$1@is.intellij.net...

Rule #1: Comments lie

>

Absolutely true. That is why I have always hated free-form comments;
however, javadoc tags have the potential to change that.

That is why the author talks about the fact that the IDE should automate the
synchronization of comments and code. Which, by the way, IDEA does quite
well for class names and parameter names. It would be nice if it supported
even more synchronization of code with javadoc tags, including custom tags.

-


Tim


0

Please sign in to leave a comment.