On Mon, Jul 6, 2015 at 8:54 AM, Chris Bennett <[email protected]>
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
> [email protected]
> 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
------------------------------------------------------------------------------
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
[email protected]
https://lists.sourceforge.net/lists/listinfo/ledger-smb-devel
