Wrap code at 120 characters #3
Comments
Problem: bisq-network/style#3 indicates code should be wrapped at 120 characters, but it is likely that people will forget and that this habit will only change slowly. Solution: Configure IDEA to wrap lines automatically when typing past 120 characters, forcing the reminder to happen in real time. If this becomes a nuisance, we can remove it later. Note that this change also explicitly sets the RIGHT_MARGIN value to 120, even though this is already IDEA's default value. This is simply to be explicit and self-documenting.
Problem: bisq-network/style#3 indicates code should be wrapped at 120 characters, but it is likely that people will forget and that this habit will only change slowly. Solution: Configure IDEA to wrap lines automatically when typing past 120 characters, forcing the reminder to happen in real time. If this becomes a nuisance, we can remove it later. Note that this change also explicitly sets the RIGHT_MARGIN value to 120, even though this is already IDEA's default value. This is simply to be explicit and self-documenting.
Problem: bisq-network/style#3 indicates code should be wrapped at 120 characters, but it is likely that people will forget and that this habit will only change slowly. Solution: Configure IDEA to wrap lines automatically when typing past 120 characters, forcing the reminder to happen in real time. If this becomes a nuisance, we can remove it later. Note that this change also explicitly sets the RIGHT_MARGIN value to 120, even though this is already IDEA's default value. This is simply to be explicit and self-documenting.
Problem: bisq-network/style#3 indicates code should be wrapped at 120 characters, but it is likely that people will forget and that this habit will only change slowly. Solution: Configure IDEA to wrap lines automatically when typing past 120 characters, forcing the reminder to happen in real time. If this becomes a nuisance, we can remove it later. Note that this change also explicitly sets the RIGHT_MARGIN value to 120, even though this is already IDEA's default value. This is simply to be explicit and self-documenting.
Problem: bisq-network/style#3 indicates code should be wrapped at 120 characters, but it is likely that people will forget and that this habit will only change slowly. Solution: Configure IDEA to wrap lines automatically when typing past 120 characters, forcing the reminder to happen in real time. If this becomes a nuisance, we can remove it later. Note that this change also explicitly sets the RIGHT_MARGIN value to 120, even though this is already IDEA's default value. This is simply to be explicit and self-documenting.
Problem: bisq-network/style#3 indicates code should be wrapped at 120 characters, but it is likely that people will forget and that this habit will only change slowly. Solution: Configure IDEA to wrap lines automatically when typing past 120 characters, forcing the reminder to happen in real time. If this becomes a nuisance, we can remove it later. Note that this change also explicitly sets the RIGHT_MARGIN value to 120, even though this is already IDEA's default value. This is simply to be explicit and self-documenting.
Problem: bisq-network/style#3 indicates code should be wrapped at 120 characters, but it is likely that people will forget and that this habit will only change slowly. Solution: Configure IDEA to wrap lines automatically when typing past 120 characters, forcing the reminder to happen in real time. If this becomes a nuisance, we can remove it later. Note that this change also explicitly sets the RIGHT_MARGIN value to 120, even though this is already IDEA's default value. This is simply to be explicit and self-documenting.
Problem: bisq-network/style#3 indicates code should be wrapped at 120 characters, but it is likely that people will forget and that this habit will only change slowly. Solution: Configure IDEA to wrap lines automatically when typing past 120 characters, forcing the reminder to happen in real time. If this becomes a nuisance, we can remove it later. Note that this change also explicitly sets the RIGHT_MARGIN value to 120, even though this is already IDEA's default value. This is simply to be explicit and self-documenting.
Problem: bisq-network/style#3 indicates code should be wrapped at 120 characters, but it is likely that people will forget and that this habit will only change slowly. Solution: Configure IDEA to wrap lines automatically when typing past 120 characters, forcing the reminder to happen in real time. If this becomes a nuisance, we can remove it later. Note that this change also explicitly sets the RIGHT_MARGIN value to 120, even though this is already IDEA's default value. This is simply to be explicit and self-documenting.
* wqking-master: Wrap code at 120 characters (bisq-network/style#3) List InstaCash (ICH)
|
@ManfredKarrer wrote at https://bisq.slack.com/archives/C91AM9JKV/p1521605566000003:
I do find this pretty important, @ManfredKarrer, not in any one particular instance, but for the overall health of a codebase. I'm not sure whether you saw the original description above or not, but do check it out, the main points of my rationale are there. There are, without a doubt, exceptions to the 120 rule, and that's why I would never introduce a "hard enforcement" of the rule, e.g. an automatic formatter that forces line breaks, or a something like checkstyle that would break the build on a violation. The middle ground is to configure IDEA to automatically wrap lines at the 120 char margin as a kind of friendly reminder, and that's what I've done in the commits above. If, as a developer you have a good reason to extend past 120, then you can ignore that hint from IDEA and re-join onto a single line. But the point of this style guideline is that doing that really should be the exception. And this is probably where we need to get aligned. Having long lines by default is just very bad for readability and comprehension (by anyone other than the original author at the time they are writing that line), essentially for the same reasons that it's hard to read very long lines of prose: it's too much for the eye to scan and for the brain to parse all at once. It's not a question of long variable names--I too prefer "clear, descriptive names" that are not artificially shortened. In my experience, it is almost always possible to use correct, idiomatic variable names, type names, and generics while keeping a line to 120 characters or less, given that one is mindful of making each line of code do just one thing, not two or three or more. Extract explanatory private methods wherever it improves comprehensibility and reduces complexity, break naturally long single-purpose statements up into multiple lines as necessary, etc, and begin to think of lines that are going past 120 characters as a signal that a line of code isn't just "too long" merely for aesthetic reasons, but that it is "doing too much" to be easily understood, reviewed and maintained over time. I hope this helps, and I'm happy to have further conversation about it as necessary. That's why, by the way, these style guidelines are modeled first here as GitHub issues--so that we can have discussions about them. Once it's clear that we have a consensus, and that contributors are actually adhering to them, we can codify them a bit more into a README in the root of this repository that becomes something like an official Bisq style guide. See #1 for more details on that process. |
|
Here are my comments from the Slack conversation: Just saw an example what I meant with bad breaks: specially those string separations are annoying. they happen with i18n string often as they tend to be longer due name spaces" |
|
@ManfredKarrer and I agreed to disable IDEA's automatic 'wrap on typing' feature at the 120 character margin because it was causing slowdowns and frustrations on his side. Wrapping at 120 isn't generally the problem, but rather IDEA forcing the wrap and causing re-work. Manfred would rather choose when and where to break manually, and that's fine. |
Problem: bisq-network/style#3 indicates code should be wrapped at 120 characters, but it is likely that people will forget and that this habit will only change slowly. Solution: Configure IDEA to wrap lines automatically when typing past 120 characters, forcing the reminder to happen in real time. If this becomes a nuisance, we can remove it later. Note that this change also explicitly sets the RIGHT_MARGIN value to 120, even though this is already IDEA's default value. This is simply to be explicit and self-documenting.
- Wrap comments at 90 chars per bisq-network/style#5 - Wrap code at 120 chars per bisq-network/style#3 - Remove unused imports - Remove extra newlines - Format code where appropriate - Remove unused Javadoc tags, e.g. @return, @param - End Javadoc summary sentence with a period where missing - Remove HTML formatting in Javadoc, e.g. extra <br>s
- Wrap comments at 90 chars per bisq-network/style#5 - Wrap code at 120 chars per bisq-network/style#3 - Remove unused imports - Remove extra newlines - Format code where appropriate - Remove unused Javadoc tags, e.g. @return, @param - End Javadoc summary sentence with a period where missing - Remove HTML formatting in Javadoc, e.g. extra <br>s
It is conventional to wrap lines of (Java) code at 120 characters. This is IDEA's default wrap margin, and (most importantly) it is the number of characters that can be displayed in GitHub's web UI without requiring horizontal scrolling.
Keeping lines of code to 120 characters or less therefore improves readability and reviewability. More generally, though, it is a code smell for lines of code to longer than this. It usually indicates that there is too much going on in a single statement and that things need to be broken up. Refactor code as necessary to eliminate the need to exceed 120 chars, or at the very least add line breaks to the code that help the reader parse and understand it more efficiently.
The text was updated successfully, but these errors were encountered: