Re: Code formatting discussion/proposal

On Mon, Jul 6, 2015 at 8:54 AM, Chris Bennett <..hidden..> wrote:

On Mon, Jul 06, 2015 at 12:04:59PM +0200, Erik Huelsmann wrote:
> Hi all,
>
> I'm going through our code quite randomly at the moment while investigating
> the multi-currency changes.
>
> What stands out at me is that we have:
>
> * different indenting methods (tabs vs spaces)
> * different intenting styles (2, 3, 4+ spaces)
> * different widths: 80 on most files, but I've seen anything above too
> * single vs double underscores as separators in tokens
> * etc
>
> I'm sorry, but it's starting to disturb me (quite a bit). So, here's my
> proposal:
>
> * We remove all tabs from the code base in one huge commit (except for
> Makefile)
> * From there on, we watch out not to add new tabs to the code base (add a
> test case?)
> * We choose a single intenting style
> - and create .emacs and vimrc examples for peolpe to use with our
> project; publish those on ledgersmb.org
> * We settle on either 80 or 132 character-width per file and reformat all
> files which are over the chosen maximum;
> --> With emacs starting up at 80 characters width, I'm all for 80
> characters (that way multiple windows fit next to each other on my screen)
> * We settle on a standard for using double underscores. My proposal:
> - In Perl, we always use a single underscore, as modules are enforced
> through OO
> - in PostgreSQL/pgPLSQL, we use the format
> <module>__<module-local-identifier>; making the payments code look like
> payment__list_all_open_invoices() or payment__post().
> (Currently the former exists, but the latter is called payment_post?!)
> * Each indenting level takes 2 spaces (to be added to the .emacs and vimrc
> examples as well)
> * SQL keywords in UPPERCASE
> * non-sql keywords in lowercase
> * COMMENTS whereever in the code base as normal sentences: One capital and
> then lowercase until the dot.
> * Comments are not essays: "Let's ...." and "We ..." are to be avoided;
> Example from the payments code: "We want to set a gl_description"
> Should be written as: "Set the gl_description"
> * Further formatting choices and minimum (function) documentation
> requirements to be established as we go and to be collected on ledgersmb.org
> .
> * Various project-root level files are to point to the ledgersmb.org URL
> where these docs can be found
>

My situation has changed and I now have time to program.

I use perltidy, which is helpful but not perfect.

I find that 4 spaces is essential for indenting.
This allows it to be very clear to see the flow of loops and ifs

I haven't looked at any of the code in a long time.
Comments are of course, very important.
Sometimes there are places that code is hard to follow.
When my code is like that, I clearly explain the strange flow so that I
can come back a year or two later and quickly understand what my
"brilliant" work was.

I also think that #XXX comments are very useful when something is just
not right and needs another person to see the answer.

80 character width is absolutely essential and NOT because of screen widths
or anything like that.
Scientists/writers or somebody discovered that because of the way the
human brain works with writing, it "gets lost" with sentences/code that
is too wide across. This is why newspapers and magazines and good
websites force column width to be narrow. If anyone working on new or
old code "gets lost", the new code will end up being lost from being
created.

What is the SQL code writing policy?
I break my work into clear and multiple lines that let me see each step
on its own line so I can quickly see what it is doing.

my $sth = $dbh->prepare(
"SELECT
assembly_id
FROM assemblies
WHERE assembly_id
IN (
SELECT full_assembly_assembly_id
FROM full_assembly
WHERE full_assembly_name=$full_assembly_selected2
)
ORDER BY assembly_name;"
);

Does formatting like this seem reasonable? I can follow my work here without any effort.
I am making the ends of the SQL commands like SELECT, FROM, and ORDER BY line up vertically.

We have been justifying sql queries, which usually is done by hand. It;s a little work but...

The basic idea is that the sql verbs are right justified and the nouns are left justified, so you get sort of a clear division where you can scan vertically to see exactly what is going on. This was Chris Murtagh's idea originally, but I think it makes it easy to debug the SQL. And once you have a little practice it isn't hard to do as you write it.

With the new code, the sql queries are all in separatre files untouched by perltidy anyway.

Just my thoughts,
Chris Bennett

------------------------------------------------------------------------------
Don't Limit Your Business. Reach for the Cloud.
GigeNET's Cloud Solutions provide you with the tools and support that
you need to offload your IT needs and focus on growing your business.
Configured For All Businesses. Start Your Cloud Today.
https://www.gigenetcloud.com/
_______________________________________________
Ledger-smb-devel mailing list
..hidden..
https://lists.sourceforge.net/lists/listinfo/ledger-smb-devel

Best Wishes,

Chris Travers

Efficito: Hosted Accounting and ERP. Robust and Flexible. No vendor lock-in.

http://www.efficito.com/learn_more