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

From: Wincent Colaiuta <win@wincent.com>
Date: Nov 14, 2007, 10:19 UTC
Message-ID: <56A87A65-3C2E-4E10-84D4-4470879EE466@wincent.com>

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 <win@wincent.com>
---

The advice is based on the following post by Junio:

El 14/11/2007, a las 10:27, Junio C Hamano escribió:

Show 21 quoted lines

> 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