I think the first one flows better and reads easier. I believe it's because I read it left-to-right and found myself consuming the content as I was going wheras the second example I needed to re-read the table a few times to understand what it was actually representin.
This might also be aided by the fact I didn't even read the request first, rather I looked at the two tables and the first caught my eye way more than the second.
This is why I much prefer the first table: it follows natural reading order for me. The second table made me read top-to-bottom by column in order for it make sense.
Aug 16, 2023·edited Aug 16, 2023Liked by Kent Beck
I think those 2 tables can be combined to one, which combines advantage of both tables. The advantage of first table is that it is natural for human who read from left to right. The advantage of the second table is that it has book information.
----------| who ----| when----| what---- | how----- | why----- |
There is no clear indication that the commenter appreciated the change.
Having worked on this codebase in the past, I don't find the improvement in readability of RealCall.kt to be significant. It may be because I rarely read a file from top to bottom to understand it; I prefer to follow call chains. If other programmers are the same, it may explain why it's not common to find examples for this kind of refactoring.
“I wanted users to know that they mattered & programmers to know that they mattered & what I had written was being used to squash them both.”
The principles in the agile manifesto pretty well communicated these values. Many people don’t believe in those values and simply misused “agile” for their own purposes. But that doesn’t change the reality of what was originally intended or communicated.
There are always those who believe and those that just ride the bandwagon. Don’t stop believing.
The top one feels like a great cheatsheet for an easy lookup while the second one made me stop and think about which book I may need to open depending on what I need at the time.
I have a preference for the top one, it is easier to read for me.
Not sure why, but it looks like I start reading these kinds of tables on the first column, top-to-bottom.
In the case of the second table, that makes me read "who? when? what? how? why?", which seems to confuse me.
Thank you 🙏 That’s why I love this community—quick, clear feedback.
I think the first one flows better and reads easier. I believe it's because I read it left-to-right and found myself consuming the content as I was going wheras the second example I needed to re-read the table a few times to understand what it was actually representin.
This might also be aided by the fact I didn't even read the request first, rather I looked at the two tables and the first caught my eye way more than the second.
This is why I much prefer the first table: it follows natural reading order for me. The second table made me read top-to-bottom by column in order for it make sense.
I think those 2 tables can be combined to one, which combines advantage of both tables. The advantage of first table is that it is natural for human who read from left to right. The advantage of the second table is that it has book information.
----------| who ----| when----| what---- | how----- | why----- |
----------|----------|----------|----------|----------|----------|
this book | Row 1 | Row 1 | Row 1 | Row 1 | Row 1 |
next book | Row 2 | Row 2 | Row 2 | Row 2 | Row 2 |
later -----| Row 3 | Row 3 | Row 3 | Row 3 | Row 3 |
This is an example of re-ordering from OkHttp: https://github.com/square/okhttp/pull/5767. It's not ideal because it includes other changes as well.
Thank you for that. Did commenters seem to appreciate the change in ordering?
There is no clear indication that the commenter appreciated the change.
Having worked on this codebase in the past, I don't find the improvement in readability of RealCall.kt to be significant. It may be because I rarely read a file from top to bottom to understand it; I prefer to follow call chains. If other programmers are the same, it may explain why it's not common to find examples for this kind of refactoring.
“I wanted users to know that they mattered & programmers to know that they mattered & what I had written was being used to squash them both.”
The principles in the agile manifesto pretty well communicated these values. Many people don’t believe in those values and simply misused “agile” for their own purposes. But that doesn’t change the reality of what was originally intended or communicated.
There are always those who believe and those that just ride the bandwagon. Don’t stop believing.
I like the 2nd layout better. with Topic as the first column. Easier for me to understand columns.
I prefer the top one, but my reaction is that I would like columns in the order: what, who, when, how why.
The top one feels like a great cheatsheet for an easy lookup while the second one made me stop and think about which book I may need to open depending on what I need at the time.