Markdown Tables Formatting Convention

[ata-nas]

To Discuss

• what shall be our accepted convention to format the md tables

Reason

• we always change the whole formatting back and forth (done automatically by our IDEs usually) and that creates a needless effort.
• we should come up with a convention as to how we are going to format the tables and stick with it

Discussion

There are two ways to format the md tables:

---

Example 1:

| Environment Variable                  | Description                                                           |       Default Value |
| :------------------------------------ | :-------------------------------------------------------------------- | ------------------: |
| PERSISTENCE_STORAGE_LIVE_ROOT_PATH    | The root path for the live storage.                                   |                     |
| PERSISTENCE_STORAGE_ARCHIVE_ROOT_PATH | The root path for the archive storage.                                |                     |
| PERSISTENCE_STORAGE_TYPE              | Type of the persistence storage                                       | BLOCK_AS_LOCAL_FILE |
| PERSISTENCE_STORAGE_COMPRESSION       | Compression algorithm used during persistence (could be none as well) |                ZSTD |
| PERSISTENCE_STORAGE_COMPRESSION_LEVEL | Compression level to be used by the compression algorithm             |                   3 |
| CONSUMER_TIMEOUT_THRESHOLD_MILLIS     | Time to wait for subscribers before disconnecting in milliseconds     |                1500 |
| SERVICE_DELAY_MILLIS                  | Service shutdown delay in milliseconds                                |                 500 |
| MEDIATOR_RING_BUFFER_SIZE             | Size of the ring buffer used by the mediator (must be a power of 2)   |            67108864 |
| MEDIATOR_TYPE                         | Type of mediator to use                                               |                     |
| NOTIFIER_RING_BUFFER_SIZE             | Size of the ring buffer used by the notifier (must be a power of 2)   |                2048 |
| PRODUCER_TYPE                         | Type of producer to use                                               |                     |
| SERVER_PORT                           | The port the server will listen on                                    |                8080 |
| SERVER_MAX_MESSAGE_SIZE_BYTES         | The maximum size of a message frame in bytes                          |             1048576 |
| PROMETHEUS_ENDPOINT_ENABLED           | Whether the Prometheus metrics endpoint is enabled                    |                true |
| PROMETHEUS_ENDPOINT_PORT_NUMBER       | The port number for the Prometheus metrics endpoint                   |                9090 |

Pros:

• more human readable in raw format

Cons:

• we rely on IDE formatting (most likely) to support this formatting when we change the table
• without automatic formatting it is very hard to manually maintain
• redundant whitespaces and dashes

---

Example 2:

| Environment Variable | Description | Default Value |
|:---|:---|---:|
| PERSISTENCE_STORAGE_LIVE_ROOT_PATH | The root path for the live storage. | |
| PERSISTENCE_STORAGE_ARCHIVE_ROOT_PATH | The root path for the archive storage. | |
| PERSISTENCE_STORAGE_TYPE | Type of the persistence storage | BLOCK_AS_LOCAL_FILE |
| PERSISTENCE_STORAGE_COMPRESSION | Compression algorithm used during persistence (could be none as well) | ZSTD |
| PERSISTENCE_STORAGE_COMPRESSION_LEVEL | Compression level to be used by the compression algorithm | 3 |
| CONSUMER_TIMEOUT_THRESHOLD_MILLIS | Time to wait for subscribers before disconnecting in milliseconds | 1500 |
| SERVICE_DELAY_MILLIS | Service shutdown delay in milliseconds | 500 |
| MEDIATOR_RING_BUFFER_SIZE | Size of the ring buffer used by the mediator (must be a power of 2) | 67108864 |
| NOTIFIER_RING_BUFFER_SIZE | Size of the ring buffer used by the notifier (must be a power of 2) | 2048 |
| SERVER_PORT | The port the server will listen on | 8080 |
| SERVER_MAX_MESSAGE_SIZE_BYTES | The maximum size of a message frame in bytes | 1048576 |

Pros:

• very easy to support
• no redundant dashes and whitespaces
• no need for automatic formatting tool (which some may not have)

Cons:

• less human readable when raw

---

[ata-nas]

@jsync-swirlds @AlfredoG87 @mattp-swirldslabs @georgi-l95

Let's vote on this and come up with a convention that we must follow, we have a lot of conflicts about this formatting.

I suggest:
Those in favor of Example 2 above (this includes me), upvote.

[mattp-swirldslabs]

Is there already a company precedent?

[AlfredoG87]

yes, I have found many examples across services and mirror node where they use example 1.
https://raw.githubusercontent.com/hashgraph/hedera-services/refs/heads/develop/docs/hedera-java-style-guide.md
https://raw.githubusercontent.com/hashgraph/hedera-services/refs/heads/develop/hedera-node/docs/system-accounts-operations.md
https://raw.githubusercontent.com/hashgraph/hedera-mirror-node/refs/heads/main/docs/configuration.md
https://raw.githubusercontent.com/hashgraph/hedera-mirror-node/refs/heads/main/docs/troubleshooting.md

that said, I've also found examples similar to example 2.

https://raw.githubusercontent.com/hashgraph/hedera-services/refs/heads/develop/hedera-node/docs/autorenew-feature.md
https://raw.githubusercontent.com/hashgraph/hedera-services/refs/heads/develop/hedera-node/docs/privileged-transactions.md

• Mirror node is more strict and there all tables are formatted like example1, we also do it like that on relay.

[jsync-swirlds]

It's very inconsistent in some of the other projects.
There isn't truly a precedent, more just people accepting IDE default behavior without thinking.

[jasperpotts]

I vote for Example 1 😀 little more work if IDE does not help you but so much more readable and easy to verify you have right thing in right column

[AlfredoG87]

IntelliJ does the format automatically for you, so is actually easier. (however I guess you can configure the IDE either way, but example 1 is the default)

[jasperpotts]

I would have done it manually if IDE did not do it for me. I am fussy about formatting. I brain is very visual so having things in being ordered and structured makes a huge difference in readability for me.

[jsync-swirlds]

I find the second example much easier to read, particularly if the table ends up large (I've seen tables that scroll forever even on really large screens).

If I want to check the visual, I just look at the rendered view (which IDEs also do for you).

[ata-nas]

So, the result currently seems to be:
(no pun intended!)

Example 2 as convention

For	Against	Undecided
@ata-nas
@jsync-swirlds
	@jasperpotts
	@AlfredoG87
		@mattp-swirldslabs
		@georgi-l95

@mattp-swirldslabs @georgi-l95 feel free to add yourselves since I cannot deduce from the discussion :)