You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@iceberg.apache.org by "ajantha-bhat (via GitHub)" <gi...@apache.org> on 2025/03/25 16:28:59 UTC

[PR] Docs: Update block spacing guideline in contribute.md [iceberg]

ajantha-bhat opened a new pull request, #12641:
URL: https://github.com/apache/iceberg/pull/12641

   (no comment)


-- 
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: issues-unsubscribe@iceberg.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org


Re: [PR] Docs: Update block spacing guideline in contribute.md [iceberg]

Posted by "ajantha-bhat (via GitHub)" <gi...@apache.org>.
ajantha-bhat commented on code in PR #12641:
URL: https://github.com/apache/iceberg/pull/12641#discussion_r2012491938


##########
site/docs/contribute.md:
##########
@@ -422,6 +422,10 @@ Use `this` when assigning values to instance variables, making it clear when the
 2. Use `.` to create a hierarchy of config groups
     * For example, `s3` in `s3.access-key-id`, `s3.secret-access-key`
 
+#### Block Spacing
+
+To improve readability and maintain consistency, always place a newline after control blocks (if, for, while, switch, etc.). This helps separate logical sections of the code, making it easier to read and debug.      
+

Review Comment:
   For new contributors, we keep on repeating this guideline. 
   Documenting it under here can help reduce the effort. 



-- 
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: issues-unsubscribe@iceberg.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org


Re: [PR] Docs: Update block spacing guideline in contribute.md [iceberg]

Posted by "ajantha-bhat (via GitHub)" <gi...@apache.org>.
ajantha-bhat commented on code in PR #12641:
URL: https://github.com/apache/iceberg/pull/12641#discussion_r2013474931


##########
site/docs/contribute.md:
##########
@@ -422,6 +422,50 @@ Use `this` when assigning values to instance variables, making it clear when the
 2. Use `.` to create a hierarchy of config groups
     * For example, `s3` in `s3.access-key-id`, `s3.secret-access-key`
 
