[GitHub] [calcite] julianhyde commented on a change in pull request #1602: [CALCITE-3531] AggregateProjectPullUpConstantsRule should not remove …

[GitBox <gi...@apache.org>]

julianhyde commented on a change in pull request #1602: [CALCITE-3531] AggregateProjectPullUpConstantsRule should not remove …
URL: https://github.com/apache/calcite/pull/1602#discussion_r349757257
 
 

 ##########
 File path: core/src/main/java/org/apache/calcite/sql/SqlOperator.java
 ##########
 @@ -908,15 +908,15 @@ public SqlMonotonicity getMonotonicity(SqlOperatorBinding call) {
   }
 
   /**
-   * @return true iff a call to this operator is guaranteed to always return
+   * @return true if a call to this operator is guaranteed to always return
    * the same result given the same operands; true is assumed by default
    */
   public boolean isDeterministic() {
     return true;
   }
 
   /**
-   * @return true iff it is unsafe to cache query plans referencing this
+   * @return true if it is unsafe to cache query plans referencing this
 
 Review comment:
   In my opinion, 'return true if...' is more verbose than it needs to be. The following all mean practically the same:
   * return true if x is greater than 5
   * return true iff x is greater than 5
   * return true if and only if x is greater than 5
   * return true if it is true that x is greater than 5
   * return whether x is greater than 5
   
   I prefer the last one.
   
   'if' is problematic if you're pedantic; the method would not be breaking its contract if it decided to return true because it's a Tuesday
   
   'iff' is jargon
   
   'true if and only if' adds another layer of indirection. Just as a `getTemperature` method would be adding indirection if it said that it `returns an integer value equal to the temperature` rather than `returns the temperature`.
   
   Lastly, I don't think that the \@return javadoc tag helps. I think that every method needs a description, and \@return and \@param are only necessary if they are not clear from the description. I'd write simply
   
   ```
   /** Returns whether x is greater than 5. */
   ```

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services