[PATCH] Add line-wrapping guidelines to the coding style documentation

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