W3C home > Mailing lists > Public > public-htacg-contrib@w3.org > January 2015

Code Style - Was Issue #139

From: Geoff McLane <ubuntu@geoffair.info>
Date: Sun, 25 Jan 2015 16:27:43 +0100
Message-ID: <54C50B6F.8020909@geoffair.info>
To: public-htacg-contrib@w3.org
Re:  Code Style - Was Issue #139

About On 17/01/13, Oleg Gordienko wrote:
 >
 > Before we start, need choice code style.
 > I propose Linux Coding Style [1]
 > But with exceptions. Line length in 80 symbols
 > looks weird in 2015 with big displays.
 > What you think?
 >
 > I propose this style:
 > astyle --mode=c --style=linux --indent=spaces=4
 > --unpad-paren --pad-header --pad-oper --suffix=none
 > ./**/*.c ./**/*.h
 >
 > [1] http://www.makelinux.net/books/lkd2/ch20lev1sec2

On 17/01/15 17:03, Ionel Roiban wrote:
 >
 > How does your suggestion aligns with existing coding style?
 >

Hi Oleg (gordio),

Sorry this is SO long... but 'style' is a
big, sometimes very 'hot' topic ;=))

I quietly read your link, Linux Coding Style (LCS),
and while I agree with some, others are sort of
indicated as optional, and others I disagree
with... as normal I suppose...

But first I would have to question the
phrase 'Before we start'. And as skynet asked
"How does your suggestion align with existing..."

So this is not 'Before we start'. We have
some 50+ source files, with nearly 50,000
lines already...

And tidy HAS style ;=)) Arnaud used to make
sure of that...

AND its current style already fairly closely
follows the Linux Coding Style (LCS) ;=))

Maybe except for tabs. Long ago tidy had a small
utility, still built today, called tabs2space,
which did two things...

(a) Ensured the file had consistent line ending,
of either dos (CRLF), MAC (CR), or unix (LF), and

(b) Converted /ALL/ tabs to a default of 4 spaces.

Now with git (a) is no longer required since git
also ensures files have the correct line endings
for the OS, unlike when we were using CVS...

And while (b) is a good thing, but you should find
most, if not ALL source are already in this
form...

So what I would prefer to say is that ALL
contributors should follow Tidy's existing style.

To cover just a few things...

Indentation:

As mentioned above 4 space characters. I think
tabs were important when the byte weight of the
file was an important time and disk consumption
consideration, but both those are not so relevant
in today's world...

Braces:

In Tidy, braces always take a new line, both for
conditionals, and functions.

While I personally prefer putting the opening brace
on the first line, for conditionals, as in LCS, but
like others, have conformed to Tidy's existing style
when in Tidy.

Line Size:

While I too think 80 character maximum is a bit
ridiculous in modern editors on modern wide
screens, but again I conform to Tidy's current
wrapping style...

Naming:

Again Tidy had a good naming convention, that is
NOT agreed with in LCS. Every function has upper
and lower case... Well so be it...

Tidy even has a naming macro TY_(Function)(...),
which by default makes it tidyFunction(...)

I have never been sure of the exact purpose of
this since that function would be listed in
tidy.h, the API definition, as tidyFunction(...)...

Functions:

Tidy does have some too long, too big functions,
but again I have never felt like 'breaking'
this... the big ones usually represent handling
a single tag... so sort of fit together...

And Tidy replaced many of the standard library
with functions of it own... like TY_(tmbstrcmp)(...)
which replaces 'strcmp', and quite a few others
like this...

Comments:

This was one of Arnaud's favorites ;=)) Everything
HAD to be C-style... NO lazy use of C++ comments
in Tidy...

Well, maybe this could be relaxed a bit...

And if we intend to add self-generating documentation,
then I suppose we have to put up with all that
'special' @ commenting ;=(((( But it is really only
mainly in tidy.h...

As a long LONG term programmer, I have NEVER found such
auto-generated documentation helpful in any way,
but for sure it *** LOOKS PRETTY ***.

And also for sure Tidy could do with a programmers
view of how it works... Will give some thought to
beginning writing this...

Use of 'typedef':

Contrary to the LCS I do NOT think typedef is
lazy, and does not particularly hide the real type!

But anyway, Tidy does not have that many, and
they are mainly used to make structures anonymous,
which I have never liked...

Use of 'ifdef':

While I agree that OVER USE of 'ifdef' is a BAD
thing, it is a simple way to say handle the
cross-porting unix vs windows, and can NOT be
removed completely.

And another point on these last two... The editor
used can have a BIG influence...

In the MSVC IDE code editor these two things
are handled very well, efficiently...

Hovering over a variable that is a typedef will
show you what it is all about, and has a right
click 'go to definition' so makes them NO PROBLEM.

Likewise, the MSVC IDE code editor does massive
include file parsing in the background, and knows
the compiler command line, so uses color coding
to show you what is enable and what is disabled
in every 'ifdef', 'ifndef', 'else' blocks.

So there is NEVER any doubt about which code is
being compiled in an ifdef...

Structure Initializers:

Very regrettably it seems the LCS document has
chosen something NOT compatible with MSVC Windows
compilers, so I certainly hope this is NOT used
in Tidy, unless we want another big 'ifdef _MSC_VER'
to fix...

Anyway, have written lots more about this than
I intended...

And do not mean to say we should not think about
'style'...

And do thank you for taking the time to comment...
we need ALL the help we can get...

But what about my simple idea?

Let us follow the current style given in some 50,000
lines of EXISTING code?

At least until we start a 100% re-write ;=))

Regards,
Geoff.
Received on Sunday, 25 January 2015 15:28:12 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:54:14 UTC