Why comment rules???
hohy opened this issue · 5 comments
Can I ask why do we have the capitalized-comments and line-comment-position rules active in default setting? Do we really need them? How they improve the code? What they bring except shitload of warning messages? And they are not autofixable...
capitalized-comments
I concur, I should have waited with this rule until it was fixable (it is as of ESLint 3.12 🎉). The intention was to make comments proper English, nothing more. 😄 I apologise if this made your day worse - I will be more careful with similar new rules in the future.
line-comment-position
This rule's configuration goes hand-in-hand with max-length rule. Let me first explain why we have that rule set to 100.
There have been studies about the optimal line length for humans to make reading easy and fast. For too long lines, the following issues occur (among others):
- The eye has to move much more, causing unnecessary strain
- Readers tend to skip to incorrect line when returning to the beginning
- For code specifically:
- Long lines usually imply there are too many statements in that line
- You are the victim of callback hell
- You are the victim of too much branching
Some might argue that this can be easily avoided by having your IDE soft-wrap the code. However, this has the same problems as using tabs instead of spaces for formatting - it is application-dependent, sometimes it is unavailable and in my personal experience, it never formats the code as well as a human would do it.
That's why there is a soft limit of 100 characters per line. Having this explained, it is quite easy to explain why we have line-comment-position set to only allow comments above code:
- Comments are usually used to explain something important -> it should not be at the end of the line where it might be missed, either when reading the code or during refactoring
- Inline comments increase the line length (see previous reasons why this is bad)
- Inline comments reduce the available space for actual code
Of course, if the team you work with decides that all of this is BS and you do not care, feel free to override these rules to a different setting. 😇
C'mon... we are writing source code, not a novel. But if the capitalized-commens rule is auto-fixable now and everyone else think it's necessary, I can probably live with it. But I still think we should have as few rules in default setting as possible and this is perfect example of a rule that should not be there.
For line-comment-position... I have no problem with max-length rule. It's one of really useful rules. But I don't see any connection between it and line-comment-possition. I guess you assume every comment needs to be full sentence, but again - it's source code, not a novel. I personally prefer comments as short as possible, just couple words, so you don't spent much time reading it. And for these short comments there is plenty of room in 100 characters. I'm not forcing anybody to write comments in this way, but I don't see any value in disabling it globally. Sometimes it might be useful and the max-length rule is enough to be sure code or comments are not overflowing of the screen.
Ultimately I must say I was wrong about enabling capitalized-comments rule - it's disabled now, will be released when new ESLint version gets out. See #14.
As for line-comment-position... you made a point. After sleeping on it for several days I agree with you - my original intent should be covered by max-length rule and there is no real necessity to enforce comment placements. Yay. 🎉
As for the idea of having as few rules in the default config as possible... The intention of this repository is to enforce a consistent coding style across all projects (mainly within STRV). You cannot do that with everything disabled - quite the contrary. You have to enable every possible rule and then selectively disable those who bring no value or do not quite work as we would like (like these comment rules, ie.).
Thanks for all your feedback.
Awesome! Thanks for reconsidering these rules.
Now released as 6.3. 🎉