diff options
Diffstat (limited to 'abs/core-testing/wlan-ng26-utils-svn/tmp/trunk/doc/codingstd/.svn/text-base')
5 files changed, 916 insertions, 0 deletions
diff --git a/abs/core-testing/wlan-ng26-utils-svn/tmp/trunk/doc/codingstd/.svn/text-base/format.hfile.svn-base b/abs/core-testing/wlan-ng26-utils-svn/tmp/trunk/doc/codingstd/.svn/text-base/format.hfile.svn-base new file mode 100644 index 0000000..71d4a5f --- /dev/null +++ b/abs/core-testing/wlan-ng26-utils-svn/tmp/trunk/doc/codingstd/.svn/text-base/format.hfile.svn-base @@ -0,0 +1,142 @@ +/* aheader.h: [one line description of the file] +* -------------------------------------------------------------------- +* +* [Project Name] +* +* [License Statement, eg. +* The contents of this file are subject to the Mozilla Public +* License Version 1.0 (the "License"); you may not use this file +* except in compliance with the License. You may obtain a copy of +* the License at http://www.mozilla.org/MPL/ ] +* +* [Warranty Statement, eg. +* Software distributed under the License is distributed on an "AS +* IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or +* implied. See the License for the specific language governing +* rights and limitations under the License. ] +* +* [Author contact, eg. +* Copyright (C) 1998 AbsoluteValue Software, Inc. All Rights Reserved. +* +* Inquiries regarding the linux-wlan Open Source project can be +* made directly to: +* +* AbsoluteValue Systems Inc. +* info@linux-wlan.com +* http://www.linux-wlan.com ] +* +* [Change History] +* +* [Verbose Description] +* +* [Implementation and usage notes] +* +* [References] +* +* -------------------------------------------------------------------- +*/ + +#ifndef _AHEADER_H +#define _AHEADER_H + +/*=============================================================*/ +/*------ Constants --------------------------------------------*/ + +/*--- Fixed memory offsets --------------------------*/ +#define SU_OFF_LAST_TXDESC 0x3ec +#define SU_OFF_RSVD1 0x400 +#define SU_OFF_BANNER 0x480 +#define SU_OFF_CMD_BLK 0x4a0 +#define SU_OFF_CNTL_STATUS_BLK 0x4f0 +#define SU_OFF_VBM 0x500 +#define SU_OFF_BUFFER 0x600 + +/*--- Global Sizes ----------------------------------*/ +#define SU_LEN_BANNER 32 + + + +/*=============================================================*/ +/*------ Macros -----------------------------------------------*/ + +/*--- next testing macro (applies to Rx and Tx) -------*/ +#define SUTXD_ISLAST(x) ((x) & BIT31) +#define SURXD_ISLAST(x) ((x) & BIT31) + + +/*=============================================================*/ +/*------ Types and their related constants --------------------*/ + +/*--- Last Completed Tx Descriptor Block ---------------*/ +__WLAN_PRAGMA_PACK1__ +typedef struct am930txcmplt_blk +{ + volatile UINT32 last_bcast __WLAN_ATTRIB_PACK__; + volatile UINT32 last_mgmt __WLAN_ATTRIB_PACK__; + volatile UINT32 last_data __WLAN_ATTRIB_PACK__; + volatile UINT32 last_pspoll __WLAN_ATTRIB_PACK__; + volatile UINT32 last_cfpoll __WLAN_ATTRIB_PACK__; +} am930txcmplt_blk_t; +__WLAN_PRAGMA_PACKDFLT__ + +#define TXCMPLT_OFF_BCAST 0 +#define TXCMPLT_OFF_MGMT 4 +#define TXCMPLT_OFF_DATA 8 +#define TXCMPLT_OFF_PSPOLL 12 +#define TXCMPLT_OFF_CFPOLL 16 + +typedef void (*am930hw_scan_callback_t)(void *); + +/*=============================================================*/ +/*--- Function Declarations -----------------------------------*/ +/*=============================================================*/ +/* public: */ +am930hw_t* +am930hw_construct(UINT32 irq, UINT32 iobase, + UINT32 membase, am930mac_t *mac); + +void +am930hw_destruct(am930hw_t *hw); + +int +am930hw_init_rx_tx( am930hw_t *hw ); + +void +am930hw_ISR( am930hw_t *hw ); + +UINT32 +am930hw_joinbss( am930hw_t *hw, UINT32 ch, UINT32 newBSS, + UINT8 *bssid, wlan_ie_ssid_t *ssid, UINT32 bcn_int, + wlan_bss_ts_t ts, UINT32 sutro_ref_time ); + +UINT32 +am930hw_scan( am930hw_t *hw, UINT32 cntl, UINT8 *bssid, + UINT32 ch, UINT32 duration, + am930hw_scan_callback_t cb, void *callback_arg ); + +UINT32 +am930hw_reset( am930hw_t *hw ); + +/*=============================================================*/ +/*--- Inline Function Definitions (if supported) --------------*/ +/*=============================================================*/ + +/*---------------------------------------------------------------- +* am930hw_reset +* +* Perform reset of am930 part and test for valid operation +* operation following reset. +* +* returns: zero on success, non-zero if part fails to come up +* after reset. +----------------------------------------------------------------*/ +__INLINE__ UINT32 am930hw_reset( am930hw_t* hw) +{ + UINT32 result = 0; + + /* perform reset */ + /* test part */ + return result; +} + +#endif /* _AHEADER_H */ diff --git a/abs/core-testing/wlan-ng26-utils-svn/tmp/trunk/doc/codingstd/.svn/text-base/format.srcfile.c.svn-base b/abs/core-testing/wlan-ng26-utils-svn/tmp/trunk/doc/codingstd/.svn/text-base/format.srcfile.c.svn-base new file mode 100644 index 0000000..fdbb997 --- /dev/null +++ b/abs/core-testing/wlan-ng26-utils-svn/tmp/trunk/doc/codingstd/.svn/text-base/format.srcfile.c.svn-base @@ -0,0 +1,113 @@ +/* [filename]: [one line description of the file] +* +* Copyright (C) 1999 AbsoluteValue Systems, Inc. All Rights Reserved. +* -------------------------------------------------------------------- +* +* linux-wlan +* +* The contents of this file are subject to the Mozilla Public +* License Version 1.1 (the "License"); you may not use this file +* except in compliance with the License. You may obtain a copy of +* the License at http://www.mozilla.org/MPL/ +* +* Software distributed under the License is distributed on an "AS +* IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or +* implied. See the License for the specific language governing +* rights and limitations under the License. +* +* Alternatively, the contents of this file may be used under the +* terms of the GNU Public License version 2 (the "GPL"), in which +* case the provisions of the GPL are applicable instead of the +* above. If you wish to allow the use of your version of this file +* only under the terms of the GPL and not to allow others to use +* your version of this file under the MPL, indicate your decision +* by deleting the provisions above and replace them with the notice +* and other provisions required by the GPL. If you do not delete +* the provisions above, a recipient may use your version of this +* file under either the MPL or the GPL. +* +* -------------------------------------------------------------------- +* +* Inquiries regarding the linux-wlan Open Source project can be +* made directly to: +* +* AbsoluteValue Systems Inc. +* info@linux-wlan.com +* http://www.linux-wlan.com +* +* -------------------------------------------------------------------- +* +* Portions of the development of this software were funded by +* Intersil Corporation as part of PRISM(R) chipset product development. +* +* -------------------------------------------------------------------- +* +* [File Description] +* +* [Implementation and Usage Notes] +* +* -------------------------------------------------------------------- +*/ + +/*================================================================*/ +/* System Includes */ + + +/*================================================================*/ +/* Project Includes */ + + +/*================================================================*/ +/* Local Constants */ + + +/*================================================================*/ +/* Local Macros */ + + +/*================================================================*/ +/* Local Types */ + + +/*================================================================*/ +/* Local Static Definitions */ + +/*----------------------------------------------------------------*/ +/* --A subsection */ + + +/*================================================================*/ +/* Local Function Declarations */ + + +/*---------------------------------------------------------------- +* [function name] +* +* [Description] +* +* Arguments: +* [arglist] +* +* Returns: +* [retlist] +* +* Side effects: +* [desc] +* +* Call context: +* [desc] +----------------------------------------------------------------*/ +int afunction(void) +{ + DBFENTER; + + if ( a ) { + prinf("xxx"); + } + + + DBFEXIT; + return 0; +} + + diff --git a/abs/core-testing/wlan-ng26-utils-svn/tmp/trunk/doc/codingstd/.svn/text-base/format.srcfile.html.svn-base b/abs/core-testing/wlan-ng26-utils-svn/tmp/trunk/doc/codingstd/.svn/text-base/format.srcfile.html.svn-base new file mode 100644 index 0000000..c2ba914 --- /dev/null +++ b/abs/core-testing/wlan-ng26-utils-svn/tmp/trunk/doc/codingstd/.svn/text-base/format.srcfile.html.svn-base @@ -0,0 +1,311 @@ +<HTML> +<HEAD> + <TITLE>AVS C Source file format</TITLE> +</HEAD> +<BODY> +<H1>1. C Source file format</H1> +<P> +The following defines the common C source file format for linux-wlan. +Most of the C-code formatting rules come from the linux kernel +document <CODE>CodingStyle</CODE>. + +<H1>2. Characters and Code layout</H1> +<H2>2.1. Character Set</H2> +<P> +For all source files, we'll stick to the US character set and avoid all +trigraphs. + +<H2>2.2. Indentation</H2> +<P> +All indentation will be done using tab characters which are mapped to a +spacing of eight characters. + +<H2>2.3. Braces</H2> +<P> +Braces will be placed according to the format originally established +in Kernighan and Ritchie's book "The C Programming Language". Here +are some example statements: +<P> +<TABLE border=1><TR><TD><PRE> + +for ( i= 0; i < N; i++) { + . + . + . +} + +if ( a < b ) { + . + . + . +} else { + . + . + . +} + +do { + . + . + . +} while ( i >> 0 ); +</PRE></TABLE> + + + +<H1>3. Naming and Definition Conventions</H1> + +<H2>3.1. Preprocessor Elements</H2> +<P> +All elements defined via the C preprocessor (constants and macros) are +named using all capital letters. An exception is for macros that are +either wrapping function calls for portability or for macros that are +inline replacements for code that would normally be in a function. + +<H2>3.2. Types</H2> +<P> +All programmer defined types must have single word type names +defined using the <PRE>typedef</PRE> statement. All type names +should be identified with an <PRE>_t</PRE> suffix. This is +particularly important for function pointers that are members of +structures or arguments to functions. + +<P> +Anonymous types are not allowed. All struct, union, and enum +types shall be named and typedef'd. + + +<H2>3.3. Variables</H2> +The following conventions should be followed for variable +declaration and naming: + <UL> + <LI>Variables should be named using meaningful names. + <LI>Avoid variables with static lifetimes. + <LI>If static lifetime variables must be used, use file + scoped static variables and avoid static lifetime + variables with visibility beyond file scope. + <LI>All static lifetime variables should be declared in + the "Local Statics" section near the top of a given + source file. + </UL> + +<H2>3.4. Functions</H2> +The following conventions should be followed for function +declaration and definition: + <UL> + <LI><B>All</B> functions must be declared above the point + where they are called. + <LI>Any functions that are only intended to be called + within a given source file should be declared static + within that file. + <LI>Functions defined within a common source file that are + visible across source file boundaries should be named + using a prefix that is unique to that source file. + </UL> + +<H1>4. File Layout</H1> +<P> +Each file should be layed out using a common format. The +following shows a complete file with all its major sections. + +<P> +Each major section within the file is begun with a comment of the +form: +<PRE> +/*================================================================*/ +/* [Section Name] */ +</PRE> + +<P> +Subsections within a major section are denoted using: +<PRE> +/*----------------------------------------------------------------*/ +/* [Subsection Name] */ +</PRE> + +<P> +<TABLE border=1><TR><TD> +<PRE> +/* [filename]: [one line description of the file] +* -------------------------------------------------------------------- +* +* [Project Name] +* +* [License Statement] +* +* [Warranty Statement] +* +* [Initial Author Statement] +* +* -------------------------------------------------------------------- +* +* [Initial Author Contact] +* +* -------------------------------------------------------------------- +* +* [File Description] +* +* [Implementation and Usage Notes] +* +* -------------------------------------------------------------------- +*/ + +/*================================================================*/ +/* System Includes */ + + +/*================================================================*/ +/* Project Includes */ + + +/*================================================================*/ +/* Local Constants */ + + +/*================================================================*/ +/* Local Macros */ + +/*----------------------------------------------------------------*/ +/* [A subsection] */ + +/*================================================================*/ +/* Local Types */ + + +/*================================================================*/ +/* Local Static Definitions */ + + +/*================================================================*/ +/* Local Function Declarations */ + + +/*================================================================*/ +/* Function Definitions */ + +</PRE> +</TABLE> + +<H2>4.1. System Includes Section</H2> +<P> +Preprocessor <CODE>#include</CODE> statements that are including +<I>system</I> includes shall be placed in this section. System +includes are those include files that are <B>not</B> part of the +managed source for this project. + +<H2>4.2. Project Includes Section</H2> +<P> +Preprocessor <CODE>#include</CODE> statements that are including +<I>project</I> includes shall be placed in this section. Project +includes are those include files that are a part of the +managed source for this project. + +<H2>4.3. Local Constants Section</H2> +<P> +Preprocessor "manifest" constants that are local to this file shall be +placed in this section. "Manifest" constants are preprocessor macros +that take no arguments. + +<H2>4.4. Local Macros Section</H2> +<P> +Proprocessor macros that accept arguments shall be placed in this +section. + +<H2>4.5. Local Types Section</H2> +<P> +Programmer defined types that are only used within the scope of this +file shall be defined in this section. Programmer defined types that +are used in more than one source file should be defined in a header +file. + +<H2>4.6. Local Static Definitions Section</H2> +<P> +Variables with static extent that are defined within this file shall +be placed in this section. Whether a variable has scope beyond this +file will be apparent based on the presence or absence of the +<CODE>static</CODE> keyword in the declaration. If a variable is +declared without the <CODE>static</CODE> keyword, there should be an +<CODE>extern</CODE> declaration for that variable in a header file. + +<H2>4.6. Local Function Declarations Section</H2> +<P> +Functions that are only used within this file should be declared +(prototyped) in this section. Additionally, these functions should be +declared using the <CODE>static</CODE> keyword. This avoids polluting +the global namespace with function names that need not be +<CODE>extern</CODE>. + +<P> +Any functions defined in this file that <I>are</I> called from outside +this file should be declared (prototyped) in a header file. + +<H2>4.6. Function Definitions Section</H2> +<P> +This section contains the definitions of the functions in this file. +Each function (or group of strongly related functions) will be +preceded by a function header comment (see below). + +<H1>5. Comments</H1> +<H2>5.1. File Header</H2> +<P> +Each source file will have a header comment containing information +about the file as a whole. That comment shall be formatted: +<P> +<TABLE border=1><TR><TD><PRE> +/* [filename]: [one line description of the file] +* -------------------------------------------------------------------- +* +* [Project Name] +* +* [License Statement] +* +* [Warranty Statement] +* +* [Initial Author Statement] +* +* -------------------------------------------------------------------- +* +* [Initial Author Contact] +* +* -------------------------------------------------------------------- +* +* [File Description] +* +* [Implementation and Usage Notes] +* +* -------------------------------------------------------------------- +*/ +</PRE> +</TABLE> + +<H2>5.2. Function Header</H2> +<P> +Each function (or group of closely related functions) will be preceded +by a function comment header. The <CODE>Side effects</CODE> and +<CODE>Call context</CODE> sections are optional. +<P> +<TABLE border=1><TR><TD><PRE> +/*---------------------------------------------------------------- +* [function name] +* +* [description] +* +* Arguments: +* [argument list] +* +* Returns: +* [return value list] +* +* Side effects: +* [description of function side effects] +* +* Call context: +* [description of calling context] +----------------------------------------------------------------*/ +</PRE> +</TABLE> + + +</BODY> +</HTML> + diff --git a/abs/core-testing/wlan-ng26-utils-svn/tmp/trunk/doc/codingstd/.svn/text-base/format.srcfile.svn-base b/abs/core-testing/wlan-ng26-utils-svn/tmp/trunk/doc/codingstd/.svn/text-base/format.srcfile.svn-base new file mode 100644 index 0000000..3c4b4c1 --- /dev/null +++ b/abs/core-testing/wlan-ng26-utils-svn/tmp/trunk/doc/codingstd/.svn/text-base/format.srcfile.svn-base @@ -0,0 +1,138 @@ +<TABLE border=1> +<TR><TD><PRE> +/* asource.c: [one line description of file] +* -------------------------------------------------------------------- +* +* [Project Name] +* +* [License Statement, eg. +* The contents of this file are subject to the Mozilla Public +* License Version 1.0 (the "License"); you may not use this file +* except in compliance with the License. You may obtain a copy of +* the License at http://www.mozilla.org/MPL/ ] +* +* [Warranty Statement, eg. +* Software distributed under the License is distributed on an "AS +* IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or +* implied. See the License for the specific language governing +* rights and limitations under the License. ] +* +* [Author contact, eg. +* Copyright (C) 1998 AbsoluteValue Software, Inc. All Rights Reserved. +* +* Inquiries regarding the linux-wlan Open Source project can be +* made directly to: +* +* AbsoluteValue Systems Inc. +* info@linux-wlan.com +* http://www.linux-wlan.com ] +* +* [Change History] +* +* [Verbose Description] +* +* [Implementation and usage notes] +* +* [References] +* +* -------------------------------------------------------------------- +*/ + +/* Portability/Compatibility header */ +#include <wlan/wlan_compat.h> + +/* The following prevents "kernel_version" from being set in this file. */ +#define __NO_VERSION__ + +/* Non-project specific includes */ +/* PCMCIA headers generated during PCMCIA package installation */ +#include <pcmcia/config.h> +#include <pcmcia/k_compat.h> + +/* Module related headers, non-module drivers should not include */ +#include <linux/version.h> + +#include <assert.h> +#include <linux/delay.h> +#include <linux/kernel.h> +#include <linux/types.h> +#include <linux/fcntl.h> +#include <linux/interrupt.h> +#include <linux/ptrace.h> +#include <linux/ioport.h> +#include <linux/in.h> +#include <linux/malloc.h> +#include <linux/string.h> +#include <linux/timer.h> +#include <asm/system.h> +#include <asm/bitops.h> +#include <asm/io.h> +#include <linux/errno.h> + +/* Project Includes */ +#include <wlan/version.h> +#include <wlan/am930mib.h> +#include <wlan/p80211hdr.h> +#include <wlan/p80211mgmt.h> +#include <wlan/wlan_ioctl.h> +#include <wlan/wlan_stable.h> +#include "am930di.h" +#include "am930llc.h" +#include "am930mac.h" +#include "am930hw.h" +#include "am930mgr.h" + +/*====================================================================*/ +/* Local Constants */ +/*====================================================================*/ + +#define ACONSTANT 22 + + +/*====================================================================*/ +/* Local Types */ +/*====================================================================*/ + +typdef struct atype +{ + struct atype *next; + struct atype *prev; +} atype_t; + + +/*====================================================================*/ +/* Static data defined in this file */ +/*====================================================================*/ + +UINT8 wepkey[WLAN_WEP_NKEYS][WLAN_WEP_KEYLEN] = +{ + { 0xf1, 0x10, 0xec, 0xe0, 0xdc }, + { 0x0f, 0xf2, 0x04, 0x09, 0xfb }, + { 0x13, 0x37, 0xf2, 0xf9, 0x2d }, + { 0xe9, 0x17, 0x19, 0x63, 0xc7 } +}; + + +/*====================================================================*/ +/* Local Function Declarations */ +/*====================================================================*/ + +static void am930mgr_authen1_rx( am930mgr_t *mgr, wlan_fr_authen_t *f ); +static void am930mgr_authen2_rx( am930mgr_t *mgr, wlan_fr_authen_t *f ); +static void am930mgr_authen3_rx( am930mgr_t *mgr, wlan_fr_authen_t *f ); +static void am930mgr_authen4_rx( am930mgr_t *mgr, wlan_fr_authen_t *f ); + +/*====================================================================*/ +/* Function Definitions */ +/*====================================================================*/ + + +/*---------------------------------------------------------------- +* am930mgr_assoc_begin_sta +* +* Start the station association procedure. Namely, send an +* association request frame to the AP. +* +* returns: nothing for now +----------------------------------------------------------------*/ +void am930mgr_assoc_begin_sta(am930mgr_t *mgr) diff --git a/abs/core-testing/wlan-ng26-utils-svn/tmp/trunk/doc/codingstd/.svn/text-base/linux.CodingStyle.svn-base b/abs/core-testing/wlan-ng26-utils-svn/tmp/trunk/doc/codingstd/.svn/text-base/linux.CodingStyle.svn-base new file mode 100644 index 0000000..edba246 --- /dev/null +++ b/abs/core-testing/wlan-ng26-utils-svn/tmp/trunk/doc/codingstd/.svn/text-base/linux.CodingStyle.svn-base @@ -0,0 +1,212 @@ + + Linux kernel coding style + +This is a short document describing the preferred coding style for the +linux kernel. Coding style is very personal, and I won't _force_ my +views on anybody, but this is what goes for anything that I have to be +able to maintain, and I'd prefer it for most other things too. Please +at least consider the points made here. + +First off, I'd suggest printing out a copy of the GNU coding standards, +and NOT read it. Burn them, it's a great symbolic gesture. + +Anyway, here goes: + + + Chapter 1: Indentation + +Tabs are 8 characters, and thus indentations are also 8 characters. +There are heretic movements that try to make indentations 4 (or even 2!) +characters deep, and that is akin to trying to define the value of PI to +be 3. + +Rationale: The whole idea behind indentation is to clearly define where +a block of control starts and ends. Especially when you've been looking +at your screen for 20 straight hours, you'll find it a lot easier to see +how the indentation works if you have large indentations. + +Now, some people will claim that having 8-character indentations makes +the code move too far to the right, and makes it hard to read on a +80-character terminal screen. The answer to that is that if you need +more than 3 levels of indentation, you're screwed anyway, and should fix +your program. + +In short, 8-char indents make things easier to read, and have the added +benefit of warning you when you're nesting your functions too deep. +Heed that warning. + + + Chapter 2: Placing Braces + +The other issue that always comes up in C styling is the placement of +braces. Unlike the indent size, there are few technical reasons to +choose one placement strategy over the other, but the preferred way, as +shown to us by the prophets Kernighan and Ritchie, is to put the opening +brace last on the line, and put the closing brace first, thusly: + + if (x is true) { + we do y + } + +However, there is one special case, namely functions: they have the +opening brace at the beginning of the next line, thus: + + int function(int x) + { + body of function + } + +Heretic people all over the world have claimed that this inconsistency +is ... well ... inconsistent, but all right-thinking people know that +(a) K&R are _right_ and (b) K&R are right. Besides, functions are +special anyway (you can't nest them in C). + +Note that the closing brace is empty on a line of its own, _except_ in +the cases where it is followed by a continuation of the same statement, +ie a "while" in a do-statement or an "else" in an if-statement, like +this: + + do { + body of do-loop + } while (condition); + +and + + if (x == y) { + .. + } else if (x > y) { + ... + } else { + .... + } + +Rationale: K&R. + +Also, note that this brace-placement also minimizes the number of empty +(or almost empty) lines, without any loss of readability. Thus, as the +supply of new-lines on your screen is not a renewable resource (think +25-line terminal screens here), you have more empty lines to put +comments on. + + + Chapter 3: Naming + +C is a Spartan language, and so should your naming be. Unlike Modula-2 +and Pascal programmers, C programmers do not use cute names like +ThisVariableIsATemporaryCounter. A C programmer would call that +variable "tmp", which is much easier to write, and not the least more +difficult to understand. + +HOWEVER, while mixed-case names are frowned upon, descriptive names for +global variables are a must. To call a global function "foo" is a +shooting offense. + +GLOBAL variables (to be used only if you _really_ need them) need to +have descriptive names, as do global functions. If you have a function +that counts the number of active users, you should call that +"count_active_users()" or similar, you should _not_ call it "cntusr()". + +Encoding the type of a function into the name (so-called Hungarian +notation) is brain damaged - the compiler knows the types anyway and can +check those, and it only confuses the programmer. No wonder MicroSoft +makes buggy programs. + +LOCAL variable names should be short, and to the point. If you have +some random integer loop counter, it should probably be called "i". +Calling it "loop_counter" is non-productive, if there is no chance of it +being mis-understood. Similarly, "tmp" can be just about any type of +variable that is used to hold a temporary value. + +If you are afraid to mix up your local variable names, you have another +problem, which is called the function-growth-hormone-imbalance syndrome. +See next chapter. + + + Chapter 4: Functions + +Functions should be short and sweet, and do just one thing. They should +fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, +as we all know), and do one thing and do that well. + +The maximum length of a function is inversely proportional to the +complexity and indentation level of that function. So, if you have a +conceptually simple function that is just one long (but simple) +case-statement, where you have to do lots of small things for a lot of +different cases, it's OK to have a longer function. + +However, if you have a complex function, and you suspect that a +less-than-gifted first-year high-school student might not even +understand what the function is all about, you should adhere to the +maximum limits all the more closely. Use helper functions with +descriptive names (you can ask the compiler to in-line them if you think +it's performance-critical, and it will probably do a better job of it +that you would have done). + +Another measure of the function is the number of local variables. They +shouldn't exceed 5-10, or you're doing something wrong. Re-think the +function, and split it into smaller pieces. A human brain can +generally easily keep track of about 7 different things, anything more +and it gets confused. You know you're brilliant, but maybe you'd like +to understand what you did 2 weeks from now. + + + Chapter 5: Commenting + +Comments are good, but there is also a danger of over-commenting. NEVER +try to explain HOW your code works in a comment: it's much better to +write the code so that the _working_ is obvious, and it's a waste of +time to explain badly written code. + +Generally, you want your comments to tell WHAT your code does, not HOW. +Also, try to avoid putting comments inside a function body: if the +function is so complex that you need to separately comment parts of it, +you should probably go back to chapter 4 for a while. You can make +small comments to note or warn about something particularly clever (or +ugly), but try to avoid excess. Instead, put the comments at the head +of the function, telling people what it does, and possibly WHY it does +it. + + + Chapter 6: You've made a mess of it + +That's OK, we all do. You've probably been told by your long-time Unix +user helper that "GNU emacs" automatically formats the C sources for +you, and you've noticed that yes, it does do that, but the defaults it +uses are less than desirable (in fact, they are worse than random +typing - a infinite number of monkeys typing into GNU emacs would never +make a good program). + +So, you can either get rid of GNU emacs, or change it to use saner +values. To do the latter, you can stick the following in your .emacs file: + +(defun linux-c-mode () + "C mode with adjusted defaults for use with the Linux kernel." + (interactive) + (c-mode) + (c-set-style "K&R") + (setq c-basic-offset 8)) + +This will define the M-x linux-c-mode command. When hacking on a +module, if you put the string -*- linux-c -*- somewhere on the first +two lines, this mode will be automatically invoked. Also, you may want +to add + +(setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode) + auto-mode-alist)) + +to your .emacs file if you want to have linux-c-mode switched on +automagically when you edit source files under /usr/src/linux. + +But even if you fail in getting emacs to do sane formatting, not +everything is lost: use "indent". + +Now, again, GNU indent has the same brain dead settings that GNU emacs +has, which is why you need to give it a few command line options. +However, that's not too bad, because even the makers of GNU indent +recognize the authority of K&R (the GNU people aren't evil, they are +just severely misguided in this matter), so you just give indent the +options "-kr -i8" (stands for "K&R, 8 character indents"). + +"indent" has a lot of options, and especially when it comes to comment +re-formatting you may want to take a look at the manual page. But +remember: "indent" is not a fix for bad programming. |