diff mbox series

[4/6] PCI: qcom: Clean up ASPM comment

Message ID 20231114135553.32301-5-johan+linaro@kernel.org
State New
Headers show
Series PCI: Fix deadlocks when enabling ASPM | expand

Commit Message

Johan Hovold Nov. 14, 2023, 1:55 p.m. UTC
Break up the newly added ASPM comment so that it fits within the soft 80
character limit and becomes more readable.

Signed-off-by: Johan Hovold <johan+linaro@kernel.org>
---
 drivers/pci/controller/dwc/pcie-qcom.c | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

Comments

Manivannan Sadhasivam Nov. 17, 2023, 10:32 a.m. UTC | #1
On Tue, Nov 14, 2023 at 02:55:51PM +0100, Johan Hovold wrote:
> Break up the newly added ASPM comment so that it fits within the soft 80
> character limit and becomes more readable.
> 
> Signed-off-by: Johan Hovold <johan+linaro@kernel.org>

I think we discussed (80column soft limit for comments) in the past, but I don't
think breaking here makes the comment more readable.

- Mani

> ---
>  drivers/pci/controller/dwc/pcie-qcom.c | 5 ++++-
>  1 file changed, 4 insertions(+), 1 deletion(-)
> 
> diff --git a/drivers/pci/controller/dwc/pcie-qcom.c b/drivers/pci/controller/dwc/pcie-qcom.c
> index 21523115f6a4..a6f08acff3d4 100644
> --- a/drivers/pci/controller/dwc/pcie-qcom.c
> +++ b/drivers/pci/controller/dwc/pcie-qcom.c
> @@ -969,7 +969,10 @@ static int qcom_pcie_post_init_2_7_0(struct qcom_pcie *pcie)
>  
>  static int qcom_pcie_enable_aspm(struct pci_dev *pdev, void *userdata)
>  {
> -	/* Downstream devices need to be in D0 state before enabling PCI PM substates */
> +	/*
> +	 * Downstream devices need to be in D0 state before enabling PCI PM
> +	 * substates.
> +	 */
>  	pci_set_power_state(pdev, PCI_D0);
>  	pci_enable_link_state_locked(pdev, PCIE_LINK_STATE_ALL);
>  
> -- 
> 2.41.0
>
Johan Hovold Nov. 17, 2023, 10:48 a.m. UTC | #2
On Fri, Nov 17, 2023 at 04:02:27PM +0530, Manivannan Sadhasivam wrote:
> On Tue, Nov 14, 2023 at 02:55:51PM +0100, Johan Hovold wrote:
> > Break up the newly added ASPM comment so that it fits within the soft 80
> > character limit and becomes more readable.
> > 
> > Signed-off-by: Johan Hovold <johan+linaro@kernel.org>
> 
> I think we discussed (80column soft limit for comments) in the past, but I don't
> think breaking here makes the comment more readable.

The coding style clearly states:

	The preferred limit on the length of a single line is 80 columns.

	Statements longer than 80 columns should be broken into sensible chunks,
	unless exceeding 80 columns significantly increases readability and does
	not hide information.

Going beyond 80 chars may sometimes be warranted for code, but the
exception is not intended for comments.

Johan
Manivannan Sadhasivam Nov. 17, 2023, 10:54 a.m. UTC | #3
On Fri, Nov 17, 2023 at 11:48:10AM +0100, Johan Hovold wrote:
> On Fri, Nov 17, 2023 at 04:02:27PM +0530, Manivannan Sadhasivam wrote:
> > On Tue, Nov 14, 2023 at 02:55:51PM +0100, Johan Hovold wrote:
> > > Break up the newly added ASPM comment so that it fits within the soft 80
> > > character limit and becomes more readable.
> > > 
> > > Signed-off-by: Johan Hovold <johan+linaro@kernel.org>
> > 
> > I think we discussed (80column soft limit for comments) in the past, but I don't
> > think breaking here makes the comment more readable.
> 
> The coding style clearly states:
> 
> 	The preferred limit on the length of a single line is 80 columns.
> 
> 	Statements longer than 80 columns should be broken into sensible chunks,
> 	unless exceeding 80 columns significantly increases readability and does
> 	not hide information.
> 
> Going beyond 80 chars may sometimes be warranted for code, but the
> exception is not intended for comments.
> 

Breaking the comment here is indeed making it hard to read. It's just one word
that needs to be broken if we go by 80 column limit and I won't prefer that,
sorry!

- Mani

> Johan
Johan Hovold Nov. 17, 2023, 11 a.m. UTC | #4
On Fri, Nov 17, 2023 at 04:24:04PM +0530, Manivannan Sadhasivam wrote:
> On Fri, Nov 17, 2023 at 11:48:10AM +0100, Johan Hovold wrote:
> > On Fri, Nov 17, 2023 at 04:02:27PM +0530, Manivannan Sadhasivam wrote:
> > > On Tue, Nov 14, 2023 at 02:55:51PM +0100, Johan Hovold wrote:
> > > > Break up the newly added ASPM comment so that it fits within the soft 80
> > > > character limit and becomes more readable.
> > > > 
> > > > Signed-off-by: Johan Hovold <johan+linaro@kernel.org>
> > > 
> > > I think we discussed (80column soft limit for comments) in the past, but I don't
> > > think breaking here makes the comment more readable.
> > 
> > The coding style clearly states:
> > 
> > 	The preferred limit on the length of a single line is 80 columns.
> > 
> > 	Statements longer than 80 columns should be broken into sensible chunks,
> > 	unless exceeding 80 columns significantly increases readability and does
> > 	not hide information.
> > 
> > Going beyond 80 chars may sometimes be warranted for code, but the
> > exception is not intended for comments.
> 
> Breaking the comment here is indeed making it hard to read. It's just one word
> that needs to be broken if we go by 80 column limit and I won't prefer that,
> sorry!

Please read the above quote again, it is as clear as it gets. 80 chars
is the preferred limit unless (for code) exceeding it *significantly*
increases readability, which clearly isn't the case here (even if this
exception applied to comments).

