Алексей!
Максим Ильяхов
Аркадий Мильчин и Людмила Чельцова. Справочник издателя и автора
В бюро мы относимся к коду двояко. Иногда как к иллюстрациям, и тогда выносим листинг отдельно или на половину разворота. Иногда как к примерам в тексте, и тогда оставляем их в текстовой полосе, как в Мильчине или книгах Максима Ильяхова. В таком же промежуточном статусе и таблицы — иногда они заслуживают вынесенного положения иллюстрации, иногда скромно стоят в текстовой полосе, как внутритекстовые примеры.
Максим Ильяхов
Аркадий Мильчин и Людмила Чельцова. Справочник издателя и автора
Чаще всего листинг кода ведёт себя, как иллюстрация. Он не требует последовательного чтения и передаёт информацию одновременно в нескольких измерениях: цвет, форма, выравнивание. Значит, и отступы у листинга должны быть соответствующими: если после иллюстрации ставят межстрочник (в бюро стандартный отступ между этажами сетки), то и после кода должен стоять межстрочник.
Технически листинг лучше заворачивать в <pre> и <code>: <pre> (от preformatted text) сохранит отступы, пробелы и переводы строк в изначальном виде, <code> подскажет браузеру, что внутри код.
<pre>
<code>
function hello() {
console.log('Hello, world!')
}
</code>
</pre>function hello() {
console.log('Hello, world!')
}
В листингах лучше использовать моноширинные шрифты и подсветку: так проще находить нужные куски кода, считывать управляющие конструкции, имена и аргументы функций. Сравните:
class CommentsChannel < ApplicationCable::Channel
def self.broadcast_comment(comment)
broadcast_to comment.message,
comment: CommentsController.render(
partial: 'comments/comment',
locals: { comment: comment }
)
end
def follow(data)
stop_all_streams
stream_for current_user
.account
.messages
.find(data['message_id'])
rescue ActiveRecord::RecordNotFound
reject
end
def unfollow
stop_all_streams
end
endclass CommentsChannel < ApplicationCable::Channel
def self.broadcast_comment(comment)
broadcast_to comment.message,
comment: CommentsController.render(
partial: 'comments/comment',
locals: { comment: comment }
)
end
def follow(data)
stop_all_streams
stream_for current_user
.account
.messages
.find(data['message_id'])
rescue ActiveRecord::RecordNotFound
reject
end
def unfollow
stop_all_streams
end
end
class CommentsChannel < ApplicationCable::Channel
def self.broadcast_comment(comment)
broadcast_to comment.message,
comment: CommentsController.render(
partial: 'comments/comment',
locals: { comment: comment }
)
end
def follow(data)
stop_all_streams
stream_for current_user
.account
.messages
.find(data['message_id'])
rescue ActiveRecord::RecordNotFound
reject
end
def unfollow
stop_all_streams
end
end