Start
About
Blog
Contact
Résumé
Login
Replay Splash
Games
Clones N Barrels
Subspace
Shutdown
Commas go after newlines
Bring to front
View
Edit
Moderate
Delete
09:18:36 AM

Commas go after newlines

saccade - sac·cade /səˈkäd,saˈkäd/

noun, technical - a rapid movement of the eye between fixation points.

Reasoning

A lot of people (usually when starting a new job) ask me why I code like this:

if($string =~ /^prefix/)
{
	thisIsALongFunctionName(
		$this . $is
		, $aLongParameterList
		, 'with '
			. $concatenated
			. $strings
			. ' involved.'
		, $itsComplex
	);
}

Rather than like this:

if($string =~ /^prefix/)
{
	thisIsALongFunctionName(
		$this . $is,
		$aLongParameterList
		'with ' . $concatenated . $strings . ' involved.',
		$itsComplex
	);
}

The thing that usually jumps out at them is that I start newlines with commas, and indent on other operators. I use a lot of vertical space where line breaks aren't completely necesary. But there is a method to my madness.

Obvious Syntax

Did you notice the missing comma after $aLongParameterList in the second example? You wouldn't have missed it in the first one. The structure of the style dictates that only the first line of any list should be lacking a comma or indentation + operator for multi-part values. Any mistakes will stick out like a sore thumb.

Vertical Space

Vertical space is no longer a premium in most dev shops. Most offices offer the ability to rotate at least one of your monitors to the vertical position, and most developers are competent enough to set up their displays if the IT department is lacking/nonexistant.

Eye Motion

Organinzing all the commas as such allows the developer to simply draw the eye down the left margin of the code and obeserve its structure, without having to search for operators along the uneven right margin. Small improvements to the readability of code like this add up and over time allow developers to do more while thinking less.

I encourage you to scroll back to the examples above and pay attention to how much your eyes move while reading the code.

Tabs vs. Spaces, Alignment, Indentation

Tabs.

Tabs allow the developer to set their preferred spacing in their IDE. This way we're not enforcing a presentation of code on anyone. Each person can decide for themselves how much spacing works for them.

Spaces, however should be used for alignment which is distinct from indentation. This ensures that the alignment will work no matter how wide your tabs are set to display.

Personally, I prefer tab=4. It show a distiction between indentation (which represents a new semantic subsection) and the comma-space combo that lists use.

export class MyClass
{
	constructor()
	{
		let $setting     = 'some';
		let $variables   = 'up';
		let $during      = 'initialization';
		let $thisIsAList = [
			'entry-1'
			, 'entry-2'
			, 'entry-3'
		];
	}
}
#tab=4

However, the same code in tab=2 looks fine:

export class MyClass
{
	constructor()
	{
		let $setting     = 'some';
		let $variables   = 'up';
		let $during      = 'initialization';
		let $thisIsAList = [
			'entry-1'
			, 'entry-2'
			, 'entry-3'
		];
	}
}
#tab=2

Aligning assignments like this, for variables and data structures allows us to once again minimize our eyes' horizontal "seeking" behavior, minimizing the amount of work they have to do to allow us to absorb the code.

Brackets

By the same logic, brackets go on newlines as well.

function doSomething()
{
	something();

	if($is = being())
	{
		return done();
	}
}

Exception: Anonymous functions, Arrays & Objects

I find that when a function or other structure involving curly or square brackets, such as PHP & JavsScript arrays, or JavsScript's objects, it makes sense to put the bracket on the previous line,

document.querySelector('#something').addEventListener(
	'click'
	, (event) => {
		doStuff();
	}
	, {
		passive:   true
		, capture: false
	}
);

let thing = {
	bunch: 'of'
	, stuff: 'in here'
};

let otherFunction = (param) => {
	doStuff();
};
$array = [
	$listOfThingsTooLong
	, $toPutOnOneLine
	, 'so we\'re breaking it up.'
];

My reasoning is as such, the function or data structure is not the first thing on the line. It's either the subject of an assignment, an operand, or a parameter to a function. If we put the bracket on the newline, we'd be generally be ending the previous line with an operator, such as a comma or an equal sign. I spent the entire first section explaining why this is terrible.

let object = {
	id: 1
	, something: {
		property: 'value'
	}
}

"nice."

let object =
{
	id: 1
	, something:
	{
		property: 'value'
	}
}

"horrendous."

Long conditions in if statements

Conditionals can get long too. We're going to want to follow all the same rules as above. We'll wait for an operator before putting a newline and break & indent before it. Repeat for each param, and close the parenthesis at the same indentaiton level as the if's opening line. Start the bracker on the same line as the parenthesis ONLY when the conditional is broken as such.

if(someObject.listProperty.filter(x=>/^prefix/.exec(x))
	&& someValue > someOtherValue
	&& temperature > 80
){
	doStuffInHere();
}

CamelCase vs Under_Score

CamelCase is the one true way. I'm already pressing shift, why do I need to push extra key?

Each word of the name we're creating should be capitalized, even if its an abbreviation. The first letter of the name should only be capitalized if its a class name.

class JsonWebToken
{
	// ...
}

Ternaries

Long ternaries should be broken up as such:

$result = $thisIsALongVariableName > NOT_A_MAGIC_NUMBER
	? moveTo($southWest)
	: doSomethingWith($turquoise);

First level nesting

First level nested ternaries should be wrapped in parenthesis:

$result = $thisIsALongVariableName > NOT_A_MAGIC_NUMBER
	? moveTo($southWest)
	: ($condition
		? doSomethingWith($turquoise)
		: playYahtzee()
	);

Secong level nesting

Don't do that.

Use if()

links go here
Back to top