Difference between revisions of "Programming Guidelines"

Revision as of 08:09, 14 June 2009

Initial starting point: LJ Programming Guidelines.

Now, let's talk a bit about how Dreamwidth code should be written. Note that this is the stylistic guideline to follow to make sure the code looks uniform. If you submit a patch that doesn't follow these guidelines, then it will likely get declined with a note to review this documentation. Realistically, we want everybody to be able to dive into the code and understand what is going on without having to try to interpret a dozen different coding styles.

Note that these are not hard and fast rules. A lot of the time you will be fixing up code somewhere that is broken, and you will want to follow the style of the code you are working in. If you're editing really old pages like talkread.bml then you should attempt to code legibly, but follow the style in use on the page. (Mixing styles within a file can be problematic.)

These are guidelines, and not to be afraid of! Please don't feel intimidated by the style of the code. People will help you out if you have questions or aren't sure how to write something.

Whitespace

Spaces for indentation

Yes, we use spaces: four per level of indentation. But use your judgment when lining things up.

Spaces around parenthesis and operators

Perl has a well-deserved reputation for being line noise. Let's try to avoid that by putting spaces around parenthesis and operators:

# This is right out:
if ((($a||$b)&&(($c>1)||$d&5))+1)>3) { ... }
 
# This is much better:
if ( ( ( $a || $b ) && ( ( $c > 1 ) || ( $d & 5 ) ) + 1 ) > 3 ) { ... }

Well. It's better, but this line is terrible anyway. If you end up with a line like this, I'd suggest rewriting it entirely. Don't be too afraid of going onto multiple lines if it makes the operation more readable.

The "spaces around parenthesis" rule also applies to method calls. Here are some examples of when this comes into play:

call_method( $arg, $arg2 );
 
do_something( 45 ) if $org || $neg;

However, do NOT use spaces around operators used to index into arrays or hashes. It gets confusing.

# Wrong:
if ( $array[ 13 ] > $hash->{ $index } ) { ... }
 
# Right:
if ( $array[13] > $hash->{$index} ) { ... }

No tabs or trailing whitespace

No tabs, ever. No trailing whitespace.

These things happen. I'll try to catch them before commit. But don't commit tabs or trailing whitespace. Convert all tabs to spaces and prune trailing whitespace.

Linebreak readably

Long lines are difficult to read. Lines 72 or fewer characters long are ideal; 80-character lines are acceptable; lines over 120 characters long should probably be rewritten.

Don't use extraneous parentheses

Don't use extraneous parentheses. This happens mostly on method calls that don't need it and postfix conditionals.

# These are wrong:
my $r = DW::Request->get();
do_something() if ( $r->method() eq 'POST' );
 
# Fixed:
my $r = DW::Request->get;
do_something() if $r->method eq 'POST';

Note that you need parentheses after bareword function calls such as the do_something() above. Otherwise Perl has no idea it's a method and not a constant or some other value. But when you call it on a reference (using the -> operator) then it's assumed to be a method.

Logic

Postfix conditionals

Use postfix conditionals. That means:

# This is incorrect:
if ( $something ) {
    do_something();
}
 
# Try this instead:
do_something() if $something;
 
# Or even:
do_something()
    if $something;

It is your discretion which of the forms you use. Pick whatever seems appropriate to the code. (I tend to prefer the latter personally unless the line is really short.)

Use human logic

This is a big one that will really help people reading the code. The human brain is good at some things, bad at others.

# if something is true is easy to understand:
if ( $whatever ) { ... }
 
# unless something is true is also easy to understand:
unless ( $whatever ) { ... }

However, some things are NOT easy to understand, and should be rewritten.

# don't use this unless you REALLY need to
if ( ! $something ) { ... }
 
# use this instead:
unless ( $something ) { ... }

In some cases, the variable in question lends itself to the negation syntax in the first example. But that's a rare case. Just think about it for a second and go with what flows.

# never use this
unless ( ! $foobar ) { ... }
 
# or this
unless ( $foobar ) { ... } else { ... }

There is no situation in which "unless not $something" makes sense. The brain just doesn't parse it. It's a double negative, you might as well just use "if $something" and call it good!

Data structures

Proper use of hashes

