Code Layout Matters - Revision history

Sf105 at 10:23, 16 August 2009

Sf105 — Sun, 16 Aug 2009 10:23:30 GMT

←Older revision		Revision as of 10:23, 16 August 2009
Line 9:		Line 9:
	* ''Compact format''. The more I can get on a screen, the more I can see without breaking context by scrolling or switching files, which means I can keep less state in my head. Long procedure comments and lots of whitespace made sense for 8 character names and line printers, but now I live in an IDE that does syntax colouring and cross linking. Pixels are my limiting factor so I want every one to contribute towards my understanding of the code. I want the layout to help me understand the code, but no more than that.		* ''Compact format''. The more I can get on a screen, the more I can see without breaking context by scrolling or switching files, which means I can keep less state in my head. Long procedure comments and lots of whitespace made sense for 8 character names and line printers, but now I live in an IDE that does syntax colouring and cross linking. Pixels are my limiting factor so I want every one to contribute towards my understanding of the code. I want the layout to help me understand the code, but no more than that.

-	A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it's there to help me understand the idea. Unfortunately, writing code ~~isn't perceived as~~	+	A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it's there to help me understand the idea. Unfortunately, writing code doesn't have the same romantic image as writing poetry.
-		+
-	doesn't have the same romantic image as writing poetry.	+

	By [[Steve Freeman]]		By [[Steve Freeman]]

Sf105 at 10:23, 16 August 2009

Sf105 — Sun, 16 Aug 2009 10:23:09 GMT

←Older revision		Revision as of 10:23, 16 August 2009
Line 9:		Line 9:
	* ''Compact format''. The more I can get on a screen, the more I can see without breaking context by scrolling or switching files, which means I can keep less state in my head. Long procedure comments and lots of whitespace made sense for 8 character names and line printers, but now I live in an IDE that does syntax colouring and cross linking. Pixels are my limiting factor so I want every one to contribute towards my understanding of the code. I want the layout to help me understand the code, but no more than that.		* ''Compact format''. The more I can get on a screen, the more I can see without breaking context by scrolling or switching files, which means I can keep less state in my head. Long procedure comments and lots of whitespace made sense for 8 character names and line printers, but now I live in an IDE that does syntax colouring and cross linking. Pixels are my limiting factor so I want every one to contribute towards my understanding of the code. I want the layout to help me understand the code, but no more than that.

-	A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it's there to help me understand the idea. Unfortunately, writing code doesn't have the same romantic image as writing poetry.	+	A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it's there to help me understand the idea. Unfortunately, writing code isn't perceived as
		+
		+	doesn't have the same romantic image as writing poetry.

	By [[Steve Freeman]]		By [[Steve Freeman]]

Sf105 at 09:50, 16 August 2009

Sf105 — Sun, 16 Aug 2009 09:50:35 GMT

←Older revision		Revision as of 09:50, 16 August 2009
Line 9:		Line 9:
	* ''Compact format''. The more I can get on a screen, the more I can see without breaking context by scrolling or switching files, which means I can keep less state in my head. Long procedure comments and lots of whitespace made sense for 8 character names and line printers, but now I live in an IDE that does syntax colouring and cross linking. Pixels are my limiting factor so I want every one to contribute towards my understanding of the code. I want the layout to help me understand the code, but no more than that.		* ''Compact format''. The more I can get on a screen, the more I can see without breaking context by scrolling or switching files, which means I can keep less state in my head. Long procedure comments and lots of whitespace made sense for 8 character names and line printers, but now I live in an IDE that does syntax colouring and cross linking. Pixels are my limiting factor so I want every one to contribute towards my understanding of the code. I want the layout to help me understand the code, but no more than that.

-	A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it's there to help me understand the idea. ~~Sadly~~, code doesn't ~~seem to be as effective~~ as poetry ~~at attracting partners~~.	+	A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it's there to help me understand the idea. Unfortunately, writing code doesn't have the same romantic image as writing poetry.

	By [[Steve Freeman]]		By [[Steve Freeman]]

