[PATCH] Add line-wrapping guidelines to the coding style documentation
From: Wincent Colaiuta <hidden>
Date: 2016-06-15 22:43:50
Help new contributors by providing some advice about line-wrapping; the advice basically boils down to "use 80-characters minus some slop as a rule of thumb", but also "use common sense", and "avoid gratuitous rewrapping". Signed-off-by: Wincent Colaiuta <redacted> --- The advice is based on the following post by Junio: El 14/11/2007, a las 10:27, Junio C Hamano escribió:
I did not mean to say 70 was the official limit. Indeed, there is no hard official limit (and there shouldn't be any "hard" limit). But 70 should certainly be lower than the limit anybody around here would want to impose, and that was why I said 70. Some considerations: - Many of us read the unformatted ASCII version, as AsciiDoc was designed to be very readable, and mixing excessively long and short lines will make the document harder to read. - We tend to exchange patches over e-mail and assume everybody has at least 80-column wide terminals, so although we say a line should be less than 80-chars, in practice the limit is somewhat lower. to accomodate diff change marks [-+ ] and quoting ">> " in e-mails. - But "80-chars minus a bit of slop" is not a very hard limit. Please apply some common sense to decide when to re-wrap and when not to within these constraints.
I also whipped up this quick Ruby script to print a histogram of line
widths in the tree. You would run it like this to get a feel for the
typical line lengths of the different types of file in the tree:
check-column-widths.rb *.c *.h
check-column-widths.rb *.sh
check-column-widths.rb *.perl
check-column-widths.rb Documentation/*.txt
A statistician could probably make some interesting comments about the
results, but the basic trend is that, while there are plenty of
examples of isolated long lines in the source tree (the longest is a
287-character line in one of the perl scripts), the frequency starts
to drop off pretty rapidly once you pass 70 columns and start climbing
towards 80.
#!/usr/bin/env ruby
extensions = {}
# count frequency of line widths
ARGV.each do |arg|
f = File.new arg
extname = File.extname arg
unless file_type = extensions[extname]
extensions[extname] = file_type = {}
end
f.readlines.each do |line|
len = line.chomp.length
count = (file_type[len] or 0)
file_type[len] = count + 1
end
end
# print results
extensions.each do |file_type, frequencies|
puts "Frequencies for #{file_type} files"
# find longest line, most frequent line width, total line count
longest = frequencies.max { |a, b| a[0] <=> b[0] }[0]
most_frequent = frequencies.max { |a, b| a[1] <=> b[1] }[1]
total_lines = frequencies.inject(0) { |sum, a| sum + a[1] }
# draw histogram
for i in 0..longest
next if frequencies[i].nil?
puts "%4d [%4d]: %s" % [i, frequencies[i], '.' * (frequencies[i]
* 60 / most_frequent)]
end
puts "Maximum length: #{longest}"
puts " Total lines: #{total_lines}"
end
Documentation/CodingGuidelines | 22 ++++++++++++++++++++++
1 files changed, 22 insertions(+), 0 deletions(-)
diff --git a/Documentation/CodingGuidelines b/Documentation/ CodingGuidelines index 3b042db..3fd698e 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines@@ -110,3 +110,25 @@ For C programs: used in the git core command set (unless your command is clearly separate from it, such as an importer to convert random-scm-X repositories to git). + +Line wrapping: + + - While there are no official hard limits for line wrapping, we + generally try to keep shell scripts, C source files and AsciiDoc + documentation within the range of "80-characters minus some + slop". + + - We assume that everyone has terminals that are at least 80 + columns wide. + + - In practice, we try to keep lines somewhat narrower than 80 + columns to accommodate diff change marks [-+ ] and quoting ">> " + in emails. + + - In the case of documentation, mixing excessively long and short + lines may make the AsciiDoc source harder to read, so try to + keep line lengths consistent. + + - When submitting patches use common sense to decide whether to + rewrap, avoiding gratuitous changes. +
--
1.5.3.5