Skip to Content.
Sympa Menu

sm-discuss - Re: [SM-Discuss] The Great E-mails: part 1 (General)

sm-discuss AT lists.ibiblio.org

Subject: Public SourceMage Discussion List

List archive

Chronological Thread  
  • From: Eric Sandall <eric AT sandall.us>
  • To: sm-discuss AT lists.ibiblio.org
  • Subject: Re: [SM-Discuss] The Great E-mails: part 1 (General)
  • Date: Fri, 28 Aug 2009 21:04:04 -0700

On Sat, 29 Aug 2009 03:35:47 +0400
Vlad Glagolev <stealth AT sourcemage.org> wrote:

> Okay, let's talk about some things I've been thinking since 2003,
> when I started to look into the spell's structure.
>
> Yes, it's all about formatting, formatting standards, what do we have
> and what would we have. Please bring some of your thoughts and
> opinions. They are really appreciated.
>
> This will be a series of discussion, about the most important files
> in (almost) every spell. This is also a small RFC of my opinion
> ("constructed" by many years and work with programming in several
> languages like C/C++, Shell script, and Python and several projects
> like T2, OpenBSD, and Lunar-Linux).
>
> I think we still need some standartisation for the formatting (like
> we have aligning in DETAILS).
>
> But, first of all, let's start talking about the general things in
> formatting:
>
> 1. Lines of code in every file (DETAILS, ChangeLog, HISTORY, INSTALL,
> DEPENDS, etc.) should have limits for the length (80 chars), this is
> a common practice.

Common practice for those that work with typical 80x25 terminals, which
have been long gone and larger terminals are more normal. We limit it
to <80 columns so those not using frame-buffer or X11 won't have long
lines wrapping.

> 2. There's no recommendation for quotes: like in
> Python, both ' and " are accepted and can be used by a developer.

Note true, at least in bash. The single-quote (') is for uninterpreted
variables and the double-quote (") is for interpreted variables.

A simple example not showing all the differences between the two, but
what we mostly use in our spells:

optional_depends spell "--with-library=$INSTALL_ROOT/usr/lib"
optional_depends spell '--with-library=$INSTALL_ROOT/usr/lib'

These will give you very different results, one intended, the other
not, though I believe you meant this to be more a question of using
quotes, at all, in DETAILS though #3 seems to cover that.

> 3.
> In variables, extra stuff shouldn't be put. Like quotes and curly
> brackets (braces). Only where it's really needed:
> - {, } in variables like: ${SOURCE/-//} (bash patterns),
> ${SOURCE}_file (underscore in name), but not in regular
> $SPELL-$VERSION, etc.
> - ", ' in variables which can contain spaces, for example
> "$INSTALL_ROOT". As it's user-defined, it can contain spaces in full
> path, so it's a good idea to quote it.

This is my current practice, but others like being verbose/pedantic. :)

> 4. UPPERCASE sub-dependencies
> in SUB_DEPENDS and PRE_SUB_DEPENDS (for example, I fixed it for
> python3 spell, at least, but python remains..).

I would go with this just to make it standard and so the lower-case
name does not get confused with a spell.

> 5. double-spaces in
> constructions if-else, etc.: use double-spaces (like 4 spaces in
> Python, tabs in C++) to align the blocks of code after a new line.

Current practice is to use two spaces as TABs are not allowed in any
file except HISTORY. We could convert to TABs and let everyone define
their own length for indentation. ;)

> 6.
> "then", like "do" should remain on the same line as "if" and "while"
> accordingly.

I believe this should be left to the developer's preference, depending
on the length of the line. Sometimes I do:

if condition; then
fi

othertimes I do
if condition
then
fi

I think the latter looks cleaner, but the former takes up less lines
and lets more fit on my screen (especially if conditionals are used a
lot in a file).

> 7. Use bash power while creating dirs, using cycles,
> etc. to minimize the code, for example: mkdir -p
> dir/{braces,are,good} instead of mkdir -p dir/braces dir/are
> dir/good, or even worse: mkdir -p dir/braces && mkdir dir/are &&
> mkdir dir/good.

Again I think this should be left to the preference of the developer. I
prefer using BASH expansion but am unsure if it uses less cycles than
the longer `mkdir -p dir/1 dir/2`.

We also want to keep requirements minimal for new developers, some of
whom may not know much about BASH when they first start developing
spells (I certainly didn't and would say I still don't know all the
joys of BASH, just the basics).

I think we want our spells to be simple to understand for everyone and
not using the most complex pieces of BASH to do something
cleaner/faster/better (unless it's noticeably cleaner/faster/better).

-sandalle

--
Eric Sandall | Source Mage GNU/Linux Developer
eric AT sandall.us PGP: 0xA8EFDD61 | http://www.sourcemage.org/
http://eric.sandall.us/ | http://counter.li.org/ #196285

Attachment: signature.asc
Description: PGP signature




Archive powered by MHonArc 2.6.24.

Top of Page