Set of rules to ignore for code-focused editing?

[idbrii]

I'm primarily using harper to check my writing in strings and comments in code. I feel like a lot of features are more focused on regular prose/poetry/technical writing that don't apply to the terser style used in code documentation. There's a huge list of rules so I'd love to know what other people in the same boat are using.

I've also found that harper checks commented-out Lua code, so I've turned off a lot of rules that trigger those warnings.

Here's my neovim config for harper, but it should be pretty clear which rules I have disabled:

lspconfig.harper_ls.setup {
    settings = {
        ["harper-ls"] = {
            linters = { -- https://writewithharper.com/docs/rules
                SpellCheck = false,  -- Doesn't respect my multiple vim dictionaries, so disable.

                AnA = false,  -- I don't always capitalize acronyms (eg, npc).
                DotInitialisms = false,  -- e.g. is too long.
                InflectedVerbAfterTo = false, -- "set to selected state" is common terse form.
                Overall = false,  -- False positives. #1249
                ToDoHyphen = false,  -- Always use todo.
                USUniversities = false,  -- I'm not in the US.

                -- Disabled due to example code in comments.
                CapitalizePersonalPronouns = false, -- i is a common variable name.
                CommaFixes = false,  -- Lua often uses commas without following space.
                Dashes = false, -- Lua uses dashes for comments.
                EllipsisLength = false, -- .. is string concat in Lua.
                ExpandDependencies = false,  -- deps is a common variable name.
                ExpandDependency = false,  -- dep is a common variable name.
                ExpandMinimum = false, -- min() is a function.
                ExpandStandardInput = false,  -- stdin is a common variable name.
                ExpandStandardOutput = false,  -- stdout is a common variable name.
                ExpandTimeShorthands = false,  -- Common variable names.
                ExpandWith = false,  -- Dividing width (w/2) is common.
                LongSentences = false,  -- Code looks like long sentences.
                PhrasalVerbAsCompoundNoun = false,  -- Complains about "startup_level".
                SentenceCapitalization = false,  -- Code doesn't start with capital.
                Spaces = false,  -- Code has lots of spaces.
            },
        },
    },
}

[hippietrail]

I mentioned similar sentiments when I first became active in Harper a couple of months ago.

We actually have conflicting rules in Harper for TODO and Todo, which are both in the spelling dictionary and to-do which is in a lint. I personally always use TODO. I think best would be to have a multi-way setting but I think everything is based on every setting being binary on-off. I've mentioned this a few times in the past too.

You bring up some excellent points about commented-out code though! It would probably be best if we could try to detect commented-out code vs prose comments, but it's probably quite difficult to do.

Documentation comments should ideally have different settings, possibly all block-comments / multi-line comments, vs. spot comments such as end-of-line comments or single-line comments interleaving code

AnA shouldn't have any bearing on whether acronyms are capitalized though?

[idbrii]

Yeah, ignoring commented-out code would be great. An option to only lint comments that end with period/punctuation could work, but maybe too restrictive. There's also code in documentation comments which would be even harder to detect since you'd definitely want to lint the rest of the comment.

I played with the long sentence detector once for something else I was doing and the problem is it expects multi-line comments, which are often the most crucial ones in code you're trying to understand, so they need to have the best English.

I think I mentioned back when I came on the scene about single-line vs multiline comments too. I did a tiny bit of research today looking into what people have done to detect commented-out code before. Turns out it's a subject people have written their thesis on before.

AnA shouldn't have any bearing on whether acronyms are capitalized though?

"Detect an npc with a hat." will flag an because it sees npc as a word instead of an acronym.

Ah yes good point. I was aware of that. Must've had my NPC hat on when I wrote my previous reply (-:

[elijah-potter]

You bring up some excellent points about commented-out code though! It would probably be best if we could try to detect commented-out code vs prose comments, but it's probably quite difficult to do.

This was the original intention of the isolateEnglish config.

We actually have conflicting rules in Harper for TODO and Todo, which are both in the spelling dictionary and to-do which is in a lint. I personally always use TODO. I think best would be to have a multi-way setting but I think everything is based on every setting being binary on-off. I've mentioned this a few times in the past too.

Same goes for the oxford comma rules. Do we have an open issue about this?

[hippietrail]

You bring up some excellent points about commented-out code though! It would probably be best if we could try to detect commented-out code vs prose comments, but it's probably quite difficult to do.

This was the original intention of the isolateEnglish config.

We actually have conflicting rules in Harper for TODO and Todo, which are both in the spelling dictionary and to-do which is in a lint. I personally always use TODO. I think best would be to have a multi-way setting but I think everything is based on every setting being binary on-off. I've mentioned this a few times in the past too.

Same goes for the oxford comma rules. Do we have an open issue about this?

I thought I must've made one for it because I've brought it up at least a few times and started looking into the code for what would be needed to go beyond only on-off settings today, but I was also doing a bunch of other things and that one didn't get far. I'll look again... No at least I never filed a specific issue for it.