Coding Standards - Revision history

Drobbins at 01:26, 18 January 2011

2011-01-18T01:26:14Z

Drobbins: removed angst, set clear standards to follow (160 chars, 4 char tabs)

2010-12-29T08:26:01Z

removed angst, set clear standards to follow (160 chars, 4 char tabs)

Drobbins: /* Profanity */

2010-12-24T20:27:01Z

‎Profanity

Drobbins: /* Word Wrap */

2010-12-24T20:25:54Z

‎Word Wrap

Drobbins: /* Word Wrap */

2010-12-24T20:25:35Z

‎Word Wrap

Drobbins: Created page with "== Word Wrap == If you are doing development on an Apple IIe with an 80-column card, then you will be forgiven for militantly keeping all your source code lines at 80 characters..."

2010-12-24T20:24:43Z

Created page with "== Word Wrap == If you are doing development on an Apple IIe with an 80-column card, then you will be forgiven for militantly keeping all your source code lines at 80 characters..."

New page

== Word Wrap ==

If you are doing development on an Apple IIe with an 80-column card, then you will be forgiven for militantly keeping all your source code lines at 80 characters in length or less. Otherwise, I will politely remind you that it is no longer 1984, and you should really take up as much of the line as you need, and then I will beat you with a stick. Modern editors do a good job of displaying very long lines of text, and modern displays have sufficient resolution for displaying much more than 80 characters per line, even at 1024x768 resolution. It might be reasonable to not go beyond 150 columns on a regular basis, but you should definitely not split an elegant single-line piece of code into multiple lines just for the sake of keeping the whole thing under 80 characters. It's especially bad if you take a 100-character line and split it into ''more'' than two lines. But I'm only talking the silliness of about enforcing an arbitrary 80-character limit -- if you need or want to use multiple lines to keep your code readable, more power to you. Don't just do it to maintain "Apple IIe with 80-column card compatibility." That's just silly.

== Tabs vs. Spaces ==

Tabs and spaces had a fight. Tabs won. They're easier to deal with and allow configurable indentation for those who require it. I don't care what some other group or organization says the convention is. Tabs won. If you don't want to use tabs because you want all your end-of-line comments to line up beautifully, then I have a solution: don't use end-of-line comments (see the next section) and you'll be fine.

== Comments ==

Add comments that provide some insight into your code, and that help to provide context. Also, because we use tabs, place comments on their own lines, separate from source code, ideally separated by a blank line above and below. This also encourages longer, more descriptive comments that may span multiple lines. If you span multiple lines, try to use a consistent right margin. You are permitted to have extra-long comment lines that are 200 characters or more in length. Modern editors will wrap these nicely and it will make editing easier. Comments help you understand your code when you come back to it a year later, so you are adding descriptive comments for yourself as much as for others. Include information you would find helpful if you had a sudden case of amnesia.

== Profanity ==

Do not place any profanity in source code comments or variable names. It just makes you look unprofessional.

← Older revision		Revision as of 01:26, 18 January 2011
Line 21:		Line 21:

	Do not place any profanity in source code comments or variable names. It just makes you look unprofessional, silly and incompetent.		Do not place any profanity in source code comments or variable names. It just makes you look unprofessional, silly and incompetent.
		+
		+
		+	[[Category:QA]]

← Older revision		Revision as of 20:27, 24 December 2010
Line 13:		Line 13:
	== Profanity ==		== Profanity ==

−	Do not place any profanity in source code comments or variable names. It just makes you look unprofessional.	+	Do not place any profanity in source code comments or variable names. It just makes you look unprofessional, silly and incompetent.

@@ Line 1: / Line 1: @@
 == Word Wrap ==
-If you are doing development on an Apple IIe with an 80-column card, then you will be forgiven for militantly keeping all your source code lines at 80 characters in length or less. Otherwise, I will politely remind you that it is no longer 1984, and you should really take up as much of the line as you need, and then I will beat you with a stick. Modern editors do a good job of displaying very long lines of text, and modern displays have sufficient resolution for displaying much more than 80 characters per line, even at 1024x768 resolution. It might be reasonable to not go beyond 150 columns on a regular basis, but you should definitely not split an elegant single-line piece of code into multiple lines just for the sake of keeping the whole thing under 80 characters. It's especially bad if you take a 100-character line and split it into ''more'' than two lines. But I'm only talking about the silliness of about enforcing an arbitrary 80-character limit -- if you need or want to use multiple lines to keep your code readable, more power to you. Don't just do it to maintain "Apple IIe with 80-column card compatibility." That's just silly.
+If you are doing development on an Apple IIe with an 80-column card, then you will be forgiven for militantly keeping all your source code lines at 80 characters in length or less. Otherwise, I will politely remind you that it is no longer 1984, and you should really take up as much of the line as you need, and then I will beat you with a stick. Modern editors do a good job of displaying very long lines of text, and modern displays have sufficient resolution for displaying much more than 80 characters per line, even at 1024x768 resolution. It might be reasonable to not go beyond 150 columns on a regular basis, but you should definitely not split an elegant single-line piece of code into multiple lines just for the sake of keeping the whole thing under 80 characters. It's especially bad if you take a 100-character line and split it into ''more'' than two lines. But I'm only talking about the silliness of about enforcing an arbitrary 80-character limit -- if you need or want to use multiple lines to keep your code readable, more power to you. Don't just do it to maintain "Apple IIe with 80-column card compatibility" for any reason. That's just silly.
 == Tabs vs. Spaces ==

@@ Line 1: / Line 1: @@
 == Word Wrap ==
-If you are doing development on an Apple IIe with an 80-column card, then you will be forgiven for militantly keeping all your source code lines at 80 characters in length or less. Otherwise, I will politely remind you that it is no longer 1984, and you should really take up as much of the line as you need, and then I will beat you with a stick. Modern editors do a good job of displaying very long lines of text, and modern displays have sufficient resolution for displaying much more than 80 characters per line, even at 1024x768 resolution. It might be reasonable to not go beyond 150 columns on a regular basis, but you should definitely not split an elegant single-line piece of code into multiple lines just for the sake of keeping the whole thing under 80 characters. It's especially bad if you take a 100-character line and split it into ''more'' than two lines. But I'm only talking about the silliness of about enforcing an arbitrary 80-character limit -- if you need or want to use multiple lines to keep your code readable, more power to you. Don't just do it to maintain "Apple IIe with 80-column card compatibility" for any reason. That's just silly.
+Modern editors do a good job of displaying very long lines of text, and modern displays have sufficient resolution for displaying much more than 80 characters per line, even at 1024x768 resolution. You should definitely not split an elegant single-line piece of code into multiple lines just for the sake of keeping the whole thing under 80 characters. It's especially bad if you take, say, a 100-character line and split it into ''more'' than two lines just for the sake of keeping it under 80 characters in length. But you need or want to use multiple lines to keep your code readable, more power to you. Don't just do it to maintain "Apple IIe with 80-column card compatibility" for any reason. That's just silly.
 == Tabs vs. Spaces ==
-Tabs and spaces had a fight. Tabs won. They're easier to deal with and allow configurable indentation for those who require it. I don't care what some other group or organization says the convention is. Tabs won. If you don't want to use tabs because you want all your end-of-line comments to line up beautifully, then I have a solution: don't use end-of-line comments (see the next section) and you'll be fine.
+Tabs and spaces had a fight. Tabs won. They're easier to deal with and allow configurable indentation for those who require it. I don't care what some other group or organization says the convention is. If you don't want to use tabs because you want all your end-of-line comments to line up beautifully, then I have a solution: don't use end-of-line comments (see the next section) and you'll be fine.
 == Comments ==
-Add comments that provide some insight into your code, and that help to provide context. Also, because we use tabs, place comments on their own lines, separate from source code, ideally separated by a blank line above and below. This also encourages longer, more descriptive comments that may span multiple lines. If you span multiple lines, try to use a consistent right margin. You are permitted to have extra-long comment lines that are 200 characters or more in length. Modern editors will wrap these nicely and it will make editing easier. Comments help you understand your code when you come back to it a year later, so you are adding descriptive comments for yourself as much as for others. Include information you would find helpful if you had a sudden case of amnesia.
+Add comments that provide some insight into your code, and that help to provide context. Also, because we use tabs, place comments on their own lines, separate from source code, ideally separated by a blank line above and below unless you are verbosely commenting every line of code. This also encourages longer, more descriptive comments that may span multiple lines. If you span multiple lines, use a consistent right margin of 160 characters. Comments help you understand your code when you come back to it a year later, so you are adding descriptive comments for yourself as much as for others. Include information you would find helpful if you had a sudden case of amnesia. They are especially important for free/open source software that needs to be maintained by various people over the years.
 == Profanity ==
 Do not place any profanity in source code comments or variable names. It just makes you look unprofessional, silly and incompetent.