I read in this Swift Style Guide, which is apparently based on Apple's own Swift library style:
'Non-documentation comments always use the double-slash format (//), never the C-style block format (/* ... */).'
Why is it important not to use C-style comments for multiple lines?
There's a few benefits I see in favour of single line comments (//) over multi-line comments (/* */, calling these "C-style" doesn't really make sense, because both styles are valid in C) are easier to toggle.
Single-line comments are easier to insert/remove, because most IDEs have a shortcut for toggling them. In Xcode, it's ⌘ + / by default.
Multi-line comments introduce more opportunities of inconsistency. Which of these should be used?
This approach is compact, but disturbs the horizontal alignment of A
/* A
B
C */
This approach keeps the alignment of elements intact, but wastes vertical space:
/*
A
B
C
*/
This approach keeps alignment of elements intact, and doesn't take too much extra vertical space
/*
A
B
C */
This is the worst of both worlds, I wouldn't recommend it.
/* A
B
C
*/
This is just better in every way. Alignment is intact. No extra horizontal space is wasted.
// A
// B
// C
It's easier to make changes to a commented section with single-line comments. Compare:
With single line comments, it's only a single action of removing the leading //s in the relevant places
Before:
// A
// B
// C
After:
// A
// B
C // Just had to remove the leading "//" here
With multi-line comments, it requires you "cut" the */ at the end, and paste it at the new end. Two actions.
Before:
/*
A
B
C
*/
After:
/*
A
B
*/ // 1. had to insert "*/" here
C // 2. had to remove "*/" from the end
This isn't a problem in Swift, but in C, multi-line comments aren't nestable. Suppose you have a function that contains a multi-line comment within it. But you want to temporarily comment out that function (for whatever reason, just an example). If both comments are multi-line, this wouldn't compile. This code isn't valid:
/* // This "/*" is treated as the start of a comment block
/* // This "/*" is commented, thus ignored.
*/ // This "*/" is treated as the end of the comment block
*/ // This "*/" tries to close the comment block, but it's not in a comment block. This is invalid.
However, Swift doesn't have this problem. I imagine the parser has an internal "comment block nesting level" that it tracks. Every /* increments it, and every */ decrements that. The comment block is only closed once the "comment block nesting level" is back down to 0.
It's not useless
However, that doesn't mean that multi-line comments don't have their use in Swift. I often use them when I'm playing around with a subexpression of a line. For example, if I have this function call:
someFunction(someValue + 1, someOtherParam)
I can see how a function behaves without that + 1 using a block comment:
someFunction(someValue /* + 1 */, someOtherParam)
Achieving the same thing using only single line comments would require me to do something like:
someFunction(someValue // + 1
, someOtherParam)
or introduce a temporary local variable:
let incrementedValue = someValue // + 1
someFunction(incrementedValue, someOtherParam)
Neither of which are as nice.
While I do not have a concrete answer for you, I'm inclined to suggest the double slash format(//)
I think the Swift Style Guide said it because they are also using it as a default.
What do I mean by that?, for example if you highlight multiple lines and press (cmd+/) it will comment/uncomment all the highlighted lines.
Note: it will uncomment the highlighted lines only if its in the double slash format(//)
When I auto re-indent my code in VS Code, multi-line comments are indented with the asterisks not vertically aligned. I would like them to be aligned so that I can comply with jsdoc-format.
How can I force it to align the asterisks vertically?
Here is an illustration:
/**
* How VSCode indents it
*/
/**
* How I want it
*/
I am using bbedit 12 in a markdown document.
I have enabled Soft Wrap Text at Page Guide as it makes the document easier to read.
As can be expected, itemised lists looks like this:
* some reallllllly long
text
* and another loooooong
paragraph
but I would like them to be shown as follow:
* some reallllllly long
text
* and another loooooong
paragraph
Is there a setting to indent the lines in one item on the display?
Thanks.
The Reverse option for soft-wrapped line indentation seems to work for me. But I don't completely understand how it operates, so it may not work in all cases.
In the picture below how can I
change the color of comments between /** and */ ( entire thing including *)
remove that single black space that I marked in red (before */)
1) Look on the appropriate Syntax Coloring preference page.
2) It's part of the vertical ruler, space reserved for the folding controls.
Is there any way you can make IntelliJ wrap scaladoc at the margin?
Basically, I want this:
/**
* This is a method description that is long enough to exceed right margin.
* <p/>
* Another paragraph of the description placed after blank line.
* <p/>
* Line with manual
* line feed.
to be formatted to this:
/**
* This is a method description that is long
* enough to exceed right margin.
* <p/>
* Another paragraph of the description
* placed after blank line.
* <p/>
* Line with manual line feed.
*
... if the line length is set to end here:
^
There is a dedicated setting for that - 'Ensure right margin is not exceeded'