I really don't understand why you keep insisting on this. Just fix your
editor.

Johan
Manivannan Sadhasivam Nov. 17, 2023, 11:23 a.m. UTC | #5
On Fri, Nov 17, 2023 at 12:00:44PM +0100, Johan Hovold wrote:
> On Fri, Nov 17, 2023 at 04:24:04PM +0530, Manivannan Sadhasivam wrote:
> > On Fri, Nov 17, 2023 at 11:48:10AM +0100, Johan Hovold wrote:
> > > On Fri, Nov 17, 2023 at 04:02:27PM +0530, Manivannan Sadhasivam wrote:
> > > > On Tue, Nov 14, 2023 at 02:55:51PM +0100, Johan Hovold wrote:
> > > > > Break up the newly added ASPM comment so that it fits within the soft 80
> > > > > character limit and becomes more readable.
> > > > > 
> > > > > Signed-off-by: Johan Hovold <johan+linaro@kernel.org>
> > > > 
> > > > I think we discussed (80column soft limit for comments) in the past, but I don't
> > > > think breaking here makes the comment more readable.
> > > 
> > > The coding style clearly states:
> > > 
> > > 	The preferred limit on the length of a single line is 80 columns.
> > > 
> > > 	Statements longer than 80 columns should be broken into sensible chunks,
> > > 	unless exceeding 80 columns significantly increases readability and does
> > > 	not hide information.
> > > 
> > > Going beyond 80 chars may sometimes be warranted for code, but the
> > > exception is not intended for comments.
> > 
> > Breaking the comment here is indeed making it hard to read. It's just one word
> > that needs to be broken if we go by 80 column limit and I won't prefer that,
> > sorry!
> 
> Please read the above quote again, it is as clear as it gets. 80 chars
> is the preferred limit unless (for code) exceeding it *significantly*