Sf105 at 09:48, 16 August 2009

Sf105 — Sun, 16 Aug 2009 09:48:59 GMT

←Older revision		Revision as of 09:48, 16 August 2009
Line 5:		Line 5:
	* ''Easy to scan''. People are really good at visual pattern matching (a leftover from the time when we had to spot lions on the Savannah), so I can help myself by making everything that isn't directly relevant to the domain, all the “accidental complexity” that comes with most commercial languages, fade into the background by standardising it. If code that behaves the same looks the same, then my perceptual system will help me pick out the differences. That's why I also observe conventions about how to layout the parts of a class within a compilation unit: constants, fields, public methods, private methods.		* ''Easy to scan''. People are really good at visual pattern matching (a leftover from the time when we had to spot lions on the Savannah), so I can help myself by making everything that isn't directly relevant to the domain, all the “accidental complexity” that comes with most commercial languages, fade into the background by standardising it. If code that behaves the same looks the same, then my perceptual system will help me pick out the differences. That's why I also observe conventions about how to layout the parts of a class within a compilation unit: constants, fields, public methods, private methods.

-	* ''Expressive layout''. We've all learned to take the time to find the right names so that our code expresses as clearly as possible what it does, rather than just listing the steps—right? The code's layout is part of this expressiveness too. A first cut is to have the team agree on an automatic formatter for the basics, then I might make adjustments by hand while I'm coding. Unless there's active dissension, a team will quickly converge on a common "hand-finished" style. A formatter cannot understand my intentions (I should know, I once wrote one), and it's more important to me that the line breaks and groupings reflect the intention of the code, not just the syntax of the language.~~<sup>1</sup>~~	+	* ''Expressive layout''. We've all learned to take the time to find the right names so that our code expresses as clearly as possible what it does, rather than just listing the steps—right? The code's layout is part of this expressiveness too. A first cut is to have the team agree on an automatic formatter for the basics, then I might make adjustments by hand while I'm coding. Unless there's active dissension, a team will quickly converge on a common "hand-finished" style. A formatter cannot understand my intentions (I should know, I once wrote one), and it's more important to me that the line breaks and groupings reflect the intention of the code, not just the syntax of the language. (Kevin McGuire freed my from my bondage to automatic code formatters).

	* ''Compact format''. The more I can get on a screen, the more I can see without breaking context by scrolling or switching files, which means I can keep less state in my head. Long procedure comments and lots of whitespace made sense for 8 character names and line printers, but now I live in an IDE that does syntax colouring and cross linking. Pixels are my limiting factor so I want every one to contribute towards my understanding of the code. I want the layout to help me understand the code, but no more than that.		* ''Compact format''. The more I can get on a screen, the more I can see without breaking context by scrolling or switching files, which means I can keep less state in my head. Long procedure comments and lots of whitespace made sense for 8 character names and line printers, but now I live in an IDE that does syntax colouring and cross linking. Pixels are my limiting factor so I want every one to contribute towards my understanding of the code. I want the layout to help me understand the code, but no more than that.

	A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it's there to help me understand the idea. Sadly, code doesn't seem to be as effective as poetry at attracting partners.		A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it's there to help me understand the idea. Sadly, code doesn't seem to be as effective as poetry at attracting partners.
-
-	----
-	1) Kevin McGuire taught me to break free from the automated code formatter
-

	By [[Steve Freeman]]		By [[Steve Freeman]]

Sf105 at 09:48, 16 August 2009

Sf105 — Sun, 16 Aug 2009 09:48:15 GMT

←Older revision		Revision as of 09:48, 16 August 2009
Line 5:		Line 5:
	* ''Easy to scan''. People are really good at visual pattern matching (a leftover from the time when we had to spot lions on the Savannah), so I can help myself by making everything that isn't directly relevant to the domain, all the “accidental complexity” that comes with most commercial languages, fade into the background by standardising it. If code that behaves the same looks the same, then my perceptual system will help me pick out the differences. That's why I also observe conventions about how to layout the parts of a class within a compilation unit: constants, fields, public methods, private methods.		* ''Easy to scan''. People are really good at visual pattern matching (a leftover from the time when we had to spot lions on the Savannah), so I can help myself by making everything that isn't directly relevant to the domain, all the “accidental complexity” that comes with most commercial languages, fade into the background by standardising it. If code that behaves the same looks the same, then my perceptual system will help me pick out the differences. That's why I also observe conventions about how to layout the parts of a class within a compilation unit: constants, fields, public methods, private methods.

