Indentation of commented code

[dhardy]

My editor has a feature to comment-out code by adding // at the beginning of the line (I expect most have something similar). When rustfmt sees this, it just adds indentation and warns if the line gets too long.

Usually when this happens it's because some code is temporarily disabled for testing. Would it be too much to ask if rustfmt would not indent comments starting at the beginning of the line but just warn about it?

"Comment at the beginning of the line" is really just a proxy identifier for commented-out-code; unfortunately I can't think of a better one since identifying code is non-trivial and in any case comments can contain code.

Example:

fn main() {
    let mut x = 1;
//     x += 5;
    println!("x: {}", x);
}

[real-or-random]

Related to #1224

[dhardy]

This is still an issue for me, so lets try to explain this better.

---

Issue: reformatting (indentation) of commented code can result in double-indentation, from:

fn trivial(x: i32) -> i32 {
//     x += 1;
    x
}

to:

fn trivial(x: i32) -> i32 {
    //     x += 1;
    x
}

instead of:

fn trivial(x: i32) -> i32 {
    // x += 1;
    x
}

---

Solution: when adding indentation before a comment, also remove indentation within the comment, if appropriate. Or: correct indentation within comments.

Sub-problem: detecting correct indentation within comments. Extra indents are valid within doc-examples and Markdown lists/indented sections.

Sub-solution (doc-comments): indents within documentation is not valid for the first line of documentation. If the first line has extra indentation, it can be removed (along with equivalent indents on following lines). [This may not be technically correct, e.g. for Markdown starting with an indented example, but I have never seen such a case and there exists a good alternative.]

Sub-solution for non-doc comments: apply the same heuristic as for doc-comments. Since we have no applicable formatting rules to reason about the validity of this approach it is technically wrong, but I suspect it will work fine in practice.

[topecongiro]

We could add a configuration option (something like normalize_leading_whitespace_in_comment), which removes all but one leading whitespace in any comment, excluding code block.

[dhardy]

You could, and it would break Markdown formatted lists etc. Luckily those are usually only in doc-comments.

Can you not follow my suggestion — if a comment (without another comment on the previous line) has more than one leading space, consider it an invalid indent, then do the same for each comment directly following it (until reaching a non-comment or a comment without extra leading spaces).

[topecongiro]

You could, and it would break Markdown formatted lists etc. Luckily those are usually only in doc-comments.

Yeah, you are right. That wasn't a good idea.

Can you not follow my suggestion — if a comment (without another comment on the previous line) has more than one leading space, consider it an invalid indent, then do the same for each comment directly following it (until reaching a non-comment or a comment without extra leading spaces).

Sorry but the ruling sounds just too complex and the benefit does not seem to worth the effort. I don't know which editor you are using, but is it possible to handle the issue by configuring/modifying the editor or the plugin you are using? (e.g., add // before the first non-whitespace character instead of the beginning of the line)

[dhardy]

Using Kate. There's no setting for that, but it is OS so in theory that may be possible.

Sorry but the ruling sounds just too complex ...

You're trying to avoid complex heuristics? IMO there are a few not-so-simple things needed to get formatting right (read our discussion here).

[Enyium]

You could, and it would break Markdown formatted lists etc. Luckily those are usually only in doc-comments.

There may also be regular comments with ASCII-art-like content to illustrate something, and spaces after // are often significant for such comments. Here are examples.

[dhardy]

Kate now has better commenting with regards to indentation which mitigates this issue for me.
E.g.

fn trivial(x: i32) -> i32 {
    x += 1;
    x
}

and using the editor to comment the second line yields:

fn trivial(x: i32) -> i32 {
    // x += 1;
    x
}

Not sure whether to close this issue, but I'll unsubscribe myself.

[Enyium]

I still get the erratic huge indent jumps in VS Code when selecting a block and pressing Ctrl+/, Ctrl+S.

[KaiBackman]

There is a broader feature request: 'do_not_indent_left_margin_code_or_comments'.

As most modern languages, including Rust, feature at least a single level of indentation for the majority of statements the left margin is useful as secondary notation for ephemeral or debug specific constructs.

In the snippet below there is a developer specific log macro KAI! in a code with suspected issues. Highlighting the existence of such macro by the jarring indentation is useful both for the original author and others traversing the code during debugging.

	// call once per frame
	fn poll(&mut self) -> PollStatus {
		let now = msec();
		match self.state {
			RpcState::OutboundRequest => PollStatus::Open,
			RpcState::PendFirstAck => {
				if (now - self.last_ack_ms) > self.policy.first_ack_timeout_ms {
					let reason = TermReason::RequestTimeout;
					self.set_state(RpcState::Terminated(reason));
KAI!("TermReason::RequestTimeout: {} {}", self.last_ack_ms, self.policy_first_ack_timeout);
					return PollStatus::Terminated(reason);
				}
				...