[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Code formatting discussion/proposal





On Mon, Jul 6, 2015 at 5:54 PM, 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.
Right. Unfortunately, the code doesn't have any comments (or at least, not that I have found) of sufficient high quality. So, I think it's good to explicitly mention this in the list of coding standards.
 
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.
Ah! Right. That's a good point. I use that convention myself too. I'll list that in the section about writing comments.
 

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.
Ok. Incorporated that as a scientific support for the 80-character limit.

 

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.
With Chris's reaction, I'll put what he said in the documentation page.

Thanks for your thoughts!

Regards,

-- 
Bye,

Erik.

http://efficito.com -- Hosted accounting and ERP.
Robust and Flexible. No vendor lock-in.
------------------------------------------------------------------------------
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