-	* ''Expressive layout''. We've all learned to take the time to find the right names so that our code expresses as clearly as possible what it does, rather than just listing the steps—right? The code's layout is part of this expressiveness too. A first cut is to have the team agree on an automatic formatter for the basics, then I ~~sometimes~~ make adjustments by hand while I'm coding. Unless there's active dissension, a team will quickly converge on a common "hand-finished" style. A formatter cannot understand my intentions (I should know, I once wrote one), and it's more important to me that the line breaks and groupings reflect the intention of the code, not just the syntax of the language.	+	* ''Expressive layout''. We've all learned to take the time to find the right names so that our code expresses as clearly as possible what it does, rather than just listing the steps—right? The code's layout is part of this expressiveness too. A first cut is to have the team agree on an automatic formatter for the basics, then I might make adjustments by hand while I'm coding. Unless there's active dissension, a team will quickly converge on a common "hand-finished" style. A formatter cannot understand my intentions (I should know, I once wrote one), and it's more important to me that the line breaks and groupings reflect the intention of the code, not just the syntax of the language.<sup>1</sup>

	* ''Compact format''. The more I can get on a screen, the more I can see without breaking context by scrolling or switching files, which means I can keep less state in my head. Long procedure comments and lots of whitespace made sense for 8 character names and line printers, but now I live in an IDE that does syntax colouring and cross linking. Pixels are my limiting factor so I want every one to contribute towards my understanding of the code. I want the layout to help me understand the code, but no more than that.		* ''Compact format''. The more I can get on a screen, the more I can see without breaking context by scrolling or switching files, which means I can keep less state in my head. Long procedure comments and lots of whitespace made sense for 8 character names and line printers, but now I live in an IDE that does syntax colouring and cross linking. Pixels are my limiting factor so I want every one to contribute towards my understanding of the code. I want the layout to help me understand the code, but no more than that.
Line 11:		Line 11:
	A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it's there to help me understand the idea. Sadly, code doesn't seem to be as effective as poetry at attracting partners.		A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it's there to help me understand the idea. Sadly, code doesn't seem to be as effective as poetry at attracting partners.

		+	----
		+	1) Kevin McGuire taught me to break free from the automated code formatter

Sf105 at 09:45, 16 August 2009

Sf105 — Sun, 16 Aug 2009 09:45:06 GMT

←Older revision		Revision as of 09:45, 16 August 2009
Line 1:		Line 1:
-	An infeasible number of years ago I worked on a Cobol system where staff weren't allowed to change the indentation unless they already had a reason to change the code because someone once broke something by letting a line slip into one of the special columns at the beginning of a line. This applied even if the layout was misleading, which it sometimes was, so we had to read the code very carefully because we couldn't trust it. The policy must have cost a fortune in programmer drag.	+	An infeasible number of years ago I worked on a Cobol system where staff weren't allowed to change the indentation unless they already had a reason to change the code, because someone once broke something by letting a line slip into one of the special columns at the beginning of a line. This applied even if the layout was misleading, which it sometimes was, so we had to read the code very carefully because we couldn't trust it. The policy must have cost a fortune in programmer drag.

	There's research to show the we all spend much more of our programming time navigating and reading code—finding ''where'' to make the change—than actually typing, so that's what we want to optimise for.		There's research to show the we all spend much more of our programming time navigating and reading code—finding ''where'' to make the change—than actually typing, so that's what we want to optimise for.

Kevlin: Code layout matters moved to Code Layout Matters

Kevlin — Sun, 19 Jul 2009 23:53:55 GMT

Code layout matters moved to Code Layout Matters

←Older revision

Revision as of 23:53, 19 July 2009

Kevlin at 16:26, 26 November 2008

Kevlin — Wed, 26 Nov 2008 16:26:58 GMT

←Older revision		Revision as of 16:26, 26 November 2008
Line 1:		Line 1:
	An infeasible number of years ago I worked on a Cobol system where staff weren't allowed to change the indentation unless they already had a reason to change the code because someone once broke something by letting a line slip into one of the special columns at the beginning of a line. This applied even if the layout was misleading, which it sometimes was, so we had to read the code very carefully because we couldn't trust it. The policy must have cost a fortune in programmer drag.		An infeasible number of years ago I worked on a Cobol system where staff weren't allowed to change the indentation unless they already had a reason to change the code because someone once broke something by letting a line slip into one of the special columns at the beginning of a line. This applied even if the layout was misleading, which it sometimes was, so we had to read the code very carefully because we couldn't trust it. The policy must have cost a fortune in programmer drag.

-	There's research to show the we all spend much more of our programming time navigating and reading code—finding ''where'' to make the change—than actually typing, so that's what we want to optimise for.	+	There's research to show the we all spend much more of our programming time navigating and reading code—finding ''where'' to make the change—than actually typing, so that's what we want to optimise for.

-	''Easy to scan''. People are really good at visual pattern matching (a leftover from the time when we had to spot lions on the Savannah), so I can help myself by making everything that isn't directly relevant to the domain, all the “accidental complexity” that comes with most commercial languages, fade into the background by standardising it. If code that behaves the same looks the same, then my perceptual system will help me pick out the differences. That's why I also observe conventions about how to layout the parts of a class within a compilation unit: constants, fields, public methods, private methods.	+	* ''Easy to scan''. People are really good at visual pattern matching (a leftover from the time when we had to spot lions on the Savannah), so I can help myself by making everything that isn't directly relevant to the domain, all the “accidental complexity” that comes with most commercial languages, fade into the background by standardising it. If code that behaves the same looks the same, then my perceptual system will help me pick out the differences. That's why I also observe conventions about how to layout the parts of a class within a compilation unit: constants, fields, public methods, private methods.

-	''Expressive layout''. We've all learned to take the time to find the right names so that our code expresses as clearly as possible what it does, rather than just listing the steps—right? The code's layout is part of this expressiveness too. A first cut is to have the team agree on an automatic formatter for the basics, then I sometimes make adjustments by hand while I'm coding. Unless there's active dissension, a team will quickly converge on a common ~~“~~hand-finished~~”~~ style. A formatter cannot understand my intentions (I should know, I once wrote one), and it's more important to me that the line breaks and groupings reflect the intention of the code, not just the syntax of the language.	+	* ''Expressive layout''. We've all learned to take the time to find the right names so that our code expresses as clearly as possible what it does, rather than just listing the steps—right? The code's layout is part of this expressiveness too. A first cut is to have the team agree on an automatic formatter for the basics, then I sometimes make adjustments by hand while I'm coding. Unless there's active dissension, a team will quickly converge on a common "hand-finished" style. A formatter cannot understand my intentions (I should know, I once wrote one), and it's more important to me that the line breaks and groupings reflect the intention of the code, not just the syntax of the language.

-	''Compact format''. The more I can get on a screen, the more I can see without breaking context by scrolling or switching files, which means I can keep less state in my head. Long procedure comments and lots of whitespace made sense for 8 character names and line printers, but now I live in an IDE that does syntax colouring and cross linking. Pixels are my limiting factor so I want every one to contribute towards my understanding of the code. I want the layout to help me understand the code, but no more than that.	+	* ''Compact format''. The more I can get on a screen, the more I can see without breaking context by scrolling or switching files, which means I can keep less state in my head. Long procedure comments and lots of whitespace made sense for 8 character names and line printers, but now I live in an IDE that does syntax colouring and cross linking. Pixels are my limiting factor so I want every one to contribute towards my understanding of the code. I want the layout to help me understand the code, but no more than that.

	A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it's there to help me understand the idea. Sadly, code doesn't seem to be as effective as poetry at attracting partners.		A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it's there to help me understand the idea. Sadly, code doesn't seem to be as effective as poetry at attracting partners.

Sf105 at 15:56, 25 November 2008

Sf105 — Tue, 25 Nov 2008 15:56:09 GMT

←Older revision		Revision as of 15:56, 25 November 2008
Line 3:		Line 3:
	There's research to show the we all spend much more of our programming time navigating and reading code—finding ''where'' to make the change—than actually typing, so that's what we want to optimise for.		There's research to show the we all spend much more of our programming time navigating and reading code—finding ''where'' to make the change—than actually typing, so that's what we want to optimise for.

-	Easy to scan. People are really good at visual pattern matching (a leftover from the time when we had to spot lions on the Savannah), so I can help myself by making everything that isn't directly relevant to the domain, all the “accidental complexity” that comes with most commercial languages, fade into the background by standardising it. If code that ~~is structurally~~ the same looks the same, then my perceptual system will help me pick out the differences. That's why I also observe conventions about how to layout the parts of a class within a compilation unit: constants, fields, public methods, private methods.	+	''Easy to scan''. People are really good at visual pattern matching (a leftover from the time when we had to spot lions on the Savannah), so I can help myself by making everything that isn't directly relevant to the domain, all the “accidental complexity” that comes with most commercial languages, fade into the background by standardising it. If code that behaves the same looks the same, then my perceptual system will help me pick out the differences. That's why I also observe conventions about how to layout the parts of a class within a compilation unit: constants, fields, public methods, private methods.

-	Expressive layout. We've all learned to take the time to find the right names so that our code expresses as clearly as possible what it does, rather than just listing the steps—right? The code's layout is part of this expressiveness too. A first cut is to have the team agree on an automatic formatter for the ~~basic layout~~, then I ~~tend to~~ make adjustments by hand while I'm coding. Unless there's active dissension, a team will quickly converge on a common “hand-finished” style. A formatter cannot understand my intentions (I should know, I once wrote one), and it's more important to me that the line breaks and groupings reflect the intention of the code, not just the syntax of the language.	+	''Expressive layout''. We've all learned to take the time to find the right names so that our code expresses as clearly as possible what it does, rather than just listing the steps—right? The code's layout is part of this expressiveness too. A first cut is to have the team agree on an automatic formatter for the basics, then I sometimes make adjustments by hand while I'm coding. Unless there's active dissension, a team will quickly converge on a common “hand-finished” style. A formatter cannot understand my intentions (I should know, I once wrote one), and it's more important to me that the line breaks and groupings reflect the intention of the code, not just the syntax of the language.

-	Compact format. The more I can get on a screen, the more I can see without breaking context by scrolling or switching files, which means I can keep less state in my head. Long procedure comments and lots of whitespace made sense for 8 character names and line printers, but now I live in an IDE that does syntax colouring and cross linking. Pixels are ~~now~~ my limiting factor so I want every one to contribute towards my understanding of the code.	+	''Compact format''. The more I can get on a screen, the more I can see without breaking context by scrolling or switching files, which means I can keep less state in my head. Long procedure comments and lots of whitespace made sense for 8 character names and line printers, but now I live in an IDE that does syntax colouring and cross linking. Pixels are my limiting factor so I want every one to contribute towards my understanding of the code. I want the layout to help me understand the code, but no more than that.

	A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it's there to help me understand the idea. Sadly, code doesn't seem to be as effective as poetry at attracting partners.		A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it's there to help me understand the idea. Sadly, code doesn't seem to be as effective as poetry at attracting partners.

Sf105 at 15:49, 25 November 2008

Sf105 — Tue, 25 Nov 2008 15:49:38 GMT

←Older revision		Revision as of 15:49, 25 November 2008
Line 1:		Line 1:
-	An infeasible number of years ago I worked on a Cobol system where staff weren't allowed to change the indentation unless they already had a ~~functional~~ reason to change the code~~. Presumably, this was~~ because someone once broke something by letting a line slip into the special columns at the beginning of ~~the~~ line. ~~Unfortunately, this~~ applied even if the layout was misleading, which it sometimes was, so we had to read the code very carefully because we couldn't trust it. The policy must have cost a fortune in programmer drag ~~and is a nice example of why code layout matters~~.	+	An infeasible number of years ago I worked on a Cobol system where staff weren't allowed to change the indentation unless they already had a reason to change the code because someone once broke something by letting a line slip into one of the special columns at the beginning of a line. This applied even if the layout was misleading, which it sometimes was, so we had to read the code very carefully because we couldn't trust it. The policy must have cost a fortune in programmer drag.

	There's research to show the we all spend much more of our programming time navigating and reading code—finding ''where'' to make the change—than actually typing, so that's what we want to optimise for.		There's research to show the we all spend much more of our programming time navigating and reading code—finding ''where'' to make the change—than actually typing, so that's what we want to optimise for.

-	~~I want~~ to ~~make scanning code as easy as possible~~. People are really good at visual pattern matching (~~probably~~ a leftover from the time when we had to spot lions on the Savannah), so I can help myself by making everything that isn't directly relevant to the domain, all the “accidental complexity” that comes with ~~the~~ languages ~~most of us get to use~~, fade into the background by standardising it. If code that is structurally the same looks the same, then my perceptual system will help me pick out the differences. I also observe conventions about how to layout the parts of a class within a compilation unit: constants, fields, public methods, private methods.	+	Easy to scan. People are really good at visual pattern matching (a leftover from the time when we had to spot lions on the Savannah), so I can help myself by making everything that isn't directly relevant to the domain, all the “accidental complexity” that comes with most commercial languages, fade into the background by standardising it. If code that is structurally the same looks the same, then my perceptual system will help me pick out the differences. That's why I also observe conventions about how to layout the parts of a class within a compilation unit: constants, fields, public methods, private methods.

-	~~I want my code~~ layout ~~to be as expressive as its content~~. We've all learned ~~nowadays~~ to take the time to find the right names so that our code expresses as clearly as possible what it does, rather than just listing the steps~~. Right~~? The code's layout is part of this expressiveness too. A first cut is to have the team agree on an automatic formatter for the basic layout, then I tend to make adjustments by hand while I'm coding. Unless there's active dissension, a team will quickly converge on a common “hand-finished” style. A formatter cannot understand ~~your~~ intentions (I should know, I once wrote one), and it's more important to me that the line breaks and groupings reflect the intention of the code, not just the syntax of the language.	+	Expressive layout. We've all learned to take the time to find the right names so that our code expresses as clearly as possible what it does, rather than just listing the steps—right? The code's layout is part of this expressiveness too. A first cut is to have the team agree on an automatic formatter for the basic layout, then I tend to make adjustments by hand while I'm coding. Unless there's active dissension, a team will quickly converge on a common “hand-finished” style. A formatter cannot understand my intentions (I should know, I once wrote one), and it's more important to me that the line breaks and groupings reflect the intention of the code, not just the syntax of the language.

-	~~I want a compact~~ format ~~so that~~ I can ~~navigate~~ more ~~quickly~~. ~~There was a time when many software shops insisted that every~~ procedure and ~~module had a long header~~	+	Compact format. The more I can get on a screen, the more I can see without breaking context by scrolling or switching files, which means I can keep less state in my head. Long procedure comments and lots of whitespace made sense for 8 character names and line printers, but now I live in an IDE that does syntax colouring and cross linking. Pixels are now my limiting factor so I want every one to contribute towards my understanding of the code.

	A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it's there to help me understand the idea. Sadly, code doesn't seem to be as effective as poetry at attracting partners.		A non-programmer friend once remarked that code looks like poetry. I get that feeling from really good code, that everything in the text has a purpose and that it's there to help me understand the idea. Sadly, code doesn't seem to be as effective as poetry at attracting partners.