corinthia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Peter Kelly <pmke...@apache.org>
Subject Re: Coding Standard Discussion
Date Tue, 24 Feb 2015 14:34:12 GMT
I’ll preface this with saying that I think that of all the tasks facing us in Corinthia,
going through 54,000 lines of code (if you include the editor) and changing the coding style
is probably the least important, and I would suggest that time could be used more productively
on other improvements. That doesn’t mean we shouldn't change it - just something worth keeping
in mind.

Anyway, here’s the rationale behind the style I used when writing the original code

100-length lines: There’s actually quite a few that are even longer than this; I was originally
using 120. The reason for this was that the code was originally written in Objective C, which
has *really* long method names, in particular because each parameter is named. Here’s just
one example:

NSRange range = [str rangeOfString: @"[0-9]+" options: NSRegularExpressionSearch range: NSMakeRange(str,str.length)];

(and yes, it’s annoying - but Xcode’s autocompletion makes it ok once you get used to
it).

After the transition to C, average line length was reduced, because of the simpler method
call syntax. However, since C is not an object-oriented programming language, and we need
to avoid name clashes between methods in the same “class", all of the functions for a particular
“class” (data structure) are prefixed with the name, e.g.:

DFNode *abstract = WordConverterCreateAbstract(conv,HTML_BODY,concrete);

In C++, this would be:

DFNode *abstract = conv.createAbstract(HTML_BODY,concrete);

that is, the method would not be prefixed with the class name. Assuming class names are often
in the range of around 10-15 characters, this results in more verbose code, and thus a longer
required line length in order to express the same thing.

Another factor is that monitors are wider than they are taller. To maximise the amount of
code visible on one screen at a time (assuming only a single file is visible at a time), longer
lines result in greater visibility than shorter lines. A function that might be 30 lines of
code might be 45 if the length reduced to 70 characters, and everything from assignment statements
to function calls and declarations split over multiple lines because they don’t fit.

I would consider 80 characters to be the absolute minimum, if we were to change. But my preference
is for 100 for the above reasons.

Spaces before function arguments: I agree this is a good idea

Brace styles: I haven’t looked up the exact K&R details or Gnu but again, for code density,
I think having braces on the same lines is better. I haven’t done this for functions though
- not for any particular reason, just out of habit.

Page breaks: I’m not sure what these mean in the context of text files.

For reference, I’ve attached a summary of the maximum line lengths in all files (and the
script I used to generate it).

Having said all this, I really think we have far more important work to do - like, say, getting
an editing UI built or adding support for ODF - I’ve kind of tuned out of the xmalloc discussion
for the same reason.


—
Dr Peter M. Kelly
pmkelly@apache.org

PGP key: http://www.kellypmk.net/pgp-key <http://www.kellypmk.net/pgp-key>
(fingerprint 5435 6718 59F0 DD1F BFA0 5E46 2523 BAA1 44AE 2966)

> On 24 Feb 2015, at 4:24 am, Gabriela Gibson <gabriela.gibson@gmail.com> wrote:
> 
> Hi All,
> 
> Jan and Peter asked to start a discussion about coding standards on the
> mailing list.(https://issues.apache.org/jira/browse/COR-46)
> 
> I think the Subversion project has a very good strategy, see here:
> http://subversion.apache.org/docs/community-guide/conventions.html
> 
> Personally I think we could easily just copy their rules and will not
> regret it, plus their rules have stood the test of time.
> 
> That all said, whatever rules are chosen I am fine with ;-)
> 
> 
> Chars per line
> --------------------
> 
> My personal rationale for liking 70 chars per line is that more gets
> tedious to read (as in line too long) and, I like to be able to use emacs
> over ssh, or, if local, -nw style.
> 
> Being a bit myopic (and a fan of my screen being at least 1m away from me),
> I also manage to max out a 15" screen with just 70 chars, but my other half
> (who is eagle eyed) manages to fit two editor windows next to each other
> with 70 char wide each.
> 
> The other thing this does is introduce shape to the code, because long
> lines now have to be broken up.
> 
> This help a lot when glancing over stuff on the quick, you see 3 lines and
> know that this function declaration has 3 parameters, whereas if it's one
> line, you have to count 'em. (and think! ;-)  Plus, you can find stuff by
> shape too, which can at times be useful, and if you have a long parameter
> list, having the vars on their own line is also useful. (easy to count, and
> easy to spot if they are in the wrong order for some strange reason and so
> on).
> 
> So, 70 is quite a good number I think, plus it's traditional for most
> software I've seen, and new people will find it easy to get used to our
> code as well this way, since it'll looks instantly familiar and they won't
> have to change their set ups (and habits) very much and find it easier to
> switch between projects during the same day too, if they don't have to
> remember greatly differing rules.  (I swear that fingers have brains too).
> 
> 
> Spaces before variables
> ---------------------------------
> 
> Regards spaces between variables --- I think it makes it easier to scan
> quickly, that way you don't have to wonder, is this a full stop or a
> comma?  Also, it makes a parameter list read more like a sentence, making
> the individual type or variable much easier to spot --- a long or short var
> name is instantly recognisable, without having to read the entire thing.
> 
> 
> Tabs/spaces
> ------------------
> 
> Everyone uses spaces, tabs usually is not popular, for a very good reason
> which I forgot by now.  Personally I like 8 spaces (which grosses everyone
> out, heh) but 4 is a good (better!) number, it's separates code levels
> nicely visually without making nested code too crowded.  (Some people use 8
> spaces to prevent code that is too deeply nested, notably, the Linux kernel
> style guide does this.).
> 
> 
> Brace styles
> ------------------
> 
> K&R or Gnu --- K&R has the advantage to preserving vertical screen real
> estate, Gnu is easier to spot (you know where the brace sits and don't have
> to scan to the end of the line, plus it's easier to copy an entire block).
> I think both styles are equally fine, just not at the same time.
> 
> 
> Page breaks
> ------------------
> 
> I find them handy if the file is large, but can live without them.
> 
> 
> ==============================================================================================
> 
> 
> I also think that we should have the same discussion about log messages.
> There is a lot to be said for uniformity (makes searches of the logs
> visually much easier and also ensures that the logs are as informative as
> can be) and I do like the svn rules here, and they also help a lot in
> making patches higher quality and much easier to comprehend for readers.
> 
> Take a look:
> http://subversion.apache.org/docs/community-guide/conventions.html#log-messages.
> 
> 
> anyway, I hope you enjoyed reading this!
> 
> G
> 
> -- 
> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/


Mime
View raw message