nsivabalan commented on a change in pull request #2061:
URL: https://github.com/apache/hudi/pull/2061#discussion_r483050848
##########
File path: docs/_pages/contributing.md
##########
@@ -130,6 +126,65 @@ and more importantly also try to improve the process along
the way as well.
- Before your change can be merged, it should be squashed into a single
commit for cleaner commit history.
- Finally, once your pull request is merged, make sure to `Close` the JIRA.
+### Coding guidelines
+
+Our code can benefit from contributors speaking the same "language" when
authoring code. After all, it gets read lot more than it gets
+written. So optimizing for "reads" is a good goal. The list below is a set of
guidelines, that contributors strive to upkeep and reflective
+of how we want to evolve our code in the future.
+
+#### Style
+
+ - **Formatting** We should rely on checkstyle and spotless to auto fix
formatting; automate this completely. Where we cannot,
+ we will err on the side of not taxing contributors with manual effort.
+ - **Refactoring**
+ - Refactor with purpose; any refactor suggested should be attributable to
functionality that now becomes easy to implement.
+ - A class is asking to be refactored, when it has several overloaded
responsibilities/have sets of fields/methods which are used more cohesively
than others.
+ - Try to name tests using the given-when-then model, that cleans separates
preconditions (given), an action (when) and assertions (then).
+ - **Naming things**
+ - Let's name uniformly; using the same word to denote the same concept.
e.g: bootstrap vs external vs source, when referring to bootstrapped tables.
+ May be they all mean the same, but having one word makes the code lot
more easily readable.
+ - Let's name consistently with Hudi terminology. e.g dataset vs table, base
file vs data file..
+ - Class names preferably are nouns (e.g Runner) which reflect their
responsibility and methods are verbs (e.g run()).
+ - Avoid filler words, that don't add value e.g xxxInfo, xxxData etc.
+ - We name classes in code starting with `Hoodie` and not `Hudi` and we want
to keep it that way for consistency/historical reasons.
+ - **Methods**
+ - Individual methods should short (~20-30 lines) and have a single purpose;
If you feel like it has a secondary purpose, then may be it needs
+ to be broken down more.
+ - Lesser the number of arguments, the better;
+ - Place caller methods on top of callee methods, whenever possible.
+ - Avoid "output" arguments e.g passing in a list and filling its values
within the method.
+ - Try to limit individual if/else blocks to few lines to aid readability.
+ - Separate logical blocks of code with a newline in between e.g read a file
into memory, loop over the lines.
+ - **Classes**
+ - Like method, each Class should have a single purpose/responsibility.
+ - Try to keep class files to about 200 lines of length, nothing beyond 500.
+ - Avoid stating the obvious in comments; e.g each line does not deserve a
comment; Document corner-cases/special perf considerations etc clearly.
+ - Try creating factory methods/builders and interfaces wherever you feel a
specific implementation may be changed down the line.
+
+#### Substance
+
+- Try to avoid large PRs; if unavoidable (many times they are) please separate
refactoring with actual implementation of functionality.
Review comment:
+1 on this.
##########
File path: docs/_pages/contributing.md
##########
@@ -130,6 +126,65 @@ and more importantly also try to improve the process along
the way as well.
- Before your change can be merged, it should be squashed into a single
commit for cleaner commit history.
- Finally, once your pull request is merged, make sure to `Close` the JIRA.
+### Coding guidelines
+
+Our code can benefit from contributors speaking the same "language" when
authoring code. After all, it gets read lot more than it gets
+written. So optimizing for "reads" is a good goal. The list below is a set of
guidelines, that contributors strive to upkeep and reflective
+of how we want to evolve our code in the future.
+
+#### Style
+
+ - **Formatting** We should rely on checkstyle and spotless to auto fix
formatting; automate this completely. Where we cannot,
+ we will err on the side of not taxing contributors with manual effort.
+ - **Refactoring**
+ - Refactor with purpose; any refactor suggested should be attributable to
functionality that now becomes easy to implement.
+ - A class is asking to be refactored, when it has several overloaded
responsibilities/have sets of fields/methods which are used more cohesively
than others.
+ - Try to name tests using the given-when-then model, that cleans separates
preconditions (given), an action (when) and assertions (then).
+ - **Naming things**
+ - Let's name uniformly; using the same word to denote the same concept.
e.g: bootstrap vs external vs source, when referring to bootstrapped tables.
+ May be they all mean the same, but having one word makes the code lot
more easily readable.
+ - Let's name consistently with Hudi terminology. e.g dataset vs table, base
file vs data file..
+ - Class names preferably are nouns (e.g Runner) which reflect their
responsibility and methods are verbs (e.g run()).
+ - Avoid filler words, that don't add value e.g xxxInfo, xxxData etc.
+ - We name classes in code starting with `Hoodie` and not `Hudi` and we want
to keep it that way for consistency/historical reasons.
+ - **Methods**
+ - Individual methods should short (~20-30 lines) and have a single purpose;
If you feel like it has a secondary purpose, then may be it needs
+ to be broken down more.
+ - Lesser the number of arguments, the better;
+ - Place caller methods on top of callee methods, whenever possible.
+ - Avoid "output" arguments e.g passing in a list and filling its values
within the method.
+ - Try to limit individual if/else blocks to few lines to aid readability.
+ - Separate logical blocks of code with a newline in between e.g read a file
into memory, loop over the lines.
+ - **Classes**
+ - Like method, each Class should have a single purpose/responsibility.
+ - Try to keep class files to about 200 lines of length, nothing beyond 500.
+ - Avoid stating the obvious in comments; e.g each line does not deserve a
comment; Document corner-cases/special perf considerations etc clearly.
+ - Try creating factory methods/builders and interfaces wherever you feel a
specific implementation may be changed down the line.
+
+#### Substance
+
+- Try to avoid large PRs; if unavoidable (many times they are) please separate
refactoring with actual implementation of functionality.
Review comment:
can we add a line about "for large PRs like bootstrap, one should add
integration tests as well".
----------------------------------------------------------------
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:
[email protected]
