corinthia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gabriela Gibson <gabriela.gib...@gmail.com>
Subject Coding Standard Discussion
Date Mon, 23 Feb 2015 21:24:36 GMT
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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message