ademakov commented on code in PR #965:
URL: https://github.com/apache/ignite-3/pull/965#discussion_r937725069
##########
modules/schema/src/main/java/org/apache/ignite/internal/schema/BinaryTupleSchema.java:
##########
@@ -289,10 +289,23 @@ public static int nullMapSize(int numElements) {
}
/**
- * Returns the null map size in bytes if there are nullable elements, zero
otherwise.
+ * Get offset of the byte that contains null-bit of a given tuple element.
Review Comment:
* The word get is perfectly natural. You could find a ton of cases where
"get" is used in docs. E.g. `man getenv`:
```
GETENV(3) Linux
Programmer's Manual
GETENV(3)
NAME
getenv, secure_getenv - get an environment variable
```
Methods are called like "getX()" instead of "returnX()" for a reason. The
Java docs use `returns` more often perhaps to escape tautology. I guess Java
doc authors think that "getX() -- returns X" looks better than "getX() -- gets
X".
* Still it does not take a long time to find some examples of using "Gets"
there:
https://docs.oracle.com/en/java/javase/18/docs/api/java.base/java/lang/System.html
```
getProperty() Gets the system property indicated by the specified key.
```
* "Returns" is not imperative. It's 3rd person indicative. "Return" would be
imperative. In python world their require to use imperative:
https://peps.python.org/pep-0257/#one-line-docstrings
```
The docstring is a phrase ending in a period. It prescribes the function or
method’s effect as a command (“Do this”, “Return that”), not as a description;
e.g. don’t write “Returns the pathname …”.
```
It appears that Python people use English more carefully than Java people.
Regardless, I edited the comments the way you asked.
--
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.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