Proper use of hashes is important. Do not quote literals unless needed. That may not make sense, so here are some examples:

# This is bad
$HASH{'DATA'} = 5;
$hashref->{'Something'} = $foo;
 
# try these instead
$HASH{DATA} = 5;
$hashref->{Something} = $foo;

The only time that you need quotes is if the value you are quoting has non-word characters in it. I.e., dashes, quotes, etc.

LJ Specific Conventions

Use $LJ::is_enabled()

Use LJ::is_enabled() instead of $LJ::DISABLED. Then you don't have to use negative logic and can pass parameters to it. LJ::is_enabled wraps $LJ::DISABLED in conf_test().

Preferred variable usage of $LJ::HOME

$LJ::HOME/cgi-bin is preferred over $ENV{LJHOME}/cgi-bin -- use $LJ::HOME instead, and if you see the old form, feel free to change it.

However, some files, notably those in the bin/ directory, need to use the old form because the code file that defines $LJ::HOME isn't loaded. So, if you see something like this:

use lib "$ENV{LJHOME}/cgi-bin";
require 'ljlib.pl';

That's trying to bootstrap the system. Until after ljlib.pl is fully loaded, $LJ::HOME is empty/undef, so we are allowed to depend on the existence of the environment variable.

Use $u->get_cap

$u->get_cap is preferred over LJ::get_cap($u, ...).

But even better is adding the method as an accessor in LJ::User. Then you won't have to actually check caps every time.

Commenting

Please comment your new code as extensively as possible so that someone coming along behind you can follow what you're doing. If you're working with old code, and you find yourself having to puzzle through what various functions are doing, comment it up to indicate what you figure out. We want everything to be as understandable as possible for anyone who comes along after you. You don't need to comment every line, but anything of moderate complexity should have a line or two indicating what it does and why.

Code comments should be kept professional -- no profanity, no offensive or exclusionary language (in particular, the LJ code has a tendency to use the words "ghetto" or "lame" to indicate that something isn't as good as it should be, and we should absolutely avoid that and change it whenever we encounter it), no self-deprecating humor ("this is totally stupid of me but ..."), etc. This does not mean comments are required to be boring - but they should be informative, precise, and not offensive.

If you are refactoring code that contains language that does not meet with the Dreamwidth standards, please go ahead and change it as you refactor the code. We want people to be able to see our codebase and come away feeling that it's a clean and approachable system.

If you need to indicate that something will need attention again later, we've standardized on "FIXME" as our "fix me or add to me later" indicator. Always indicate why you're flagging something FIXME:

# FIXME: Works as-is, but needs foo, bar, and baz later.

# FIXME: Totally broken. Needs foo, bar, and baz to work again.

English stripping

Effective English stripping is a requirement! While we might not translate DW.org into other languages, other people who are using the DW code should be given the functionality to do so on their own sites. This means that you need to be conscious of how to effectively strip a page or file of the text in it.

TODO: Create a page for how to localize a page.

Source file headers and credit

Header on source files, please use this on all original files created for Dreamwidth. Existing/originaly LJ code should get a header eventually, when we figure out an appropriate one.

#!/usr/bin/perl
#
# DW::User::Edges
#
# This module defines relationships between accounts.  It allows for finding
# edges, defining edges, removing edges, and other tasks related to the edges
# that can exist between accounts.  Methods are added to the LJ::User/DW::User
# classes as appropriate.
#
# Authors:
#      Mark Smith <mark@dreamwidth.org>
#
# Copyright (c) 2009 by Dreamwidth Studios, LLC.
#
# This program is free software; you may redistribute it and/or modify it under
# the same terms as Perl itself.  For a copy of the license, please reference
# 'perldoc perlartistic' or 'perldoc perlgpl'.
#

Copyright is maintained by the Dreamwidth Studios, LLC. organization, as all committers/contributors should have signed a contributor's agreement to properly grant license to their work. But authors should be noted for credit purposes.

Rule of thumb: if you are writing a new file, you can add yourself to the authors. If you are editing an existing file, you should only add yourself to the authors list if you are making significant changes (>10% or 100 lines, whichever is less). (Fixing typos does not qualify one to be a called out author of a file, sorry!)