google / google/comprehensive-rust

Eliminate horizontal scrolling in rust code blocks

Open
#2,012 18 comments 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
33.4k
Forks
2.1k
Avg merge
1d 3h
Merged PRs (30d)
10

Description

The style guide [mentiones](https://github.com/google/comprehensive-rust/blob/main/STYLE.md#vertical-space) presentation use case for the course. That means much inconvenience while dealing with very long lines in the code snippets.

The problem was addressed earlier as it can be seen from `rustfmt.toml` configuration:
```toml
# The code blocks get a scrollbar if they are wider than this.
max_width = 85
```

This works well for read only blocks, but fails for editable ones. Due to line numbering, there is less space left for the code. My observations are that the scrolling threshold is 83 for less than 10 line long code, 82 - less than 100 and 81 - above 100. There are no snippets above 1k and I suppose there must not be in the context of the course.

The following merge request adopts max 81-character width and eliminates detected scrolling in rust code blocks.

I suppose it is a partial solution though. But further steps require a discussion.

There should be an automated format validation step. `rustfmt` can do so with rust files, but not markdown. Across the course there are examples where rust code is separated from markdown files and included like:
```markdown
{{#include testing/src/lib.rs:leftpad}}
```
But. Firstly, that means all the rust code should be excluded from `md` files and guides updated. Secondly, rust code contains comments that are translated. And translations can turn out to be longer than the source. And the result should also be tested. Thirdly, `rustfmt` seems to ignore long `use` expressions and long strings in macro arguments - leaves them as they are without errors.

Also the course has some code blocks with long shell commands and text output. Were left unchanged.

Summary questions:
* Should we exclude all rust code from markdown files?
* How can we validate rust code with translated comments?
* How to deal with `use` and macros arguments that can still produce horizontal scrolling?
* What to do with other code blocks with very long lines?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.