Where does it say "code" in the Documentation? As I read it, the doc weighs both
code and comment as "statement".

And how on the world that breaking a single word to the next line improves
readability? I fail to get it :/

> increases readability, which clearly isn't the case here (even if this
> exception applied to comments).
> 
> I really don't understand why you keep insisting on this. Just fix your
> editor.
> 

May you should fix yours to extend the limit to 100?

But I do not want to get into a spat here. Checkpatch, the tool supposed to
check for the kernel coding style is not complaining and I do not want a patch
that _fixes_ a coding style that is not an issue.

And I do not want to argue more on this. If the PCI maintainers are comfortable
with this patch, they can apply it, but I'm not.

- Mani

> Johan
Johan Hovold Nov. 17, 2023, 2:03 p.m. UTC | #6
On Fri, Nov 17, 2023 at 04:53:52PM +0530, Manivannan Sadhasivam wrote:
> On Fri, Nov 17, 2023 at 12:00:44PM +0100, Johan Hovold wrote:
> > On Fri, Nov 17, 2023 at 04:24:04PM +0530, Manivannan Sadhasivam wrote:
> > > On Fri, Nov 17, 2023 at 11:48:10AM +0100, Johan Hovold wrote:

> > > > The coding style clearly states:
> > > > 
> > > > 	The preferred limit on the length of a single line is 80 columns.
> > > > 
> > > > 	Statements longer than 80 columns should be broken into sensible chunks,
> > > > 	unless exceeding 80 columns significantly increases readability and does
> > > > 	not hide information.
> > > > 
> > > > Going beyond 80 chars may sometimes be warranted for code, but the
> > > > exception is not intended for comments.
> > > 
> > > Breaking the comment here is indeed making it hard to read. It's just one word
> > > that needs to be broken if we go by 80 column limit and I won't prefer that,
> > > sorry!
> > 
> > Please read the above quote again, it is as clear as it gets. 80 chars
> > is the preferred limit unless (for code) exceeding it *significantly*
> 
> Where does it say "code" in the Documentation? As I read it, the doc weighs both
> code and comment as "statement".

No, comments are not statements (in C).

You'd also never even consider interpreting it that way if you knew
where that exception comes from (namely that people break long
*statements* just to fit under 80 chars, thereby sometimes making the
*code* unnecessarily hard to read).

> And how on the world that breaking a single word to the next line improves
> readability? I fail to get it :/

You got it backwards; you should only go *beyond* 80 chars if it
"significantly increases readability".

But again, this does NOT apply to comments in the first place.

> > increases readability, which clearly isn't the case here (even if this
> > exception applied to comments).
> > 
> > I really don't understand why you keep insisting on this. Just fix your
> > editor.

> But I do not want to get into a spat here. Checkpatch, the tool supposed to
> check for the kernel coding style is not complaining and I do not want a patch
> that _fixes_ a coding style that is not an issue.

Checkpatch is just a tool, not the standard, and knowing when it is ok
to break the 80 column rule for code requires human judgement.

Johan
diff mbox series

Patch

diff --git a/drivers/pci/controller/dwc/pcie-qcom.c b/drivers/pci/controller/dwc/pcie-qcom.c
index 21523115f6a4..a6f08acff3d4 100644
--- a/drivers/pci/controller/dwc/pcie-qcom.c
+++ b/drivers/pci/controller/dwc/pcie-qcom.c
@@ -969,7 +969,10 @@  static int qcom_pcie_post_init_2_7_0(struct qcom_pcie *pcie)
 
 static int qcom_pcie_enable_aspm(struct pci_dev *pdev, void *userdata)
 {
-	/* Downstream devices need to be in D0 state before enabling PCI PM substates */
+	/*
+	 * Downstream devices need to be in D0 state before enabling PCI PM
+	 * substates.
+	 */
 	pci_set_power_state(pdev, PCI_D0);
 	pci_enable_link_state_locked(pdev, PCIE_LINK_STATE_ALL);