Granny's Programming Pearls
"inside of every large program is a small program struggling to get out"
JavaRanch.com/granny.jsp
Win a copy of Functional Reactive Programming this week in the Other Languages forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Does a reader carry an "if" into a comment?

 
Jamie Cole
Ranch Hand
Posts: 36
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Here's an example of a line of code with comment:
if ( number <= 19 ) // print the entry . . .
Would this normally be read as "if the number is less than or equal to 19, print the entry . . ."? In other words, would the reader understand that the action expressed in the comment is something that will be done if the "if" is satisfied?
 
Tony Alicea
Desperado
Sheriff
Posts: 3226
5
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I'd say YES. Although remember that the comments are as good as the programmer writes them and are not checked by the compiler for accuracy
[This message has been edited by Tony Alicea (edited February 04, 2000).]
 
paul wheaton
Trailboss
Pie
Posts: 21742
Firefox Browser IntelliJ IDE Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
How about
 
Frank Carver
Sheriff
Posts: 6920
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
or even:

In my opinion the aim of every programmer should be to make the actual code as close to a direct expression of intent as possible. Given that the code actually works, all other issues are secondary. In this case I'd also use a better variable name than "number" which is almost meaningless, and give some sort of name to the "19". I can't tell from your example what your intent is, so I can't help you to find better names.
By all means use comments where you really need them (to explain non-obvious algorithm or performance issues, to indicate why you chose to do somthing a particular way, and so on) but only after you have tried your very best with the actual code.
Remember, comments can lie, so you should be vary wary of them.
If you really want to have the example code as listed, I'd probably try to capture intent with a comment before the block
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic