Difference between pages "Coding Standards" and "Usability Testing"

From Funtoo
(Difference between pages)
Jump to: navigation, search
 
 
Line 1: Line 1:
== Basic Coding Standards In A Nutshell ==
+
This page provides a place to document your install experiences, highlighting pain points so that they can be addressed in future versions of Funtoo Linux.
  
* word wrap at 160 characters
+
== Daniel Robbins, ninja2, 12/24/2010 ==
* use tabs, not spaces, for indentation
+
* use a tab size of 4 characters (tab size can be adjusted but it affects when you reach the magic 160 char wrap limit)
+
* comments on separate lines, at same indent level as code (sections can be marked by 'outdented' comments)
+
  
== Word Wrap ==
+
Installation of ninja2 (Dell R710) using rhel5-openvz-binaries kernel/modules/initrd .tbz2 (compiled on another machine using gcc-4.1.2) and GPT/GUID partitions. Use of binary kernel was successful although directing Portage to use the binary package was difficult - it wanted to find it inside a package repository rather than accept it directly from the command-line. Forgot to downgrade udev-160 to udev-146-r4 which resulted in a missing /etc/udev/rules.d/70-persistent-net.rules. Also didn't have brctl (bridge-utils) or ifenslave on the stage3 to allow me to set up the network correctly. Also ran into an issue with boot-update where I got the configuration wrong, because I used "kernel-[-v]" instead of "kernel[-v]". This could be a usability issue with the boot.conf syntax.
  
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.
+
After getting the system booted, I ran into an issue with macaddr renaming - you can't rename a device to eth1 if eth1 already exists! So I realized the limitations of macaddr renaming using nameif (built in to the Funtoo Linux network configuration scripts.) After fixing 70-persistent-net.rules and thinking of ways we could have some kind of default assignment rather than the currently random approach, I rebooted, configured my network, firewall, OpenVZ using the masked vzctl-3.0.25-r2 -- without issue -- and had the system up and running. I found that "bc" is no longer installed by default (I thought it was) -- so I added it to the default Metro stage3. Only ~90K.
  
== Tabs vs. Spaces ==
+
Possible usability improvements:
  
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.
+
* document use of rhel5-openvz-binaries
 +
* improve Portage's ability to install binary packages by having the .tbz2 specified on the command-line
 +
* improve management of udev to either force downgrade or allow multiple versions to exist on the same system (this is becoming more appealing....)
 +
* add bridge-utils to default stage3 (DONE)
 +
* add ifenslave to default stage3
 +
* add bc to default stage3 (DONE)
 +
* integrate some scheme for logically ordering ethX devices when you have many on a machine
 +
* look into improving boot-update configuration syntax to avoid "-[-v]" issues that can cause thorny config problems.
  
== Comments ==
+
Successes:
 
+
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.
+
  
 +
* the test of rhel5-openvz-binaries tbz2 was successful overall. It worked, and saved a ton of effort.
 +
* GPT/GUID partitioning worked fine.
 +
* testing of vzctl-3.0.25-r2 (currently in testing) worked perfectly.
 +
* install was relatively pain-free for a pro but still needs work.
  
 
[[Category:QA]]
 
[[Category:QA]]

Latest revision as of 01:26, 18 January 2011

This page provides a place to document your install experiences, highlighting pain points so that they can be addressed in future versions of Funtoo Linux.

Daniel Robbins, ninja2, 12/24/2010

Installation of ninja2 (Dell R710) using rhel5-openvz-binaries kernel/modules/initrd .tbz2 (compiled on another machine using gcc-4.1.2) and GPT/GUID partitions. Use of binary kernel was successful although directing Portage to use the binary package was difficult - it wanted to find it inside a package repository rather than accept it directly from the command-line. Forgot to downgrade udev-160 to udev-146-r4 which resulted in a missing /etc/udev/rules.d/70-persistent-net.rules. Also didn't have brctl (bridge-utils) or ifenslave on the stage3 to allow me to set up the network correctly. Also ran into an issue with boot-update where I got the configuration wrong, because I used "kernel-[-v]" instead of "kernel[-v]". This could be a usability issue with the boot.conf syntax.

After getting the system booted, I ran into an issue with macaddr renaming - you can't rename a device to eth1 if eth1 already exists! So I realized the limitations of macaddr renaming using nameif (built in to the Funtoo Linux network configuration scripts.) After fixing 70-persistent-net.rules and thinking of ways we could have some kind of default assignment rather than the currently random approach, I rebooted, configured my network, firewall, OpenVZ using the masked vzctl-3.0.25-r2 -- without issue -- and had the system up and running. I found that "bc" is no longer installed by default (I thought it was) -- so I added it to the default Metro stage3. Only ~90K.

Possible usability improvements:

  • document use of rhel5-openvz-binaries
  • improve Portage's ability to install binary packages by having the .tbz2 specified on the command-line
  • improve management of udev to either force downgrade or allow multiple versions to exist on the same system (this is becoming more appealing....)
  • add bridge-utils to default stage3 (DONE)
  • add ifenslave to default stage3
  • add bc to default stage3 (DONE)
  • integrate some scheme for logically ordering ethX devices when you have many on a machine
  • look into improving boot-update configuration syntax to avoid "-[-v]" issues that can cause thorny config problems.

Successes:

  • the test of rhel5-openvz-binaries tbz2 was successful overall. It worked, and saved a ton of effort.
  • GPT/GUID partitioning worked fine.
  • testing of vzctl-3.0.25-r2 (currently in testing) worked perfectly.
  • install was relatively pain-free for a pro but still needs work.