Add a hint to avoid capitalisms #1608

bgohla · 2024-07-11T15:13:38Z

I add a module Hints.NoCapitalisms that provides a hint to avoid capitalisms in identifiers, with some exceptions. E.g.

class FOO a where
class Foo a where getFOO
data Foo = Bar | BAAZ
getSMS

are discouraged.

The hint has severity Ignored, so it is off by default.

Things that might need attention

potentially factor out some code.
break into several commits.

bgohla · 2024-07-11T15:15:48Z

src/Hint/NoCapitalisms.hs

+      a:b:c:as -> [a,b,c] : trigrams (c:as)
+      _otherwise -> []
+
+--- these are copied from Hint.Naming ---


If this PR goes ahead, I would propose factoring out the code below.

arybczak · 2024-08-25T18:16:27Z

src/Hint/NoCapitalisms.hs

+{-
+    Detect uses of capitalisms
+
+    Only allow up to two consecutive capital letters in identifiers.


What is the reason for this exception? ID? Personally I'd prefer uniformity here.

That would be one case.

I'm all for uniformity, by I'm afraid not allowing this exception could make this rule very annoying. Let me do some statistics on our internal code base…

Actually, prohibiting two consecutive capitals would catch an identifier like MVar, I think that would be awkward.

I agree, we should favor the spelling Id over ID, but I can't think of a good rule here, that doesn't also catch, e.g., getIData.

Maybe we could tighten the proposed rule to prohibit two consecutive capitals unless followed by a lower case letter.

This is a good point. There are many violations in the ecosystem that are utterly entrenched. Even if you try to be clever, for instance, allowing two capitals followed by lower-case / end of string, users will still need to do something about e.g. STM, TBQueue. There is no principled way to say the latter two are fine, but HTTP is not.

Hence I think the ideal solution would be to trigger on all consecutive capitals (no special rules), and allow users to easily disable specific cases globally. Can warnings be parameterized in this way? The best I can think of is something like:

# .hlint.yaml - ignore: name: "No Capitalism" within: # I think this could work for functions. - "Module.readTBQueue" # Does this work for type / data declarations? Or does this assume # module Another/TBQueue.hs? - "Another.TBQueue"

This doesn't get you a global rule for ignoring e.g. IO, but maybe it's workable enough.

I thought this PR only complains about local definitions, not all occurrences of such names 🤔 Doesn't it? If it does, then definitions from other packages are not a problem.

You are correct, though I am thinking of interop with upstream definitions, where re-using a captialized name is arguably more readable than adhering to this rule. For instance, I imagine quite a few people (most?) would say runInIO is better than runInIo, even for new definitions, because of how familiar IO is.

I thought this PR only complains about local definitions, not all occurrences of such names 🤔 Doesn't it? If it does, then definitions from other packages are not a problem.

This rule only checks top-level definitions of value, constructor, type and class identifiers; it does not check occurrences, be they imported or not.

# .hlint.yaml - ignore: name: "No Capitalism" within: # I think this could work for functions. - "Module.readTBQueue" # Does this work for type / data declarations? Or does this assume # module Another/TBQueue.hs? - "Another.TBQueue"

This doesn't get you a global rule for ignoring e.g. IO, but maybe it's workable enough.

I don't understand the configuration language well enough to be able to confirm that your suggestion works. OTOH, ANN pragmas might be more effective for defining exceptions.

@arybczak I have become convinced that the stricter rule is feasible, i.e., prohibiting all consecutive capitals, exceptions have to be allowed using pragmas.

src/Hint/NoCapitalisms.hs

zliu41 · 2025-06-13T04:31:33Z

src/Hint/NoCapitalisms.hs

+</TEST>
+-}
+
+module Hint.NoCapitalisms(noCapitalismsHint) where


"capitalism"? How about "NoCAPs"?

Capitalism, as in, an expression written in all caps.

I do not see such a meaning for capitalism in the dictionary.

Yeah, "NoCAPs" seems better since it doesn't have political connotations and shouldn't provoke unnecessary discussions, unlike the current name.

zliu41 · 2025-06-13T04:34:40Z

src/Hint/NoCapitalisms.hs

+import GHC.Util
+
+noCapitalismsHint :: DeclHint
+noCapitalismsHint _ _ decl = [ remark Ignore "Avoid capitalisms" (reLoc (shorten decl))


Add a Note to the hint, explaining what it does?

Isn't the description at beginning of the file sufficient? I followed the style of Hint.Naming.

That's just a code comment. A Note is attached to a hint and is displayed with the hint. Alternatively, you can make the hint name more descriptive: "Avoid three consecutive capital letters" instead of "Avoid capitalisms".

zliu41 · 2025-06-13T04:35:26Z

src/Hint/NoCapitalisms.hs

+
+--- these are copied from Hint.Naming ---
+
+shorten :: LHsDecl GhcPs -> LHsDecl GhcPs


Please add some comments explaining what this does.

bgohla commented Jul 11, 2024

View reviewed changes

bgohla force-pushed the noCapitalisms branch from a305b89 to 7013099 Compare July 11, 2024 15:24

arybczak reviewed Aug 25, 2024

View reviewed changes

tbidne reviewed Aug 26, 2024

View reviewed changes

src/Hint/NoCapitalisms.hs Outdated Show resolved Hide resolved

Add a hint to avoid capitalisms in identifiers, with some exceptions.

dcce769

bgohla force-pushed the noCapitalisms branch from c3bd578 to dcce769 Compare June 10, 2025 09:54

fix test cases, caveat descrition, a little refactor

bd5cb3c

zliu41 reviewed Jun 13, 2025

View reviewed changes

bgohla added 2 commits June 13, 2025 21:04

change criterion to two consecutive capitals

1a107f5

refactor name helper functions

82c4457

bgohla force-pushed the noCapitalisms branch from a2c8358 to 82c4457 Compare June 13, 2025 22:43

remove TODO

c268f6b


		--- these are copied from Hint.Naming ---

		shorten :: LHsDecl GhcPs -> LHsDecl GhcPs

Add a hint to avoid capitalisms #1608

Are you sure you want to change the base?

Add a hint to avoid capitalisms #1608

Uh oh!

Conversation

bgohla commented Jul 11, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bgohla Jul 11, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bgohla Sep 13, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bgohla Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bgohla Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bgohla commented Jul 11, 2024 •

edited

Loading

bgohla Jul 11, 2024 •

edited

Loading

bgohla Sep 13, 2024 •

edited

Loading

bgohla Jun 13, 2025 •

edited

Loading

bgohla Jun 13, 2025 •

edited

Loading