+#### Block Spacing
+
+To improve readability and maintain consistency, always place a newline after control blocks (if, for, while, switch, etc.). 
+This helps separate logical sections of the code, making it easier to read and debug.
+
+```java
+  // BAD: No newline separator after `if` block
+  public static WriteBuilder write(OutputFile file) {
+     if (file instanceof EncryptedOutputFile) {
+        return write((EncryptedOutputFile) file);
+     }
+     return new WriteBuilder(file);
+  }
+
+  // GOOD: newline separator after `if` block
+  public static WriteBuilder write(OutputFile file) {
+     if (file instanceof EncryptedOutputFile) {
+        return write((EncryptedOutputFile) file);
+     }
+     
+     return new WriteBuilder(file);
+  }
+
+  // BAD: No newline separator before and after `for` block
+  public static Schema convert(Schema schema) {
+     ImmutableList.Builder<Field> fields = ImmutableList.builder();
+     for (NestedField f : schema.columns()) {
+        fields.add(convert(f));
+     }
+     return new Schema(fields.build());
+  }
+
+  // GOOD: newline separator before and after `for` block

Review Comment:
   But some places they follow it



-- 
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: issues-unsubscribe@iceberg.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org


Re: [PR] Docs: Update block spacing guideline in contribute.md [iceberg]

Posted by "ajantha-bhat (via GitHub)" <gi...@apache.org>.
ajantha-bhat commented on code in PR #12641:
URL: https://github.com/apache/iceberg/pull/12641#discussion_r2013364189


##########
site/docs/contribute.md:
##########
@@ -422,6 +422,50 @@ Use `this` when assigning values to instance variables, making it clear when the
 2. Use `.` to create a hierarchy of config groups
     * For example, `s3` in `s3.access-key-id`, `s3.secret-access-key`
 
+#### Block Spacing
+
+To improve readability and maintain consistency, always place a newline after control blocks (if, for, while, switch, etc.). 
+This helps separate logical sections of the code, making it easier to read and debug.
+
+```java
+  // BAD: No newline separator after `if` block
+  public static WriteBuilder write(OutputFile file) {
+     if (file instanceof EncryptedOutputFile) {
+        return write((EncryptedOutputFile) file);
+     }
+     return new WriteBuilder(file);
+  }
+
+  // GOOD: newline separator after `if` block
+  public static WriteBuilder write(OutputFile file) {
+     if (file instanceof EncryptedOutputFile) {
+        return write((EncryptedOutputFile) file);
+     }
+     
+     return new WriteBuilder(file);
+  }
+
+  // BAD: No newline separator after `for` block
+  public static Schema convert(final org.apache.iceberg.Schema schema) {

Review Comment:
   done



-- 
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: issues-unsubscribe@iceberg.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org


Re: [PR] Docs: Update block spacing guideline in contribute.md [iceberg]

Posted by "ajantha-bhat (via GitHub)" <gi...@apache.org>.
ajantha-bhat commented on code in PR #12641:
URL: https://github.com/apache/iceberg/pull/12641#discussion_r2012556259


##########
site/docs/contribute.md:
##########
@@ -422,6 +422,10 @@ Use `this` when assigning values to instance variables, making it clear when the
 2. Use `.` to create a hierarchy of config groups
     * For example, `s3` in `s3.access-key-id`, `s3.secret-access-key`
 
+#### Block Spacing
+
+To improve readability and maintain consistency, always place a newline after control blocks (if, for, while, switch, etc.). This helps separate logical sections of the code, making it easier to read and debug.      
+

Review Comment:
   done



-- 
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: issues-unsubscribe@iceberg.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org


Re: [PR] Docs: Update block spacing guideline in contribute.md [iceberg]

Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra commented on code in PR #12641:
URL: https://github.com/apache/iceberg/pull/12641#discussion_r2013456761


##########
site/docs/contribute.md:
##########
@@ -422,6 +422,50 @@ Use `this` when assigning values to instance variables, making it clear when the
 2. Use `.` to create a hierarchy of config groups
     * For example, `s3` in `s3.access-key-id`, `s3.secret-access-key`
 
+#### Block Spacing
+
+To improve readability and maintain consistency, always place a newline after control blocks (if, for, while, switch, etc.). 
+This helps separate logical sections of the code, making it easier to read and debug.
+
+```java
+  // BAD: No newline separator after `if` block
+  public static WriteBuilder write(OutputFile file) {
+     if (file instanceof EncryptedOutputFile) {
+        return write((EncryptedOutputFile) file);
+     }
+     return new WriteBuilder(file);
+  }
+
+  // GOOD: newline separator after `if` block
+  public static WriteBuilder write(OutputFile file) {
+     if (file instanceof EncryptedOutputFile) {
+        return write((EncryptedOutputFile) file);
+     }
+     
+     return new WriteBuilder(file);
+  }
+
+  // BAD: No newline separator before and after `for` block
+  public static Schema convert(Schema schema) {
+     ImmutableList.Builder<Field> fields = ImmutableList.builder();
+     for (NestedField f : schema.columns()) {
+        fields.add(convert(f));
+     }
+     return new Schema(fields.build());
+  }
+
+  // GOOD: newline separator before and after `for` block

Review Comment:
   I don't believe we ever said that there should be a newline before the block



-- 
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: issues-unsubscribe@iceberg.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org


Re: [PR] Docs: Update block spacing guideline in contribute.md [iceberg]

Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra merged PR #12641:
URL: https://github.com/apache/iceberg/pull/12641


-- 
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: issues-unsubscribe@iceberg.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org


Re: [PR] Docs: Update block spacing guideline in contribute.md [iceberg]

Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra commented on code in PR #12641:
URL: https://github.com/apache/iceberg/pull/12641#discussion_r2012521650


##########
site/docs/contribute.md:
##########
@@ -422,6 +422,10 @@ Use `this` when assigning values to instance variables, making it clear when the
 2. Use `.` to create a hierarchy of config groups
     * For example, `s3` in `s3.access-key-id`, `s3.secret-access-key`
 
+#### Block Spacing
+
+To improve readability and maintain consistency, always place a newline after control blocks (if, for, while, switch, etc.). This helps separate logical sections of the code, making it easier to read and debug.      
+

Review Comment:
   you might want to add a simple example to show what is meant here



-- 
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: issues-unsubscribe@iceberg.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org


Re: [PR] Docs: Update block spacing guideline in contribute.md [iceberg]

Posted by "ebyhr (via GitHub)" <gi...@apache.org>.
ebyhr commented on code in PR #12641:
URL: https://github.com/apache/iceberg/pull/12641#discussion_r2013356552


##########
site/docs/contribute.md:
##########
@@ -422,6 +422,50 @@ Use `this` when assigning values to instance variables, making it clear when the
 2. Use `.` to create a hierarchy of config groups
     * For example, `s3` in `s3.access-key-id`, `s3.secret-access-key`
 
+#### Block Spacing
+
+To improve readability and maintain consistency, always place a newline after control blocks (if, for, while, switch, etc.). 
+This helps separate logical sections of the code, making it easier to read and debug.
+
+```java
+  // BAD: No newline separator after `if` block
+  public static WriteBuilder write(OutputFile file) {
+     if (file instanceof EncryptedOutputFile) {
+        return write((EncryptedOutputFile) file);
+     }
+     return new WriteBuilder(file);
+  }
+
+  // GOOD: newline separator after `if` block
+  public static WriteBuilder write(OutputFile file) {
+     if (file instanceof EncryptedOutputFile) {
+        return write((EncryptedOutputFile) file);
+     }
+     
+     return new WriteBuilder(file);
+  }
+
+  // BAD: No newline separator after `for` block

Review Comment:
   ```suggestion
     // BAD: No newline separator before and after `for` block
   ```



-- 
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: issues-unsubscribe@iceberg.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org


Re: [PR] Docs: Update block spacing guideline in contribute.md [iceberg]

Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra commented on code in PR #12641:
URL: https://github.com/apache/iceberg/pull/12641#discussion_r2012585502


##########
site/docs/contribute.md:
##########
@@ -422,6 +422,50 @@ Use `this` when assigning values to instance variables, making it clear when the
 2. Use `.` to create a hierarchy of config groups
     * For example, `s3` in `s3.access-key-id`, `s3.secret-access-key`
 
+#### Block Spacing
+
+To improve readability and maintain consistency, always place a newline after control blocks (if, for, while, switch, etc.). 
+This helps separate logical sections of the code, making it easier to read and debug.
+
+```java
+  // BAD: No newline separator after `if` block
+  public static WriteBuilder write(OutputFile file) {
+     if (file instanceof EncryptedOutputFile) {
+        return write((EncryptedOutputFile) file);
+     }
+     return new WriteBuilder(file);
+  }
+
+  // GOOD: newline separator after `if` block
+  public static WriteBuilder write(OutputFile file) {
+     if (file instanceof EncryptedOutputFile) {
+        return write((EncryptedOutputFile) file);
+     }
+     
+     return new WriteBuilder(file);
+  }
+
+  // BAD: No newline separator after `for` block
+  public static Schema convert(final org.apache.iceberg.Schema schema) {

Review Comment:
   since we really only care about the newline, I would just change this example so that we don't deal with different Schema objects here, which could add confusion when reading it.
   ```
     // BAD: ...
     public static Schema convert(Schema schema) {
        ImmutableList.Builder<Field> fields = ImmutableList.builder();
        for (NestedField f : schema.columns()) {
           fields.add(convert(f));
        }
        return new Schema(fields.build());
     }
   ```
   ```
     // GOOD: ...
     public static Schema convert(Schema schema) {
        ImmutableList.Builder<Field> fields = ImmutableList.builder();
        for (NestedField f : schema.columns()) {
           fields.add(convert(f));
        }
   
        return new Schema(fields.build());
     }
   ```
   



-- 
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: issues-unsubscribe@iceberg.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org


Re: [PR] Docs: Update block spacing guideline in contribute.md [iceberg]

Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra commented on code in PR #12641:
URL: https://github.com/apache/iceberg/pull/12641#discussion_r2013456761


##########
site/docs/contribute.md:
##########
@@ -422,6 +422,50 @@ Use `this` when assigning values to instance variables, making it clear when the
 2. Use `.` to create a hierarchy of config groups
     * For example, `s3` in `s3.access-key-id`, `s3.secret-access-key`
 
+#### Block Spacing
+
+To improve readability and maintain consistency, always place a newline after control blocks (if, for, while, switch, etc.). 
+This helps separate logical sections of the code, making it easier to read and debug.
+
+```java
+  // BAD: No newline separator after `if` block
+  public static WriteBuilder write(OutputFile file) {
+     if (file instanceof EncryptedOutputFile) {
+        return write((EncryptedOutputFile) file);
+     }
+     return new WriteBuilder(file);
+  }
+
+  // GOOD: newline separator after `if` block
+  public static WriteBuilder write(OutputFile file) {
+     if (file instanceof EncryptedOutputFile) {
+        return write((EncryptedOutputFile) file);
+     }
+     
+     return new WriteBuilder(file);
+  }
+
+  // BAD: No newline separator before and after `for` block
+  public static Schema convert(Schema schema) {
+     ImmutableList.Builder<Field> fields = ImmutableList.builder();
+     for (NestedField f : schema.columns()) {
+        fields.add(convert(f));
+     }
+     return new Schema(fields.build());
+  }
+
+  // GOOD: newline separator before and after `for` block

Review Comment:
   I don't believe we ever said that there should be a newline before the block, so I would just remove this and update the example



-- 
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: issues-unsubscribe@iceberg.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org